Feature/qresfep integration

[David-Araripe]

Integrate the dual-topology QresFEP workflow

Summary

This PR replaces the stale QresFEP.py implementation on this repository with the residue-mutation FEP workflow built around the published QresFEP-2 hybrid-topology method implemented on the qusers/qligfep repository. It connects spherical protein preparation, mutation setup, two-stage production, SLURM validation, and analysis through three command-line tools:

qresfep            set up one protein or reference-peptide leg
setup_resFEP       prepare and set up a mutation series
qresfep_analyze    combine both legs into folding ddG results

The workflow now supports both charge-maintaining and charge-changing mutations (manuscript in preparation), records preparation metadata to map user PDB residue numbering to Q topology numbering, and includes the end-to-end T4 lysozyme tutorial included in the qusers/qligfep repo.

Most of the PR's line count comes from the bundled OPLS-AA/M force-field files, T4L structures, and integration tests.

Residue-FEP setup

• Builds a hybrid residue with a shared backbone and separate wild-type and mutant side chains.
• Normalizes PyMOL atom names to Q/force-field conventions and supports one- or three-letter mutation notation.
• Generates the two consecutive FEP stages:
  • stage 1 removes the wild-type side-chain charges and introduces soft-core interactions;
  • stage 2 introduces the mutant charges, removes its soft-core treatment, and leaves the wild type as a ghost.
• Removes direct non-bonded and bonded coupling between the two side chains, adds missing zero-force bonded terms, and restrains overlapping equivalent heavy atoms to prevent side-chain flapping.
• Handles glycine transitions and protonation variants (ASH, GLH, HIP, ARN, and LYN), including cross-topology chi1 torsions. This includes regression coverage for the protonation-variant issue reported in Update/tutorials #24.
• Builds capped reference peptides from packaged AXA, GXG, single-residue, or native-neighbour templates.
• Adds restrained counterions to charge-changing reference legs so their sphere charge matches the prepared protein leg.

Preparation and residue mapping

qprep_prot now writes prep.json, which records the sphere centre and radius, force field, total charge, disulfides, and the mapping between the input PDB and Q residue numbering. QresFEP uses this manifest instead of attempting to reconstruct information that is lost after preparation.

Related preparation changes:

• adds OPLS-AA/M as a packaged force field;
• preserves crystallographic waters by default, while --strip-crystal-waters restores the previous removal behavior;
• derives force-field-specific neutralization atom changes from the selected residue library;
• retains complete in-sphere solvent residues and molecular fragments;
• uniquely reindexes residues for systems whose chains reuse residue numbers;
• validates that the requested mutation remains inside the active sphere and was not converted to an out-of-sphere neutral form.

Batch setup and reproducibility

setup_resFEP validates an entire mutation list before writing calculations, prepares one sphere per mutated residue by default, generates both thermodynamic-cycle legs, and arranges the result as:

work/<MUTATION>/
protein/FEP_<MUTATION>/
tripeptide/FEP_<MUTATION>/

Mutant coordinates can be generated through the PyMOL executable or supplied as ready-made <MUTANT><POSITION>.pdb files for cluster workflows.

The CLI exposes the protocol settings needed for reproducible campaigns, including:

• lambda windows and spacing;
• equilibration and per-window production steps;
• Q's separate_scaling setting;
• trajectory output and post-run cleanup;
• deterministic random-state or explicit per-replicate seeds;
• a named --manuscript-settings preset with the fixed settings and seed vector used by the in-preparation charge-changing campaign.

Each setup writes resfep_config.json so the effective protocol can be inspected after generation.

Run safety

The generated SLURM script keeps both FEP stages in one job because stage 2 starts from stage 1's endpoint. It additionally:

• checks every equilibration and production log for normal qdyn termination;
• records successful equilibration before removing quota-heavy equilibration logs;
• validates qfep's exit status, non-empty output, absence of reported errors, and a complete numerical Part 3 section;
• writes stage-validation status files;
• performs cleanup only after qdyn and qfep validation, preserving failed-stage files for diagnosis;
• emits the standard EXPRESS LOG footer from an EXIT trap, including runtime, seed, replicate, working directory, and exit status.

Analysis

qresfep_analyze discovers mutations from FEP_<WT><POSITION><MUT> directory names, sums both FEP stages for each leg, and reports:

ddG_fold = dG_protein - dG_tripeptide

The resulting CSV contains each leg's estimate and SEM, completed-replicate counts, propagated folding-ddG uncertainty, and failed-replicate counts. Zwanzig, forward, reverse, and BAR estimates are available. Optional experimental data can be used to report RMSE, MUE, and correlation. Missing or unfinished legs remain visible as NaN results rather than being silently omitted.

Tutorial and documentation

A new tutorials/T4L/ walkthrough covers:

1. generating mutant side chains;
2. preparing a mutation-centred water sphere;
3. setting up one mutation or a complete mutation list;
4. submitting both legs;
5. collecting folding-ddG results.

It includes the prepared 2LZM structures, neutral and charge-changing mutation lists, PyMOL helper, shell-loop example, protocol rationale, and a distinction between the published 2025 protocol H and the separate in-preparation manuscript preset.

Verification

Focused QresFEP, qprep, template, CLI, and batch-setup tests:

300 passed, 15 warnings

The T4L tutorial was also exercised locally through all pre-submission stages:

• PyMOL generated all 10 neutral-mutant residue PDBs;
• qprep_prot completed normally for the LEU39ALA example;
• both manual LEU39ALA legs produced 5 equilibration inputs and 25 windows per stage;
• the all-at-once workflow set up 10/10 mutations, 20 legs, and 20 submission scripts;
• all generated run and submission scripts passed bash -n;
• every generated run script contained the EXPRESS LOG footer;
• pre-submission analysis produced all 10 expected rows and correctly marked them unfinished.

Full qdyn production was not run locally because it requires the documented SLURM workload (200 jobs for the ten-mutation, two-leg, ten-replicate example).

Reviewer notes

• The old src/QligFEP/QresFEP.py is intentionally removed; the replacement is split into focused preparation, chemistry, setup, run, and analysis modules.
• Preserving crystallographic waters is a deliberate qprep_prot default change; --strip-crystal-waters is available for the old behavior.
• --manuscript-settings refers to the separate in-preparation charge-changing campaign, not protocol H from the 2025 QresFEP-2 paper. The tutorial calls out this distinction explicitly.
• Generated QresFEP production remains cluster-oriented because its two stages must be chained through the stage-1 restart.