Geinium
Home › Project file keys

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

These cross-checks are made before anything runs:

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):

FolderContent
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

KeyDefaultMeaning, 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_resnrnot setChoose one copy when the ligand residue occurs several times.
inputs.ligand_posenot setChoose 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_topologynot setReady ligand parameters (itp, atomtypes, gro, posre); skips the ligand stage and the contact check.
inputs.receptor_conf, inputs.receptor_topnot setA prepared receptor; skips structure repair and protein topology.
inputs.apofalsetrue: simulate the protein alone; ligand residues of the input are ignored.

system (report information and the membrane decision)

KeyDefaultMeaning, 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_startnot setReference numbering information for the report.
system.membrane_proteinnot setNot 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)

KeyDefaultMeaning, 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_gap8Longest 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_capsfalseACE/NME caps also at the real chain ends. Use it when the construct is a fragment of a longer protein.
structure.keep_protonationfalseKeep 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_waterfalseKeep crystal waters of the input.
structure.keep_ionstrueKeep 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_acidsfalsetrue: 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_modificationsfalsetrue: crystallisation artefacts (MLY, CSO, CSD, OCS, CSX, CME, KCX) become the parent amino acid. A list such as ["SEP"] reverts the named residues.
structure.capsfalseKey of earlier versions, still accepted.

force_field and protonation

KeyDefaultMeaning, 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.ph7.4The pH for the ligand and the protein residues.

box, ions and membrane

KeyDefaultMeaning, and when to change it
box.type"dodecahedron"Box shape: dodecahedron (least water), cubic, octahedron, triclinic.
box.distance_nm1.0Smallest distance between the solute and the box faces. Raise it for a flexible or elongated protein.
ions.concentration_M0.15Salt added after neutralisation, mol/L.
ions.neutraltrueNeutralise the system.
ions.positive, ions.negative"NA", "CL"Ion names.
ions.seed1993Seed 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_chainnot setAn oriented reference structure of the protein (membrane normal along z). Strongly recommended.
membrane.ion_files, reference_ions[], trueStructural ions to transfer into the system.
membrane.margin_nm, water_layer_nm, z_pad_nm, flip1.5, 2.0, 1.5, falseLateral lipid margin, water beyond the head groups, water beyond the protein, and turning the protein upside down.
membrane.equilibration_scale1.0Factor on the length of the six equilibration stages; for functional tests only.

protocol

KeyDefaultMeaning, and when to change it
protocol.temperature_K310Temperature of the thermostat.
protocol.pressure_bar1.0Pressure of the barostat.
protocol.dt_fs22 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_steps1000, 50000Minimisation stops when the largest force is below the tolerance (kJ/mol/nm) or after the steps.
protocol.nvt_ps, npt_ps100, 100Restrained equilibration (soluble systems).
protocol.production_ns100Production length per replica. Changing it later reruns the production from the equilibrated state.
protocol.posres_fc1000Heavy-atom restraints during equilibration, kJ/mol/nm2.
protocol.cutoff_nm1.0Coulomb and van der Waals cut-off.
protocol.tau_t_ps, tau_p_ps0.1, 2.0Coupling times of thermostat and barostat (soluble systems).
protocol.constraints"h-bonds"Bonds to hydrogen constrained; all-bonds is accepted.
protocol.gen_seed20261005Velocity seed of replica 1; replica i uses gen_seed + i - 1. Jobs of the application get their own seed.
protocol.mts_factor12: multiple time stepping in production (long-range forces every second step).
protocol.output.xtc_ps, energy_ps, log_ps10, 10, 10Intervals of frames, energies and log entries. 10 ps gives 10,001 frames per 100 ns.
protocol.output.trr_ps0Full-precision frames; 0 writes the final state only.

replicas and engine

KeyDefaultMeaning, and when to change it
replicas.count3Independent replicas with different velocity seeds. Three or more give standard deviations between independent runs. (Run MD uses 1 unless you choose more.)
replicas.seedsnot setExplicit seeds, one per replica, pairwise different.
replicas.concurrent1Replicas 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.threads0Threads of the CPU engine and of the analyses; 0 = default.
engine.gpu_id-1-1 = automatic; N = that device.
engine.checkpoint_minutes5At most this much simulation is lost when the PC fails during an MD stage.
engine.pinfalsePin CPU threads to cores.
engine.max_hours-1Stop 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

KeyDefaultMeaning, and when to change it
analysis.start_ns, end_ns0, -1Analysis window. Setting start_ns also sets the start of the statistics window; otherwise the statistics leave out the first 10 % of production.
analysis.stride_ps0Analyse every n ps; 0 = every frame.
analysis.receptor_group"Protein"Index group of the receptor.
analysis.sasa, hbond, contacts, dsasa, energy, interactionstrueSwitch single analyses off.
analysis.interaction_threshold0.30Occupancy an interaction needs to be drawn in the interaction diagram.
mmgbsa.enabledtrueMM-GBSA for complexes.
mmgbsa.igb, radii5, "auto"GB model (5 = OBC2) and radius set (auto = mbondi2 for OBC2).
mmgbsa.saltcon_M0.15Salt concentration of the GB model.
mmgbsa.start_ns, end_ns-1, -1MM-GBSA window; -1 = the analysis window.
mmgbsa.interval_ps, frames0, 1000About 1000 evenly spaced frames per replica by default; or a fixed interval; frames: 0 uses every frame.
mmgbsa.decompositionfalsePer-residue decomposition, written to 08_summary\mmgbsa\decomp.csv.
mmgbsa.interaction_entropyfalseInteraction-entropy estimate (not validated against another implementation).

export

KeyDefaultMeaning, and when to change it
export.enabledtrueWrite 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, png600300, falsePNG 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:

StateConditionWhat happens
doneMarker present, fingerprint unchanged, outputs completeSkipped.
staleSettings or inputs changed, an output is missing, or an earlier stage rerunsIts files are removed and it runs again, and so does everything after it.
partialAn MD stage that was interrupted, with a checkpoint of the current settingsContinues from the checkpoint, bit for bit, and appends to its files.
pendingNot run yetRuns.

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.