The bash workflow PyMACS expedites.

Manual idea

Pick a `.pdb`, `.cif`, or `.mmcif` file, or download a PDB entry by hand.

Command pattern

python 1_AutomateGromacs.py --pdb <complex.pdb>
# or
python 1_AutomateGromacs.py --fetch-pdb <PDB_ID>

What PyMACS is doing

PyMACS records the selected source, normalizes structure input, and prepares a reproducible setup workspace.

Manual idea

grep -v "<LIG>" <complex.pdb> > protein.pdb

Command pattern

protein.pdb = complex minus selected ligand/cofactors
retained_components = <LIG>, <COFACTOR>, ...

What PyMACS is doing

Instead of relying on fragile residue-name grep commands, PyMACS detects ligands, cofactors, waters, ions, polymers, and chain choices in a controlled way.

Manual idea

Manually inspect missing atoms, hydrogens, chain IDs, residue names, and termini prompts.

Command pattern

repair protein.pdb
write protein_pdb2gmx_ready.pdb
cache chain names and component metadata

What PyMACS is doing

The script prepares the structure for GROMACS, stores chain/component metadata, and makes later automation less ambiguous.

Manual idea

gmx pdb2gmx -f protein.pdb -o protein_processed.gro -p topol.top -ignh -water spc -ter

Command pattern

gmx pdb2gmx -f <protein_ready.pdb> -o protein_processed.gro -p topol.top -water spc -ter

What PyMACS is doing

PyMACS automates force-field selection and chain-aware termini choices so the protein topology is generated consistently.

Manual idea

Rename long CGenFF files, change residue names like `obj01` to `<LIG>`, and keep MOL2/STR files aligned.

Command pattern

<LIG>.cgenff.mol2
<LIG>.str
residue name = <LIG>

What PyMACS is doing

The script checks the retained component path and expects ligand naming to line up across coordinates, MOL2, STR, and topology outputs.

Manual idea

python cgenff_charmm2gmx_py3_nx2.py <LIG> <LIG>.cgenff.mol2 <LIG>.str charmm36_ljpme-jul2022.ff

Command pattern

python cgenff_charmm2gmx_py3_nx2.py <LIG> <LIG>.cgenff.mol2 <LIG>.str <charmm_forcefield>

What PyMACS is doing

PyMACS wraps the conversion path that creates ligand `.itp`, `.prm`, and coordinate helper files for GROMACS.

Manual idea

gmx editconf -f <ligand>_ini.pdb -o <ligand>.gro

Command pattern

gmx editconf -f <ligand_pose.pdb> -o <ligand>.gro

What PyMACS is doing

The script generates GROMACS coordinate files for retained small molecules so they can be merged back into the complex.

Manual idea

Copy protein_processed.gro to complex.gro, paste ligand atoms at the end, then update the atom count.

Command pattern

protein_processed.gro + <ligand>.gro -> complex.gro
update atom count

What PyMACS is doing

PyMACS assembles the coordinate file while preserving atom counts and component placement more reliably than manual copy/paste editing.

Manual idea

#include "<ligand>.itp"
#include "<ligand>.prm"
[ molecules ]
Protein_chain_A 1
<LIG> 1

Command pattern

topol.top includes force field, ligand parameters, ligand topology, and molecule counts

What PyMACS is doing

The script updates `topol.top` so GROMACS knows which molecules exist and where their parameters are defined.

Manual idea

gmx editconf -f complex.gro -o newbox.gro -bt cubic -d 1.0

Command pattern

gmx editconf -f complex.gro -o newbox.gro -bt <box_type> -d <box_distance>

What PyMACS is doing

PyMACS creates a box around the solute with configurable geometry and padding.

Manual idea

gmx solvate -cp newbox.gro -cs spc216.gro -p topol.top -o solv.gro

Command pattern

gmx solvate -cp newbox.gro -cs spc216.gro -p topol.top -o solv.gro

What PyMACS is doing

The script adds solvent molecules and updates the topology molecule counts.

Manual idea

gmx grompp -f ions.mdp -c solv.gro -p topol.top -o ions.tpr -maxwarn 2

Command pattern

gmx grompp -f ions.mdp -c solv.gro -p topol.top -o ions.tpr -maxwarn 2

What PyMACS is doing

PyMACS builds the temporary binary input needed for `genion` and can retry known ordering problems when safe.

Manual idea

Choose `SOL` interactively, then run genion to neutralize the box.

Command pattern

gmx genion -s ions.tpr -o solv_ions.gro -p topol.top -pname NA -nname CL -neutral -conc 0.15

What PyMACS is doing

The script detects the water group, replaces water molecules with counterions, neutralizes the system, and adds physiological salt when configured.

Manual idea

gmx grompp -f em.mdp -c solv_ions.gro -p topol.top -o em.tpr -maxwarn 2

Command pattern

gmx grompp -f em.mdp -c solv_ions.gro -p topol.top -o em.tpr -maxwarn 2

What PyMACS is doing

Step 1 ends by writing `em.tpr`, which proves the solvated, ionized system can be compiled for minimization.

Manual idea

gmx mdrun -v -deffnm em
# optional CPU pinning / GPU session settings

Command pattern

gmx mdrun -v -deffnm em <resource_options>

What PyMACS is doing

PyMACS runs minimization, chooses CPU/GPU behavior, logs the command, and checks the minimization output before continuing.

Manual idea

gmx make_ndx -f em.gro -o index.ndx
# manually name groups like Protein_LIG, Water_and_ions, Ligase, Target_A

Command pattern

gmx make_ndx -f em.gro -o index.ndx
optional: gmx genrestr -f <ligand>.gro -o posre_<ligand>.itp

What PyMACS is doing

The script creates or validates index groups used by NVT/NPT/production and can generate ligand restraints when the workflow needs them.

Manual idea

gmx grompp -f nvt.mdp -c em.gro -r em.gro -p topol.top -n index.ndx -o nvt.tpr -maxwarn 2
gmx mdrun -v -deffnm nvt

Command pattern

gmx grompp -f nvt.mdp -c em.gro -r em.gro -p topol.top -n index.ndx -o nvt.tpr
gmx mdrun -v -deffnm nvt <resource_options>

What PyMACS is doing

PyMACS warms the minimized system at fixed volume, carries the correct index groups, and writes checkpoint files for continuation.

Manual idea

gmx grompp -f npt.mdp -c nvt.gro -r nvt.gro -t nvt.cpt -p topol.top -n index.ndx -o npt.tpr
gmx mdrun -deffnm npt
gmx grompp -f md.mdp -c npt.gro -t npt.cpt -p topol.top -n index.ndx -o md_0_1.tpr
gmx mdrun -deffnm md_0_1

Command pattern

gmx grompp -f npt.mdp ... -o npt.tpr
gmx mdrun -deffnm npt
gmx grompp -f md.mdp ... -o md_0_1.tpr
gmx mdrun -deffnm md_0_1 <resume_or_gpu_options>

What PyMACS is doing

PyMACS stabilizes density and pressure, compiles the production input, runs or resumes production MD, and records resource choices such as GPU IDs, thread counts, and checkpoint use.

Manual idea

Manually decide whether this is ligand, protein-only, peptide/interface, biological, or PROTAC analysis, then point every script to the right `.gro`, `.xtc`, `.tpr`, ligand code, and output folder.

Command pattern

python 3A_AutomateGromacs.py --mode <ligand|protein|peptide|biological|protac> --ligand <LIG>

What PyMACS is doing

PyMACS detects or prompts for the analysis route, loads the production trajectory, creates `Analysis_Results/`, and keeps the user's ligand, chain, and component choices connected to the setup metadata.

Manual idea

Run `trjconv` or write custom MDAnalysis code to remove periodic-boundary jumps, center the complex, and export analysis-ready files.

Command pattern

md_0_1.xtc + npt.gro -> Final_Trajectory.xtc
Final_Trajectory.pdb

What PyMACS is doing

The script writes centered `Final_Trajectory` files so downstream calculations and visualization tools operate on a coherent molecular system.

Manual idea

Select residues within a cutoff of the ligand, write a smaller PDB/XTC, and keep the selection consistent across frames.

Command pattern

select protein residues within <pocket_cutoff> A of <LIG>
write binding_pocket_only.pdb / binding_pocket_only.xtc

What PyMACS is doing

PyMACS creates pocket-only files that are easier to inspect and faster to use for ligand-centered analysis.

Manual idea

Keep notes mapping atom ranges to chain names, ligand IDs, cofactors, and biological components, then rewrite those mappings in every analysis notebook.

Command pattern

read atomIndex.txt
read pymacs_system_registry.json
read pymacs_components.json

What PyMACS is doing

The analysis stage reuses setup metadata so chain-resolved plots and component-aware outputs keep the same names the user chose earlier.

Manual idea

Align each frame to a reference, calculate RMSD over time, export a CSV table, and make a plot.

Command pattern

Protein_RMSD.csv / .png
FullComplex_RMSD.csv / .png

What PyMACS is doing

PyMACS creates the basic stability plots that tell users whether the protein or full simulated assembly drifted, plateaued, or changed substantially.

Manual idea

Split the system by chain, align selections carefully, compute RMSD/RMSF for each chain, then label plots and CSVs by hand.

Command pattern

RMSD_<CHAIN>.csv / .png
RMSF_<CHAIN>.csv / .png
RMSF_<CHAIN>_per_residue.csv

What PyMACS is doing

The script breaks global motion into chain-level stability and flexibility so users can see which protein region is rigid, mobile, or asymmetric.

Manual idea

Select ligand atoms, align to the protein or complex, calculate ligand RMSD and per-atom RMSF, then format ligand-specific plots.

Command pattern

<LIG>_Ligand_RMSD.csv / .png
<LIG>_Ligand_RMSF.csv / .png

What PyMACS is doing

PyMACS shows whether the ligand stayed near the original binding pose, sampled nearby poses, became internally flexible, or left the pocket.

Manual idea

Compute compactness traces for the protein, ligand, and complex, then overlay them into a readable figure.

Command pattern

Radius_of_Gyration_Protein.csv / .png
Radius_of_Gyration_Protein_Ligand_Complex.csv
Radius_of_Gyration_Overlay.png

What PyMACS is doing

The script adds a compactness check that complements RMSD by showing expansion, collapse, or breathing motion.

Manual idea

Run secondary-structure assignment, encode residue states over time, make heatmaps, and summarize helix/sheet/coil fractions.

Command pattern

DSSP_raw.csv
DSSP_encoded_numeric.csv
DSSP_Heatmap.png
SSE_Fractions.png
Residue_SSE_Persistence.csv

What PyMACS is doing

PyMACS helps users see whether helices, sheets, loops, and structural motifs persist or change during the trajectory.

Manual idea

For every frame, calculate distances between ligand/partner atoms and nearby protein residues, apply cutoffs, and save a large contact table.

Command pattern

AllContacts_Framewise.csv
FilteredContacts_Framewise.csv
--contact_cutoff <distance>

What PyMACS is doing

The script turns a trajectory into residue-level contact evidence: which residues touch the ligand or partner, how often, and when.

Manual idea

Separate distance contacts from hydrogen-bond-like, hydrophobic, ionic, and water-mediated patterns, then build timelines, heatmaps, violins, and ranked residue plots.

Command pattern

InteractionTypes_Framewise.csv
InteractionTypes_Summary.csv
interaction_heatmap_normalized.png
interaction_type_violin.png
binding_importance_ranking.png

What PyMACS is doing

PyMACS converts raw contacts into chemically interpretable summaries that are easier for medicinal chemistry and structural biology users to read.

Manual idea

Write separate scripts for chain-chain contacts, protein-peptide contacts, biological macromolecule distances, and mode-specific outputs.

Command pattern

Biomolecule_Chain_Interaction_Heatmap.png
Biomolecule_Chain_Interaction_Distances.png
Interface_* outputs when applicable

What PyMACS is doing

When the system is not a simple small-molecule case, PyMACS routes analysis toward chain interfaces, peptide contacts, or biological assemblies instead of forcing a ligand-only interpretation.

Manual idea

Manually decide frame stride, component roles, linker handling, protein partners, and which expensive analyses to run for a PROTAC trajectory.

Command pattern

python 3_PROTAC_Analysis.py --ligand <PROTAC> --frame-step <N>
optional: --quick-test, --basic-only, --contacts-only

What PyMACS is doing

In PROTAC mode, PyMACS hands off to the dedicated ternary-complex analyzer with controlled sampling and mode-specific outputs.

Manual idea

Write separate analyses for ligand contacts by protein partner, ternary geometry, networks, water bridges, PCA, QC manifests, and figure routing.

Command pattern

Analysis_Results/PROTAC/RMSD_RMSF/
Analysis_Results/PROTAC/Contacts/
Analysis_Results/PROTAC/Networks/
Analysis_Results/PROTAC/QC/protac_figure_manifest.csv

What PyMACS is doing

The PROTAC script organizes ternary-complex results into a dedicated tree that keeps component roles, contact summaries, structures, geometry, and QC metadata together.

Manual idea

Read contact summary CSVs, draw a ligand or peptide interaction map, label residues, choose thresholds, and export presentation-ready panels.

Command pattern

python 3B_NETWORX.py --ligand <LIG>
Analysis_Results/NETWORX/<LIG>_bar.png
Analysis_Results/NETWORX/<LIG>_network.png
Analysis_Results/NETWORX/<LIG>_expanded_clean.png

What PyMACS is doing

NETWORX translates contact and interaction tables into visual residue-network figures that are much easier to discuss than spreadsheets.

Manual idea

Collect the useful PNGs, write captions, arrange pages, handle missing figures, and build separate report formats for ligand, protein, peptide, biological, or PROTAC runs.

Command pattern

python 4PDF4MD.py
MD_ANALYSIS_FIGUREBOOK.pdf
PROTAC_MD_ANALYSIS_FIGUREBOOK.pdf

What PyMACS is doing

The final script packages the generated analyses into a clean figurebook so users can review and share the simulation without hunting through folders.

Manual idea

Open several `Analysis_Results/` folders, normalize naming, compare RMSD/RMSF/contact outputs, and build a side-by-side summary by hand.

Command pattern

python 00_Pymacs_X_analysis.py --root <runs_folder> --outdir <dashboard_folder>

What PyMACS is doing

For larger projects, the optional comparative dashboard builder helps compare apo, ligand-bound, mutant, species, or replicate simulations after individual runs have been analyzed.