Collective variables¶

Primary references for TICA, TVAE, and Deep-TICA are collected on the References page.

Trails-MD can sample in fixed physical CVs or learn CVs on the fly. The available learned methods live in a single registry (trails_md/spaces/registry.py), which also tracks each method's backend and whether it is available in your environment.

All eight methods below are implemented behind the same interface and are exercised end-to-end in the test suite and in the alanine-dipeptide benchmark campaign. They differ in what they optimize, which is the thing to reason about when choosing: variance (PCA), slow modes (TICA, Deep-TICA, VAMPnet), time-lagged reconstruction (TVAE), predictive information (SPIB), or endpoint discrimination (Deep-LDA).

Available methods¶

`space_mode`	Method	Optimizes	Backend
`fixed`	User CVs via a project file	— (you choose)	—
`pca`	Principal component analysis	variance	scikit-learn
`tica`	Time-lagged ICA	autocorrelation (slow modes)	deeptime
`tvae`	Time-lagged VAE	time-lagged reconstruction (nonlinear)	deeptime + torch
`deep-tica`	Deep (nonlinear) TICA	slow modes (nonlinear)	mlcolvar + lightning
`vampnet`	VAMPNet	VAMP-2 score (soft metastable states)	deeptime + torch
`spib`	State predictive information bottleneck	predictive information	torch
`deep-lda`	Deep LDA (supervised)	endpoint discrimination	mlcolvar + lightning

SPIB state refinement

Since v1.1.0 spib performs the iterative self-consistent state refinement of the original method: after each pass the frames are relabelled by the current latent classifier and the model is refit, repeating until the labels stop moving or adaptive_model.spib_refine_rounds is exhausted (default 5). Set it to 0 to recover the earlier single-pass behaviour, in which the states were exploratory rather than converged metastable assignments. The number of rounds actually run, and the label churn per round, are recorded with the fitted model.

deep-tica and deep-lda need the optional extra: pip install "trails-md[deep-tica]". deep-lda additionally requires per-frame state labels.

fixed mode uses a user project_file exposing extract_cvs(trajectories, top_file, conf_file) -> ndarray.

Choosing a method¶

Start simple: tica (fast, robust, interpretable) or pca.
Nonlinear CVs: tvae or deep-tica when a good linear projection isn't enough to separate conformations that overlap in physical coordinates.
Kinetically meaningful states: vampnet (soft metastable assignment) or spib.
You know the endpoints: deep-lda — but note that endpoint separation is not the same as having sampled a pathway between them; check the lineage (see Concepts).
Pairs with kinetics mode: a learned slow coordinate (tica/deep-tica) makes a natural progress coordinate for a weighted-ensemble rate — see Exploration vs. kinetics.
Whatever you pick, validate against an interpretable observable for your system.

Configuring¶

space_mode: tica
adaptive_feature_type: distances      # distances | fitted_coords | phi_psi
retrain_freq: 5                       # retrain the CV every 5 iterations
adaptive_model:
  lagtime: 5                          # in FRAMES: lag = lagtime x stride x dt
  latent_dim: 2
  epochs: 50
  encoder_hidden_dims: [256, 128]     # also the built-in default

lagtime is counted in saved frames, not in time units, so the physical lag is lagtime × stride × dt. With stride: 100 and dt: 0.002 ps, lagtime: 5 is a 1 ps lag.

When a model is retrained, the full accumulated feature history is reprojected into the updated latent space before spawning, so selection always reflects the current coordinates.

Time-lagged pairs never cross a respawn¶

For every time-lagged method (TICA, TVAE, Deep-TICA, VAMPNets, SPIB) the features are split per walker before the lagged dataset is built, so a lagged pair is always drawn from one continuous walker segment. Velocities are redrawn at each respawn, so a pair spanning that boundary would relate dynamically unrelated configurations. This also means the lag must be shorter than a walker segment: lagtime < step / stride.

Adaptive sampling still biases which segments exist, so the estimator sees a non-Boltzmann mixture of short trajectories. That affects the estimated timescales, not the validity of the pairs; see Reweighting.

The TVAE objective¶

The time-lagged variational autoencoder encodes frame $\mathbf{x}t$ and reconstructs $\mathbf{x}{t+\tau}$, so the latent space is trained to retain slowly-decorrelating information rather than high-variance information. Its loss is

$$ \mathcal{L} = \underbrace{\lVert \mathbf{x}{t+\tau} - \hat{\mathbf{x}}{t+\tau} \rVert^2}{\text{reconstruction}} \; + \; \frac{\beta}{n\text{features}} \, D_\mathrm{KL}!\left(q(\mathbf{z}\mid\mathbf{x}_t) \,\Vert\, p(\mathbf{z})\right) $$

with $p(\mathbf{z}) = \mathcal{N}(0, I)$. Note the KL term is divided by the number of input features, so $\beta$ is defined per feature; the same $\beta$ therefore means the same thing across systems of different dimensionality.

adaptive_model.tvae_beta sets $\beta$ and defaults to 1.0, the standard VAE objective and the value used for every published Trails-MD result. Lowering it favours reconstruction accuracy; raising it favours a smoother, more strongly regularised latent space at the cost of reconstruction.

Availability checks¶

If a method's backend is missing, Trails-MD raises an actionable error, e.g.:

CV method 'deep-tica' requires missing package(s): mlcolvar, lightning.
Install via: pip install "trails-md[deep-tica]".

Programmatically:

from trails_md.spaces.registry import is_available
is_available("tica")   # True / False

Adding a new CV method¶

Register a CVMethod in trails_md/spaces/registry.py and add a branch in AdaptiveSpaceModel.fit / .project. The rest of the framework (training cadence, spawning) works unchanged.