Troubleshooting
Messages you may see, what they mean, and what to do.
Geinium stops with a message rather than guess when an input is ambiguous or a step cannot be done
correctly, and every message names what to change. This page collects the messages by situation.
The full record of a job is in pipeline.log in its work folder and in the Log panel
(Ctrl+L), which can be saved; the findings of an export are in
09_results\export.log.
The GPU engine is not used
When a run cannot use the GPU, it continues on the CPU engine and says why. The results are the same; the run takes much longer. The status bar shows "No hardware acceleration", its tooltip "Hardware acceleration is not available: <reason>. Simulations run much slower.", and the log says "Simulations run on the CPU engine: the results are the same, the run takes much longer."
| Message begins with | Cause | What to do |
|---|---|---|
| "No NVIDIA graphics driver was found on this PC" | No NVIDIA driver is installed, or the PC has no NVIDIA card. | Install the current driver from the NVIDIA web site. The GPU engine needs an NVIDIA GPU with compute capability 5.0 or higher and driver 527.41 or newer. |
| "The NVIDIA driver of this PC (version ...) is too old for the GPU engine." | The driver predates the CUDA 12.2 build. | Update the driver (NVIDIA web site or the NVIDIA app) and start the program again. |
| "The NVIDIA driver (...) reports no CUDA device" | The card is disabled in the Device Manager, or not present. | Enable the card. If the message adds that CUDA_VISIBLE_DEVICES "hides all devices", remove that environment variable. |
| "GPU 0 (<name>) cannot run the GPU engine" | The card is older than compute capability 5.0. | Simulations run on the CPU engine on this PC; use a newer card for production work. |
| "The CUDA FFT library cufft64_11.dll was not found next to the program." | A file of the bin folder is missing. | Restore it from the package or install the program again. Until then, PME runs use the CPU engine. |
| "The GPU engine could not be started on <device>" | Start failure; with "the GPU does not have enough free memory for this system" the memory is taken by other programs. | Close other programs that use the GPU (games, video, other simulations), or use a smaller system. |
| "MDS_GPU_ID=N: this PC has n CUDA device(s), numbered from 0." | The variable names a device that does not exist. | Correct or remove MDS_GPU_ID. |
| "Note: the NVIDIA driver supports CUDA x.y, this program was built with CUDA 12.2." | A notice, not an error. | If the GPU engine does not start, update the driver. |
To see the situation of a PC at once, run mdsim gpuinfo -probe; to check that the GPU
computes correctly, mdsim gpuinfo -selftest. When a run should rather fail than continue
slowly, start it with -nb gpu or set MDS_GPU_NO_CPU_FALLBACK=1.
Run inputs made outside the pipeline can contain features the GPU engine does not run:
free-energy perturbation, integrators other than leap-frog, Andersen or MTTK coupling, LJ-PME,
virtual sites, freeze or acceleration groups, walls, pulling, distance restraints, SHAKE, a PME order
other than 4, or ewald-rtol below 1e-6. Such a run stops with a message that names the
feature. The pipeline never writes them.
The viewer is blank or slow
The viewer needs OpenGL 3.3 from the graphics driver. Without it (remote desktop, virtual machine, very old graphics), the log says "3D viewer: OpenGL 3.3 is not available on this PC (<details>). Start the program with the option --software-gl to draw the 3D view without a graphics driver.", the status bar shows "3D view unavailable", and the application restarts once with the software renderer that is shipped with it.
- Update the graphics driver; this resolves most cases on a local PC.
- Start
Geinium.exe --software-glto use the software renderer directly. It is slower and has no ambient occlusion, outlines or anti-aliasing in the live view; image export still works. - Everything except the viewer works without OpenGL: jobs, results, figures and the export.
- Playback stutters on a weak graphics driver: lower "Quality" in the viewer and "Anti-aliasing" in Settings.
A job does not start
| Message | Meaning | What to do |
|---|---|---|
| "Not started: missing residues decision needed" | The protein has internal gaps, and the "Before the start" question was cancelled. | Start again and answer it: "Model the missing residues" (with a sequence) or "Cap the ends (neutral)". |
| "Not started: membrane decision needed" | The protein looks like a membrane protein and no membrane was chosen. | Answer the "Membrane protein" question: "Use a membrane (POPC:CHOL 7:3)", or "Simulate without a membrane" with a reason. |
| "Not started: <reason>"; "Cannot run: <reason>" in the Dry run | An input problem found before anything runs. | Read the reason; the Preparation section of Run MD opens at the choice that is needed. |
| "Ligands: A, B (choose one)" | The complex holds several ligand residues. | Choose one under "Ligand residue" (project: inputs.ligand_resname). |
| "... contains n copies of ligand residue X ... One copy is simulated" | The same ligand occurs several times. | Choose one under "Ligand copy" (project: inputs.ligand_chain or inputs.ligand_resnr). |
| A list of poses with their scores | A docking file with several poses. | Choose one under "Ligand pose" (project: inputs.ligand_pose). |
| "... holds 2D coordinates ..." or "... has z = 0 for every atom ..." | A drawing, not a docked pose. | Export the docked 3D pose from the docking program. |
| "the ligand is not in contact with the protein: ..." | Closest ligand-receptor heavy-atom distance above 0.6 nm. | The pose and the receptor are probably from different coordinate frames: use the receptor the docking was run on. |
| "the ligand overlaps the protein: ..." | Closest distance below 0.15 nm. | The receptor still contains a molecule at that place, or the input has duplicated atoms. |
| "the ligand has only a loose contact with the protein: ..." | A warning: 0.4 to 0.6 nm. | Check that this is the intended pose. |
| "no ligand residue of '<file>' matches X; the ligand residues of the complex are: ..." | The ligand name given does not exist in the file. | Choose one of the names listed. |
| "no ligand (HETATM residue that is not water or an ion) found ..." | The complex contains no ligand. | Give a separate ligand file, or simulate the protein alone ("Ligand residue": "None"). |
| An unknown element, or a ligand of several fragments | Only H, C, N, O, F, P, S, Cl, Br and I in one connected molecule can be parametrised; metals, B, Si and Se are refused. | Supply the ligand as one molecule without counter-ions or solvent. |
| "A job is running: this job is queued" | Not an error: one job runs at a time. | Nothing; it starts when the running job ends. |
A job stops during preparation
The structure stage stops when it would otherwise have to change the system silently. The message names the project option that resolves it; on the Run MD page the Preparation section opens with the matching choice.
| Message begins with | What to do |
|---|---|
| "The structure contains nucleic acids: ..." | Protein-DNA/RNA complexes cannot be simulated. To simulate the protein without them on purpose, tick "Remove DNA/RNA" (structure.remove_nucleic_acids). |
| "The input contains molecules besides the protein that would NOT be simulated: ..." | A cofactor, glycan or unknown molecule. Removing it changes the system (an enzyme without its cofactor is not the native protein). If that is acceptable, select it under "Remove molecules" (structure.remove_residues, or "all-unsupported"). A molecule without metal atoms can be simulated as the ligand instead. |
| "The ligand ... contains metal atoms ..." | Metal-containing molecules cannot be parametrised automatically. Choose another ligand, or simulate the protein without it. |
| "Covalent ligand: not supported - the ligand ... is bonded to ..." | Simulate the protein without it, or provide a non-covalent pose of the unreacted ligand as a ligand file. |
| "The protein contains modified amino acids that the force field ... has no parameters for." | Crystallisation artefacts: tick "Revert crystallisation artefacts" (structure.revert_modifications = true). Phosphorylated residues need parameters that are not available; list them in structure.revert_modifications to simulate the unphosphorylated protein. |
| "This protein looks like a MEMBRANE protein: ..." | Choose a membrane (membrane.type), or set system.membrane_protein = false with a reason in system.membrane_justification. |
| "The project declares a membrane protein ... but no membrane is chosen" | Choose a membrane type, or remove the declaration. |
| "The ligand ... is also listed in the project option structure.remove_residues" | Remove it from that list, or choose another ligand. |
| "structure.sequence_fasta '...' not found" | Correct the path; relative paths start at the folder of the project file. |
| "the membrane system failed its structural checks: ..." | The bilayer could not be built cleanly around the protein (lipid overlaps, ring piercing, charge, leaflet balance). Check the orientation; give an oriented reference structure. |
| "the system is not neutral after adding ions: ..." | Usually an unusual charge state; check the residue states and the ligand charge. |
Warnings do not stop a job but deserve a look: removed crystallisation additives (sulfate, glycerol), metal sites without restraints, a single hydrophobic segment, a histidine next to a carboxylate, buried charged residues, and ligand parameters taken by analogy with a high penalty.
The analyses are out of date
A job made by an older version, or copied to another folder, shows the band "Analyses were made
by an older version and must be recomputed" (or "Analyses not computed") on the Results page.
"Recompute" or "Compute" runs the analyses again in the background; the simulations are never
repeated. The export dialog asks the same question before it writes a package, and mdsim
export refuses such a job ("the analyses of <job> were made by an older version and must be
recomputed first") until it is given -recompute.
The report was not written
A blocking finding of the scientific checks stops report.pdf; images and raw data are still written.
The dialog says "Report not written (see the log)", or "Report not written: membrane protein
simulated in water."; the command line prints "report.pdf was NOT written: resolve the blocking
findings listed above, or acknowledge them with a written justification". Read the finding in the
export log. Resolve it, or acknowledge it with "Acknowledge" in the dialog, -ack
rule=justification, or export.acknowledged; the justification is printed in the
report. The rules are listed in Exporting results.
A queue was interrupted
When the window is closed or the PC fails while a job runs, the job is marked "interrupted at <stage>". At the next start a banner offers "Queue interrupted. Next: <name> (<stage>)" with "Resume now" (after a 10 s countdown when "Resume at start" is ticked) and "Not now"; the Start button reads "Continue queue". The job continues from its stage markers and its last checkpoint, losing at most five minutes of simulation. Closing the application on purpose pauses the running job the same way.
Opening files
| Message | What to do |
|---|---|
| "Cannot open results: <reason>" | The folder is not a finished job, or a file of it is missing. Open the job folder itself, not a sub-folder of it. |
| "<name>: unsupported file type" | See File formats for what can be opened. |
| "Open the structure first." | A trajectory needs its structure: open the .gro or .pdb first, or use "Job folder" in the viewer. |
| "<file> has <n> atoms per frame: open the matching structure first" | The trajectory belongs to another system. |
| "The bundle is DAMAGED:" | A file of the bundle does not match its checksum; the bundle was changed or damaged in transfer. Copy it again. |
Folder and file names
- Folder and file names may contain blanks and any characters on Windows 10 version 1903 or newer. On older Windows 10 the programs print a note when started in such a folder; use plain names there.
- Paths longer than 260 characters also need the Windows setting "Enable Win32 long paths".
- A processor without AVX2 ends the programs at once with an illegal-instruction fault and no message.
Command line
- In
mdsim contacts,dsasaandinteractions, an index group given to-ligandmust be written-ligand "group NAME". mdsim mmgbsaneeds a trajectory with exactly the atoms of the topology; another system is refused with both atom counts in the message.mdsim mmgbsauses no salt by default, the pipeline 0.15 mol/L: give-saltcon 0.15to reproduce a job.- Errors print "Input error in 'mdsim <command>':" with the reason and return exit code 1; see The command line.
Jobs of version 1.0.0
A job started with version 1.0.0 and not yet finished may repeat stages when it is continued with this version, because the program version is part of the stage inputs. A finished 1.0.0 job opens normally; its analyses must be recomputed once before export, and its MD is never repeated.