From 18c171d0a51b6c14591b071810ab48d3d409f248 Mon Sep 17 00:00:00 2001 From: lenhan Date: Tue, 19 May 2026 20:07:12 +1000 Subject: [PATCH] Troubleshooting --- README.md | 59 ++++++++- docs/src/SUMMARY.md | 6 + docs/src/troubleshooting.md | 254 ++++++++++++++++++++++++++++++++++++ 3 files changed, 318 insertions(+), 1 deletion(-) create mode 100644 docs/src/troubleshooting.md diff --git a/README.md b/README.md index 6f1771f..1c927f9 100644 --- a/README.md +++ b/README.md @@ -1929,7 +1929,64 @@ use_hybrid_gediis = false # default for blend, can be omitted **Symptoms**: Many optimization steps required -**Solutions**: add more steps; try other optimizers +**Solutions**: +- Add more steps: +``` +max_steps = 300 # maximum optimization steps +``` +- Try other optimizers, for examples: +``` +#===== Pure GDIIS: blend mode but zero contribution of GEDIIS =================================== +switch_step = 3 # 0=DIIS-only, 3=BFGS→DIIS (default), >=max_steps=BFGS-only +hessian = direct_psb # direct_psb (default) | inverse_bfgs | bofill | powell | bfgs_powell_mix + # Note: blend mode requires a direct Hessian method. +use_gediis = blend # options: false/none=GDIIS (default), true/sequential=GEDIIS, + # blend=GDIIS_blend with trust region +use_hybrid_gediis = false # activated when use_gediis = true or blend + # options: true/false +gediis_blend_mode = fixed_sequential # activated when use_gediis = blend AND use_hybrid_gediis = true + # options: fixed, fixed_sequential (default), gradient, sequential + +``` + +``` +#===== Blend mode with hybrid GDIIS/GEDIIS sequential =================================== +switch_step = 3 # 0=DIIS-only, 3=BFGS→DIIS (default), >=max_steps=BFGS-only +hessian = direct_psb # direct_psb (default) | inverse_bfgs | bofill | powell | bfgs_powell_mix + # Note: blend mode requires a direct Hessian method. +use_gediis = blend # options: false/none=GDIIS (default), true/sequential=GEDIIS, + # blend=GDIIS_blend with trust region +use_hybrid_gediis = true # activated when use_gediis = true or blend + # options: true/false +gediis_blend_mode = sequential # activated when use_gediis = blend AND use_hybrid_gediis = true + # options: fixed, fixed_sequential (default), gradient, sequential + +``` +``` +#===== Blend mode with hybrid GDIIS/GEDIIS fixed_sequential =================================== +switch_step = 3 # 0=DIIS-only, 3=BFGS→DIIS (default), >=max_steps=BFGS-only +hessian = direct_psb # direct_psb (default) | inverse_bfgs | bofill | powell | bfgs_powell_mix + # Note: blend mode requires a direct Hessian method. +use_gediis = blend # options: false/none=GDIIS (default), true/sequential=GEDIIS, + # blend=GDIIS_blend with trust region +use_hybrid_gediis = true # activated when use_gediis = true or blend + # options: true/false +gediis_blend_mode = fixed_sequential # activated when use_gediis = blend AND use_hybrid_gediis = true + # options: fixed, fixed_sequential (default), gradient, sequential +``` + +#===== Blend mode with hybrid GDIIS/GEDIIS gradient =================================== +switch_step = 3 # 0=DIIS-only, 3=BFGS→DIIS (default), >=max_steps=BFGS-only +hessian = direct_psb # direct_psb (default) | inverse_bfgs | bofill | powell | bfgs_powell_mix + # Note: blend mode requires a direct Hessian method. +use_gediis = blend # options: false/none=GDIIS (default), true/sequential=GEDIIS, + # blend=GDIIS_blend with trust region +use_hybrid_gediis = true # activated when use_gediis = true or blend + # options: true/false +gediis_blend_mode = gradient # activated when use_gediis = blend AND use_hybrid_gediis = true + # options: fixed, fixed_sequential (default), gradient, sequential +``` + ## Cite diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 9817151..255d35b 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -61,3 +61,9 @@ - [Run Modes](run-modes.md) - [Configuration File](configuration.md) - [API Reference](api-reference.md) + +--- + +# Troubleshooting + +- [Troubleshooting](troubleshooting.md) diff --git a/docs/src/troubleshooting.md b/docs/src/troubleshooting.md new file mode 100644 index 0000000..ff96785 --- /dev/null +++ b/docs/src/troubleshooting.md @@ -0,0 +1,254 @@ +# Troubleshooting + +## Common Errors + +### "No such file or directory" + +**Cause**: QM program not found in PATH, or input file is missing. + +**Solutions**: +- Verify the QM program is installed and accessible in your `$PATH`. +- Check that the input file path is spelled correctly. + +--- + +### "QM calculation failed" + +**Cause**: The QM program encountered an internal error. + +**Solutions**: +- Open the `running_dir/*.log` (or `*.out`) files and look for program-specific error messages. +- Confirm that the method and basis set are valid for the chosen program. +- Check that `nprocs` and `mem` do not exceed available resources. +- Switch to `mode = noread` to force a fresh SCF each step and avoid reading a corrupted wavefunction: + +``` +mode = noread +``` + +**Program-specific hints**: + +| Program | Symptom | Remedy | +|---|---|---| +| Gaussian | "Convergence failure" | Add `scf=(xqc,qc,nofermi)` to the `*TAIL` section | +| ORCA | "SCF not converged" | Add `%scf SOSCF true end` to the `*TAIL` section | +| Custom | Unexpected output | Verify the `energy_parser` / `forces_parser` regex patterns in the JSON interface | + +--- + +### "Failed to parse output" + +**Cause**: The QM output format was not recognized — often because the calculation did not finish normally. + +**Solutions**: +- Confirm the QM calculation completed without errors before OpenMECP tries to read it. +- Check that the program version is supported. + +**Parsing-specific tips**: + +| Issue | Action | +|---|---| +| Energy not found | Check the `energy_parser` regex in the custom interface | +| Forces not found | Verify `forces_parser` matches the output format | +| Geometry incomplete | Ensure the optimization step wrote a complete geometry block | +| State extraction failed (TD-DFT) | Confirm `state_a` / `state_b` indices are valid (0 = ground, 1+ = excited) | + +--- + +### "Maximum steps exceeded" + +**Cause**: The optimizer did not converge within `max_steps` (default 100). + +**Solutions**: +- Increase the step limit: + ``` + max_steps = 300 + ``` +- Verify that the starting geometry is chemically reasonable. +- Use [LST interpolation](advanced/lst.md) to generate a better initial guess. +- Check for recurring SCF convergence failures — if the QM energy/gradient is wrong the optimizer cannot converge. + +--- + +## SCF Convergence Issues + +**Symptoms**: QM calculations fail repeatedly, or the energy oscillates step-to-step. + +**Solutions**: + +1. **Use `mode = noread`** — starts every SCF from scratch, avoids corrupted guess orbitals: + ``` + mode = noread + ``` + +2. **Use `mode = stable`** — checks wavefunction stability before proceeding: + ``` + mode = stable + ``` + +3. **Use `mode = inter_read`** — recommended for open-shell singlets, reads MOs from the previous step to maintain spin symmetry: + ``` + mode = inter_read + ``` + +4. **Increase the SCF iteration limit** via the `*TAIL` section: + - Gaussian: + ``` + scf=(maxcycle=200,xqc) + ``` + - ORCA: + ``` + %scf maxiter 200 end + ``` + +See [Run Modes](run-modes.md) for a full comparison of `mode` options. + +--- + +## Slow Convergence + +**Symptoms**: Optimization requires an unusually large number of steps. + +### Step 1 — Increase the step limit + +``` +max_steps = 300 +``` + +### Step 2 — Try a different optimizer + +The examples below go from fastest/least-robust to most-robust. Pick the first +one that converges for your system. + +#### Pure GDIIS (default) + +No changes needed — GDIIS is the default. Explicitly: + +``` +use_gediis = false # GDIIS only (default) +switch_step = 3 # 3 BFGS warm-up steps, then DIIS (default) +``` + +--- + +#### Sequential Hybrid GEDIIS/GDIIS + +Three-phase switching: GDIIS → GEDIIS (near seam) → GDIIS (final). Typically +2–4× faster than pure GDIIS. + +``` +use_gediis = true +use_hybrid_gediis = true +gediis_switch_rms = 0.005 # GDIIS → GEDIIS when RMS grad < 0.005 Ha/Å (default) +gediis_switch_step = 0.001 # GEDIIS → GDIIS when RMS disp < 0.001 Å (default) +``` + +--- + +#### GDIIS\_blend — Pure (trust-radius GDIIS, no EDIIS) + +GDIIS protected by an adaptive trust radius. Very robust; no EDIIS component. + +``` +switch_step = 3 +hessian = direct_psb # required for blend mode +use_gediis = blend +use_hybrid_gediis = false # default for blend; can be omitted +``` + +--- + +#### GDIIS\_blend — Fixed-Sequential Hybrid (recommended blend default) + +50/50 GDIIS+EDIIS far from the minimum, transitions to pure GDIIS near +convergence. Best overall blend mode for production runs. + +``` +switch_step = 3 +hessian = direct_psb +use_gediis = blend +use_hybrid_gediis = true +gediis_blend_mode = fixed_sequential # default when use_hybrid_gediis = true +``` + +--- + +#### GDIIS\_blend — Gradient-Weighted Hybrid + +Smooth sigmoid blend driven by the RMS gradient. EDIIS-heavy when forces are +large, GDIIS-heavy near convergence. Useful for systems with energy plateaus. + +``` +switch_step = 3 +hessian = direct_psb +use_gediis = blend +use_hybrid_gediis = true +gediis_blend_mode = gradient +``` + +--- + +#### GDIIS\_blend — Sequential Hybrid + +Per-step binary switching (GDIIS or EDIIS) based on the RMS displacement trend. + +``` +switch_step = 3 +hessian = direct_psb +use_gediis = blend +use_hybrid_gediis = true +gediis_blend_mode = sequential +``` + +--- + +### Optimizer Quick-Reference + +| Optimizer | Keywords | Speed | Stability | +|---|---|---|---| +| Pure BFGS | `switch_step ≥ max_steps` | Slowest | Highest | +| GDIIS (default) | `use_gediis = false` | Good | High | +| Sequential Hybrid | `use_gediis = true`, `use_hybrid_gediis = true` | ~2–4× GDIIS | High | +| GDIIS\_blend Pure | `use_gediis = blend`, `use_hybrid_gediis = false` | Good | High | +| GDIIS\_blend Fixed-Seq | `use_gediis = blend`, `gediis_blend_mode = fixed_sequential` | Good | Medium–High | +| GDIIS\_blend Gradient | `use_gediis = blend`, `gediis_blend_mode = gradient` | Good | Medium–High | +| GDIIS\_blend Sequential | `use_gediis = blend`, `gediis_blend_mode = sequential` | Good | Medium | + +> **Note**: All `blend` modes require a direct Hessian update method: +> `direct_psb` (default), `bofill`, `powell`, or `bfgs_powell_mix`. +> `inverse_bfgs` is incompatible with blend mode. + +--- + +### Hessian Update Methods + +The `hessian` keyword affects both step quality and compatibility with blend +mode. Choose a method suited to your system: + +| Value | Description | Blend Compatible | +|---|---|---| +| `direct_psb` | Powell–Symmetric–Broyden (default) | Yes | +| `bofill` | Bofill update — better for TS-like crossings | Yes | +| `powell` | Powell update | Yes | +| `bfgs_powell_mix` | Mixed BFGS/Powell | Yes | +| `inverse_bfgs` | Classic inverse BFGS | **No** | + +For transition-state-like crossings, `bofill` is recommended: + +``` +hessian = bofill +``` + +--- + +### Robust DIIS + +For particularly difficult cases, enable the [Robust DIIS](algorithms/robust-diis.md) +sanity-check layer, which detects and rejects ill-conditioned DIIS steps: + +``` +use_robust_diis = true +``` + +Combine with any optimizer above for extra protection. See the +[Robust DIIS](algorithms/robust-diis.md) page for full options.