Add 2RN2 FKC-steered free-energy example; reorganise notebooks by YuuuXie · Pull Request #222 · microsoft/bioemu

YuuuXie · 2026-06-09T14:43:24Z

Summary

Adds a release-ready, end-to-end FKC-steered folding free-energy (ΔG) example on a real protein (2RN2, E. coli RNase H), and reorganises notebooks/ into self-documented per-topic subfolders.

What's included

notebooks/Enhanced_Diffusion_Sampling_Protein/ (new example):

steered_dg_2rn2.py — single-run, single-GPU generation of ~1000 steered + ~1000 unsteered samples (a direct call to bioemu sample()), then a ΔG convergence curve (with error bars) via batch subsampling.
steered_denoiser.yaml / unsteered_denoiser.yaml — self-contained denoiser configs (passed straight to sample()), mirroring src/bioemu/config/steering/cv_steer.yaml. The steered config is the RMSD CV + linear potential with the per-system 2RN2 values; the unsteered config is the same FKC integrator with an empty potential.
steered_dg_lib.py — shared library: 2RN2 system definition, YAML config loader, the Fraction-of-Native-Contacts ΔG recipe, and the subsampling utilities. Uses release APIs only.
README.md — usage, outputs, example result, and implementation notes.

Reorganisation of notebooks/ into per-topic subfolders, each with its own README, and a slimmed top-level index README:

Enhanced_Diffusion_Sampling_Protein/ (steered protein ΔG)
Enhanced_Diffusion_Sampling_GMM/ (toy-GMM FKC validation + umbrella/MBAR)
Physicality_Steering/ (physical/clash steering)
PPFT/ (property-prediction fine-tuning)

Key technical notes

Slope sign: RMSD steering biases toward high RMSD (unfolding) to enhance the rare unfolded basin, so the linear-potential slope is negative. It is written explicitly in steered_denoiser.yaml as slope: -9.77 (the per-system 2RN2 value from the internal systems_config.csv); the release default in cv_steer.yaml is a generic -7.4. The steered ensemble is reweighted back to the unbiased ensemble with inverse-Boltzmann weights, using a steering potential instantiated from the same YAML entry so sampling and reweighting cannot drift.
Comparability: the unsteered baseline runs through the same FKC integrator with an empty potential (fk_potentials: [], steering_config: null) and identical step count / SDE noise (N=100, noise=1.0), so the two ΔG estimates are directly comparable.
Single process: ΔG and the plot are computed only from the batch_*.npz this run writes directly into steered_pool/ and unsteered_pool/.
ΔG recipe: FNC CV → foldedness_from_fnc (steepness=20, p_fold_thr=0.5) → weighted p_fold → ΔG = -kT·ln(p_fold/(1-p_fold)).

Verification

All scripts parse and import in the bioemu env.
Ran the subsampling analysis on generated pools: steered full-pool ΔG = -4.79 (≈ ref -5.3); unsteered saturates at ≈ -9.5. The convergence plot shows the steered curve settling onto the reference within a few hundred effective samples with shrinking error bars.

Follow-up

bioemu.__version__ is now 1.4.0 but the latest published tag is v1.3.1 — a new release should be cut.

🤖 Generated with assistance from GitHub Copilot CLI.

Add a self-contained FKC steered-sampling example (notebooks/steered_dg_example.py) that compares folding ΔG with and without RMSD steering across particle counts, evaluated via the FNC CV, plus a README documenting all notebook examples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Run the unsteered ΔG baseline through dpm_solver_fkc with an empty potential (fk_potentials=[], steering_config=None) at the same step count and SDE noise (N=100, noise=1.0) as the steered runs, so the two estimates are directly comparable. Document the FNC-CV reference-ΔG provenance (thermomutdb_fnc_slopes.csv). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The steering slope for RMSD-based CVs must be negative (drive toward high RMSD / unfolding, then reweight), matching run_steering_foldedness.py's NEGATIVE_SLOPE_CVS and the release cv_steer.yaml default. Earlier code used a positive slope which over-folded and biased ΔG. Empirically validated on 2ABD (negative -> ΔG -1.18 ≈ ref -1.2; positive -> -1.55, biased). Add steered_dg_subsampling.py: generates a large pool of steered (FKC) and unsteered (empty-potential FKC) samples in batches, sub-samples to produce ΔG convergence curves with error bars. On 2RN2 the steered curve converges to the internal reference (-5.3 kcal/mol) by a few hundred samples while the unsteered baseline saturates at an artifactual floor (~-9.5). Update README with corrected 2ABD numbers, the negative slope-sign convention, and the 2RN2 convergence result. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Reorganise notebooks/ into self-documented subfolders (Enhanced_Diffusion_ Sampling_Protein, Enhanced_Diffusion_Sampling_GMM, Physicality_Steering, PPFT), each with its own README, and slim notebooks/README.md to a brief index. The protein steered free-energy example is consolidated for release as a two-file 2RN2 example: - steered_dg_2rn2.py: single-run, single-GPU generation of ~1000 steered and unsteered samples, then a ΔG convergence curve (with error bars) via batch subsampling. - steered_dg_lib.py: shared library (2RN2 system, FKC steering / unsteered denoiser configs, FNC ΔG recipe, subsampling utilities). FKC RMSD steering recovers the internal reference folding ΔG (≈ -5.3 kcal/mol) at a sample budget where the unsteered baseline saturates and cannot resolve the rare unfolded state. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Yu Xie <xieyu.fish@outlook.com>

…irectly Ship the steered (RMSD CV + linear potential) and unsteered (empty potential) denoiser configs as self-contained YAML files next to the example, mirroring config/steering/cv_steer.yaml. The driver loads them via load_denoiser_config() (injecting only the runtime reference_pdb / num_particles) and calls bioemu sample() directly instead of a generate_pool wrapper. The steering potential used for inverse-Boltzmann reweighting is now instantiated from the same YAML fk_potentials entry, so the sampling and reweighting potentials cannot drift. The RMSD slope sign is written explicitly in YAML (-9.77, the per-system 2RN2 value) rather than via -abs() in code. System no longer carries steer_slope / steer_clip_max. Verified: ΔG on existing pools unchanged (steered -4.786, unsteered -9.504). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

precompute_steered_batches / precompute_unsteered_cv now glob the batch_*.npz written directly into each pool directory instead of rglob-ing recursively, so the single-process steered_dg_2rn2.py example computes ΔG and the convergence plot from exactly the samples it generated under steered_pool/ and unsteered_pool/, rather than inadvertently pooling stale shard subdirectories from earlier runs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Apply black/isort, strip trailing whitespace, and satisfy mypy: assert the steering potential's CV is not None before use, and array-ify the per-draw ΔG lists under new names so they are not flagged as List[float]. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

test_steering_numerically imports toy_gmm, which moved into notebooks/Enhanced_Diffusion_Sampling_GMM/ during the notebooks reorganisation. Point sys.path at that subfolder so collection succeeds. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

YuuuXie · 2026-06-09T17:03:22Z

@ludwigwinkler @nw13slx this PR adds the steering and dG calculation example of a real protein 2RN2

@sarahnlewis @ludwigwinkler I re-organized our previous examples into subdirs

@sarahnlewis @josejimenezluna , we might need to make a new release after this because after my three PR of refactorizing the steering code and adding new steering features, the version is bumped to 1.4.0 now

…e/fkc-steer-example

github-actions · 2026-06-26T14:35:57Z

Summary


Generated on:	06/26/2026 - 14:35:56
Parser:	Cobertura
Assemblies:	5
Classes:	32
Files:	32
Line coverage:	86.4% (2182 of 2524)
Covered lines:	2182
Uncovered lines:	342
Coverable lines:	2524
Total lines:	8079
Covered branches:	0
Total branches:	0
Method coverage:	Feature is only available for sponsors

Coverage

src.bioemu - 89%

Name	Line	Branch
src.bioemu	89%	****
init.py	100%
chemgraph.py	100%
convert_chemgraph.py	97%
denoiser.py	98.3%
get_embeds.py	92.1%
md_utils.py	85.8%
model_utils.py	78%
models.py	94.1%
run_hpacker.py	0%
sample.py	92.2%
sde_lib.py	88.3%
seq_io.py	100%
shortcuts.py	100%
sidechain_relax.py	75%
so3_sde.py	90.3%
structure_module.py	84.3%
utils.py	65.6%

src.bioemu.colabfold_inline - 79.1%

Name	Line	Branch
src.bioemu.colabfold_inline	79.1%	****
init.py
features.py	100%
input_parsing.py	100%
model_runner.py	99%
msa_client.py	60.8%

src.bioemu.hpacker_setup - 69.2%

Name	Line	Branch
src.bioemu.hpacker_setup	69.2%	****
init.py
setup_hpacker.py	69.2%

src.bioemu.steering - 79.5%

Name	Line	Branch
src.bioemu.steering	79.5%	****
init.py	100%
collective_variables.py	34.8%
dpm_fkc.py	100%
dpm_smc.py	100%
potentials.py	95.3%
utils.py	83.5%

src.bioemu.training - 100%

Name	Line	Branch
src.bioemu.training	100%	****
foldedness.py	100%
loss.py	100%

YuuuXie and others added 4 commits June 1, 2026 08:07