Geinium
Home › The command line

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
OptionDefaultWhat it does, and when to use it
-configproject.jsonThe project file.
-stageallRuns 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-runoffValidates 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.
-statusoffPrints the state of every stage (pending, done, stale, partial) with the result line of finished stages.
-templateoffPrints 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-1For one process per replica: 0 runs only the stages shared by all replicas, i only the stages of replica i.
-[no]vonStage 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
OptionDefaultWhat it does
-jobOne 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, -energynm, kcal/molLength unit (nm or angstrom) and energy unit (kcal/mol or kJ/mol) of the whole package.
-dpi, -png600, -[no]vector300, off, onPNG resolution (300 or 600), additional 600 dpi copies in images\600dpi, and the SVG and PDF files.
-widthnaturalOne width for all figures: single, onehalf, double (85, 114, 174 mm).
-figures, -listallFigure ids to include; -list prints the catalogue and the state of each figure. An unknown id is an error.
-[no]report, -[no]images, -[no]rawonThe three parts of the package.
-[no]compute, -[no]recomputeon, offRun 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.
-thresholdthe job's ownOccupancy (0 to 1) an interaction needs to be drawn in the interaction diagram.
-ack rule=justificationAccepts a blocking finding with a written reason, printed in the report.
-checks, -log, -checks-fileOnly run the scientific checks; write the export log to a file; add the findings as checks.txt to the package.
-analyses, -forceOnly run the detail analyses (no package); with -force even when they are up to date.
-logo, -nologocompany logoAnother logo image (PNG, JPG, SVG), or none.
-compound-reports, -textAn additional report per compound of a combined package; the report text in reading order.
-timestampA 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

CommandWhat it does
pdbfixRepairs 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.
pdb2gmxBuilds 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.
editconfDefines the periodic box (type and solute distance), centres, translates, rotates, converts between .gro and .pdb.
solvateFills the box with water and updates the topology.
genionReplaces water molecules by ions to neutralise the system and set a salt concentration (-neutral, -conc), at least -rmin from the solute.
insert-moleculesInserts copies of a molecule into a box or into free space.
make_ndxCreates an index file with the standard groups and groups of your own.
membraneEmbeds 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.
assembleCombines the receptor and the ligand coordinates and topologies into one system.
ligparamGives 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

CommandWhat it does
gromppProcesses run parameters (.mdp), coordinates and topology into a run input file (.mdtpr). -t continues exactly from the final state of a previous stage.
mdrunRuns 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.
pipelineThe 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

CommandWhat it does
energyExtracts terms of an energy file to .xvg, with average, error estimate, RMSD and drift.
rmsRMSD after a least-squares fit (-fitgroup, -group).
rmsfFluctuation per atom or per residue.
gyrateRadius of gyration.
sasaSolvent-accessible surface area.
hbondHydrogen bonds between groups (0.35 nm, 30 degrees).
distance, mindistDistances between positions; minimum distance and contacts between groups.
trjconvConverts and trims trajectories, makes molecules whole, centres, fits.
covarCovariance analysis and principal components.
clusterClusters structures on their pairwise RMSD.
dsspSecondary structure per frame by the DSSP method.
contactsReceptor-ligand contacts per residue: hydrogen bonds with occupancy, hydrophobic, ionic, water bridges.
dsasaBuried surface area per frame: SASA of receptor plus ligand minus complex.
interactionsProtein-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).
mmgbsaMM-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.
ligpropsLigand information (SMILES, formula, mass, rotatable bonds) and the ligand analyses of the results export (RMSF, RMSD, radius of gyration, surfaces, torsions).
analyzeRuns 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

CommandWhat it does
exportThe results package (see above).
ligplotThe 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.
plotPublication figures from .xvg files as PNG, SVG or PDF, in the figure style of the export by default.

Utility

CommandWhat 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.
benchMeasures 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.
checkInspects or compares trajectory, structure, energy and index files.
xvgdiffCompares two .xvg files numerically within tolerances (exit code 0 when they match).
packPacks a finished job into one result bundle (.gnm), with the trajectory thinned to about 500 frames per replica (-frames, 0 = every frame).
unpackExtracts 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

OptionMeaning
-h, -helpLists the options of a command with type and default.
-gmxverA format profile that every command accepts. Leave it at its default.
-ntNumber 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, -tuFirst 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, -fmaArithmetic variants used for validation. Leave them at their defaults.

Exit codes

CommandCodeMeaning
every command0Success.
every command1An 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.
pipeline2Stopped cleanly before the target was complete (Ctrl+C or engine.max_hours). Run the same command again to continue.
export3The 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, -selftest1The GPU engine cannot be used, or the self test failed ("RESULT: FAILED").
xvgdiff1The files differ beyond the tolerances.