MLMD configuration reference¶

Import the interface with from matmalib import mlmd. Configuration classes are nested dataclasses: mlmd.MDConfig(...), for example. The tables below are generated from the checkout at build time, so their defaults match the browser bundle and API reference. Each table lists fields declared or overridden by that class; inherited fields are linked explicitly.

Constructing a config or mlmd() does not load models, run a simulation, or fully validate the configuration. Geometry-dependent and operation-specific checks happen when the operation starts. Use dataclasses.replace(config, steps=...) to derive another configuration without mutating the original.

Choose an operation¶

Call	Configuration	Result
`simulation.minimize(system, config)`	`MinimizationConfig`	Relaxed `State`, or output `Path`
`simulation.equilibrate(system, config)`	`EquilibrationConfig`	Final `State` with masses/momenta, or output `Path`
`simulation.run_md(system, config)`	`MDConfig`	Streamed trajectory `Path`
`simulation.restart_md(checkpoint, steps=...)`	Saved configuration; additional-step count supplied to the method	New trajectory segment `Path`
`simulation.solvate(solute, solvent, config)`	`SolvationConfig`	Packed `State`/output `Path`, or `Data` for a dry run
`simulation.analyze_metadynamics(config)`	`AnalysisConfig`	Analysis `Data`, or output directory with `output_format="files"`

Simulation inputs accept a supported XYZ/PDB path, a matmalib State, or ASE Atoms. The geometry is copied. minimize, equilibrate, and solvate accept output=... and output_format="state"/"xyz"; requesting XYZ requires an output path. simulation.data holds diagnostics for the most recent operation, so save a reference before starting another operation. Trajectories stream to files rather than accumulating frames in memory.

Worked examples: running simulations, checkpoints, solvation, metadynamics, and FES analysis. See the API reference for exact method signatures.

Calculator selection¶

`mlmd(...)` argument	Default	Meaning
`model_path`	`None`	Default four-member AIMNet2-2025 B97-3c/D3 ensemble; a supported alias, inference-file path, or sequence selects other AIMNet weights
`device`	`None`	Device selection passed to AIMNet; specify `"cpu"` or a supported CUDA device for the local environment
`compile_model`	`False`	Pass model-compilation preference to AIMNet
`calculator`	`None`	Supply an ASE calculator instead of constructing AIMNet adapters
`model_kwargs`	`None`	Additional AIMNet calculator options (stored as an empty dictionary when omitted); supply `device` and `compile_model` through the explicit arguments

calculator and model_path are mutually exclusive. Injected calculators are used directly; model construction settings do not configure them. The default model lookup and downloads occur at the first operation needing a calculator. AIMNet adapters are cached separately by charge, multiplicity, and periodicity. Use the same potential, weights, and numerical environment when continuing a checkpoint. A restart does not serialize the model itself.

Units and indexing¶

Quantity	MLMD convention
Coordinates/cell/distances	Å
Energy and force	eV and eV/Å
Integration and damping times	fs
Temperature and pressure	K and bar
Atomic masses	Atomic mass units
Density	g/mL, total system mass divided by cell volume
`fixed_atoms`	Zero-based positions in the input system
Generated PLUMED `atoms`	One-based atom indices
Generated PLUMED distance, energy, time	nm, kJ/mol, ps
Generated PLUMED angle/torsion widths	Radians
Analysis free energies	kJ/mol internally; `Plot.fes_1d` can convert its displayed energy axis

Custom PLUMED input can declare different units. Keep its widths, walls, grids, and analysis metadata consistent. A units label does not rescale the input CV values.

SystemConfig¶

Inherited by minimization, production MD, and equilibration.

Field	Type	Default
`cell`	`Any`	`None`
`pbc`	`bool \\| tuple[bool, bool, bool] \\| None`	`None`
`charge`	`float \\| None`	`None`
`multiplicity`	`int \\| None`	`None`
`min_distance`	`float`	`0.5`
`fixed_atoms`	`tuple[int, ...]`	`()`
`fix_com`	`bool`	`False`
`shake_hydrogens`	`bool`	`False`
`shake_cutoff`	`float`	`1.3`
`shake_tolerance`	`float`	`1e-06`

cell and pbc override input metadata when supplied; otherwise existing settings are retained. Periodic geometry needs a valid cell.
charge and multiplicity supply electronic-state metadata. They do not change atom count or automatically add counterions.
min_distance rejects initial atom pairs closer than the threshold, including periodic neighbors; zero disables this check.
fixed_atoms freezes selected atom positions. fix_com creates a persistent center-of-mass constraint.
shake_hydrogens constrains the lengths of nearby atom pairs involving hydrogen within shake_cutoff, at shake_tolerance, and also fixes the center of mass. Pair selection uses distance, not chemical bond order. NPT and Nose–Hoover-chain dynamics reject constrained systems.

MinimizationConfig¶

Inherits every SystemConfig field.

Field	Type	Default
`optimizer`	`str`	`'FIRE'`
`fmax`	`float`	`0.05`
`steps`	`int`	`10000`
`maxstep`	`float`	`0.1`
`optimizer_kwargs`	`dict[str, Any]`	`{}`
`require_convergence`	`bool`	`True`
`trajectory`	`str \\| PathLike \\| None`	`None`
`trajectory_interval`	`int`	`1`
`log_file`	`str \\| PathLike \\| None`	`None`
`overwrite`	`bool`	`False`

optimizer selects an optimizer class exported by ase.optimize, matched case-insensitively, such as FIRE, BFGS, LBFGS, or BFGSLineSearch. optimizer_kwargs forwards additional optimizer settings; use the dedicated fields instead for maxstep, trajectory, and log output. fmax is the force convergence threshold, steps the iteration limit, and maxstep limits optimizer displacement when the selected optimizer explicitly accepts that argument. FIRE enables downhill_check by default. require_convergence=True raises when the threshold is not reached. Inspect the convergence report when deliberately disabling that requirement.

trajectory and log_file enable optional minimization output. trajectory_interval controls saved optimizer frames. overwrite=False protects existing outputs; even with overwriting enabled, conflicting input/output paths are rejected. See minimization and production.

MDConfig¶

Inherits every SystemConfig field.

Field	Type	Default
`steps`	`int`	`10000`
`timestep_fs`	`float`	`0.5`
`temperature_K`	`float`	`300.0`
`ensemble`	`str`	`'NVT'`
`thermostat`	`str`	`'langevin'`
`barostat`	`str`	`'mtk'`
`thermostat_time_fs`	`float`	`100.0`
`barostat_time_fs`	`float`	`1000.0`
`pressure_bar`	`float`	`1.0`
`compressibility_per_bar`	`float`	`4.57e-05`
`thermostat_chain`	`int`	`3`
`barostat_chain`	`int`	`3`
`seed`	`int \\| None`	`None`
`initialize_velocities`	`bool \\| None`	`None`
`remove_com_motion`	`bool`	`True`
`hydrogen_mass`	`float \\| None`	`None`
`heavy_mass_multiplier`	`float`	`1.0`
`max_velocity_angstrom_fs`	`float \\| None`	`None`
`max_force_eV_A`	`float \\| None`	`150.0`
`trajectory`	`str \\| PathLike`	`'trajectory.xyz'`
`trajectory_interval`	`int`	`10`
`wrap_output`	`bool`	`False`
`log_file`	`str \\| PathLike \\| None`	`'md.log'`
`log_interval`	`int`	`10`
`checkpoint_interval`	`int`	`1000`
`checkpoint_file`	`str \\| PathLike \\| None`	`'auto'`
`mode`	`str`	`'md'`
`metadynamics`	`mlmd.MetadynamicsConfig \\| None`	`None`
`minimization`	`mlmd.MinimizationConfig \\| None`	`None`
`equilibration`	`mlmd.EquilibrationConfig \\| None`	`None`
`continue_equilibration_bias`	`bool`	`False`
`overwrite`	`bool`	`False`

Integration and ensembles. steps × timestep_fs is the duration requested for this phase. NVE uses velocity Verlet; temperature_K initializes velocities when requested rather than applying a thermostat. NVT supports "langevin", "berendsen", and "nose-hoover"; Nose–Hoover chains reject constraints. NPT supports isotropic "mtk" or "berendsen" dynamics, requires full three-dimensional PBC and stress from the calculator, and disallows constraints. Ensemble, thermostat, and barostat names are matched case-insensitively. thermostat_time_fs and barostat_time_fs set coupling times; the chain fields configure the chain integrators. NPT includes its thermostat; the NVT thermostat selector does not choose it. pressure_bar is the NPT target; compressibility_per_bar is required by the Berendsen barostat and should match the material.

Velocities and masses. initialize_velocities=None preserves existing momenta and initializes when absent; True requests fresh thermal velocities, and False requires input momenta/velocities. A plain geometry without them is rejected with False. seed controls initialization and stochastic dynamics. remove_com_motion removes translation only when initializing an unconstrained system with more than one atom; persistent fixing is controlled separately by fix_com. hydrogen_mass replaces hydrogen masses, while heavy_mass_multiplier scales other masses. Existing velocities are preserved when masses change. These settings alter the dynamics and are not mass-conserving repartitioning. max_velocity_angstrom_fs and max_force_eV_A are abort thresholds, not clipping operations.

Files and diagnostics. trajectory, trajectory_interval, wrap_output, log_file, and log_interval control streamed output and its cadence. Wrapping changes the written coordinates. checkpoint_interval controls periodic checkpoint saves; a final checkpoint is also written. checkpoint_file="auto" derives a name from the run output, while None disables checkpointing. Reusing output paths requires overwrite=True. Checkpoints and trajectory files are distinct; see restart behavior.

Phases and bias. Set mode="metadynamics" together with metadynamics=MetadynamicsConfig(...) for a biased run. Optional minimization and equilibration configs prepare the input before production. continue_equilibration_bias=True keeps one live PLUMED instance across compatible equilibration and production phases; it requires matching bias settings and timestep. It is not a replacement for a disk checkpoint.

EquilibrationConfig¶

Inherits MDConfig, including its SystemConfig fields. These defaults are overridden:

Field	Type	Default
`steps`	`int`	`2000`
`thermostat_time_fs`	`float`	`10.0`
`max_force_eV_A`	`float \\| None`	`None`
`trajectory`	`str \\| PathLike \\| None`	`None`
`log_file`	`str \\| PathLike \\| None`	`'equilibration.log'`

Equilibration uses a shorter thermostat time and disables the production force-abort threshold by default. Its trajectory is optional. Masses, cell, and momenta can pass into production when a returned State is reused. Equilibration can also save ordinary or biased checkpoints. It supports an optional minimization but rejects a nested equilibration configuration.

SolvationConfig¶

Field	Type	Default
`cell`	`float \\| tuple[float, float, float]`	`30.0`
`density_g_ml`	`float`	`1.0`
`counterion`	`Any`	`None`
`counterion_gap`	`float`	`0.5`
`packmol`	`str \\| PathLike`	`'packmol'`
`tolerance`	`float`	`2.0`
`nloop`	`int`	`1000`
`timeout`	`float`	`600.0`
`seed`	`int`	`12345`
`volume_samples`	`int`	`200000`
`vdw_radii`	`dict[str, float]`	`{}`
`work_dir`	`str \\| PathLike \\| None`	`None`
`dry_run`	`bool`	`False`
`charge`	`float \\| None`	`None`
`multiplicity`	`int`	`1`
`overwrite`	`bool`	`False`

cell defines a cubic or orthorhombic periodic box. density_g_ml targets total density, including the solute and optional single counterion; solvent count is an integer, so inspect the achieved density. counterion_gap separates the solute/ion van der Waals surfaces; their positions are fixed during packing only. volume_samples and element-keyed vdw_radii configure diagnostic molecular sphere-union volume estimates, which are not subtracted from the cell volume for density counting. The radii also affect fixed-molecule placement.

packmol selects the executable; tolerance, nloop, timeout, and seed control packing. A supplied work_dir preserves generated packing inputs and reports. dry_run=True requires this directory, skips Packmol execution, and returns Data; omit geometry output arguments for a dry run. charge=None sums component charge metadata; multiplicities are not summed, so set the complete system's multiplicity explicitly. overwrite governs replacement of generated files. See the solvation walkthrough for diagnostics and periodic collision checks.

MetadynamicsConfig¶

Field	Type	Default
`plumed_file`	`str \\| PathLike \\| None`	`None`
`input_lines`	`tuple[str, ...] \\| None`	`None`
`save_input`	`str \\| PathLike \\| None`	`None`
`cv`	`str`	`'DISTANCE'`
`cv_label`	`str`	`'cv'`
`atoms`	`tuple[int, ...]`	`(1, 2)`
`metad_label`	`str`	`'metad'`
`metad_arg`	`str \\| None`	`None`
`sigma`	`float`	`0.02`
`height_kj_mol`	`float`	`2.0`
`pace`	`int`	`300`
`biasfactor`	`float`	`10.0`
`temperature_K`	`float \\| None`	`None`
`hills_file`	`str \\| PathLike`	`'HILLS'`
`colvar_file`	`str \\| PathLike`	`'COLVAR'`
`colvar_stride`	`int`	`10`
`colvar_arg`	`str \\| None`	`None`
`wall_type`	`str \\| None`	`None`
`wall_label`	`str`	`'wall'`
`wall_arg`	`str \\| None`	`None`
`wall_at`	`float`	`0.35`
`wall_kappa`	`float`	`150000.0`
`wall_exp`	`int`	`2`
`wall_eps`	`float`	`1.0`
`wall_offset`	`float`	`0.0`
`calc_rct`	`bool \\| None`	`None`
`grid_auto`	`bool \\| None`	`None`
`grid_min`	`float`	`0.0`
`grid_max`	`float \\| None`	`None`
`grid_bins`	`int \\| None`	`None`
`grid_spacing`	`float`	`0.002`
`log_file`	`str \\| PathLike \\| None`	`None`

Input. Supply either plumed_file or input_lines for custom actions, or use the generated-input settings. Custom input controls its own CVs, units, bias parameters, output paths, and restart directives; generated fields do not override its actions. save_input writes the resolved input for reproducibility. log_file selects the native PLUMED log.

Collective variable and deposition. Generated input supports DISTANCE, ANGLE, and TORSION. cv_label names the CV and atoms selects its unique one-based indices. metad_label names the bias; metad_arg=None uses cv_label. sigma, height_kj_mol, pace, and biasfactor configure well-tempered Gaussian deposition; the bias factor must exceed one. temperature_K=None uses the dynamics temperature; an explicit positive value overrides the generated METAD temperature without changing the MD thermostat temperature. Keep these temperatures physically consistent for your intended protocol.

History/output. For generated input, hills_file records deposited Gaussians. colvar_file and colvar_stride control observable output. With colvar_arg=None, the implementation selects available CV/bias/normalization columns; an explicit value selects requested PLUMED fields, omitting references to disabled wall and normalization fields. Generated HILLS/COLVAR paths must be distinct and contain no whitespace.

Walls. wall_type selects an upper or lower wall. wall_label and wall_arg name the wall and its argument; wall_arg=None uses the CV. wall_at, wall_kappa, wall_exp, wall_eps, and wall_offset configure its position and shape in the PLUMED unit system.

Normalization grid. grid_auto, grid_min, grid_max, grid_bins, and grid_spacing control the metadynamics grid. calc_rct controls normalization needed for reweighted analysis. With automatic defaults, normalization and a grid are enabled for a fixed-cell, fully periodic scalar distance CV; a complete explicit grid also enables normalization unless calc_rct=False. An explicit grid requires both grid_max and grid_bins, with grid_min < grid_max. NPT and other CVs need suitable explicit bounds when requesting normalization. Use the metadynamics tutorial before enabling a bias: generated defaults are not an experiment-specific CV definition.

AnalysisConfig¶

Field	Type	Default
`colvar`	`Any`	`None`
`hills`	`str \\| PathLike \\| None`	`None`
`fes_file`	`str \\| PathLike \\| None`	`None`
`plumed_input`	`str \\| PathLike \\| None`	`None`
`plumed`	`str \\| PathLike \\| None`	`None`
`cv`	`str \\| None`	`None`
`temperature`	`float \\| None`	`None`
`energy_unit`	`str \\| None`	`None`
`time_unit`	`str \\| None`	`None`
`cv_unit`	`str \\| None`	`None`
`bins`	`int`	`100`
`grid_range`	`tuple[float, float] \\| None`	`None`
`energy_column`	`str`	`'file.free'`
`rbias_column`	`str \\| None`	`None`
`bias_column`	`str \\| None`	`None`
`rct_column`	`str \\| None`	`None`
`additional_bias`	`tuple[str, ...] \\| None`	`None`
`start_time`	`float \\| None`	`None`
`end_time`	`float \\| None`	`None`
`upper_wall`	`tuple[float, float] \\| None`	`None`
`keep_wall`	`bool`	`False`
`reactant`	`tuple[float, float] \\| None`	`None`
`product`	`tuple[float, float] \\| None`	`None`
`kappa`	`float`	`1.0`
`infrequent`	`bool`	`False`
`acceleration_column`	`str \\| None`	`None`
`smooth_window`	`int`	`11`
`plot`	`bool`	`False`
`output_dir`	`str \\| PathLike \\| None`	`None`
`overwrite`	`bool`	`False`

Inputs and metadata. fes_file loads an existing one-dimensional free-energy grid; hills requests PLUMED reconstruction; colvar supplies samples or independent infrequent runs. Do not provide both hills and fes_file. plumed_input supplies action/units metadata and can resolve associated files. plumed selects the native command for reconstruction. Explicit cv, temperature, energy_unit, time_unit, and cv_unit settings override inferred values. Supported energy units are kJ/mol, kcal/mol, and eV; time units are fs, ps, ns, and s. Output energy arrays use kJ/mol. cv_unit labels the coordinate without rescaling it.

Profiles and weights. bins and grid_range define a histogram/reconstruction grid; grid_range cannot resample an existing fes_file. energy_column names the existing-grid free-energy column. rbias_column supplies normalized bias directly, or bias_column and rct_column supply its components. additional_bias names recorded static-bias columns to remove through population reweighting. start_time and end_time restrict the COLVAR population histogram to an inclusive time window; they do not truncate first-passage runs or HILLS. upper_wall=(at, kappa) subtracts a quadratic upper wall from a supplied or reconstructed FES. keep_wall disables automatic wall removal and conflicts with upper_wall; for COLVAR, explicitly named additional_bias columns are still removed.

Basins and kinetics. reactant and product specify non-overlapping CV intervals; provide both or neither. Absent explicit intervals, a profile may receive inferred basin assignments. kappa (greater than zero and at most one) enters Eyring proxies and the rate-to-activation-energy conversion; it does not change the first-passage event/exposure rate estimator. infrequent=True requests first-passage analysis of independent COLVAR runs; explicit basin ranges are required. acceleration_column selects a cumulative acceleration factor instead of integrating raw bias_column. Multiple COLVAR inputs are accepted only for this independent-run mode. Rate interpretation requires the assumptions discussed in FES and kinetics analysis.

Display and export. smooth_window is zero (off) or an odd integer of at least five, configuring local cubic least-squares smoothing. Raw thermodynamics retain the unsmoothed profile and unsampled gaps. output_dir enables CSV/JSON output; plot=True additionally requests a PNG and requires that directory. overwrite protects existing exports. For directory return instead of Data, call analyze_metadynamics(config, output_format="files").

The current analysis supports one CV and rejects FES grids marked periodic. COLVAR histograms treat the coordinate as a line and do not join its periodic endpoints, so boundary-crossing basins are unsupported. It has no automatic convergence certificate or uncertainty estimator. Compare independent sampling, inspect diagnostics, and follow the analysis tutorial.