OpenMM PDB Fixer

This node prepares real-world PDB structures for OpenMM simulation by repairing common structural issues before solvation, minimization, or molecular dynamics. It standardizes residues, adds missing atoms and hydrogens at a chosen pH, and gives explicit control over ligands, cofactors, metals, and water molecules so they are not silently removed.

Usage

Use OpenMM PDB Fixer immediately after loading or generating a PDB structure and before OpenMM Solvate, OpenMM Energy Minimize, or OpenMM Simulate. It is especially useful for downloaded PDB entries, antibody complexes, multi-chain proteins, structures with missing terminal atoms, alternate-location conflicts, non-standard residues such as MSE, and inputs that fail force-field matching downstream.

Typical workflow: Load PDB → OpenMM PDB Fixer → OpenMM ForceField Config + OpenMM Solvate → OpenMM Energy Minimize → OpenMM Simulate. For ligand-containing systems, set heterogen_mode to preserve, add an OpenMM Ligand Parameters node for each ligand residue, and pass those ligand parameters into OpenMM Solvate, OpenMM Energy Minimize, and OpenMM Simulate. For protein-only simulations, use remove_nonwater to strip ligands/cofactors/metals, and usually keep keep_water disabled so OpenMM Solvate can add a fresh, consistent solvent box.

Best practice is to leave replace_nonstandard_residues enabled for crystal structures and use the default physiological pH of 7.4 unless your experiment requires a different protonation environment. Keep the default heterogen_mode=error_if_present when inspecting new structures, because it prevents accidental removal of a ligand or cofactor that may be scientifically important.

Inputs

Field	Required	Type	Description	Example
pdb	True	PDB	Input PDB structure(s) to repair. Expects a dictionary-like PDB object where each entry maps a structure ID to PDB-format text containing parseable ATOM and/or HETATM records.	{'7KOO_antibody': 'HEADER IMMUNE SYSTEM\nATOM 1 N GLN H 1 12.414 23.810 8.921 1.00 42.18 N\n...'}
pH	False	FLOAT	pH used when adding hydrogens and assigning protonation states. Valid range is 0.0 to 14.0, with a default of 7.4 for physiological conditions.	7.4
heterogen_mode	False	COMBO	Controls handling of non-water HETATM residues such as ligands, cofactors, and metals. `error_if_present` stops when such residues are detected; `remove_nonwater` strips them; `preserve` keeps them for ligand-parameterized downstream workflows.	error_if_present
keep_water	False	BOOLEAN	Keeps water molecules from the input PDB when `heterogen_mode` is `remove_nonwater`. Usually leave this disabled because **OpenMM Solvate** adds a fresh explicit water box.	False
replace_nonstandard_residues	False	BOOLEAN	Replaces non-standard residues with canonical equivalents where possible, such as MSE to MET or phosphorylated residues to their base amino acids. Enabled by default and recommended for most simulation preparation.	True
timeout	False	INT	Maximum wait time per PDB structure in seconds. Default is 600 seconds; valid range is 60 to 3600 seconds. Increase for very large complexes or unusual structures.	600

Outputs

Field	Type	Description	Example
fixed.pdb	PDB	Repaired PDB structure(s), keyed by the same PDB IDs as the input. The output is ready for **OpenMM Solvate**, **OpenMM Energy Minimize**, or **OpenMM Simulate**, depending on whether the structure already has the required simulation setup.	{'7KOO_antibody': 'HEADER IMMUNE SYSTEM\nATOM 1 N GLN H 1 12.414 23.810 8.921 1.00 42.18 N\nATOM 2 H GLN H 1 12.027 24.632 8.476 1.00 42.18 H\n...\nEND'}
statistics	DATAFRAME	A table summarizing the fixed structures. Contains one row per input PDB with `pdb_id` and `num_atoms` columns.	[{'pdb_id': '7KOO_antibody', 'num_atoms': 6842}, {'pdb_id': '1HZH_fab', 'num_atoms': 6127}]

Important Notes

• Heterogen safety: The default error_if_present mode intentionally stops when non-water HETATM residues are present, preventing accidental removal of ligands, cofactors, or metals.
• Ligand workflows: If you set heterogen_mode to preserve, downstream OpenMM nodes usually need matching OpenMM Ligand Parameters entries for each preserved ligand residue.
• Water handling: keep_water only matters when heterogen_mode is remove_nonwater. For most workflows, leave input waters removed and let OpenMM Solvate create a consistent solvent box.
• Performance: PDB fixing is usually fast for protein-only structures, but the timeout is applied per input PDB. Batch inputs can take up to number of structures × timeout.

Troubleshooting

• Input pdb dictionary is empty. At least one PDB structure is required.: Connect a valid PDB-producing upstream node, such as Load PDB, and confirm the input contains PDB text rather than an empty object.
• Structure contains non-standard residues that PDBFixer would strip: Your structure contains ligands, cofactors, metals, or other non-water HETATM residues. Use heterogen_mode=preserve with OpenMM Ligand Parameters, or use heterogen_mode=remove_nonwater for a protein-only simulation.
• PDBFixer received empty PDB content: The upstream file input may have lost access to the uploaded file or produced no data. Re-upload the PDB file and rerun the workflow.
• PDBFixer produced an empty topology: The PDB content has no parseable ATOM/HETATM records or is not valid PDB text. Verify the file format and reload a valid structure.