Macromolecular Coarse-Grained Flexibility with FlexServ

What this workflow does

This workflow reproduces the FlexServ protocol. It derives the flexibility of a macromolecule from one static structure. The example is Ribosomal Protein S15 (PDB: 1A32).

The workflow reduces the protein to a coarse-grained Cα model. It then generates three independent conformational ensembles: Brownian Dynamics (BD), Discrete Molecular Dynamics (DMD), and Normal Mode Analysis (NMA).

Each ensemble goes through PCA compression to the PCZ format. The workflow then runs a battery of flexibility analyses on the compressed data: eigenvectors, B-factors, hinge-point detection, apparent stiffness, and collectivity. A final set of stages compares all ensemble pairs, including a reference all-atom MD trajectory from the MoDEL database.

The compute problem

This workflow has three distinct hardware profiles in one graph.

The three ensemble generators are the heavy stages. BD, DMD, and NMA each write a full trajectory. They are independent of each other. They can run at the same time on three cores or three machines.

The PCA compression stages read a whole trajectory into memory. They need RAM more than they need cores.

The analysis stages are small. Sixteen similarity comparisons, five B-factor stages, and three hinge-detection stages each finish in seconds. There are many of them, so scheduling cost dominates.

A single-machine run serializes all of this. You wait for BD, then DMD, then NMA, then dozens of short stages.

How Horus solves it

Horus reads the dependency graph and runs the independent stages together. BD, DMD, and NMA have no edge between them, so they start at the same time. The three cpptraj_rms stages follow their own ensemble.

The analysis fan-out benefits the most. The similarity matrix is sixteen separate comparisons. Horus dispatches them as soon as the PCZ files exist. You do not write a loop or a job array.

biobb_flexserv has no osx-arm64 conda package. On Apple Silicon the FlexServ stages run in the Docker executor, inside a quay.io/biocontainers Linux/amd64 image. The biobb_io, biobb_analysis, and biobb_structure_utils stages have native arm64 builds and stay in the conda executor. Each stage names its executor with one field. The command strings are identical on macOS and on Linux.

This is the portability argument in practice. You develop the workflow on a laptop with mixed executors. You then move the three ensemble stages to an HPC scheduler by editing three executor: fields.

Pipeline

fetch_pdb            Download 1A32 from the PDB (pdb)
   │
extract_atoms_ca      Reduce structure to Cα-only coarse-grained model (extract_atoms)
   │
   ├── bd_run          Brownian Dynamics ensemble (bd_run)
   │      └── cpptraj_rms_bd         RMSD + convert to XTC (cpptraj_rms)
   ├── dmd_run         Discrete Molecular Dynamics ensemble (dmd_run)
   │      └── cpptraj_rms_dmd        RMSD + convert to XTC (cpptraj_rms)
   └── nma_run         Normal Mode Analysis ensemble (nma_run)
          └── cpptraj_rms_nma        RMSD + convert to XTC (cpptraj_rms)
   │
   ├── pcz_zip_bd / pcz_zip_dmd / pcz_zip_nma     PCA-compress each trajectory to PCZ (pcz_zip)
   │      └── pcz_unzip_*                          Decompress back to CRD (pcz_unzip)
   │             └── cpptraj_rms_*_uncompressed     RMSD of decompressed trajectory (cpptraj_rms)
   │
   ├── pcz_info                     PCA report: eigenvalues, variance, dimensionality (pcz_info)
   ├── pcz_evecs                    Extract eigenvectors for NMA PC1 (pcz_evecs)
   ├── pcz_animate ──► cpptraj_convert_proj1   Animate NMA PC1 mode, convert to XTC (pcz_animate / cpptraj_convert)
   ├── pcz_bfactor_all / pcz_bfactor_mode1-5   B-factors per PCA mode (pcz_bfactor)
   ├── pcz_hinges_bfactor / _dyndom / _fcte    Hinge-point detection, 3 methods (pcz_hinges)
   ├── pcz_stiffness                Apparent inter-residue stiffness (pcz_stiffness)
   ├── pcz_collectivity             Collectivity index (pcz_collectivity)
   └── pcz_similarity_*             All-pairs BD/DMD/NMA/MD(MoDEL) similarity matrix (pcz_similarity, 16 comparisons)

Inputs and outputs

Inputs

The workflow fetches 1A32 from the PDB. It also reads one bundled file, Files/1a32.MoDEL.pcz. This is a pre-compressed 10 ns all-atom MD trajectory. The workflow uses it only as a comparison baseline.

Outputs land in results/:

• 1a32.pdb, 1a32_ca.pdb: the downloaded and Cα-reduced structures.
• bd_ensemble.mdcrd, dmd_ensemble.mdcrd, nma_ensemble.mdcrd: the raw coarse-grained ensembles, with .log, .xtc, and RMSD .dat files.
• bd_ensemble.pcz, dmd_ensemble.pcz, nma_ensemble.pcz: the PCA-compressed trajectories.
• *_uncompressed.crd, .rmsd.dat, .xtc: the decompressed trajectories, for compression-quality checks.
• pcz_report.json, pcz_evecs.json: the PCA report and the eigenvector data.
• pcz_proj1.crd, pcz_proj1.xtc: the PC1 mode animation.
• bfactor_all.dat, bfactor_mode1-5.dat and the matching .pdb files: the B-factor profiles per mode.
• hinges_bfactor_report.json, hinges_dyndom_report.json, hinges_fcte_report.json, the hinge-point predictions.
• pcz_stiffness.json, pcz_collectivity.json: the stiffness and collectivity metrics.
• pcz_similarity_*.json: the pairwise similarity indices.

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. Horus pulls the biocontainers image on the first run.

References

• BioExcel Building Blocks (biobb)
• biobb_flexserv
• FlexServ web server
• PCA suite
• BioExcel FlexServ tutorial