`module` `adabmDCA.api.ptt`

Archive-based generation and direct entropy using the shared PTT sampler.

Global Variables

STATIONARY_BLOCKS_PER_WARMUP

`function` `load_ptt_backend`

load_ptt_backend(
    source: 'PTTSampler | str | Path',
    device: 'str' = 'cpu',
    seed: 'int | None' = None,
    alphabet: 'str | None' = None
) → PTTSampler

Return a PTT sampler ready for generation, loaded or forked from source.

An in-memory PTTSampler is forked, so the original is not modified. An archive keeps its precision and alphabet.

Args:

source: A PTTSampler or a path to a PTT archive.
device: Device to load the archive on; "auto" prefers CUDA, then MPS, then CPU. Changing device requires a new seed.
seed: New random seed, or None to continue the archived random stream.
alphabet: Optional alphabet; must match the archive's tokens.

Returns: A PTTSampler in generation mode.

Raises:

InputValidationError: If the archive is invalid or alphabet conflicts with it.

`function` `sample_ptt_sequences`

sample_ptt_sequences(
    source: 'PTTSampler | str | Path',
    n_sequences: 'int',
    local_sweeps: 'int' = 10,
    reference_fasta: 'AlignmentInput | None' = None,
    weights_path: 'WeightInput | None' = None,
    test_fasta: 'AlignmentInput | None' = None,
    privet_window: 'tuple[float, float]' = (0.01, 0.5),
    clustering_seqid: 'float' = 0.8,
    no_reweighting: 'bool' = False,
    seed: 'int' = 0,
    device: 'str' = 'cpu',
    alphabet: 'str | None' = None,
    sampler: 'str | None' = None,
    dtype: 'str | None' = None,
    n_measure: 'int' = 10000,
    pseudocount: 'float | None' = None,
    max_rounds: 'int' = 20000,
    mixing_method: 'str' = 'renewal',
    renewal_tolerance: 'float' = 0.01,
    stationary: 'bool' = False,
    local_kernel: 'str | None' = 'metropolized_gibbs',
    steering_potential: 'SteeringPotential | None' = None,
    steering_strength: 'float' = 1.0,
    steering_input: 'SteeringInput' = 'sequences',
    steering_proposal_steps: 'int | None' = None,
    steering_acceptance: 'float' = 0.3,
    collect_diagnostics: 'bool' = False,
    return_full_ladder: 'bool' = False,
    progress: 'Callable[[SamplingProgress], None] | None' = None,
    is_cancelled: 'Callable[[], bool] | None' = None
) → SamplingResult

Equilibrate the ladder in place, then collect endpoint samples.

mixing_method='renewal' (default) tracks the birth round of every configuration and waits until the ladder has twice been repopulated by exact rung-0 draws (see PTTSampler.measure_renewal); extra batches are spaced by the measured renewal time. By default the renewal runs only the warmup, which replaces the initial populations once; stationary=True adds the stationary renewal, which certifies that the returned population descends from draws made after the ladder had forgotten its start. 'autocorrelation' keeps the replica-index TRWA estimate of tau_int and tau_exp. Each round runs one pass of adjacent exchanges and population permutations, then the local sweeps, as in training. local_kernel selects the local update ('metropolized_gibbs' by default, 'metropolis' or 'gibbs'); None keeps the archived training kernel. All of them leave every replica's distribution invariant. The ladder is the training ladder (see PTTSampler.prepare_sampling_ladder). With steering_potential, steered rungs are added on top of it (PTTSampler.prepare_steering) and the samples come from the top one; see adabmDCA.api.sampling.sample_sequences for the steering arguments. With return_full_ladder, every rung's chains are kept at the same rounds as the endpoint batches, in the result's ladder_samples.

`function` `estimate_ptt_entropy`

estimate_ptt_entropy(
    model: 'PTTSampler | str | Path',
    n_sweeps: 'int' = 1,
    seed: 'int' = 0,
    device: 'str' = 'cpu',
    alphabet: 'str | None' = None,
    output_dir: 'str | Path | None' = None,
    label: 'str' = 'entropy',
    is_cancelled: 'Callable[[], bool] | None' = None
) → PTTEntropyResult

Estimate the entropy of a PTT-trained model as <E> + log Z.

A PTT archive already carries an estimate of log Z (bridges along its replica ladder), so no thermodynamic integration is needed: the ladder is advanced for the archive's equilibration_rounds exchange rounds, then log Z is re-estimated with Bennett's acceptance ratio and <E> is averaged over the endpoint chains.

Args:

model: A PTT archive path, or a PTTSampler (it is forked, not modified).
n_sweeps: Local sweeps per exchange round of the warmup.
seed: Random seed of the warmup.
device: "cpu", "cuda", "mps" (float32) or "auto".
alphabet: Optional alphabet; must match the archive.
output_dir: If given, the result is written to <output_dir>/<label>.json.
label: File-name stem of the written JSON.
is_cancelled: Optional callable; returning True stops the warmup.

Returns: A PTTEntropyResult; entropy is in nats per sequence.

Example:

estimate_ptt_entropy(model="output/ptt.h5", device="cuda").entropy  # 131.2

`class` `PTTEntropyResult`

Entropy of a PTT model, returned by estimate_ptt_entropy.

Attributes:

entropy: Entropy of the endpoint model, in nats per sequence (mean_energy + log_z).
free_energy: -log_z.
mean_energy: Mean endpoint energy over the endpoint chains.
log_z: Log partition function from the PTT bridges.
method: Estimator of log_z, e.g. "ptt_bridge".
status: Status of the log_z estimate.
model_id: Hash identifying the endpoint parameters.
model_version: Number of training updates of the endpoint.
ladder_version: Version of the replica ladder used.
sample_round: Exchange round at which the chains were measured.
artifacts: Written files by kind, when output_dir was given.

`method` `init`

__init__(
    entropy: 'float',
    free_energy: 'float',
    mean_energy: 'float',
    log_z: 'float',
    method: 'str',
    status: 'str',
    model_id: 'str',
    model_version: 'int',
    ladder_version: 'int',
    sample_round: 'int',
    artifacts: 'dict[str, Path]' = <factory>
) → None

`method` `to_dict`

to_dict() → dict[str, Any]

Return a JSON-compatible document with the result type and schema version.

`method` `to_json`

to_json(path: 'str | Path') → Path

Write to_dict as JSON and return the written path.

This file was automatically generated via lazydocs.

module adabmDCA.api.ptt

Global Variables

function load_ptt_backend

function sample_ptt_sequences

function estimate_ptt_entropy

class PTTEntropyResult

method __init__

method to_dict

method to_json