Skip to content

recipes-common-errors.md

Latest commit

 

History

History
61 lines (50 loc) · 4.28 KB

recipes-common-errors.md

File metadata and controls

61 lines (50 loc) · 4.28 KB

Common Error Recipes

Use this page when you know the symptom but do not know which subcommand page to open first. For full details, keep Troubleshooting open in parallel.

Quick routing

Symptom Start here Then read
Missing element columns / extraction aborts add-elem-info on the original PDB Input / extraction
"Charge is required" errors Set -q/--charge and -m/--multiplicity explicitly Charge / spin
Energies/states look wrong after a run Re-check charge/multiplicity policy in CLI conventions Charge / spin
mm-parm cannot run (tleap/antechamber/parmchk2 missing) Fix AmberTools availability first AmberTools / mm-parm
hessian_ff import/build errors Rebuild native extension (hessian_ff/native) hessian_ff build
DMF mode import errors (cyipopt) Install cyipopt in the active environment DMF mode
TSOPT/IRC does not converge Reduce step length (trust_radius for RFO/RS-I-RFO, max_step for L-BFGS), increase cycles, validate TS quality first Convergence
Optimizer stalls at flat energy (MLIP noise floor) Rely on the default energy_plateau fallback (v0.2.8+); tune energy_plateau_thresh / energy_plateau_window if the trigger fires too early or too late Plateau fallback
CUDA/GPU runtime mismatch Verify torch.cuda.is_available() and CUDA build pairing CUDA / PyTorch
Plot export failures Install Chrome runtime for Plotly export Plot export

Recipe 1: Extraction fails before MEP starts

Signal:

  • Errors mention missing element symbols, atom-count mismatch, or empty pockets. First checks:
  • Confirm all inputs are prepared by the same workflow and atom ordering is consistent.
  • Ensure element columns are present before running extract or all. Typical fix path:
  • Repair elements -> rerun extraction -> confirm pocket size and residue inclusion.

Recipe 2: Charge/spin validation fails

Signal:

  • If the log shows unexpected charges (e.g., protein charge is wrong, or total charge does not match expectations), review the charge resolution rules. First checks:
  • Ensure total charge and multiplicity are physically correct for the target state.
  • If using residue maps, validate each residue key in --ligand-charge.
  • Verify the resolution rules in CLI Conventions when results look physically inconsistent. Typical fix path:
  • Prefer explicit -q and -m for critical runs, then retry scan/path/tsopt.

Recipe 3: Build or environment blockers

Signal:

  • mm-parm tooling not found, hessian_ff import failures, CUDA mismatch. First checks:
  • Confirm required executables and Python extension modules exist in the active env.
  • Validate GPU visibility and PyTorch CUDA compatibility. Typical fix path:
  • Repair toolchain/build first, then rerun with --help-advanced to verify available options before full execution.

Recipe 4: Convergence and post-processing failures

Signal:

  • TSOPT stalls, IRC branches look unstable, or MEP refinement stops unexpectedly. First checks:
  • Confirm TS candidate quality with one dominant imaginary mode.
  • Reduce step length (trust_radius / max_step) and increase cycle limits. Note that trust_max defaults to 0.10 bohr since v0.2.8 (was 0.20) for both RFO and RS-I-RFO.
  • Check whether the energy has already plateaued: if the last ~50 cycles show |dE| < 1e-4 au while forces are flat, the MLIP force noise floor is the culprit rather than an optimization bug. The default energy_plateau fallback will declare convergence automatically (see Troubleshooting). Typical fix path:
  • Run a smaller diagnostic case, tune thresholds/step sizes, then scale back up.