API Overview

Modules

• adabmDCA.alphabet: Alphabet definitions shared by lightweight and tensor-based APIs.
• adabmDCA.alignment: Alignment containers and FASTA/Stockholm input-output helpers.
• adabmDCA.input_loading: Shared, side-effect-free loading of alignments and sequence weights.
• adabmDCA.preprocessing: Pure and file-oriented multiple-sequence-alignment preprocessing.
• adabmDCA.training_config: Canonical configuration values and validation for DCA training.
• adabmDCA.training_control: Shared lifecycle primitives for DCA training routines.
• adabmDCA.api.contacts: High-level contact-prediction operations.
• adabmDCA.api.diagnostics: Turn the files of a training run (and optionally a sampling check) into a verdict.
• adabmDCA.api.entropy: High-level thermodynamic-integration entropy estimation.
• adabmDCA.exceptions: Structured exceptions shared by every adabmDCA layer.
• adabmDCA.api.input_loading: Aggregate input loading for high-level workflows.
• adabmDCA.api.model: Notebook-friendly DCA model object.
• adabmDCA.api.ptt: Archive-based generation and direct entropy using the shared PTT sampler.
• adabmDCA.api.mutations: High-level mutation-scanning operations.
• adabmDCA.api.reintegration: High-level orchestration for experimental sequence reintegration.
• adabmDCA.api.results: Result objects returned by the high-level adabmDCA API.
• adabmDCA.api.sampling: High-level sequence-generation operations.
• adabmDCA.api.scoring: High-level sequence-energy operations.
• adabmDCA.serialization: Portable and atomic serialization helpers for results, logs and archives.
• adabmDCA.api.splitting: High-level API for homology-aware alignment splitting.
• adabmDCA.api.training: High-level DCA training workflow.
• adabmDCA.checkpoint: Training checkpoints and the versioned human-readable training log.
• adabmDCA.cobalt
• adabmDCA.dataset
• adabmDCA.dca
• adabmDCA.fasta
• adabmDCA.functional
• adabmDCA.graph
• adabmDCA.io
• adabmDCA.plot
• adabmDCA.ptt.config: Configuration for PTT snapshot retention, reservoirs and mixing analysis.
• adabmDCA.ptt.mixing: Replica-index autocorrelation analysis used by PTT's TRWA experiment.
• adabmDCA.ptt.sampler: Parallel Trajectory Tempering with snapshot retention and mixing recovery.
• adabmDCA.resampling
• adabmDCA.sampling
• adabmDCA.sampling_triton: Optional Triton kernels for categorical GPU sampling.
• adabmDCA.statmech
• adabmDCA.steering: Steered sampling: a user potential added to the DCA Hamiltonian.
• adabmDCA.stats
• adabmDCA.training
• adabmDCA.utils

Classes

• alignment.Alignment: Aligned sequences with optional alphabet and filtering provenance.
• alignment.AlignmentConversionResult: Outcome of convert_alignment.
• input_loading.AlignmentLoadConfig: How load_alignment reads, validates and filters an alignment.
• preprocessing.AlignmentFilterResult: Outcome of filter_gap_fraction.
• preprocessing.AlignmentProcessingConfig: Transformations applied by preprocess_alignment, in this order.
• preprocessing.AlignmentProcessingReport: What preprocess_alignment changed.
• preprocessing.AlignmentProcessingResult: Outcome of preprocess_alignment.
• training_config.ConfigurationError: Raised when a training configuration is internally inconsistent.
• training_config.TrainingConfig: All settings of one training run, validated on construction.
• training_control.CheckpointStore: Persistence interface used by the training controller.
• training_control.StageProgress: Transient stage update; separate from committed metric records.
• training_control.StopReason: Reason why a training strategy stopped.
• training_control.TrainingCancelled: Internal cancellation signal raised by the shared controller.
• training_control.TrainingController: Coordinate one training run without owning its numerical updates.
• training_control.TrainingCounters: Progress counters of a training run.
• training_control.TrainingLimits: Step budgets of a training run; None means no limit.
• training_control.TrainingMetrics: Common metrics emitted after a meaningful training step.
• exceptions.AdabmDCAError: Base class for recoverable errors raised by adabmDCA.
• exceptions.AlignmentError: Base class for alignment input and processing errors.
• exceptions.AlignmentFormatError: Raised when an alignment format cannot be detected or parsed.
• exceptions.AlignmentLengthError: Raised when sequences do not share a common aligned length.
• exceptions.AlignmentLoadError: Raised when an alignment resource cannot be opened or decoded.
• exceptions.ChainLoadError: Raised when an initial chain state cannot be loaded or validated.
• exceptions.ComputationError: Raised when a valid scientific operation cannot be completed.
• exceptions.ConvergenceError: Raised when an iterative operation exhausts its convergence budget.
• exceptions.InputLoadError: Raised when an input resource cannot be read or decoded.
• exceptions.InputValidationError: Raised when a high-level API input is invalid.
• exceptions.ModelCompatibilityError: Raised when data are incompatible with a DCA model.
• exceptions.ModelLoadError: Raised when model parameters cannot be loaded.
• exceptions.OperationCancelledError: Raised when a caller-provided cancellation hook stops an operation.
• exceptions.OutputSerializationError: Raised when a result cannot be serialized to the requested output.
• exceptions.WeightLoadError: Raised when sequence weights cannot be loaded or aligned.
• input_loading.TrainingInputs: Loaded and cross-checked inputs of one training run.
• model.DCAModel: DCA parameters and convenience methods for scoring and sampling.
• ptt.PTTEntropyResult: Entropy of a PTT model, returned by estimate_ptt_entropy.
• results.ContactMapResult: Contact scores returned by predict_contacts.
• results.EnergyResult: DCA energies of scored sequences, returned by score_sequences.
• results.ModelMetadata: Portable description of a loaded DCA model.
• results.MutationRecord: One single-site mutant from scan_mutations.
• results.MutationScanResult: All single-site mutants of a sequence, returned by scan_mutations.
• results.ProfileSplitResult: Training/test split of an alignment, returned by split_alignment.
• results.ReintegrationResult: Outcome of reintegrate_model.
• results.SamplingProgress: Progress event passed to the progress callback of sample_sequences.
• results.SamplingResult: Generated sequences and diagnostics, returned by sample_sequences.
• results.ThermodynamicIntegrationProgress: Progress event passed to the progress callback of estimate_entropy.
• results.ThermodynamicIntegrationResult: Outcome of estimate_entropy.
• results.TrainingDatasetSummary: Size and filtering of one training or validation alignment.
• results.TrainingInitialization: Resolved training setup, passed to on_initialized of train_model.
• results.TrainingProgress: One accepted update, passed to the progress callback of train_model.
• results.TrainingResult: Outcome of train_model.
• checkpoint.Checkpoint: Save model state and write the training history, events and readable log.
• dataset.DatasetDCA: Encoded alignment with sequence weights, as a PyTorch dataset.
• config.PTTConfig: Settings of Parallel Trajectory Tempering, for training and sampling.
• mixing.MixingEstimate: Outcome of one PTT mixing check.
• mixing.RenewalEstimate: Population renewal measured with configuration birth rounds.
• mixing.RenewalForecast: Exponential fit of the old fraction G(t) of a renewal phase.
• sampler.PTTSampler: A Parallel Trajectory Tempering ladder: models, their chains and its own RNG.
• sampler.PartitionEstimate: Estimate of the endpoint's log partition function, with its provenance.
• steering.SteeredKernel: Metropolis-Hastings kernel for exp(-beta * H - V(·, strength)).
• steering.Steering: A validated steering potential, evaluated on batches of chains.

Functions

• alphabet.detect_alphabet: Select the smallest compatible standard alphabet (DNA wins ties).
• alphabet.get_tokens: Return the ordered token string of an alphabet.
• alignment.convert_alignment: Convert a FASTA or Stockholm alignment to canonical aligned FASTA.
• alignment.convert_stockholm_to_fasta: Convert one Stockholm alignment to FASTA; see convert_alignment.
• alignment.detect_alignment_format: Detect whether a file is FASTA or Stockholm from its first non-empty line.
• alignment.normalize_gap_symbols: Replace one alignment gap symbol with another.
• alignment.read_alignment: Read one aligned FASTA or Stockholm alignment, without filtering.
• alignment.write_alignment: Write an alignment to a FASTA file.
• input_loading.load_alignment: Parse, validate, filter, and deduplicate an alignment.
• input_loading.load_sequence_weights: Load or calculate weights and align them with retained sequences.
• preprocessing.filter_gap_fraction: Remove sequences whose gap fraction is greater than the threshold.
• preprocessing.preprocess_alignment: Clean a raw alignment for DCA: read, transform, filter and optionally write it.
• preprocessing.remove_insertions: Remove dots and lowercase insertion residues from every sequence.
• contacts.compute_contact_map: Return only the (L, L) contact-score matrix of predict_contacts.
• contacts.predict_contacts: Predict residue contacts from a DCA model or directly from an alignment.
• diagnostics.diagnose_run: Indicators and findings for a training run directory, and optionally a sampling check.
• entropy.estimate_entropy: Estimate the entropy of a DCA model by thermodynamic integration.
• input_loading.load_training_inputs: Load the training inputs of train_model and check they fit together.
• model.inspect_model: Describe a model without using it: length, alphabet, device and precision.
• model.load_model: Load DCA parameters from a text parameter file or a PTT archive.
• ptt.estimate_ptt_entropy: Estimate the entropy of a PTT-trained model as <E> + log Z.
• ptt.load_ptt_backend: Return a PTT sampler ready for generation, loaded or forked from source.
• ptt.sample_ptt_sequences: Equilibrate the ladder in place, then collect endpoint samples.
• mutations.scan_mutations: Score every single-site substitution of an aligned wild-type sequence.
• reintegration.reintegrate_model: Train a model on natural sequences plus experimentally scored ones.
• sampling.generate_sequences: Return only the sequences of sample_sequences.
• sampling.sample_sequences: Generate sequences from a DCA model, with an energy for each.
• scoring.compute_energies: Return only the DCA energies of score_sequences, without CDE.
• scoring.fit_local_lambda: Fit E = intercept + lambda * summed CDE by ordinary least squares.
• scoring.score_sequences: Compute DCA energies of aligned sequences, with their local free energies.
• scoring.summed_cde: Return summed conditional entropy for each one-hot sequence, in nats.
• serialization.resolve_format: Resolve an explicit format or infer it from a filename suffix.
• serialization.result_document: Wrap result data in a stable, versioned document envelope.
• serialization.to_jsonable: Recursively convert a value to plain JSON types.
• serialization.write_dataframe: Write a pandas-compatible dataframe atomically.
• serialization.write_json: Write strict UTF-8 JSON atomically.
• serialization.write_numpy: Write a NumPy array atomically without altering the requested suffix.
• serialization.write_numpy_text: Write a NumPy array as an atomic text artifact.
• serialization.write_text: Write UTF-8 text atomically.
• splitting.split_alignment: Split an alignment into training and test sets that are not too similar.
• training.train_model: Train a DCA model from an alignment and return its in-memory result.
• cobalt.has_neighbours: Check if a sequence 'seq' has neighbours in the database 'db', that is, sequences
• cobalt.prune_redundant_sequences: Prunes sequences from X such that no sequence has more than 'seqid_th' fraction of its residues identical to any other sequence in the set.
• cobalt.run_cobalt: Runs the Cobalt algorithm to split the input MSA into training and test sets.
• cobalt.split_train_test: Splits X into two sets, T and S, such that no sequence in S has more than
• dca.get_contact_map: Computes the contact map from the model coupling matrix.
• dca.get_mf_contact_map: Computes the contact map using the mean-field DCA approximation from the data.
• dca.get_seqid: Returns a tensor containing the sequence identities between two sets of one-hot encoded sequences.
• dca.get_seqid_stats: - If s2 is provided, computes the mean and the standard deviation of the sequence identity between two sets of one-hot encoded sequences.
• dca.set_zerosum_gauge: Sets the zero-sum gauge on the coupling matrix.
• fasta.compute_weights: Computes the weight to be assigned to each sequence 's' in 'data' as 1 / n_clust, where 'n_clust' is the number of sequences
• fasta.decode_sequence: Takes a numeric sequence or list of seqences in input an returns the corresponding string encoding.
• fasta.encode_sequence: Encodes a sequence or a list of sequences into a numeric format.
• fasta.validate_alphabet: Validates that all characters in the sequences are present in the provided alphabet.
• functional.one_hot: A fast one-hot encoding function faster than the PyTorch one working with torch.int32 and returning a float Tensor.
• graph.activate_elements: Activates the unique entries at the flat indices together with their transposes.
• graph.activate_graph_elements: Updates the interaction graph by activating a fraction of the inactive couplings.
• graph.compute_Dkl_decimation: Computes the Kullback-Leibler divergence matrix between the initial distribution and the same
• graph.compute_Dkl_edge_activation: Computes the Kullback-Leibler divergence matrix of all the possible edges.
• graph.compute_Dkl_element_activation: Computes the Kullback-Leibler divergence matrix of all the possible couplings.
• graph.compute_density: Computes the density of active couplings in the coupling matrix.
• graph.compute_sym_Dkl: Computes the symmetric Kullback-Leibler divergence matrix between the initial distribution and the same
• graph.decimate_graph: Performs one decimation step and updates the parameters and mask.
• graph.rank_inactive_elements: Flat indices of the inactive unique (i < j) coupling entries, by decreasing Dkl.
• graph.select_inactive_elements: Activates the inactive off-diagonal coupling entries with the largest Dkl.
• graph.update_mask_decimation: Updates the mask by removing the n_remove couplings with the smallest Dkl.
• io.is_gzip: Whether a file is gzip-compressed, judged by its content rather than its name.
• io.load_chains: Load chain sequences from FASTA and return their one-hot encoding.
• io.load_params: Import parameters from the established J/h text format.
• io.load_params_old: Import the parameters of the model from a file.
• io.load_params_oldformat: Import the parameters of the model from a file. Assumes the old DCA format.
• io.open_params: Open a parameter file as text; gzip is detected on reading and chosen by a .gz name on writing.
• io.save_chains: Saves the chains in a fasta file.
• io.save_params: Save parameters in the established J/h text format.
• io.save_params_oldformat: Saves the parameters of the model in a file. Assumes the old DCA format.
• plot.plot_PCA: Makes the scatter plot of the components (pc1, pc2) of the input data and shows the histograms of the components.
• plot.plot_autocorrelation: Plots the time-autocorrelation curve of the sequence identity and the generated and data sequence identities.
• plot.plot_cij_scatter: Plot reference versus generated connected two-site correlations.
• plot.plot_contact_map: Plots the contact map.
• plot.plot_data_comparison: Compare samples with the data: clusters of the data and energy distributions.
• plot.plot_distance_comparison: Hamming distances within and between natural and generated sequences.
• plot.plot_energy_cde_scatter: Plot sequence energies against summed CDE and their fitted line.
• plot.plot_pearson_sampling: Plots the Pearson correlation coefficient over sampling time.
• plot.plot_privet: PRIVET: the null law, the excess of samples near the training set, and per-sample scores.
• plot.plot_ptt_autocorrelation: Plot replica-index autocorrelation and the two PTT time estimates.
• plot.plot_ptt_ladder_health: Plot how configurations move through a PTT ladder.
• plot.plot_ptt_renewal: Plot PTT population renewal for the warmup and, if it ran, the stationary phase.
• plot.plot_scatter_correlations: Plots the scatter plot of the data and generated Cij and Cijk values.
• mixing.exponential_autocorrelation_time: Fit the reference tail window: first zero / 3 through twice that zero.
• mixing.exponential_decay
• mixing.integrated_autocorrelation_time: Self-consistent window t >= 6 tau_int(t), with C(0)/2.
• mixing.process_replica_experiment: Return (tau_int, tau_exp, C) without changing the recorded labels.
• mixing.renewal_forecast: Fit log G against rounds over the recent half of the decay and predict the renewal round.
• mixing.replica_autocorrelation: Normalized C(t) for (rounds, replicas, chains) origin labels.
• sampler.bridge_increment: Return log(Z_upper/Z_lower) from samples of the lower Hamiltonian.
• resampling.compute_mixing_time: Computes the mixing time using the t and t/2 method. The sampling will halt when the mixing time is reached or
• sampling.get_sampler: Returns the sampling function corresponding to the chosen method.
• sampling.gibbs_sampling: Gibbs sampling. Attempts L * nsweeps mutations to each sequence in 'chains'.
• sampling.gibbs_step_independent_sites: Performs a single mutation using the Gibbs sampler. This version selects different random sites for each chain. It is
• sampling.gibbs_step_uniform_sites: Performs a single mutation using the Gibbs sampler. In this version, the mutation is attempted at the same sites for all chains.
• sampling.metropolis_sampling: Metropolis sampling. Attempts L * nsweeps mutations to each sequence in 'chains'.
• sampling.metropolis_step_independent_sites: Performs a single mutation using the Metropolis sampler. This version selects different random sites for each chain. It is
• sampling.metropolis_step_uniform_sites: Performs a single mutation using the Metropolis sampler. In this version, the mutation is attempted at the same sites for all chains.
• sampling.metropolized_gibbs_sampling: Metropolized Gibbs sampling. Attempts L * nsweeps updates to each sequence in 'chains'.
• sampling.metropolized_gibbs_sampling_categorical: Metropolized Gibbs sampling of integer states of shape (N, L).
• sampling.metropolized_gibbs_step_uniform_sites: Performs a single Metropolized Gibbs update at the same site for all chains.
• sampling.prepare_fixed_model_sampler: Prepare a sampler and parameters for a model that will not be updated.
• sampling.prepare_sampler: Select the fastest sampler for device.
• sampling.prepare_training_sampler: Prepare sampling for training with optional BF16 coupling storage.
• sampling.sampling_profile: Samples from the profile model defined by the local biases only.
• sampling.sampling_profile_categorical: Sample integer states (N,L) from the uncoupled profile, without encoding.
• sampling_triton.exchange_log_acceptance_categorical_triton: Compute Hamiltonian-exchange log acceptance from categorical states.
• sampling_triton.exchange_log_acceptance_sparse_triton: Hamiltonian-exchange log acceptance from sparse coupling layouts, or None if a graph is dense.
• sampling_triton.gibbs_sampling_categorical_triton: Run Gibbs sampling directly on contiguous int32 categorical states.
• sampling_triton.gibbs_sampling_triton: Run Gibbs updates, keeping each chain in registers across short chunks.
• sampling_triton.gibbs_step_independent_sites_triton: Apply one fused Gibbs update at an independently drawn site per chain (CUDA, Triton).
• sampling_triton.is_triton_available: Return whether Triton was imported successfully.
• sampling_triton.metropolis_sampling_categorical_triton: Run Metropolis sampling directly on contiguous int32 categorical states.
• sampling_triton.metropolis_sampling_replicas_categorical_triton: Sample a stack of PTT replicas in one sequence of Triton launches.
• sampling_triton.metropolis_sampling_triton: Run Metropolis updates with steps_per_launch updates per kernel.
• sampling_triton.metropolis_step_independent_sites_triton: Apply one fused Metropolis update at an independently drawn site per chain (CUDA, Triton).
• sampling_triton.metropolized_gibbs_sampling_categorical_triton: Metropolized Gibbs sampling of contiguous CUDA int32 states (N, L).
• sampling_triton.metropolized_gibbs_sampling_replicas_categorical_triton: Metropolized Gibbs sampling of a stack of replicas in one sequence of launches.
• sampling_triton.metropolized_gibbs_sampling_replicas_triton: Metropolized Gibbs sampling of a stack of replicas, from couplings in their original layout.
• sampling_triton.metropolized_gibbs_sampling_triton: Metropolized Gibbs sampling of one-hot chains; see metropolized_gibbs_sampling_categorical_triton.
• sampling_triton.sparse_coupling_layout: The sparse layout of stacked couplings (R, L, q, L, q) if it pays off for method, else None.
• sampling_triton.transpose_couplings_for_metropolized_gibbs: View (L, q, L, q) couplings as (site, source_site, source_state, state).
• statmech.compute_energy: Compute the DCA energy for a batch of sequences.
• statmech.compute_entropy: Compute the entropy of the DCA model.
• statmech.compute_logZ_exact: Compute the log-partition function of the model.
• statmech.compute_log_likelihood: Compute the log-likelihood per residue of the model.
• statmech.couplings_are_symmetric: Whether J[i, a, j, b] == J[j, b, i, a] exactly, as for every trained Potts model.
• statmech.enumerate_states: Enumerate all possible states of a system of L sites and q states.
• statmech.exchange_log_acceptance: Deterministic log Metropolis acceptance for Hamiltonian exchange.
• statmech.get_cde: Compute per-site context-dependent entropy of one-hot sequences.
• statmech.iterate_tap: Iterates the TAP equations until convergence.
• steering.importance_summary: Log importance weights back to the unsteered model and their effective sample size.
• steering.importance_warning: A warning when the importance weights are too concentrated to reweight reliably.
• stats.extract_Cij_from_freq: Extracts the lower triangular part of the covariance matrices of the natural data and generated data starting from the frequencies.
• stats.extract_Cij_from_seqs: Extracts the lower triangular part of the covariance matrices of the natural data and generated data starting from the sequences.
• stats.generate_unique_triplets: Generates a set of unique triplets of positions. Used to compute the 3-points statistics.
• stats.get_correlation_two_points: Computes the Pearson coefficient and the slope between the two-point frequencies of data and chains.
• stats.get_covariance_matrix: Computes the weighted covariance matrix of the input multi sequence alignment.
• stats.get_freq_single_point: Computes the single point frequencies of the input MSA.
• stats.get_freq_three_points: Computes the 3-body connected correlation statistics of the input MSAs.
• stats.get_freq_two_points: Computes the 2-points statistics of the input MSA.
• training.compute_gradient: Computes the gradient of the log-likelihood of the model using PyTorch.
• training.train_eaDCA: Fits an eaDCA model on the training data and saves the results in a file.
• training.train_edDCA: Fits an edDCA model on the training data and saves the results in a file.
• training.train_edgeDCA: Fits an edge activation DCA model (edgeDCA) on the training data and saves the results in a file.
• training.train_graph: Trains the model on a given graph until the target Pearson correlation is reached or the maximum number of epochs is exceeded.
• training.update_params: Updates the parameters of the model.
• training.update_params_edge_activation: Updates the mask and the coupling parameters using the edge-activation algorithm.
• utils.get_device: Returns the device where to store the tensors.
• utils.get_dtype: Returns the data type of the tensors.
• utils.get_mask_save: Returns the mask to save the upper-triangular part of the coupling matrix.
• utils.init_chains: Initialize the Markov chains of the DCA model. If 'fi' is provided, the chains are sampled from the
• utils.init_parameters: Initialize the parameters of the DCA model. The bias terms are initialized
• utils.parse_log_file: Parse a DCA training log file.
• utils.resample_sequences: Extracts nextract sequences from data with replacement according to the weights.
• utils.systematic_resampling: Performs the systematic resampling of the chains according to their relative weight.

---

This file was automatically generated via lazydocs.