> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincept.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculate Boltzmann Distribution Properties

> Calculates properties of a Boltzmann distribution given energy levels and temperature. The Boltzmann distribution describes the probability of states in thermal equilibrium and can be applied to portfolio optimization, maximum entropy models, and market microstructure. Returns comprehensive thermodynamic properties including probabilities, partition function, average energy, entropy, free energy, and heat capacity.

**Use Cases:**
- Maximum entropy portfolio optimization with return constraints
- Model market equilibrium states
- Calibrate energy-based models for risk
- Analyze statistical mechanics of trading systems
- Temperature-parameterized risk preferences

**Formula:** P(E_i) = exp(-E_i/T) / Z, where Z = Σ exp(-E_i/T)

**Credits:** 5 credits per request (Pro Tier) [Tier: ENTERPRISE, Credits: 10]



## OpenAPI

````yaml api-specs/physics.json post /quantlib/physics/boltzmann
openapi: 3.1.0
info:
  title: FinceptQuantLib API - Physics Module
  description: >-
    Physics and Information Theory module for FinceptQuantLib API. Includes
    Shannon/Renyi/Tsallis entropy, KL/JS divergence, mutual information,
    transfer entropy, Fisher information, Boltzmann distribution, Ising model,
    maximum entropy, thermodynamics (free energy, Carnot cycle, van der Waals
    equation), and Maxwell relations. **Pro Tier required. 5 credits per
    request.**
  version: 3.0.0
  contact:
    name: Fincept API Support
    url: https://fincept.in
servers:
  - url: https://api.fincept.in
    description: Fincept API Production Server
security:
  - APIKeyHeader: []
tags:
  - name: quantlib-physics
    description: Physics and Information Theory module for FinceptQuantLib API
    x-displayName: Physics
paths:
  /quantlib/physics/boltzmann:
    post:
      tags:
        - quantlib-physics
      summary: Calculate Boltzmann Distribution Properties
      description: >-
        Calculates properties of a Boltzmann distribution given energy levels
        and temperature. The Boltzmann distribution describes the probability of
        states in thermal equilibrium and can be applied to portfolio
        optimization, maximum entropy models, and market microstructure. Returns
        comprehensive thermodynamic properties including probabilities,
        partition function, average energy, entropy, free energy, and heat
        capacity.


        **Use Cases:**

        - Maximum entropy portfolio optimization with return constraints

        - Model market equilibrium states

        - Calibrate energy-based models for risk

        - Analyze statistical mechanics of trading systems

        - Temperature-parameterized risk preferences


        **Formula:** P(E_i) = exp(-E_i/T) / Z, where Z = Σ exp(-E_i/T)


        **Credits:** 5 credits per request (Pro Tier) [Tier: ENTERPRISE,
        Credits: 10]
      operationId: boltzmann_distribution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - energies
                - temperature
              properties:
                energies:
                  type: array
                  items:
                    type: number
                  description: >-
                    Energy levels of states (can represent negative returns,
                    costs, or losses)
                  example:
                    - 0
                    - 1
                    - 2
                    - 3
                    - 5
                temperature:
                  type: number
                  description: >-
                    Temperature parameter (higher = more uniform distribution,
                    lower = concentrate on low energy)
                  example: 1.5
            examples:
              portfolio_states:
                summary: Portfolio state energies (losses)
                value:
                  energies:
                    - 0
                    - 0.5
                    - 1.2
                    - 2.1
                    - 3.5
                  temperature: 1
              low_temperature:
                summary: Low temperature (concentrate on minimum)
                value:
                  energies:
                    - 1
                    - 2
                    - 3
                    - 4
                    - 5
                  temperature: 0.5
      responses:
        '200':
          description: Boltzmann distribution calculated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      probabilities:
                        type: array
                        items:
                          type: number
                        description: Boltzmann probabilities for each state
                        example:
                          - 0.4066
                          - 0.2472
                          - 0.1504
                          - 0.0915
                          - 0.0336
                      partition_function:
                        type: number
                        description: Partition function Z (normalization constant)
                        example: 2.4596
                      average_energy:
                        type: number
                        description: Expected energy <E>
                        example: 1.2834
                      energy_variance:
                        type: number
                        description: Variance of energy
                        example: 1.5623
                      entropy:
                        type: number
                        description: Thermodynamic entropy S
                        example: 1.3456
                      free_energy:
                        type: number
                        description: Helmholtz free energy F = <E> - TS
                        example: -0.7351
                      heat_capacity:
                        type: number
                        description: Heat capacity C = d<E>/dT
                        example: 0.6943
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/InsufficientCreditsError'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Invalid API key
    InsufficientCreditsError:
      description: Insufficient API credits
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Insufficient credits. This endpoint requires 5 credits.
    ValidationError:
      description: Request validation error
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: array
                items:
                  type: object
                  properties:
                    loc:
                      type: array
                      items:
                        type: string
                    msg:
                      type: string
                    type:
                      type: string
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Get your key at
        https://api.fincept.in/auth/register

````