Molecular Structure Checking and Repair

What this workflow does

This workflow checks and repairs a raw PDB structure. It prepares that structure as input for a Molecular Dynamics simulation. The example is human Adenylate Kinase 1A with the AP5A inhibitor (PDB: 1Z83).

The workflow writes a structure-quality report first. It then selects one model and one chain. It resolves alternate locations and marks disulfide bridges as CYX. It strips the zinc ions, the SO4 and AP5 ligands, the existing hydrogens, and the crystallographic waters.

Next the workflow fixes the ASN and GLN amide assignments and the THR and ILE chirality. It models the missing side-chain atoms. It models the missing backbone atoms with Modeller against the canonical FASTA sequence.

The last part builds an AMBER topology, runs a short energy minimization with sander, renumbers the residues, and writes a final structure-quality report. You compare the two reports to confirm the repair.

The compute problem

This is a long serial chain. Each stage depends on the output of the previous stage. There is almost no parallelism to find.

Most stages are cheap. They read one PDB file, edit it, and write another. A CPU and a second is enough.

Two stages are different. Modeller needs its own license file and its own environment. The sander_mdrun minimization needs an AMBER build and real CPU time on a solvated system.

The environment is the real cost, not the compute. Modeller, AmberTools, and the biobb stack rarely install cleanly in one place. Many groups keep three separate environments and copy PDB files between them by hand. Every hand copy is a place where the chain breaks.

How Horus solves it

Horus provisions one environment from conda_env.yaml and runs every stage inside it. The AMBER and Modeller dependencies come with it. You do not manage three environments.

biobb_amber has no osx-arm64 conda package. On Apple Silicon the leap_gen_top, sander_mdrun, and amber_to_pdb stages run in the Docker executor against a Linux/amd64 biocontainers image. Every other stage runs natively in the conda executor. The command strings are the same in both cases.

This matters for a repair pipeline because you rerun it often. You change one ligand mask, then rerun. Horus reruns only the affected stages and keeps the cached environment. A hand-run chain of twenty commands does not give you that.

The minimization is the one stage worth moving. Change its executor: field to send it to a cluster node. The twenty cheap stages stay on your laptop where the files are.

Pipeline

fetch_pdb                Download 1Z83 from the PDB (pdb)
   │
structure_check           Initial structure-quality report (structure_check)
   │
extract_model              Select model 1 (extract_model)
   │
extract_chain               Extract chain A (extract_chain)
   │
fix_altlocs                  Resolve alternate locations, keep altloc A (fix_altlocs)
   │
fix_ssbonds                   Identify/mark disulfide bridges as CYX (fix_ssbonds)
   │
remove_molecules_metals        Remove zinc ions (remove_molecules)
   │
remove_molecules_ligands        Remove SO4 and AP5 ligands (remove_molecules)
   │
reduce_remove_hydrogens           Strip existing hydrogen atoms (reduce_remove_hydrogens)
   │
remove_pdb_water                   Remove crystallographic waters (remove_pdb_water)
   │
fix_amides                          Fix ASN/GLN amide assignments (fix_amides)
   │
fix_chirality                        Fix THR/ILE chirality (fix_chirality)
   │
fix_side_chain                        Model missing side-chain atoms (fix_side_chain)
   │
canonical_fasta ──► fix_backbone       Model missing backbone atoms via Modeller (canonical_fasta / fix_backbone)
   │
leap_gen_top ──► sander_mdrun ──► amber_to_pdb   AMBER topology + energy minimization
   │
fix_pdb                                Renumber residues, restore chain IDs (fix_pdb)
   │
structure_check_final                   Final structure-quality report (structure_check)

Inputs and outputs

Inputs

The workflow has no file inputs. It fetches 1Z83 from the RCSB PDB. configs/fetch_pdb.yaml sets the PDB code.

Outputs land in results/:

• downloaded.pdb, report.json: the raw structure and its first quality report.
• models.pdb, chains.pdb, altloc.pdb, ssbonds.pdb: the model, chain altloc, and disulfide fixes.
• metals.pdb, ligands.pdb, hydrogens.pdb, water.pdb: the structure after each removal stage.
• amides.pdb, chiral.pdb, sidechains.pdb: the amide, chirality, and side-chain fixes.
• canonical.fasta, backbone.pdb: the canonical sequence and the backbone-completed structure.
• amber.pdb, amber.top, amber.crd: the AMBER topology and coordinates.
• trj.crd, trj.rst, trj.log: the minimization trajectory, restart, and log.
• amber_min.pdb, final.pdb: the minimized and final structures.
• report_final.json: the final quality report.

Run the workflow

Install the horus-runtime one time:

uv sync

If you do not have uv, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

You can also install the packages with pip:

pip install horus-runtime horus-environments

Then run the workflow:

uv run horus run workflow.yaml

On Apple Silicon you also need Docker for the AMBER stages.

References

• BioExcel Building Blocks (biobb)
• biobb_structure_utils
• biobb_model
• Modeller
• AMBER / AmberTools
• BioExcel structure checking tutorial