Skip to content

module adabmDCA.api.entropy

High-level thermodynamic-integration entropy estimation.

function estimate_entropy

estimate_entropy(
    model: 'str | Path',
    natural_alignment: 'AlignmentInput',
    target_alignment: 'AlignmentInput',
    initial_chains_path: 'str | Path | None' = None,
    n_chains: 'int' = 8192,
    n_sweeps: 'int' = 100,
    n_steps: 'int' = 100,
    theta_max: 'float' = 5.0,
    theta_sweeps: 'int' = 100,
    zero_sweeps: 'int' = 100,
    target_fraction: 'float' = 0.1,
    max_theta_iterations: 'int' = 10000,
    sampler: 'str' = 'metropolized_gibbs',
    alphabet: 'str | None' = None,
    seed: 'int' = 0,
    device: 'str' = 'auto',
    dtype: 'str' = 'float32',
    output_dir: 'str | Path | None' = None,
    label: 'str' = 'entropy',
    progress: 'EntropyProgress | None' = None,
    is_cancelled: 'Callable[[], bool] | None' = None
) → ThermodynamicIntegrationResult

Estimate the entropy of a DCA model by thermodynamic integration.

A field theta * x_target biases the model towards a target sequence. theta_max is first increased (by 1% per 100 sweeps) until more than target_fraction of the chains coincide with the target, which fixes the free energy at theta_max. The free energy at theta = 0 then follows by integrating the mean sequence identity over n_steps values of theta (trapezoidal rule), and the entropy is <E> - F. For PTT archives, adabmDCA.api.ptt.estimate_ptt_entropy is cheaper and needs no integration.

Args:

  • model: Path to a parameter file or PTT archive.
  • natural_alignment: Natural alignment, checked for compatibility with the model.
  • target_alignment: Alignment whose first valid sequence is the target; a warning is emitted if it contains more.
  • initial_chains_path: Optional FASTA of starting chains, resampled to n_chains if needed; random chains otherwise.
  • n_chains: Number of Markov chains.
  • n_sweeps: Sweeps at each integration step.
  • n_steps: Integration points between 0 and theta_max (at least 2).
  • theta_max: Initial largest bias strength; increased if needed.
  • theta_sweeps: Sweeps to equilibrate the chains at the initial theta_max.
  • zero_sweeps: Sweeps to estimate the unbiased mean energy <E>.
  • target_fraction: Fraction of chains, in (0, 1), that must reach the target at theta_max.
  • max_theta_iterations: Largest number of theta_max increases.
  • sampler: "metropolized_gibbs", "gibbs" or "metropolis".
  • alphabet: Alphabet of a text parameter file; None reads it from a PTT archive and assumes "protein" for text files.
  • seed: Random seed.
  • device: "auto", "cpu", "cuda" or "mps".
  • dtype: "float32" or "float64".
  • output_dir: If given, the result files are written there.
  • label: Prefix of the files written to output_dir.
  • progress: Optional callback receiving ThermodynamicIntegrationProgress updates.
  • is_cancelled: Optional callable; returning True stops the run.

Returns: A ThermodynamicIntegrationResult with the entropy (nats), the free energy and the integration history.

Raises:

  • InputValidationError: If a numerical setting is out of range.
  • ModelCompatibilityError: If the initial chains do not match the model.
  • ConvergenceError: If target_fraction is not reached within max_theta_iterations.
  • OperationCancelledError: If is_cancelled returns True.

This file was automatically generated via lazydocs.