Molecular Dynamics

.oqp control reference

Use canonical routes and controls in input files. Raw names identify implementation storage. A control without an accepted canonical spelling is not available in .oqp files.

OpenQP uses three explicit input calls for dynamics:

• md(...) contains nuclear propagation, initial-condition, ensemble, and output settings.
• namd(...) adds excited-state propagation and surface hopping.
• qmmm(...) selects a QM/MM model. It does not replace either dynamics call.

Thus md(...) alone requests ground-state Born--Oppenheimer molecular dynamics, while namd(...) md(...) requests nonadiabatic molecular dynamics (NAMD). Add qmmm(...) to either form when a QM/MM calculation is intended.

These calls give four supported compositions: ground-state MD, ground-state QM/MM MD, NAMD, and QM/MM NAMD.

Dynamics Backend Selection

Gas-phase dynamics uses the native OpenQP integrator. Every QM/MM calculation, periodic or not, propagates the complete system with OpenMM and evaluates the QM forces with OpenQP. Periodicity is selected by the QM/MM electrostatics, qmmm(cutoff=PME), Ewald, or CutoffPeriodic, which require box vectors in the PDB file; there is no separate periodic switch.

Calculation	Input form	Dynamics backend
Gas-phase ground-state dynamics	md(...)	native OpenQP
QM/MM ground-state dynamics	md(...) qmmm(...)	OpenMM with OpenQP QM forces
Gas-phase NAMD	namd(...) md(...)	native OpenQP
QM/MM NAMD	namd(...) md(...) qmmm(...)	OpenMM environment with OpenQP QM forces

Ownership of Dynamics Controls

md(...) owns every control of nuclear propagation: nstep, dt, velocity, temperature, ensemble, friction, seed, rng_stream, mo_reuse, and the output and continuation keywords trajectory_file, trajectory_interval, energy_file, restart_file, restart_interval, restart, snapshot, and snapshot_interval. namd(...) owns the electronic treatment: the initial state, scheme, continuity, and the surface-hopping controls. qmmm(...) owns the system partition and the MM model.

A control given in two places is rejected rather than resolved silently. For example, md(nstep=400) qmmm(n_steps=400) and md(dt=0.5) qmmm(timestep=0.5) are errors; keep nuclear propagation in md(...). Older inputs that place nstep, dt, and the other common controls inside namd(...), or n_steps and timestep inside qmmm(...) without md(...), are still read.

namd(...) tightens the SCF and response convergence to 1e-8 unless scf(conv=...) or tdhf(conv=...,zvconv=...) is given, because analytic coupling vectors require converged states.

Minimal Inputs

Ground-state gas-phase dynamics:

bhhlyp/6-31g* geom="molecule.xyz"
md(nstep=400,dt=0.5,velocity="molecule.vel",ensemble=nve)

Gas-phase ground-state MD evaluates the ground-state energy and analytic gradient at every geometry and propagates the nuclei with velocity Verlet. ensemble=nvt adds a Langevin thermostat at temperature with friction in ps⁻¹ (default 1.0). It currently requires a single MPI rank (--nompi) and writes no checkpoint; see Initial Conditions and Restart for its output files.

Recommended MRSF-TDDFT NAMD:

mrsf(nstate=4)/bhhlyp/6-31g* geom="molecule.xyz"
namd(S1,scheme=TDC_NAC,continuity=on)
md(nstep=400,dt=0.5,velocity="molecule.vel",ensemble=nve)

continuity=on is shown explicitly because it is part of the recommended method definition. It is also the default and may be omitted after the input has been established. The complete treatment is described in NAMD Numerical Continuity.

QM/MM NAMD:

mrsf(nstate=4)/bhhlyp/6-31g* geom="system.xyz"
namd(S1,scheme=TDC_NAC,continuity=on)
md(nstep=400,dt=0.5,velocity="system.vel",ensemble=nve)
qmmm(pdb_file="system.pdb",forcefield_files="forcefield.xml",
     qm_atoms="0-12")

TDC_NAC and NAC are available for QM/MM NAMD under the documented frozen-embedding-field QM-region NAC approximation and without link atoms. See NAC for its exact scope.

Choose One NAMD scheme

Every concise namd(...) input requires one complete surface-hopping scheme. The choice determines electronic-amplitude propagation, momentum-adjustment direction, hop-gap ceiling, and the treatment of a frustrated directional hop.

scheme	Electronic propagation	Successful-hop velocity adjustment	Hop-gap ceiling	Frustrated directional hop
BaeckAn	lagged time-dependent Baeck--An coupling	isotropic	10 kcal mol⁻¹	unchanged
Overlap	overlap NPI TDC	isotropic	10 kcal mol⁻¹	unchanged
TDC_NAC	overlap NPI TDC	analytic NAC for the selected hop	10 eV	reflect NAC-direction component
NAC	analytic NAC contracted with velocity	analytic NAC	10 eV	reflect NAC-direction component

TDC_NAC is the principal general setting: overlaps propagate the electronic amplitudes, while the analytic derivative-coupling vector is evaluated for a selected hop. NAC evaluates analytic couplings for electronic propagation as well. Full definitions and scheme=custom are on NAMD Coupling Schemes.

Essential Options

For a standard calculation, choose only the nuclear duration and initial conditions, the ensemble, one named NAMD scheme, and the continuity treatment. The defaults are suitable for a first input except for the system-dependent trajectory length and, when reproducibility is required, the initial velocity file or ensemble specification.

Keyword	Default	Meaning
nstep	100	Number of nuclear steps.
dt	0.5 fs	Nuclear timestep. Total time is nstep * dt.
velocity	maxwell	maxwell, zero, or a velocity-file path.
temperature	300.0 K	Maxwell--Boltzmann sampling temperature and NVT target.
ensemble	nve	Choose nve or nvt; npt is rejected (equilibrate the cell classically and start from a snapshot).
scheme	required by namd()	One of the four schemes above or custom.
continuity	on	Complete A--D numerical-continuity treatment; use manual only for individual controls.

Use a state label such as namd(S1,...) to select the initial electronic state. The lower-level active index is documented with the advanced controls. Random streams and detailed velocity preparation are on Initial Conditions and Restart; decoherence and electronic substeps are on NAMD Coupling Schemes; energy and coupling criteria are on NAMD Diagnostics.

Essential Definitions

nstep

Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.

Positive integer number of nuclear steps. The requested propagation time is nstep * dt; there is no separate total_time keyword.

dt

Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.

Positive nuclear timestep in femtoseconds. Establish nuclear-time-step convergence for the system and observable of interest.

continuity

Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.

on is the default and applies the complete A--D numerical-continuity treatment. Use manual only to reproduce or assess a specifically reported variation. The four numerical situations and every manual control are defined on NAMD Numerical Continuity.

Grouped Reference Pages

The remaining options are separated by scientific purpose:

Page	Contents
NAMD Coupling Schemes	scheme, tdc, rescale, thrshe, frustrated, Baeck--An controls, and optional trivial-crossing following
NAMD Numerical Continuity	Analytic-NAC cases A--D, continuity=on|manual, SCF/reference controls, retained-state criterion, substepping, and numerical energy correction
NAMD Diagnostics	NACME comparison and NVE energy criteria, including which error policies can terminate a run
Initial Conditions and Restart	velocity files and units, temperature, random streams, output files of each driver, NAMD and QM/MM MD checkpoint restart, QM/MM phase-space snapshots, and local continuation
Ensembles and experimental SOC-NAMD	NVE/NVT/NPT, OpenMM restrictions, adaptive timestep, SOC development status, basis, initialization, and force diagnostics
NAMD Advanced Controls	compact index of rarely changed settings and links to the detailed group pages

Underlying configuration correspondence

The concise input above is recommended. Legacy sectioned input places the same runtime settings in md; temperature and friction correspond to init_temp/thermostat_temperature and thermostat_friction where required by the legacy spelling. The scientific meaning and defaults are the same.

Legacy nacme_gate* and nve_gate* names are accepted as aliases for nacme_policy* and nve_policy*. New inputs should use policy. Do not specify both spellings for the same setting.

Python API

The Python API uses the same concise calls and keyword names as .oqp input. For reproducible trajectory ensembles, set seed and give each trajectory a different rng_stream. Restart files bind all trajectory-changing controls, including scheme, continuity, and the manual A--D settings.

Scientific references

Nonadiabatic Dynamics; Software libraries and data formats.