boltzkit.evaluation.sample_based.energy_histogram

Functions

get_reduced_energy_hist(log_probs[, n_bins, ...])

Compute a histogram of reduced energies from log-probabilities.

visualize_energy_hist_dual(pred_energy_hist, ...)

boltzkit.evaluation.sample_based.energy_histogram.get_reduced_energy_hist(log_probs: ndarray, n_bins: int = 100, energy_range: tuple[float, float] | None = None, quantile_range: tuple[float, float] | None = (0.01, 0.99), margin_ratio: float = 0.5)[source]

Compute a histogram of reduced energies from log-probabilities.

The reduced energy (dimensionless) is defined as

u(x) = -log p(x),

i.e., the negative log-probability, where p can be unnormalized.

For a Boltzmann distribution

p(x) ∝ exp(-E(x) / (k_B T)),

the reduced energy corresponds to

u(x) = E(x) / (k_B T).

Only relative differences in reduced energy are physically meaningful, since the normalization constant Z = ∫ p(x) dx is generally unknown.

Parameters:

  • log_probs (np.ndarray) – Array of log-probabilities log p(x). Can have arbitrary shape; the histogram is computed over all elements.

  • n_bins (int, default=100) – Number of bins for the histogram.

  • energy_range (tuple[float, float] | None, default=None) – Explicit (min, max) range for the histogram. If provided, quantile_range is ignored.

  • quantile_range (tuple[float, float] | None, default=(0.01, 0.99)) – Lower and upper quantiles used to automatically determine the histogram range if energy_range is None. This is useful to exclude extreme outliers. If None, the full data range is used.

  • margin_ratio (float, default=0.5) – Fraction of the data range to add as padding on both sides of the histogram range when it is determined from quantile_range. For example, a value of 0.5 extends the lower and upper bounds by 50% of the selected quantile width, providing extra margin to ensure edge data points are included, which are not extreme outliers.

Returns:

  • Histogram1D

  • A Histogram1D object containing the histogram and bin edges

boltzkit.evaluation.sample_based.energy_histogram.visualize_energy_hist_dual(pred_energy_hist: Histogram1D, true_energy_hist: Histogram1D, show: bool = False)[source]