AIMNet script integration

The mlmd interface incorporates the active simulation workflows from run_md_aimnet2.py, build_solvated_cell.py, and analyze_metadynamics.py in the AIMNet project. The table maps script settings and behavior to the library API. Configurations are nested dataclasses, for example mlmd.MDConfig(...).

Script feature	Library interface
Single inference model or model ensemble; device; optional compilation	mlmd(model_path=..., device=..., compile_model=..., model_kwargs=...); a list of paths averages predictions
Default 2025 model ensemble	mlmd() uses all four AIMNet2-2025 B97-3c/D3 members
Input geometry, charge, multiplicity, PBC, cell, minimum-distance check	XYZ/PDB path, State, or ASE Atoms; SystemConfig fields
PDB-derived XYZ with missing residue-name strings	Streaming XYZ input repairs only missing string fields; malformed numerical data still raises
Geometry minimization, optimizer selection and convergence guard	minimize; MinimizationConfig.optimizer, maxstep, fmax, steps, optimizer_kwargs, require_convergence
Separate equilibration and production damping/timesteps	equilibrate and run_md with their own configs; optional preparation configs inside MDConfig
Same metadynamics bias through equilibration and production with different damping	continue_equilibration_bias=True, matching phase metadynamics configs and timestep; live bias and clock continue without duplicate deposition
Hydrogen/heavy-atom mass scaling	hydrogen_mass, heavy_mass_multiplier; applied once in a combined workflow
Constraints on bonds involving hydrogen and fixed center of mass	shake_hydrogens, shake_cutoff, shake_tolerance; SHAKE includes persistent COM fixing; standalone fix_com is also available
Langevin NVT	ensemble="NVT", thermostat="langevin", temperature_K, thermostat_time_fs
Output and log stride, wrapped coordinate output	trajectory_interval, log_interval, wrap_output; trajectories stream to extended XYZ
Finite energy/force checks and production force threshold	Automatic finite checks; max_force_eV_A=150.0 for production, configurable or disabled with None
Per-step status, uncertainty, timings and run averages	Log file and simulation.data; statistics use bounded memory
Normal MD or PLUMED metadynamics	mode="md" or mode="metadynamics" and MetadynamicsConfig
Generated PLUMED input or existing input file	MetadynamicsConfig settings, plumed_file, or input_lines; save_input records resolved input
CV type, label and atom indices	cv, cv_label, atoms (one-based)
Gaussian deposition and well-tempered parameters	metad_label, metad_arg, pace, height_kj_mol, sigma, biasfactor, temperature_K, hills_file
Upper/lower wall and all wall parameters	wall_type, wall_label, wall_arg, wall_at, wall_kappa, wall_exp, wall_eps, wall_offset
Normalization grid derived from the actual periodic cell	calc_rct, grid_auto, grid_min, grid_max, grid_bins, grid_spacing
COLVAR fields, stride and filename	colvar_arg, colvar_stride, colvar_file; automatic fields omit disabled actions
Solute, solvent, optional single counterion	solvate(solute, solvent, SolvationConfig(counterion=...))
Total-density molecule counting and volume estimates	cell, density_g_ml, volume_samples, vdw_radii; preserves custom/isotope masses
Centered fixed solute/ion placement	counterion_gap; nearest valid vdW-separated ion placement among 26 directions
Packmol controls, periodic collision checks and retry	packmol, tolerance, nloop, timeout, seed
Dry run and packing artifacts	dry_run=True, work_dir=... returns Data and writes inputs without running Packmol
Solvation summaries and reports	simulation.data, State.solvation_report, and summary.json in a persistent work_dir
COLVAR population FES, HILLS reconstruction, existing FES grid	analyze_metadynamics(AnalysisConfig(colvar=.../hills=.../fes_file=...))
PLUMED metadata inference and overrides	plumed_input, cv, temperature, energy/time/CV units, column names and grid settings
Time windows, normalized weights and static-wall removal	start_time, end_time, rbias_column, bias_column, rct_column, additional_bias, upper_wall, keep_wall
Basin populations, free-energy differences and projected barriers	Automatic or explicit reactant/product ranges; results in data.summary
Infrequent-metadynamics first-passage statistics and censored runs	infrequent, acceleration_column, multiple colvar paths, kappa
Raw and smoothed 1D FES, basin shading and barrier marker	Plot().fes_1d(data, ...); smoothing affects the displayed curve only
CSV/JSON/PNG analysis output	AnalysisConfig(output_dir=..., plot=True); output_format="files" returns the directory

Library additions and deliberate differences

The library adds NVE, additional NVT thermostats, isotropic NPT integrators, State inputs/outputs, explicit output protection, and atomic restart checkpoints every 1,000 steps and at completion. By default, MD runs save positions, velocities, RNG state, thermostat/barostat state and constraints, including ordinary MD and any custom PLUMED input. Generated metadynamics also saves its bias history.

Library defaults do not encode the original experiment's atom numbers, box, density, two-million-step duration, or fine-tuned fifth ensemble member. Set the configs explicitly to reproduce that experiment. The old velocity-cap code was commented out; the library offers an optional velocity abort guard instead. Older nested script copies' retry-and-continue minimization behavior is replaced by an explicit convergence result and failure by default.

For fixed-cell periodic distance CVs, normalized metadynamics weights and an automatic grid are enabled by default. For other CVs and NPT, supply suitable explicit grid bounds to enable normalization, or reconstruct the FES from HILLS. Ordinary MD and generated PLUMED input support automatic restart. Custom PLUMED input still produces checkpoints, but restoring its bias requires action-specific restart files. The 1D analysis retains the source script's limitations on multidimensional and periodic-boundary-crossing free-energy profiles.

Script-only process management (package installation, Python re-execution, hardcoded cluster library paths, global compilation environment changes and CLI/IDE globals) is replaced by optional package dependencies and explicit API arguments. Select a timestamped output_dir in Python when needed. Training, dataset conversion, model export, and training TUI utilities are outside this simulation interface.

Start with running MLMD simulations, then follow the solvation, metadynamics, restart, and FES analysis tutorials. The configuration reference lists every setting and its current default.