Project file keys
The project file: every key, its default, and the folder layout of a job.
A project file describes a whole job: the input structure, the preparation choices, the force
field, the box, the protocol, the replicas, the analyses and the export. Run MD and the Batch queue
write one into every job folder (project.json, rewritten at every start), and
mdsim pipeline -config project.json repeats the job from it exactly. Writing a project
file by hand gives access to the few settings that the pages do not show, such as 1 fs time steps,
segment removal or per-residue MM-GBSA.
Rules
- The file is JSON with
"schema": "mdsim-pipeline/1". Comments in // and /* */ form are accepted.
- Only
inputs.complex is required; every other key has a default. mdsim pipeline -template prints them all.
- Parsing is strict: an unknown key, a wrong type or a value out of range is an error that names the key. A misspelt key therefore never goes unnoticed.
- Keys beginning with
_ or comment are notes and are ignored.
- Relative paths are relative to the folder of the project file.
- Run
mdsim pipeline -config project.json -dry-run after every edit: it checks everything and writes nothing.
These cross-checks are made before anything runs:
- every duration must be a whole number of time steps;
- the analysis window must lie inside the production run;
analysis.stride_ps must be a multiple of protocol.output.xtc_ps;
- a membrane needs the
amber14sb force field;
- replica seeds must differ.
The job folder
A job runs in its work folder, workdir (default <project folder>\<name>;
jobs of the application use run inside the job folder):
| Folder | Content |
01_structure\ | The repaired structure and the ligand split from it; a converted copy of an mmCIF or PDBQT input |
02_ligand\ | GAFF2 atom types and AM1-BCC charges of the ligand |
03_topology\ | Protein topology and the assembled complex |
04_system\ | Box, water, ions or membrane; system.gro, system.top, index.ndx |
05_mdp\ | Run parameters of minimisation, equilibration and production |
06_run\em\, 06_run\rep<i>\ | Minimisation (shared by all replicas), then NVT, NPT and production of each replica |
07_analysis\rep<i>\ | Trajectory and interaction analyses of each replica, with detail\ |
08_summary\ | Statistics over the replicas, MM-GBSA, merged interactions, detail\ |
09_results\ | The results package <name>_results and export.log |
Next to them: pipeline.log, project.resolved.json (every default spelled out)
and report.json. The first two folders are left out when their result is supplied (a
prepared receptor or ready ligand parameters).
Keys by group
Top level and inputs
| Key | Default | Meaning, and when to change it |
schema | (required) | Must be "mdsim-pipeline/1". |
name | "my_project" | Name of the job; also the default work folder and package name. Keep it short and file-system friendly. |
workdir | <name> | Output folder of the job. |
inputs.complex | "complex.pdb" | The protein with the docked ligand (.pdb, .cif, .pdbqt). |
inputs.ligand_resname | "" | The ligand residue of the complex. Empty: the only residue that is not protein, water or an ion. Set it when the complex holds several. |
inputs.ligand_chain, inputs.ligand_resnr | not set | Choose one copy when the ligand residue occurs several times. |
inputs.ligand_pose | not set | Choose one pose of a ligand file with several poses. |
inputs.ligand_file | "" | A separate ligand file (.sdf, .mol, .mol2, .pdb, .pdbqt), 3D, in the receptor frame; used instead of the ligand of the complex. |
inputs.ligand_topology | not set | Ready ligand parameters (itp, atomtypes, gro, posre); skips the ligand stage and the contact check. |
inputs.receptor_conf, inputs.receptor_top | not set | A prepared receptor; skips structure repair and protein topology. |
inputs.apo | false | true: simulate the protein alone; ligand residues of the input are ignored. |
system (report information and the membrane decision)
| Key | Default | Meaning, and when to change it |
system.label, ligand_name, pdb_id, construct | "" | Names printed in the report. Fill them in for a readable report. |
system.reference_sequence, reference_sequence_start | not set | Reference numbering information for the report. |
system.membrane_protein | not set | Not set: the structure stage decides from the sequence (two or more transmembrane segments without a membrane stop the job). true: a membrane protein (needs membrane.type). false: simulate it without a membrane on purpose; needs the justification. |
system.membrane_justification | "" | Why a protein that looks like a membrane protein is simulated in water. Stated in the log and the report. |
structure (preparation)
| Key | Default | Meaning, and when to change it |
structure.gaps | "model" | model: gaps of up to max_model_gap residues with a known sequence are modelled, other breaks get neutral ACE/NME caps. caps: nothing modelled, caps at every break. charged: charged ends at breaks (an artificial ion pair; not recommended). |
structure.max_model_gap | 8 | Longest gap that is modelled (1 to 12). Longer loops are poorly predicted; see Accuracy. |
structure.sequence_fasta, structure.sequence | "" | The full protein sequence (FASTA file, or one-letter codes), for inputs without sequence records, such as docking exports. |
structure.terminal_caps | false | ACE/NME caps also at the real chain ends. Use it when the construct is a fragment of a longer protein. |
structure.keep_protonation | false | Keep the protonation states implied by the hydrogens of the input instead of assigning states at the pH. |
structure.residue_states | [] | Explicit states, for example ["A:32=ASH", "A:107=HIP"]. They win over the pH. |
structure.keep_water | false | Keep crystal waters of the input. |
structure.keep_ions | true | Keep monatomic ions of the input. |
structure.remove_residues | [] | Residues not simulated on purpose: names, "A:301", "A:HEM", or "all-unsupported". Without it, a cofactor, glycan or unknown molecule stops the job, because removing it changes the system. |
structure.remove_nucleic_acids | false | true: simulate the protein without its DNA or RNA. |
structure.remove_segments | [] | Protein segments removed before repair, for example ["A:1001-1161"] for a fusion insert; both ends are capped, and the gap is modelled only from sequence_fasta or sequence. |
structure.revert_modifications | false | true: crystallisation artefacts (MLY, CSO, CSD, OCS, CSX, CME, KCX) become the parent amino acid. A list such as ["SEP"] reverts the named residues. |
structure.caps | false | Key of earlier versions, still accepted. |
force_field and protonation
| Key | Default | Meaning, and when to change it |
force_field.protein | "amber14sb" | Protein force field (AMBER ff14SB). |
force_field.water | "tip3p" | Water model. |
force_field.ligand | "gaff2" | Ligand force field; only GAFF2. |
force_field.charge_method | "bcc" | AM1-BCC (bcc); gas or input (the charges of a MOL2 file) for special cases. |
force_field.ligand_charge | "auto" | Net charge of the ligand: auto (from the protonation rules) or an integer. |
force_field.ligand_resname | "LIG" | Residue and group name of the ligand (1 to 4 characters). |
force_field.ligand_protonation | "auto" | Protonation of the ligand at the pH; keep keeps the state of the input. |
force_field.ph | 7.4 | The pH for the ligand and the protein residues. |
box, ions and membrane
| Key | Default | Meaning, and when to change it |
box.type | "dodecahedron" | Box shape: dodecahedron (least water), cubic, octahedron, triclinic. |
box.distance_nm | 1.0 | Smallest distance between the solute and the box faces. Raise it for a flexible or elongated protein. |
ions.concentration_M | 0.15 | Salt added after neutralisation, mol/L. |
ions.neutral | true | Neutralise the system. |
ions.positive, ions.negative | "NA", "CL" | Ion names. |
ions.seed | 1993 | Seed for the placement of the ions. |
membrane.type | "none" | popc_chol_7_3 (POPC:cholesterol 7:3, Lipid21), popc128 (pure POPC), or the path of a bilayer patch .gro. |
membrane.orient | "" | Orientation: from the reference when given, else a hydrophobic-slab fit; ref, auto, none. |
membrane.reference, reference_chain | not set | An oriented reference structure of the protein (membrane normal along z). Strongly recommended. |
membrane.ion_files, reference_ions | [], true | Structural ions to transfer into the system. |
membrane.margin_nm, water_layer_nm, z_pad_nm, flip | 1.5, 2.0, 1.5, false | Lateral lipid margin, water beyond the head groups, water beyond the protein, and turning the protein upside down. |
membrane.equilibration_scale | 1.0 | Factor on the length of the six equilibration stages; for functional tests only. |
protocol
| Key | Default | Meaning, and when to change it |
protocol.temperature_K | 310 | Temperature of the thermostat. |
protocol.pressure_bar | 1.0 | Pressure of the barostat. |
protocol.dt_fs | 2 | 2 fs with standard hydrogen masses. 4: hydrogen-mass repartitioning and two LINCS iterations in every MD stage. 1: soluble systems only. |
protocol.em_tolerance, em_max_steps | 1000, 50000 | Minimisation stops when the largest force is below the tolerance (kJ/mol/nm) or after the steps. |
protocol.nvt_ps, npt_ps | 100, 100 | Restrained equilibration (soluble systems). |
protocol.production_ns | 100 | Production length per replica. Changing it later reruns the production from the equilibrated state. |
protocol.posres_fc | 1000 | Heavy-atom restraints during equilibration, kJ/mol/nm2. |
protocol.cutoff_nm | 1.0 | Coulomb and van der Waals cut-off. |
protocol.tau_t_ps, tau_p_ps | 0.1, 2.0 | Coupling times of thermostat and barostat (soluble systems). |
protocol.constraints | "h-bonds" | Bonds to hydrogen constrained; all-bonds is accepted. |
protocol.gen_seed | 20261005 | Velocity seed of replica 1; replica i uses gen_seed + i - 1. Jobs of the application get their own seed. |
protocol.mts_factor | 1 | 2: multiple time stepping in production (long-range forces every second step). |
protocol.output.xtc_ps, energy_ps, log_ps | 10, 10, 10 | Intervals of frames, energies and log entries. 10 ps gives 10,001 frames per 100 ns. |
protocol.output.trr_ps | 0 | Full-precision frames; 0 writes the final state only. |
replicas and engine
| Key | Default | Meaning, and when to change it |
replicas.count | 3 | Independent replicas with different velocity seeds. Three or more give standard deviations between independent runs. (Run MD uses 1 unless you choose more.) |
replicas.seeds | not set | Explicit seeds, one per replica, pairwise different. |
replicas.concurrent | 1 | Replicas run side by side: N, or 0 for automatic. |
engine.backend | "auto" | auto uses the GPU when one is usable; gpu makes a missing GPU an error; cpu forces the CPU engine. |
engine.threads | 0 | Threads of the CPU engine and of the analyses; 0 = default. |
engine.gpu_id | -1 | -1 = automatic; N = that device. |
engine.checkpoint_minutes | 5 | At most this much simulation is lost when the PC fails during an MD stage. |
engine.pin | false | Pin CPU threads to cores. |
engine.max_hours | -1 | Stop cleanly after this wall time (exit code 2); run again to continue. |
Engine settings are not part of the stage fingerprints: a job can be continued with another thread count, another GPU or after a driver update.
analysis and mmgbsa
| Key | Default | Meaning, and when to change it |
analysis.start_ns, end_ns | 0, -1 | Analysis window. Setting start_ns also sets the start of the statistics window; otherwise the statistics leave out the first 10 % of production. |
analysis.stride_ps | 0 | Analyse every n ps; 0 = every frame. |
analysis.receptor_group | "Protein" | Index group of the receptor. |
analysis.sasa, hbond, contacts, dsasa, energy, interactions | true | Switch single analyses off. |
analysis.interaction_threshold | 0.30 | Occupancy an interaction needs to be drawn in the interaction diagram. |
mmgbsa.enabled | true | MM-GBSA for complexes. |
mmgbsa.igb, radii | 5, "auto" | GB model (5 = OBC2) and radius set (auto = mbondi2 for OBC2). |
mmgbsa.saltcon_M | 0.15 | Salt concentration of the GB model. |
mmgbsa.start_ns, end_ns | -1, -1 | MM-GBSA window; -1 = the analysis window. |
mmgbsa.interval_ps, frames | 0, 1000 | About 1000 evenly spaced frames per replica by default; or a fixed interval; frames: 0 uses every frame. |
mmgbsa.decomposition | false | Per-residue decomposition, written to 08_summary\mmgbsa\decomp.csv. |
mmgbsa.interaction_entropy | false | Interaction-entropy estimate (not validated against another implementation). |
export
| Key | Default | Meaning, and when to change it |
export.enabled | true | Write the results package as the last stage. |
export.title | "" | Report title; empty = "Molecular dynamics results". |
export.length_unit, energy_unit | "nm", "kcal/mol" | Units of the package: nm or angstrom; kcal/mol or kJ/mol. |
export.dpi, png600 | 300, false | PNG resolution; additional 600 dpi copies. |
export.logo | "" | Logo image for the report; empty = the company logo of the program. |
export.acknowledged | [] | Accepted blocking findings: [{"rule": "...", "justification": "..."}]. The justification is printed in the report. |
A report section written by versions before the PDF report is still read: its title,
unit, resolution and acknowledgements are taken over, and its other keys are ignored.
Resuming and re-running stages
Every stage writes a marker file as its last action. The marker records a fingerprint of the
settings the stage depends on, of its input files and of the stages before it. On the next run each
stage is in one of four states:
| State | Condition | What happens |
| done | Marker present, fingerprint unchanged, outputs complete | Skipped. |
| stale | Settings or inputs changed, an output is missing, or an earlier stage reruns | Its files are removed and it runs again, and so does everything after it. |
| partial | An MD stage that was interrupted, with a checkpoint of the current settings | Continues from the checkpoint, bit for bit, and appends to its files. |
| pending | Not run yet | Runs. |
- A power cut between stages loses nothing; inside an MD stage it loses at most
engine.checkpoint_minutes. Minimisation has no checkpoint and starts again.
- A changed production length reruns only the production and what follows; a changed salt concentration reruns everything from the
system stage on.
- A finished production cannot be extended; a longer
production_ns reruns the production from the equilibrated state.
-status shows the states; -invalidate <stage> forces a stage and everything after it to run again.
- A job started with version 1.0.0 and not yet finished may repeat stages when continued with this version, because the program version is part of the stage inputs.
Example
A project for one complex, with three replicas run side by side, a sequence file for the missing
residues, the statistics window starting at 10 ns and the package in angstrom. Every key that is not
written keeps its default.
{
"schema": "mdsim-pipeline/1",
"name": "m3_dicyclomine",
"inputs": { "complex": "m3_dicyclomine.pdb", "ligand_resname": "LIG" },
"system": { "label": "M3 receptor with dicyclomine", "pdb_id": "4DAJ" },
"structure": { "gaps": "model", "sequence_fasta": "4DAJ.fasta" },
"protocol": { "production_ns": 100, "dt_fs": 2 },
"replicas": { "count": 3, "concurrent": 0 },
"analysis": { "start_ns": 10 },
"export": { "length_unit": "angstrom", "energy_unit": "kcal/mol" }
}
This receptor is a membrane protein, so the structure stage stops the job until a membrane
is chosen ("membrane": {"type": "popc_chol_7_3"}) or the decision to simulate in water is
declared with system.membrane_protein: false and a justification. The example shows the
keys; it is not a recommended set-up for a membrane receptor.