BOLTZMANN

Overview

The BOLTZMANN function computes values for the Boltzmann distribution, also known as the truncated discrete exponential distribution. This discrete probability distribution models random variables that take integer values from 0 to N-1, with probabilities that decrease exponentially. It is commonly used in statistical mechanics to describe energy state distributions in physical systems.

The Boltzmann distribution is characterized by two shape parameters: \lambda (lambda), which controls the rate of exponential decay, and N, which defines the number of possible states. The probability mass function (PMF) is defined as:

f(k) = \frac{(1 - e^{-\lambda}) \cdot e^{-\lambda k}}{1 - e^{-\lambda N}}

for k = 0, 1, \ldots, N-1, where \lambda > 0 and N > 0.

This implementation uses the SciPy library’s scipy.stats.boltzmann module, which provides a complete suite of statistical functions for this distribution. For detailed information, see the SciPy Boltzmann distribution documentation and the source code on GitHub.

The function supports multiple computational modes: PMF (probability mass function), CDF (cumulative distribution function), SF (survival function), ICDF (inverse CDF/quantile function), and ISF (inverse survival function). It also computes summary statistics including the mean, variance, standard deviation, and median of the distribution. The optional loc parameter shifts the distribution along the integer axis.

This example function is provided as-is without any representation of accuracy.

Excel Usage

=BOLTZMANN(k, lambda_, n, boltzmann_mode, loc)

k (list[list], required): Value(s) at which to evaluate. For PMF/CDF/SF this is an integer in {0, ..., n-1}. For ICDF/ISF this is a probability in [0, 1].
lambda_ (float, required): Rate parameter (must be > 0).
n (int, required): Number of possible values in the support (must be > 0).
boltzmann_mode (str, optional, default: “pmf”): Output type to compute.
loc (float, optional, default: 0): Location parameter that shifts the distribution.

Returns (float): Distribution result (float), or error message string.

Examples

Example 1: PMF at k=3 for Boltzmann distribution

Inputs:

k	lambda_	n	boltzmann_mode	loc
3	1.4	19	pmf	0

Excel formula:

=BOLTZMANN(3, 1.4, 19, "pmf", 0)

Expected output:

Result
0.0113

Example 2: CDF at k=3 for Boltzmann distribution

Inputs:

k	lambda_	n	boltzmann_mode	loc
3	1.4	19	cdf	0

Excel formula:

=BOLTZMANN(3, 1.4, 19, "cdf", 0)

Expected output:

Result
0.9963

Example 3: Survival function at k=3 for Boltzmann distribution

Inputs:

k	lambda_	n	boltzmann_mode	loc
3	1.4	19	sf	0

Excel formula:

=BOLTZMANN(3, 1.4, 19, "sf", 0)

Expected output:

Result
0.0037

Example 4: Inverse CDF (quantile) at probability 0.5

Inputs:

k	lambda_	n	boltzmann_mode	loc
0.5	1.4	19	icdf	0

Excel formula:

=BOLTZMANN(0.5, 1.4, 19, "icdf", 0)

Expected output:

Result
0

Example 5: PMF for array input

Inputs:

k		lambda_	n	boltzmann_mode	loc
0	1	1.4	19	pmf	0
2	3

Excel formula:

=BOLTZMANN({0,1;2,3}, 1.4, 19, "pmf", 0)

Expected output:

Result
0.7534	0.1858
0.0458	0.0113

Python Code

from scipy.stats import boltzmann as scipy_boltzmann

def boltzmann(k, lambda_, n, boltzmann_mode='pmf', loc=0):
    """
    Compute Boltzmann distribution values: PMF, CDF, SF, ICDF, ISF, mean, variance, std, or median.

    See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.boltzmann.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        k (list[list]): Value(s) at which to evaluate. For PMF/CDF/SF this is an integer in `{0, ..., n-1}`. For ICDF/ISF this is a probability in [0, 1].
        lambda_ (float): Rate parameter (must be > 0).
        n (int): Number of possible values in the support (must be > 0).
        boltzmann_mode (str, optional): Output type to compute. Valid options: PMF, CDF, SF, ICDF, ISF, Mean, Variance, Std, Median. Default is 'pmf'.
        loc (float, optional): Location parameter that shifts the distribution. Default is 0.

    Returns:
        float: Distribution result (float), or error message string.
    """
    # Helper to normalize 2D list args
    def to2d(x):
        return [[x]] if not isinstance(x, list) else x

    # Validate lambda_
    try:
        lam_val = float(lambda_)
        if not (lam_val > 0):
            return "Invalid input: lambda must be > 0."
    except Exception:
        return "Invalid input: lambda must be a number."

    # Validate n
    try:
        n_val = int(n)
        if not (n_val > 0):
            return "Invalid input: n must be > 0."
    except Exception:
        return "Invalid input: n must be an integer."

    # Validate loc
    try:
        loc_val = float(loc)
    except Exception:
        return "Invalid input: loc must be a number."

    # Validate boltzmann_mode
    valid_modes = {"pmf", "cdf", "sf", "icdf", "isf", "mean", "var", "std", "median"}
    if not isinstance(boltzmann_mode, str) or boltzmann_mode not in valid_modes:
        return f"Invalid input: boltzmann_mode must be one of {sorted(valid_modes)}."

    # Handle statistics
    if boltzmann_mode in ["mean", "var", "std", "median"]:
        if boltzmann_mode == "mean":
            return float(scipy_boltzmann.mean(lam_val, n_val, loc=loc_val))
        if boltzmann_mode == "var":
            return float(scipy_boltzmann.var(lam_val, n_val, loc=loc_val))
        if boltzmann_mode == "std":
            return float(scipy_boltzmann.std(lam_val, n_val, loc=loc_val))
        if boltzmann_mode == "median":
            return float(scipy_boltzmann.median(lam_val, n_val, loc=loc_val))

    # PMF, CDF, SF, ICDF, ISF
    k = to2d(k)
    result = []
    for row in k:
        result_row = []
        for val in row:
            try:
                kval = float(val)
            except Exception:
                return "Invalid input: k must be a number."

            if boltzmann_mode == "pmf":
                res = scipy_boltzmann.pmf(kval, lam_val, n_val, loc=loc_val)
            elif boltzmann_mode == "cdf":
                res = scipy_boltzmann.cdf(kval, lam_val, n_val, loc=loc_val)
            elif boltzmann_mode == "sf":
                res = scipy_boltzmann.sf(kval, lam_val, n_val, loc=loc_val)
            elif boltzmann_mode == "icdf":
                res = scipy_boltzmann.ppf(kval, lam_val, n_val, loc=loc_val)
            elif boltzmann_mode == "isf":
                res = scipy_boltzmann.isf(kval, lam_val, n_val, loc=loc_val)

            result_row.append(float(res))
        result.append(result_row)
    return result

Overview

Excel Usage

Examples

Python Code

Online Calculator