PhyloPath: Physics-Constrained Antibody Evolutionary Planning

PhyloPath treats affinity maturation as a trajectory-planning problem rather than endpoint-only sequence optimization. It searches measured antibody fitness landscapes with a scalar state potential, uncertainty-aware objectives, and explicit penalties for unfavorable intermediates.

This repository is the validated, compact release extracted from the broader dyGF research workspace. It contains the frozen protocol, focused tests, public-data downloader with SHA-256 verification, four landscape evaluations, machine-readable results, figures, and manuscript sources.

Validated result

Across four antibodies and eight primary antibody--antigen tasks, horizon-5 path-aware beam search improved fully monotonic trajectory rate over matched greedy search by 0.584 (antibody-cluster 95% CI 0.371--0.796) and final measured gain by 0.087 (95% CI 0.058--0.108).

The stronger global-oracle non-inferiority claim did not pass its frozen gate and is not presented as a headline result. See the frozen result ledger and gate summary for the complete claim boundary.

One-command reproduction

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-physics-evolution.txt
./reproduce_physics_evolution.sh

The script downloads the exact public landscape tables, verifies their fingerprints, runs 22 focused tests, rebuilds all four landscape evaluations, regenerates figures and supplement tables, compiles both PDFs, and refreshes the submission manifest. Set PHYSICS_EVOLUTION_OFFLINE=1 to verify already downloaded data without network access.

PDF compilation additionally requires pdflatex and bibtex. The measured landscape workflow is CPU reproducible; retraining the released ESM2-650M oracle is a separate GPU tier and is not part of the one-command audit.

Repository map

• physics_evolution.py — trajectory objective and planners
• bnab_landscape.py — measured binary landscape representation
• binary_state_potential.py — additive and pairwise integrable potentials
• eval/ — frozen planning, ablation, learned-potential, and noise evaluations
• tests/ — the 22 focused contract tests
• outputs/ — released machine-readable results and oracle audit artifacts
• manuscript_physics_evolution/ — manuscript, supplement, and figures
• REPRODUCIBILITY_PHYSICS_EVOLUTION.md — tiered reproducibility contract

Scope and limitations

• There are four independent antibody backgrounds; eight antigen tasks are not eight independent antibodies.
• Several assay-floor-heavy tasks are excluded by the frozen 25% rule.
• Pairwise shell extrapolation fails on Omi32 and does not transfer uniformly.
• The global structure oracle misses its frozen prediction gate.
• No prospective wet-lab validation is claimed.

The manuscript currently uses anonymous author metadata. Citation information will be updated after venue selection or public preprint registration.