Geinium
Home › The Run MD page

The Run MD page

Starting one simulation from a complex: the input, the protocol, preparation and advanced options, the questions before the start, and the buttons that start, pause and open a job.

Run MD takes one complex from file to results package. The form on the left holds the input and the options; the buttons at its foot stay visible while the form scrolls; the live monitor on the right follows the running job (see Monitoring a running job).

The Run MD page before an input is chosen. Look at the form on the left: Input, Protocol with the
The Run MD page before an input is chosen. Look at the form on the left: Input, Protocol with the "Preparation" and "Advanced" sections closed and their summaries beside the titles, and the grey force-field line. "Start", "Add to queue" and "Dry run" are greyed until a complex is chosen.

Input

ControlMeaningWhen to change it
"Complex or project" with "Browse"The protein with the docked ligand (.pdb, .ent, .cif, .mmcif, .pdbqt) or a project file (project*.json). A file can be dropped on the page. The grey line below reports the ligand found ("Ligand: LIG", "Ligands: A, B (choose one)", "No ligand: protein only", "Unreadable: ...", or "Project <name>").Always: this is the job.
"Ligand file"A docked ligand in its own file (.sdf, .sd, .mol, .mol2, .pdb, .pdbqt), copied into the job folder. Empty ("From the complex"): the ligand of the complex.When the docking program wrote the poses to a separate file.
"Job name"The name of the job and of its folder; filled from the file name.To run the same complex twice with different settings, give each job its own name.
"Output folder"The parent folder of the job folder. Empty ("Automatic"): a folder mdsim_runs next to the complex.To keep all jobs in one place, for example on a data drive with enough space for trajectories.

Choosing another complex clears the choices that belonged to the previous one: pose, copy, sequence, molecules to remove and the membrane decision. A project file fills and locks the whole form (see Input files).

The page with P:\Geinium\Complexes\m3_dicyclomine.pdb chosen. Look at the line
The page with P:\Geinium\Complexes\m3_dicyclomine.pdb chosen. Look at the line "Ligand: LIG" under the file, the job name taken from the file, and "Start" now enabled in blue. The defaults shown are those of a new job: 100 ns, 2 fs, one replica, 310 K.

Protocol

ControlDefault (range)Meaning and when to change it
"Production"100 ns (0.001 to 1,000,000)Length of the production run of every replica. Shorter for a test of the setup (0.2 ns runs the whole pipeline in minutes), longer for slow processes.
"Time step""2 fs, standard hydrogen masses"Or "4 fs, hydrogen-mass repartitioning" (hydrogen masses tripled, two constraint iterations). See The simulation protocol.
"Replicas"1 (1 to 20)Independent production runs with different velocity seeds. Use three or more for results you will compare or publish.
"Temperature"310 K (1 to 1000)Reference temperature of the thermostat. 310 K is body temperature; use the temperature of an experiment you want to compare with.
"Ligand residue""Automatic"The residue simulated as the ligand; "None" simulates the protein alone (no MM-GBSA). See Input files.
"Membrane (POPC:CHOL 7:3)"offEmbeds the protein in a Lipid21 bilayer with a staged equilibration of 8.5 ns per replica; the box controls are then greyed. For membrane proteins; see Box, solvent, ions and membranes.

The grey line "AMBER ff14SB · GAFF2 / AM1-BCC · TIP3P" under the form names the force fields; its tooltip lists the rest of the model: "V-rescale thermostat, C-rescale barostat, PME, 1.0 nm cut-offs, h-bond constraints; MM-GBSA with GB-OBC2". Other force fields are available on the System Builder page.

Preparation

The "Preparation" section holds the choices about protonation, missing residues and the contents of the input. Its summary line, for example "pH 7.4, model short gaps", shows the current state. The input is scanned in the background as soon as it is chosen; when it needs a decision, the summary ends in "choice needed" and the section opens itself. Rows that do not apply to the input stay hidden.

The Preparation section opened for a complex. Look at the summary beside the title, which repeats the pH and the missing-residue choice, and at the rows that appear only because this input needs them, such as the sequence fields or the list of molecules to remove.
The Preparation section opened for a complex. Look at the summary beside the title, which repeats the pH and the missing-residue choice, and at the rows that appear only because this input needs them, such as the sequence fields or the list of molecules to remove.
ControlShownMeaning and when to change it
"pH"always0 to 14, default 7.4. Protonation of protein and ligand. See Protonation at pH.
"Ligand protonation"always"At pH" (default) or "As in the input file".
"Ligand pose"when the ligand file holds several posesThe pose that is simulated; "Choose a pose" until one is chosen.
"Ligand copy"when the ligand residue occurs several timesThe copy that is simulated; "Choose a copy" until one is chosen.
"Missing residues"always"Model short gaps" (default), "Cap breaks" or "Charged ends (not recommended)". See Structure preparation.
"Longest modelled gap"always; active with "Model short gaps"1 to 12 residues, default 8. Longer gaps are capped, not built.
"Cap chain ends"alwaysNeutral ACE/NME groups also at the first and last residue of every chain (default: charged termini).
"Protein sequence", "Sequence"when the chain has breaks and the file no sequenceA FASTA file or one-letter codes, used to build missing residues.
"Remove molecules"when the input holds other moleculesTicked molecules are removed. "Removing a cofactor changes the system."
"Remove DNA/RNA"when the input holds nucleic acidsSimulates the protein without its nucleic-acid partner.
"Revert crystallisation artefacts"when modified residues are foundTurns methylated lysines and oxidised cysteines back into the natural residue.
"Metal sites: ..."when metals are foundThe metals and their coordinating atoms.
"Advanced" > "Residue states"alwaysPer-residue protonation states that win over the pH, with "Add", "Remove" and (with metal sites) "Apply suggested states".

When a job stops in the structure stage on a choice of the input (molecules to remove, nucleic acids, a ligand copy or pose), the section reopens with the choices, so the job can be corrected and started again in place.

Advanced

The "Advanced" section holds settings that rarely need changing. Its summary line reads, for example, "1 bar, 0.15 mol/L NaCl, NVT 100 ps, NPT 100 ps", with the box when it is not the default, ", MTS" when multiple time stepping is on, and ", n more" for extra keys.

The Advanced section opened. Look at the box shape and solute-box distance, the two equilibration lengths, the multiple-time-stepping and concurrent-replica choices, and the
The Advanced section opened. Look at the box shape and solute-box distance, the two equilibration lengths, the multiple-time-stepping and concurrent-replica choices, and the "More keys" button at the bottom.
ControlDefault (range)Meaning and when to change it
"Pressure"1 bar (0.01 to 1000)Reference pressure of the barostat.
"Salt"0.15 mol/L NaCl (0 to 2)NaCl added after neutralisation.
"NVT equilibration"100 psRestrained NVT equilibration of soluble systems.
"NPT equilibration"100 psRestrained NPT equilibration of soluble systems.
"Box""Rhombic dodecahedron"Or "Cubic", "Truncated octahedron". The dodecahedron needs the least water.
"Solute-box distance"1.0 nm (0.8 to 2.0)Smallest distance between the solute and the box edge.
"Multiple time stepping""Off"Or "Long-range every 2nd step": the mesh forces of production every second step. See The simulation protocol.
"Concurrent replicas""One at a time"Or "Automatic", 2, 3, 4: replicas of the job running at the same time on one GPU.
"More keys"noneFurther keys of the project file, described below.

The reasons for each default are given in The simulation protocol and Box, solvent, ions and membranes.

More keys

"More keys" opens an editor for any key of the project file that the form does not show: output intervals, the analysis window, MM-GBSA options and others (all listed in Project file keys). The text is a JSON object that is merged over the project the form generates. After OK the button reads "More keys (n)" with the number of top-level keys set. Text that is not a JSON object is refused with "Not a JSON object: ..." and the dialog stays open.

The
The "More keys" dialog with a JSON object that starts the analysis window at 10 ns and widens the box distance. Look at the nesting: each key sits inside the group it belongs to, exactly as in the project file.
{
  "box":      {"distance_nm": 1.2},
  "analysis": {"start_ns": 10},
  "protocol": {"output": {"xtc_ps": 20}},
  "mmgbsa":   {"decomposition": true}
}

The example widens the box to 1.2 nm, starts the analysis window at 10 ns, writes a frame every 20 ps instead of 10 ps (half the trajectory size), and adds the per-residue decomposition of MM-GBSA, which the form does not offer. Unknown keys are errors; "Dry run" shows the result before anything is started.

Before the start

"Start" and "Add to queue" first check whether the job needs a decision that would change the system. Two questions can appear, in this order. Neither is asked for a job started from a project file, nor for a job whose structure stage has already run or whose decision is already stored.

Missing residues and fusion partners

The "Before the start" dialog appears when residues are missing inside a chain or a fusion partner was found. It reads "<job>: residues are missing inside the chain:" with one line per gap, for example "A:486-488 missing (3 residues)", and offers "Model the missing residues" (with the sequence "from the file", a FASTA file, "or one-letter codes", or the button "Get the sequence of <ID> from the PDB") and "Cap the ends (neutral)". A fusion partner adds "Fusion partner (not part of the native protein):" with "Keep" and "Remove (ends capped)". Nothing is preselected, OK is enabled only when every question is answered, and Cancel leaves the job unstarted with "Not started: missing residues decision needed". The dialog is described in full in Structure preparation.

The
The "Before the start" dialog. Look at the gap list, the sequence source under "Model the missing residues", and the separate "Keep" / "Remove (ends capped)" choice for the fusion partner; OK is greyed until all are answered.

Membrane protein

The "Membrane protein" dialog appears when the protein has two or more transmembrane segments and no membrane was chosen. It reads "<name> looks like a membrane protein: n transmembrane segments (...). In water it is not in its native environment." and offers "Use a membrane (POPC:CHOL 7:3)", which is preselected, or "Simulate without a membrane" with "Reason (required)". The reason is printed in the report. Cancel leaves the job unstarted with "Not started: membrane decision needed". See Box, solvent, ions and membranes.

The
The "Membrane protein" dialog. Look at the segment count in the first line and at the reason field, which is enabled only with "Simulate without a membrane" and must be filled before OK can be pressed.

Buttons

ButtonWhat it doesWhen to use it
"Start"Does everything "Add to queue" does, then starts this job. If another job is running, this one is queued behind it ("A job is running: this job is queued").To run the job now.
"Add to queue"Asks the questions above, checks the job, and adds it to the batch queue without starting it.To collect several jobs and start them together from the Batch page.
"Dry run"Checks the job and shows its plan in a read-only dialog "Dry run: <name>"; writes nothing.Before a long run, to see the stages, steps, seeds and analysis window that will be used.
"Pause"Stops the running job at its next checkpoint; "Start" continues from there.To free the PC for a while.
"Stop after stage"Finishes the running stage, then stops.To stop at a clean point, for example after equilibration, to inspect the system.
"Live structure"Shows the running system in the viewer. Available while a job runs.To watch the ligand in its pocket during production.
"Job folder"Opens the folder of the running or last job in Explorer.To look at the files.
"Report"Opens report.pdf of the last job. "Available when the report is written".At the end of the job.
"Results"Opens the figures and tables of the last job on the Results page. "Available after the analysis stage".At the end of the job, or to look at the analyses before the report is written.

The dry-run plan starts with "DRY RUN - nothing is written, nothing is computed" and lists the project, the work directory, the inputs with every non-water hetero residue of the file, the system (force field, water, box or membrane, ions and their seed), the protocol with the number of steps of every stage, the replicas with their velocity seeds, the engine settings, the analysis window, and each stage with the action it would take: run, redo, continue or skip. A job that cannot run reports "Cannot run: <reason>" in the status line instead.

The
The "Dry run" dialog of a complex. Look at the Protocol block, which states the time step, temperature, pressure coupling and the number of steps of each stage, at the velocity seed of each replica, and at the analysis window: these are the values the job will use, read from the project it would write.

The job folder

A job lives in <output folder>\<job name>\, by default mdsim_runs\<job name> next to the complex. It holds:

ItemContents
The complex (and the ligand file)Copies of the inputs, so the folder is self-contained.
project.jsonThe complete job, rewritten at every start. mdsim pipeline -config project.json reproduces it.
run\The work directory: 01_structure to 09_results (see Project file keys), pipeline.log, and the report as run\09_results\<name>_results\report.pdf.

Starting a job whose folder already exists continues it: the queue entry is updated rather than duplicated, the job keeps its velocity seed, finished stages are skipped, an interrupted MD stage continues from its checkpoint, and stages whose settings were changed are repeated.

Status messages

MessageMeaning
"<name> started"The job runs.
"<name> queued (n jobs)", "<name> queued (position n)"The job was added to the queue, or an existing entry for the same folder was updated.
"<name> queued behind the running job"Another job is running; this one follows.
"Dry run of <name> passed"The plan could be made; nothing was written.
"Cannot run: <reason>"The job is not valid as it stands, for example a missing file or a ligand that is not in contact with the protein.
"Not started: missing residues decision needed"The "Before the start" dialog was cancelled.
"Not started: membrane decision needed"The "Membrane protein" dialog was cancelled.
"<name>: done - report written; n ns/day"The job finished; failed jobs show the message of the stage that failed, in red.
The page while the production stage of m3_dicyclomine runs. Look at the header (
The page while the production stage of m3_dicyclomine runs. Look at the header ("Stage 9 of 14 · Production"), the strip with 14.4 % done at 389.2 ns/day, the energy plots filling from the log, and the stage table with the results of the two equilibration stages. "Pause", "Stop after stage" and "Live structure" are now enabled.