FAQ

FAQ

Common questions and recovery procedures. If your question is not here, open an Issue.

Installation

ImportError: cannot import name 'cypforge_core'

The package is not on your PYTHONPATH. Either:

• run pip install -e ".[qm,test]" from the repo root, or
• set $env:PYTHONPATH = "<repo>\src" for ad-hoc script usage.

pytest fails with ModuleNotFoundError: No module named 'requests_toolbelt'

This is a stale langsmith pytest plugin in your environment, not a CYPForge issue. Workaround:

$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD = "1"
python -B -m pytest tests -q

Expected result for V1.3: 97 passed, 6 skipped. The 6 skips need real Amber fixtures and are normal.

cypforge --version says command not found

You haven't run pip install -e . yet. Install from the repository root:

pip install -e ".[qm,test]"
cypforge --version

The legacy cypforge.cmd wrapper and python scripts/cypforge_run.py remain compatibility shims only; new documentation and examples use cypforge.

Environment

Amber environment not configured

AMBER_SH or AMBERHOME is not set, or points somewhere tleap cannot find. Verify:

wsl -- bash -lc 'source $AMBER_SH && which tleap && which pmemd.cuda'

Both commands should print a path under your Amber install. If pmemd.cuda is missing, you have AmberTools but not full Amber; production MD will fail but preprocessing through stage 06 (render_pre_md) still works.

Multiwfn path not configured

Only required for Core 2 RESP. Set MULTIWFN_BIN to the absolute path of Multiwfn_noGUI (the GUI-less build). The version-suffixed binary is typically inside ~/Multiwfn_<ver>/, not directly in $HOME. If you can't find it, grep ~/.bashrc for the Multiwfnpath export.

wsl_user is required

CYPForge does not have a hardcoded default WSL user. Set it per machine via --wsl-user <name> at init, or via $env:WSL_USER. Run wsl -- whoami to find your WSL username.

Heme

"Two cysteines within 4 Å of Fe"

The axial Cys was not uniquely resolvable from Fe–S distance alone. The orchestrator chose the closer one and emitted a WARN. If you know the correct axial Cys residue ID, declare it explicitly with --axial-cys-resid <N> at init; the workflow will then enforce that choice and the WARN disappears.

"Propionate-side QC product negative"

The signed-distance gate detected a proximal/distal flip in the heme placement. This is a hard FAIL. Causes:

• the source PDB has the porphyrin flipped (rare but real in some homology models),
• the macrocycle atom-name conventions in your PDB don't match the bundled template (NA/NB/NC/ND or CGA/CGD have been renamed),
• a degenerate plane fit (very flat distortions in the porphyrin).

Inspect the structure visually before debugging the code path. If your PDB uses non-standard heme atom names, normalize them with pdb4amber or a manual rename before init.

Heme state mismatch

If you declared --heme-state IC6 but the PDB has an axial oxo (O=Fe) or dioxygen (Fe–O–O), detect_heme_state will WARN. The most common cause is reading a Compound I structure (CPDI) but assuming it's the resting state. Read the WARN and re-init with the correct state if needed.

Ligand

Charge-sum check fails (sum ≠ declared formal charge)

The HF/6-31G* wavefunction was built for a different total charge than you declared at init. Typical causes:

• you passed --formal-charge 0 but the SDF actually carries a net charge (e.g. a quaternary ammonium),
• the SDF has explicit Hs but the formal charge wasn't recomputed,
• the spin multiplicity is wrong (open-shell ligand declared as closed-shell).

Fix by editing --formal-charge (and --spin) to match the SDF chemistry, then resume.

Heavy-atom RMSD > 0.05 Å after coordinate embedding

The atom mapping $\phi$ chose the wrong correspondence. If the workflow logged equivalent_ok in the resolver decision, you may have an undetected symmetry case. Inspect ligand_mapping_resolver output; supplying an explicit atom-name map (--ligand-atom-name-map) can break the tie.

equivalent_ok recorded

This is a WARN, not a FAIL. It means the hypergraph fallback found multiple candidate mappings that are indistinguishable under its retained checks. Read the per-stage report:

• if the ambiguity is genuine ligand symmetry (e.g. a phenyl ring's 2-fold rotation), the choice does not affect MD outcomes — accept the WARN.
• if the ambiguity is unexpected (asymmetric ligand), do not accept; provide an explicit atom-name map and re-resume.

Protonation

"protonation_decision.json missing"

Core 3 stage finalize_protonation requires this file. If you haven't created one, the workflow halts here on purpose. Typical contents:

{
  "decisions": [
    { "chain": "A", "resid": 376, "from": "HIS", "to": "HIE", "reason": "PROPKA pKa = 5.8" },
    { "chain": "A", "resid": 442, "from": "CYS", "to": "CYM", "reason": "axial heme thiolate" }
  ],
  "rationale": "PROPKA 3.4 at pH 7.4; manually reviewed for active-site residues"
}

Use PROPKA / reduce / pdb2pqr as upstream evidence; CYPForge does not run these for you because the right choice in a CYP active site often disagrees with the default-pH prediction.

Default protonation differs from PROPKA

Expected. PROPKA's bulk-water pKa prediction is a useful prior but not a final answer for residues coordinating Fe or near the substrate. The audit trail in 14_complex_protonation_finalize/ records every decision and your stated rationale.

Pre-MD

Stage 09 (20 ns free NPT) is slow

It's running real MD. On a single GPU it takes about a wall-day for a typical CYP system. If your endpoint must remain no-MD, use cypforge prep-only <run_name>; this stops before cypforge.core3_run_pre_md after rendering the inputs in 17_complex_pre_md_equilibration/.

"Vacuum bubble" warning in stage 09

The NPT box reached a low-density transient. Often self-corrects within 100 ps. If it persists past 1 ns, your starting topology has a problem — usually a counterion clash or a heme-edge solvation gap. Inspect cpptraj density evolution in the audit report.

Production MD crashes after CYPForge says PASS

CYPForge guarantees internal consistency (Theorem 11.1), not MD stability under arbitrary integrator settings. Common production-side issues that are not CYPForge's domain:

• timestep too large for Hs that weren't SHAKE-constrained,
• restraint masks copied from a non-CYP template,
• temperature ramp too fast for membrane-embedded systems.

Check your production mdin; CYPForge's stage_09_final.rst7 is a valid starting structure.

Workflow / orchestration

Workflow stopped on WARN — how do I continue?

Two options:

1. Inspect the WARN, decide it's acceptable, and run cypforge resume <run_name>. The acceptance is recorded in the manifest.
2. Re-init with --auto-accept-warn if this is a batch run and you've already validated the WARN patterns are harmless for your systems.

Workflow stopped on FAIL

Read the failing stage's report (<stage_dir>/*.report.md) and manifest (<stage_dir>/*.manifest.json). The manifest's checks array tells you exactly which check failed and with what value. Fix the underlying issue (often an input-data problem, less often a CYPForge bug), then cypforge resume <run_name>. The orchestrator re-runs the failed stage and continues.

Can I skip a stage?

Setting a stage to SKIPPED is supported in the orchestrator but should be used with extreme care — downstream stages assume the skipped stage's outputs exist. The only safe use is when you've produced the outputs by some other means and want CYPForge to pick up from a later checkpoint. Document the skip in your manifest.

Where are the results?

By default:

• Windows: C:\cypforge_runs\<run_name>\
• POSIX: ~/cypforge_runs/<run_name>/
• Override either with $env:CYPFORGE_RUNS_DIR (global) or --run-root (per run).

The top-level files you care about:

• run_config.json — the inputs you declared at init,
• run_manifest.json — the current workflow state,
• <stage_dir>/<stage_name>.report.md — human-readable summary per stage,
• <stage_dir>/<stage_name>.manifest.json — machine-readable evidence per stage,
• 17_complex_pre_md_equilibration/stage_09_final.rst7 — final equilibrated coordinates,
• 15_complex_solvation_ionization/system.prmtop — final topology,
• 18_global_cyp450_audit/global_audit_report.md — the end-of-pipeline audit.

Benchmarks and reproducibility

Can I reproduce the bundled benchmarks?

Yes. The three cases (4EJJ / 1Z10 / 1Z11) ship with the repo. Set up benchmark/config.json from benchmark/config.example.json with your local paths, then:

python benchmark/render_prompt.py --case 4EJJ --variant full

Render and execute. See QUICKSTART.md §5–§7 for the agent-driven path.

The benchmark PDBs are not raw RCSB files

Correct. They are CYPForge-prepared intermediates with the axial Cys already renamed (CYM for 4EJJ, CYP for 1Z10/1Z11) for reproducibility. Raw RCSB X-ray files would require an extra pdb4amber + Cys-rename step that varies by structure. The no_cypforge ablation prompt makes this explicit so an AmberTools-only agent knows what to expect.

Citation

What do I cite?

Cite all of the tools you actually used, not just CYPForge. CYPForge is an orchestration layer — Amber/AmberTools, PySCF, and Multiwfn do the chemistry, and the bundled heme parameters are from Shahrokh et al. 2012.

Bundled heme parameters (IC6, DIOXY, CPDI):

Shahrokh K, Orendt A, Yost GS, Cheatham TE III. Quantum mechanically derived AMBER-compatible heme parameters for various states of the cytochrome P450 catalytic cycle. J. Comput. Chem. 2012, 33(2): 119–133. doi:10.1002/jcc.21922

Amber (MD engine, pre-MD equilibration):

Case D.A. et al. Amber 2024, University of California, San Francisco, 2024.

Salomon-Ferrer R, Götz A.W, Poole D, Le Grand S, Walker R.C. Routine microsecond molecular dynamics simulations with AMBER on GPUs. 2. Explicit solvent particle mesh Ewald. J. Chem. Theory Comput. 2013, 9(9): 3878–3888. doi:10.1021/ct400314y

AmberTools (Antechamber + GAFF / GAFF2 for ligand typing):

Wang J, Wang W, Kollman P.A, Case D.A. Automatic atom type and bond type perception in molecular mechanical calculations. J. Mol. Graph. Model. 2006, 25(2): 247–260. doi:10.1016/j.jmgm.2005.12.005

Wang J, Wolf R.M, Caldwell J.W, Kollman P.A, Case D.A. Development and testing of a general amber force field. J. Comput. Chem. 2004, 25(9): 1157–1174. doi:10.1002/jcc.20035

PySCF / GPU4PySCF (HF/6-31G* wavefunction in Core 2):

Sun Q. et al. PySCF: the Python-based simulations of chemistry framework. WIREs Comput. Mol. Sci. 2018, 8(1): e1340. doi:10.1002/wcms.1340

Sun Q. et al. Recent developments in the PySCF program package. J. Chem. Phys. 2020, 153(2): 024109. doi:10.1063/5.0006074

Multiwfn (ESP grid + two-stage RESP fit):

Lu T, Chen F. Multiwfn: A multifunctional wavefunction analyzer. J. Comput. Chem. 2012, 33(5): 580–592. doi:10.1002/jcc.22885

Lu T. A comprehensive electron wavefunction analysis toolbox for chemists, Multiwfn. J. Chem. Phys. 2024, 161(8): 082503. doi:10.1063/5.0216272

RESP method (the charge model itself):

Bayly C.I, Cieplak P, Cornell W.D, Kollman P.A. A well-behaved electrostatic potential based method using charge restraints for deriving atomic charges: the RESP model. J. Phys. Chem. 1993, 97(40): 10269–10280. doi:10.1021/j100142a004

CYPForge itself: a manuscript is in preparation. Until then, cite the repository URL and the released tag (v1.3.0).

---

If you hit something not covered here, open an issue with:

• the CYPForge version (cypforge --version),
• the OS and WSL distro,
• the Amber / Multiwfn versions,
• the contents of run_config.json,
• the failing manifest (<stage_dir>/*.manifest.json),
• the relevant logs/<stage>.log.