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. The system, engine, and spawning blocks are required — each may be minimal (their fields all have defaults), but the block must be present, or the run fails at load with a "field required" error. msm, binning, execution, feature_selection, and adaptive_model are optional/opt-in with sensible defaults. (The starter file from trails-md-init includes all of them, so you only edit what you need.)

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 (+ experimental we · msm).

CV method — space_mode: fixed (your project_file) · pca · tica · tvae · deep-tica (+ experimental vampnet · spib · deep-lda). 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             # advisory only; format is inferred from extensions
  # 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                 # atm (OpenMM MonteCarloBarostat)
  dt: 0.002                     # ps
  npt: false                    # constant-pressure ensemble
  equilibrate: false
  # seed: 12345                 # deterministic engine RNG seed (else derived from random_seed)
  # gpu_ids: [0, 1]             # explicit GPUs for the local backend
  # --- GROMACS-only ---
  # gromacs_executable: gmx
  # gromacs_include_dir: /path/to/gromacs/top   # also needed when OpenMM reads a GROMACS .top with force-field includes
  # --- 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
  # ---- Kinetics mode (rate / MFPT): spawn_scheme: we + md_engine: openmm --------
  # inherit_velocities: true                   # continue parent velocities (required for a rate)
  # recycle_target: [[-2.5, -1.0], [2.0, 3.0]] # source->sink sink box, one [lo, hi] per CV dim
  # recycle_basis_index: 0                      # source frame walkers restart from
  # See docs/modes.md for how to read MFPT = 1/flux off the run.
  # 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: tica
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)
  # persistent_workers: true             # local: reuse workers + warm OpenMM Contexts across iterations (big speed-up for short segments)
  # --- scheduler settings (slurm/pbs) ---
  # gres: "gpu:1"                        # first-class SLURM --gres (preferred over a raw extra_directive)
  # 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. It covers the common and representative fields — including some advanced, opt-in blocks (e.g. input-feature selection, in-loop MSM convergence, adaptive binning) — but not literally every schema field (kinetics-mode and some engine tuning options are set by hand; see below). The Configuration reference lists the keys, defaults, and allowed values in table form, and Exploration vs. kinetics covers the rate-mode options.

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.