The input file¶
Everything about a run — the system, MD engine, sampling method, CV space, and where jobs execute — is described by a single YAML input file. There is no code to write for a standard run.
Get a starter file¶
trails-md-init # writes ./config.yaml (annotated template)
trails-md-init -o my_run.yaml # custom path
Then edit it and validate before running:
trails-md --config config.yaml --check # checks files, engine, settings
trails-md --config config.yaml --iterations 200
The starter file is also at examples/template.yaml, and worked examples live
under examples/AlaD/ and examples/AIB9/.
Structure¶
The file has one block per concern. Only system (and project_file for
space_mode: fixed) is mandatory; everything else has sensible defaults, and
the advanced blocks (execution, adaptive_model) are opt-in.
| Block | Selects |
|---|---|
system |
structure, topology, and the atom mask for features |
engine |
MD backend (OpenMM/GROMACS/Amber) and thermodynamics |
spawning |
how the next walkers are chosen, and walker/step counts |
space_mode + adaptive_model |
the CV method and its hyperparameters |
execution |
where walkers run: workstation, SLURM, or PBS |
| run-level keys | outdir, random_seed, checkpoint_freq, … |
Choosing methods (the knobs that matter most)¶
Sampling method — spawning.spawn_scheme:
density · voronoi · lof · fps.
CV method — space_mode:
fixed (your project_file) · pca · tica · tvae · deep-tica.
Hyperparameters live in adaptive_model (lagtime, latent_dim, epochs,
encoder_hidden_dims, …). See Collective variables.
Features — adaptive_feature_type (distances/fitted_coords/phi_psi)
restricted by system.feature_selection.
Convergence — sampling proceeds for the configured iteration budget, or stops early when grid/Voronoi bin occupancy plateaus. See Concepts.
Where it runs — execution.backend: local (multi-GPU workstation) or
slurm / pbs (HPC array jobs). See Execution.
Annotated template¶
# ============================================================================
# Trails-MD input file
#
# A single YAML file fully describes a run: the system, MD engine, how walkers
# are spawned, the collective-variable (CV) space, optional feature selection
# and MSM-convergence, and where jobs execute. Paths are resolved relative to
# this file. Validate before running: trails-md --config config.yaml --check
# Full reference: docs/input_file.md and docs/configuration.md
# ============================================================================
# ---- System: structure, topology, and how features are read ----------------
system:
conf_file: start.gro # coordinates (.gro/.pdb/.crd/...)
top_file: topol.top # topology
topology: gromacs # gromacs | amber | charmm
# system_file: system.py # optional: custom OpenMM System builder
# project_file: project.py # required for space_mode: fixed (defines extract_cvs)
trajectory_topology_file: start.gro
feature_selection: "protein and not (type H)" # MDAnalysis atom selection
# ---- Engine: the MD backend and thermodynamic settings ---------------------
engine:
md_engine: openmm # openmm | gromacs | amber
platform_name: CUDA # use CPU if OpenMM has no registered CUDA platform
precision: mixed # mixed | single | double
temperature: 300.0 # Kelvin
pressure: 1.0 # bar
dt: 0.002 # ps
npt: false # constant-pressure ensemble
equilibrate: false
# gpu_ids: [0, 1] # explicit GPUs for the local backend
# --- GROMACS-only ---
# gromacs_executable: gmx
# gromacs_include_dir: /path/to/gromacs/top
# --- Amber-only ---
# amber_executable: pmemd.cuda
# amber_input_file: prod.in
# ---- Spawning: how the next walkers are chosen -----------------------------
spawning:
spawn_scheme: density # density | voronoi | lof | fps | msm | we
spawn_type: hard # hard | probabilistic
search_mode: explore # explore | target
walker: 16 # walkers per iteration
step: 5000 # MD steps per walker
stride: 50 # save a frame every N steps
max_workers: 4 # concurrent walkers (local backend)
# target: [1.5, -1.2] # CV target when search_mode: target
voronoi_clusters: 150 # cells / microstates (voronoi & msm spawners)
we_target_per_bin: 4 # walkers per bin for spawn_scheme: we
lof_neighbors: 20
# Coverage-based (legacy) convergence; superseded by msm.* when msm.enabled:
resolution_check_patience: 5
convergence_patience: 0
# ---- CV space: fixed physical CVs or a learned latent space ----------------
# space_mode: fixed | pca | tica | tvae | vampnet | spib | deep-tica | deep-lda
space_mode: vampnet
adaptive_feature_type: distances # distances | fitted_coords | phi_psi (AIB9-only)
# adaptive_angle_encoding: sincos # raw | sincos — for phi_psi features, embed
# dihedrals as [sin, cos] so they aren't torn at ±pi
retrain_freq: 5 # retrain cadence for retrain_policy: fixed
retrain_policy: fixed # fixed | vamp_adaptive (retrain on VAMP-2 drop)
# vamp_retrain_tol: 0.1 # relative VAMP-2 drop that triggers a retrain
# retrain_min_interval: 1
# retrain_max_interval: 20
aggregate_memory: true
max_adaptive_memory_frames: 50000
adaptive_model: # hyperparameters for learned CVs
lagtime: 5
latent_dim: 2
epochs: 50
learning_rate: 0.0005
encoder_hidden_dims: [64, 32]
decoder_hidden_dims: [32, 64]
dropout_rate: 0.1
deep_tica_hidden_dims: [64, 32]
spib_n_states: 10 # SPIB only
spib_beta: 0.001 # SPIB only
# ---- Feature selection: VAMP-2 optimisation of the input features ----------
feature_selection:
enabled: false # opt-in
method: greedy_vamp # greedy_vamp | all
lagtime: 10
cadence: 5 # re-select every N iterations
# max_features: 50
# min_gain: 1.0e-4
# candidate_feature_types: [distances, fitted_coords] # rank types by VAMP-2
# ---- MSM: build a Markov State Model and stop on convergence ---------------
msm:
enabled: false # opt-in; stops sampling on convergence
cadence: 1 # estimate the MSM every N iterations
min_frames: 2000 # wait for this many cumulative frames
lagtime: 10
lagtimes: [1, 2, 5, 10, 20] # implied-timescale sweep (diagnostics)
n_microstates: 100
cluster_method: kmeans # kmeans | regspace
estimator: mle # mle | bayesian (error bars)
n_timescales: 3
n_metastable: 4 # PCCA+ coarse-graining
stable_clustering: false # comparable microstate IDs / T_ij across iters
# MSM-guided spawner (spawn_scheme: msm): uncertainty x leverage x flux
spawn_alpha: 1.0 # exploration / least-counts weight
spawn_leverage: 1 # slow eigenvectors used for leverage
spawn_uncertainty: true # include outflow-uncertainty factor
convergence_mode: all # all | any
convergence_patience: 3
convergence_criteria:
- name: implied_timescales
params: {tol: 0.1, n_timescales: 2}
- name: vamp2
params: {tol: 0.05}
# - name: transition_matrix # flux-weighted T_ij statistical convergence
# params: {tol: 0.2, min_flux: 1.0e-3}
# - name: statistical_error # needs estimator: bayesian
# params: {tol: 0.2}
# ---- Binning: landscape-adaptive stratification for density / WE spawners ---
binning:
scheme: uniform # uniform | gradient | mab | eigenvector
# n_fine: 100 # density-histogram resolution (gradient scheme)
# smoothing: 3 # density smoothing window (gradient scheme)
# ---- Execution: where walkers run ------------------------------------------
execution:
backend: local # local | slurm | pbs
# walker_timeout: 3600 # local: kill a walker after N seconds (hang guard)
# --- scheduler settings (slurm/pbs) ---
# partition: gpu
# account: my_alloc
# walltime: "02:00:00"
# cpus_per_task: 8
# gpus_per_task: 1
# memory: "16G"
# max_retries: 2
# max_in_flight: 64 # cap concurrent array elements (SLURM `%N`)
# max_array_size: 1000 # split larger batches into sequential sub-arrays
# marker_grace: 30 # tolerate shared-FS metadata lag (seconds)
# wait_timeout: null # ceiling on waiting for one array job; null = derive from walltime
# module_loads:
# - "module load cuda/12.2"
# extra_directives: # raw scheduler lines (e.g. GPU gres / QoS)
# - "#SBATCH --gres=gpu:1"
# ---- Run-level settings ----------------------------------------------------
outdir: runs/my_run
random_seed: 42 # base seed; per-walker seeds derive from it deterministically
checkpoint_freq: 1
# min_success_fraction: 1.0 # HPC: continue an iteration if >= this fraction of walkers succeed
save_features: true
n_bins: [30, 30] # binning for coverage / fixed-space grid
# min_values: [-3.14159, -3.14159] # fixed-space bounds (space_mode: fixed)
# max_values: [3.14159, 3.14159]
Note
The snippet above is the exact file trails-md-init writes, and includes
every field the underlying config schema accepts — including some
advanced, opt-in blocks (e.g. input-feature selection, in-loop MSM
convergence, adaptive binning) that are not yet covered by the current
manuscript scope and aren't otherwise documented on this site. The
Configuration reference lists the manuscript-scope
keys, defaults, and allowed values in table form.
How settings flow¶
trails-md --config config.yaml loads the YAML, validates it against the
schema (trails_md/config.py), resolves relative paths, and runs the adaptive
loop. Invalid values (e.g. an unknown space_mode or spawn_scheme) are
rejected immediately with a clear message, before any MD is launched.
```