The command line
mdsim, the command-line program: the complete pipeline, the results export, and the individual tools.
mdsim.exe is the command-line program of Geinium. It contains the same engine,
preparation, analyses and export as the desktop application, and a job made in the application can
be repeated with it exactly. Use it for scripts, for long series of jobs, for a PC without a screen
session, and for the individual tools that the application does not expose one by one.
Running mdsim
mdsim.exe is in the bin folder of the installation, next to
Geinium.exe. Open a Command Prompt there, or add the folder to the PATH
variable of Windows so that mdsim works in any folder. Every call has the form
mdsim <command> [options].
mdsim help list of all commands
mdsim pipeline -h options of one command, with their defaults
mdsim pipeline -template a project file with every key and its default
Options are written with a single hyphen. A switch shown as -[no]report is turned on
with -report and off with -noreport. File options take one path; list options
take several values separated by blanks (or commas where the help says so). Times are in ps unless a
command offers -tu to change the unit. Paths may contain blanks if they are quoted.
The complete pipeline
mdsim pipeline runs a whole job from a project file: structure preparation, ligand
parameters, topology, box, water and ions (or the membrane), minimisation, equilibration, replicated
production, the analyses, MM-GBSA and the results package. It is the same pipeline the Run MD and
Batch pages run; every job folder they create contains the project.json that reproduces
it. The keys are described in Project file keys.
rem write a project file with every key and its default, then edit "inputs.complex"
mdsim pipeline -template > project.json
rem check the project and see what would run, without writing anything
mdsim pipeline -config project.json -dry-run
rem run the job; run the same command again after an interruption to continue it
mdsim pipeline -config project.json
rem the state of every stage
mdsim pipeline -config project.json -status
rem run only the preparation stages, for example to inspect the prepared system first
mdsim pipeline -config project.json -stage prep
rem forget a stage and everything after it (here the production run of replica 2), then run again
mdsim pipeline -config project.json -invalidate rep2/md
mdsim pipeline -config project.json
| Option | Default | What it does, and when to use it |
|---|---|---|
-config | project.json | The project file. |
-stage | all | Runs every stage up to and including this group that is not done yet: prep, equil, prod, analysis, report or all. Use prep to check the system before committing GPU time. |
-dry-run | off | Validates the project, checks that the input files exist and prints the inputs, the protocol, the run parameters and the action of every stage (RUN, REDO, CONTINUE or skip). Writes nothing. Run it after every edit of a project file. |
-status | off | Prints the state of every stage (pending, done, stale, partial) with the result line of finished stages. |
-template | off | Prints a project file with every key and its default. |
-invalidate <stage> | Forgets a stage and everything downstream of it, for example system or rep2/md. | |
-replica | -1 | For one process per replica: 0 runs only the stages shared by all replicas, i only the stages of replica i. |
-[no]v | on | Stage messages and the MD progress line. |
To run the replicas of one job as separate processes, for example on two GPUs, run the shared
stages first, then one process per replica, then a final call without -replica that adds
the summary and the results package:
mdsim pipeline -config project.json -stage equil -replica 0
start mdsim pipeline -config project.json -stage analysis -replica 1
start mdsim pipeline -config project.json -stage analysis -replica 2
rem when both have finished:
mdsim pipeline -config project.json
Ctrl+C asks for a clean stop: a running MD stage writes a checkpoint at its next pair-search step and the program ends with exit code 2. A second Ctrl+C ends it at once; the job can still be continued from its last periodic checkpoint.
The results package
mdsim export -job P:\Geinium\Jobs\m3_dicyclomine -o P:\Geinium\Export
mdsim export -job P:\Geinium\Jobs -o P:\Geinium\Export -name series
mdsim export -job P:\Geinium\Jobs\m3_dicyclomine -units angstrom -energy kJ/mol -dpi 600
mdsim export -job P:\Geinium\Jobs\m3_dicyclomine -list
| Option | Default | What it does |
|---|---|---|
-job | One or more job folders, work folders, or folders whose sub-folders are jobs. Several jobs give one combined package. | |
-o, -name, -title | ., job name, "Molecular dynamics results" | Where the package <name>_results is written, its name, and the title of the report. |
-units, -energy | nm, kcal/mol | Length unit (nm or angstrom) and energy unit (kcal/mol or kJ/mol) of the whole package. |
-dpi, -png600, -[no]vector | 300, off, on | PNG resolution (300 or 600), additional 600 dpi copies in images\600dpi, and the SVG and PDF files. |
-width | natural | One width for all figures: single, onehalf, double (85, 114, 174 mm). |
-figures, -list | all | Figure ids to include; -list prints the catalogue and the state of each figure. An unknown id is an error. |
-[no]report, -[no]images, -[no]raw | on | The three parts of the package. |
-[no]compute, -[no]recompute | on, off | Run missing detail analyses first; recompute the analyses of a job made by an older version (the MD is never repeated). Without -recompute such a job is refused. |
-threshold | the job's own | Occupancy (0 to 1) an interaction needs to be drawn in the interaction diagram. |
-ack rule=justification | Accepts a blocking finding with a written reason, printed in the report. | |
-checks, -log, -checks-file | Only run the scientific checks; write the export log to a file; add the findings as checks.txt to the package. | |
-analyses, -force | Only run the detail analyses (no package); with -force even when they are up to date. | |
-logo, -nologo | company logo | Another logo image (PNG, JPG, SVG), or none. |
-compound-reports, -text | An additional report per compound of a combined package; the report text in reading order. | |
-timestamp | A fixed creation time (ISO 8601) that makes two exports byte-identical. |
The package itself is described in Exporting results.
Commands by group
The individual tools read and write the common text and binary formats of biomolecular
simulation (File formats). Most analysis tools take a run input or a
structure with -s, a trajectory with -f, an index file with -n,
an output with -o, and a time window with -b, -e, -dt
and -tu. Where a tool needs index groups and none is given on the command line, it asks
for them on the console.
Preparation
| Command | What it does |
|---|---|
pdbfix | Repairs a protein or complex: missing side-chain atoms, alternate conformers, non-standard names, optional modelling of short gaps (-modelgaps, -maxgap, -seqfasta, -seq), caps, structure checks (transmembrane segments, fusion partners, buried charges), reverting crystallisation artefacts, removing residues. Writes the repaired protein and the ligand separately, with a report. |
pdb2gmx | Builds the protein topology and coordinates from a repaired structure with a force field of the data library; protonation states can be set residue by residue. |
editconf | Defines the periodic box (type and solute distance), centres, translates, rotates, converts between .gro and .pdb. |
solvate | Fills the box with water and updates the topology. |
genion | Replaces water molecules by ions to neutralise the system and set a salt concentration (-neutral, -conc), at least -rmin from the solute. |
insert-molecules | Inserts copies of a molecule into a box or into free space. |
make_ndx | Creates an index file with the standard groups and groups of your own. |
membrane | Embeds a membrane protein into a pre-equilibrated Lipid21 bilayer (POPC:cholesterol 7:3 or POPC), orients it from a reference structure or by a hydrophobic-slab fit, adds water and ions, and writes the staged equilibration parameters. |
assemble | Combines the receptor and the ligand coordinates and topologies into one system. |
ligparam | Gives a ligand GAFF2 atom types and AM1-BCC charges, with protonation at a pH (-ph, -protonation), pose choice (-pose) and the perception report alone (-perceive). Writes the ligand topology, coordinates and a JSON report. It can also convert parameter files made elsewhere. |
Run
| Command | What it does |
|---|---|
grompp | Processes run parameters (.mdp), coordinates and topology into a run input file (.mdtpr). -t continues exactly from the final state of a previous stage. |
mdrun | Runs minimisation or MD on the GPU engine or the CPU engine (-nb auto|cpu|gpu). -deffnm names all output files at once, -cpi continues from a checkpoint, -cpt sets the checkpoint interval (5 min), -maxh stops cleanly after a wall time, -multidir with -concurrent runs several simulations side by side on one GPU. |
pipeline | The complete protocol from a project file (see above). |
mdsim grompp -f md.mdp -c npt.gro -t npt_final.trr -r em.gro -p topol.top -n index.ndx -o md.mdtpr
mdsim mdrun -s md.mdtpr -deffnm md -v
mdsim mdrun -s md.mdtpr -deffnm md -cpi md.cpt -v continue after an interruption
Analysis
| Command | What it does |
|---|---|
energy | Extracts terms of an energy file to .xvg, with average, error estimate, RMSD and drift. |
rms | RMSD after a least-squares fit (-fitgroup, -group). |
rmsf | Fluctuation per atom or per residue. |
gyrate | Radius of gyration. |
sasa | Solvent-accessible surface area. |
hbond | Hydrogen bonds between groups (0.35 nm, 30 degrees). |
distance, mindist | Distances between positions; minimum distance and contacts between groups. |
trjconv | Converts and trims trajectories, makes molecules whole, centres, fits. |
covar | Covariance analysis and principal components. |
cluster | Clusters structures on their pairwise RMSD. |
dssp | Secondary structure per frame by the DSSP method. |
contacts | Receptor-ligand contacts per residue: hydrogen bonds with occupancy, hydrophobic, ionic, water bridges. |
dsasa | Buried surface area per frame: SASA of receptor plus ligand minus complex. |
interactions | Protein-ligand interactions with occupancy: hydrogen bonds, water and salt bridges, pi stacking, pi-cation, halogen bonds, metal coordination, hydrophobic contacts, solvent exposure. The criteria can be changed with options (see Protein-ligand interactions). |
mmgbsa | MM-GBSA binding energy over a trajectory with the force field of the MD (single trajectory, GB-OBC2 by default). Note that the default salt concentration of the command is 0, while the pipeline uses 0.15 mol/L; give -saltcon 0.15 to match a job. |
ligprops | Ligand information (SMILES, formula, mass, rotatable bonds) and the ligand analyses of the results export (RMSF, RMSD, radius of gyration, surfaces, torsions). |
analyze | Runs several analysis commands in one pass, decoding the trajectory once: mdsim analyze -f traj.xtc -- rms ... -- gyrate .... |
mdsim rms -s md.mdtpr -f md_center.xtc -n index.ndx -fitgroup Backbone -group Backbone -o rmsd.xvg
mdsim interactions -s md.mdtpr -f md_center.xtc -n index.ndx -ligand LIG -o interactions.json
mdsim mmgbsa -s md.mdtpr -f md_center.xtc -n index.ndx -ligand LIG -saltcon 0.15 -o results.csv
Reporting
| Command | What it does |
|---|---|
export | The results package (see above). |
ligplot | The interaction diagram, the per-residue fraction bars and the timeline from one or more interactions.json files (several files are merged as replicas), or the 2D structure of any molecule (-mol); SVG, PNG or PDF. -maxwidth 240 -theme compact gives a one-column diagram. |
plot | Publication figures from .xvg files as PNG, SVG or PDF, in the figure style of the export by default. |
Utility
| Command | What it does |
|---|---|
gpuinfo | -probe reports the GPUs of this PC and whether the GPU engine can use them; -selftest compares the GPU with the CPU engine in about two seconds; -check exits with 1 when the GPU engine cannot be used; -config prints where the data library was searched. |
bench | Measures the speed of the engine in ns/day on a run input (-nsteps, -nb), and with -batch N the total throughput of 1 to N runs side by side. |
check | Inspects or compares trajectory, structure, energy and index files. |
xvgdiff | Compares two .xvg files numerically within tolerances (exit code 0 when they match). |
pack | Packs a finished job into one result bundle (.gnm), with the trajectory thinned to about 500 frames per replica (-frames, 0 = every frame). |
unpack | Extracts a result bundle and verifies every checksum; -verify only checks, -list only lists. |
mdsim gpuinfo -probe
mdsim gpuinfo -selftest
mdsim bench -s P:\Geinium\Jobs\m3_dicyclomine\run\06_run\rep1\md.mdtpr -nb gpu -batch 4
mdsim pack -run P:\Geinium\Jobs\m3_dicyclomine -o m3_dicyclomine.gnm
mdsim unpack -f m3_dicyclomine.gnm -verify
Common options
| Option | Meaning |
|---|---|
-h, -help | Lists the options of a command with type and default. |
-gmxver | A format profile that every command accepts. Leave it at its default. |
-nt | Number of threads; 0 means all logical processors (or OMP_NUM_THREADS). Results do not depend on it, except the last bits of the energies of the CPU engine. |
-b, -e, -dt, -tu | First and last time, frame interval, and the time unit of these values. |
-ligand "group NAME" | In contacts, dsasa and interactions, -ligand takes a selection; an index group must be written as "group NAME". |
-precision, -fma | Arithmetic variants used for validation. Leave them at their defaults. |
Exit codes
| Command | Code | Meaning |
|---|---|---|
| every command | 0 | Success. |
| every command | 1 | An error. An input error prints "Input error in 'mdsim <command>':" and the reason; anything else prints "Fatal error in 'mdsim <command>':". An unknown command prints "mdsim: unknown command" and suggests mdsim help. mdsim without arguments prints the list and returns 1. |
pipeline | 2 | Stopped cleanly before the target was complete (Ctrl+C or engine.max_hours). Run the same command again to continue. |
export | 3 | The report was blocked by a finding that is not acknowledged, or a part of the analyses failed. Images and raw data were written. |
gpuinfo -check, -selftest | 1 | The GPU engine cannot be used, or the self test failed ("RESULT: FAILED"). |
xvgdiff | 1 | The files differ beyond the tolerances. |