! AIS: 10 switching paths ! ! Generated by `md-openmm build-md`. Run it with: ! ! md-openmm md-run -i THIS_FILE -p V0.pdb -s V0.xml -p2 V1.pdb -s2 V1.xml ! ! AIS transforms V0 (-s/-p, the state the source ensemble was sampled from) into V1 (-s2/-p2): ! V(lambda) = (1 - lambda) V0 + lambda V1, lambda 0 -> 1 ! The two Systems hold the same particles and differ only in parameters. For a REST2 switch, V0 is ! the scaled state the hot run integrated and V1 is ../build/built.xml. ! ! `resolved.config` beside this file is AUTHORITATIVE: md-run resolves this input ! and writes the result there, and that resolved document is what the run reads. ! This file resolves to exactly that document -- editing it changes the run. ! ! WHAT A RUN WRITES. Every stage's `.out` opens with what it actually ran, read off the ! SERIALISED System rather than off this file -- a configuration asking for a 1.0 nm cutoff and a ! System carrying 0.8 nm are different runs, and only one of them integrates: ! ! System atoms, residues by name, net charge, degrees of freedom, box and volume ! Method nonbonded treatment and cutoff, Ewald tolerance, dispersion correction, ! switching, 1-4 exception count, constraints, barostat present, force inventory ! Selections the solute atom count, and which omega bonds are left unscaled ! ! The same facts go into the `.log` as structured fields, because prose is not a database. A box ! is reported only when the System is actually periodic: an OpenMM System defaults to a 2 nm cube, ! so an implicit run would otherwise print an invented box in the same voice as a measurement. ! ! `energy_components_.csv` carries the potential energy term by term, beside `mdout*.csv`. ! Where the System has usable force groups -- the implicit route, via ParmEd -- they are read ! directly. Where it does not, which is every explicit-solvent System built through ! `ForceField.createSystem`, a group-separated COPY is probed instead: `built.xml`, the run's own ! Context and every digest taken from them are untouched. `EELEC` from `VDWAALS`, and the 1-4 ! terms from either, are NOT reachable that way -- the 1-4 pairs are exceptions inside the single ! NonbondedForce -- so that split lives in post-hoc `md_tools.openmm.decomposition`. ! ! An rms fluctuation over a single report reads `n/a (single sample)`, not 0: over one sample ! sqrt( - ^2) is exactly zero, which reads as "this did not move" when it means "there was ! nothing to compare it against". ! ! AIS WRITES ITS OWN TABLES. `observations.csv` per path -- one row per observation, carrying the ! work of the switches since the previous one, measured at the frozen pre-switch coordinate -- ! aggregated into `AIS_work.csv`, `AIS_hs.csv` (the frame-aligned subset) and `AIS_cv.csv`, with ! `AIS_run.json` recording the run's identity and `AIS_traj.nc` one trajectory per global ! path. `system.csv` is the per-path state table. ! ! The work convention is a finite difference at frozen coordinates: ! dW_j = V(lambda_{j+1}, x_j) - V(lambda_j, x_j) = (lambda_{j+1} - lambda_j) (V1 - V0)(x_j) ! Because V is linear in lambda this is exactly Amber's Jarzynski increment (section 27.8, ! (dU/dlambda)*dlambda); the finite difference stays the definition so a future non-linear ! schedule cannot change what `work` means. &cntrl ! ! cMD is plain molecular dynamics. REST2 adds a replica-exchange ladder in which only the ! solute's Hamiltonian is scaled. AIS runs non-equilibrium switching paths from an EXISTING ! equilibrium source ensemble -- it has no minimisation or equilibration chain of its own, ! because its input is a trajectory you have already produced. ! one of: cMD, REST2, AIS, umbrella protocol = AIS, ! ! Must match the System `build-top` produced. Under implicit solvent there is no box and no ! barostat, so the pressure-coupled equilibration stages are replaced by honest NVT ! equivalents with different file names -- they are NOT NPT stages with the pressure quietly ! ignored. ! one of: explicit, implicit solvent = explicit, ! ! `auto` (the default) resolves the timestep from the masses serialised in built.xml when ! the run starts: 2.0 fs on ordinary hydrogens, 4.0 fs on repartitioned ones. `build-md` ! never opens built.xml, so it cannot know whether HMR was applied -- and a configuration ! CLAIMING it is not evidence. A number may be given instead: it is honoured up to 3.0 fs, ! and above that only if the System really was repartitioned. The resolved value and its ! basis are recorded in every log. ! unit: fs timestep_fs = auto, temperature_K = 300.0, ! ! Barostat pressure. Ignored -- and refused if a stage claims NPT -- under implicit solvent, ! which has no volume. ! unit: bar; minimum: 0.0 pressure_bar = 1.0, ! ! LangevinMiddleIntegrator collision rate. ! unit: 1/ps; minimum: 0.01 friction_per_ps = 1.0, ! ! MonteCarloBarostat volume-move attempt interval, in STEPS. It is the frequency, not the ! barostat's presence, that makes a stage NPT. ! unit: steps; minimum: 1 barostat_interval_steps = 25, restraint_kcal_per_mol_A2 = 1.0, ! ! Fixed REST2 scaling for a cMD run. 0.0 (the default) is the unmodified physical ! Hamiltonian. A non-zero value runs cMD at ONE rung of the REST2 ladder -- the same scaling ! the ladder applies, held fixed -- which is how a hot ensemble is produced without running ! an exchange. A scaled run is NVT by construction: it must sample the top rung's ! fixed-volume ensemble, so a barostat would sample the wrong distribution and is refused. ! minimum: 0.0 tau = 0.0, ! ! Write a phase-space stream (positions, VELOCITIES and box) every N steps. 0 disables it. A ! complete sample needs velocities, which a trajectory does not carry. ! unit: steps; minimum: 0 phase_space_printout = 0, ! ! Minimiser ITERATIONS, not a time interval: minimisation does not integrate and has no ! timestep. 0 skips minimisation. ! minimum: 0 minimization_iterations = 1000, ! ! Restrained NVT heating/settling. 5000 steps = 10 ps at 2 fs. ! unit: steps; minimum: 0 restrained_nvt_steps = 5000, ! ! Restrained NPT density equilibration. 5000 steps = 10 ps at 2 fs. Under implicit solvent ! this becomes a second restrained NVT stage instead. ! unit: steps; minimum: 0 restrained_npt_steps = 5000, ! ! Unrestrained NPT, the last stage before production. 5000 steps = 10 ps at 2 fs. Under ! implicit solvent this becomes unrestrained NVT. ! unit: steps; minimum: 0 unrestrained_npt_steps = 5000, ! ! Production length -- for AIS, the length of the `source` stage when ais_source.generate ! is true, and unused otherwise. 2,500,000 steps = 5 ns at 2 fs. This is the authoritative number; the ! log prints the derived ps and ns beside it. ! unit: steps; minimum: 0 production_steps = 2500000, ! ! How many SEGMENTS the production run is written as. 1 is a single `prod1` segment. ! It SPLITS the production total rather than multiplying it: each segment gets ! `production_steps / number_of_segments`, and a value that does not divide exactly is ! refused. On a REST2/rREST2 ladder the split is of `number_of_exchanges`, so an exchange ! never straddles a boundary. Each segment writes its own files, so segments cannot ! overwrite one another. ! minimum: 1 number_of_segments = 1, ! ! Trajectory output interval. 1000 steps = 2 ps at 2 fs. ! unit: steps; minimum: 0 crd_printout_solute = 500, ! ! COORDINATE output interval for the WHOLE system, in steps, written to `whole_prod.nc` ! (or `whole_rep_prod.nc` per replica on a ladder). ! 0, the default, writes no whole-system trajectory. Say what you want kept: on a solvated ! system the whole stream is two orders of magnitude larger than the solute one -- 1796 ! atoms against 22 for alanine dipeptide in water -- so an unasked-for whole-system ! trajectory at a solute cadence is how a 26 MB run becomes 2.1 GB. ! Distinct from `crd_printout_solute`, which is the solute alone, and from `info_printout`, ! which is scalars and no coordinates at all. Those three were previously two, and the two ! were named for what a reader assumed rather than for what they wrote. ! unit: steps; minimum: 0 crd_printout_whole = 0, ! ! Scalar state (energy, temperature, volume, density) interval, written to a CSV beside the ! log. ! unit: steps; minimum: 0 info_printout = 500, ! ! Checkpoint interval. A checkpoint is what an interrupted stage resumes from, and it is ! written with a fingerprint of the configuration that produced it so it cannot be resumed ! under different settings. ! unit: steps; minimum: 0 checkpoint_printout = 500, ! ! Steps between collective-variable observations. Independent of the trajectory and state- ! data intervals, and may be more frequent than either. 0 disables collective-variable ! reporting. ! unit: steps; minimum: 0 cv_interval_steps = 0, / &AIS ! ! How many independent switching paths to run. Each gets its own directory, its own ! trajectory, and its own deterministic seeds. ! minimum: 1 number_of_paths = 10, ! ! The length of the switching path, as an exact step count. 50000 steps is 100 ps at 2 fs. ! WORK IS PATH-LENGTH DEPENDENT: a faster switch does more dissipative work, so this is a ! scientific choice and not a performance knob. The log states the derived ps. ! unit: steps; minimum: 1 switching_steps = 5000, ! ! How often a path is observed: one coordinate frame and one work row. switching_steps must ! divide by this exactly, so the last observation lands at lambda = 1. 50000/2500 gives 20 ! intervals and therefore 21 observations, counting both endpoints. AN OBSERVATION IS NOT A ! STEP. ! unit: steps; minimum: 1 observation_interval_steps = 500, ! ! How often lambda moves. 1 changes the Hamiltonian every step -- 50000 parameter changes over ! the path above. observation_interval_steps must divide by this, or observations would not ! sit on the update grid. ! unit: steps; minimum: 1 parameter_update_interval_steps = 1, ! ! How lambda follows the switching progress t. linear: lambda = t. tau-linear: lambda = ! [(1 - tau0 + tau0 t)^2 - (1 - tau0)^2] / [1 - (1 - tau0)^2], for V0 a saved REST2 state at ! tau0 and V1 its unscaled source; it also needs lambda_schedule_tau0. ! one of: linear, tau-linear lambda_schedule = linear, ! ! First eligible frame, INCLUSIVE, as a 0-based index into the trajectory file. A frame ! index, never a time: the two are interchangeable only when the frame interval is known, ! and it is not always. Use this to discard equilibration. ! minimum: 0 source_frame_start = 0, ! ! Take every Nth frame of the window as eligible. Consecutive frames of an MD trajectory are ! correlated, so drawing paths from every frame draws several of them from what is ! effectively one configuration. A stride is the honest way to say how far apart samples ! have to be; it does not make them independent, it stops them being obviously dependent. ! minimum: 1 source_frame_stride = 1, ! ! How starting frames are drawn from the eligible window. uniform_random draws with the ! run's seed; evenly_spaced takes them at a fixed stride. ! one of: uniform_random, evenly_spaced source_frame_selection = uniform_random, ! ! Whether two paths may start from the SAME frame. False by default: two paths from one ! configuration are not two independent realisations, and treating them as such understates ! the spread of the work distribution. allow_repeated_frames = false, ! ! REQUIRED for AIS. The equilibrium trajectory the paths start from, sampled from V0 -- ! typically a fixed-tau cMD run whose System is the -s given to AIS. A trajectory that records ! its System digest is checked against -s. Resolved relative to the directory run.sh is ! invoked from. source_traj = ../hot/whole_prod1.nc, ! ! true: this run PRODUCES its source ensemble -- minimisation of the unscaled built System, ! the equilibration stages and a `source` production stage on V0 -- and source_traj is that ! stage's whole_prod1.nc. false: source_traj names an ensemble that already exists. source_generate = false, /