diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index b6c3deb..9817151 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -48,6 +48,14 @@ --- +# Examples + +- [Overview](examples/overview.md) + - [Gaussian Examples](examples/gaussian.md) + - [ORCA Examples](examples/orca.md) + +--- + # Reference - [Run Modes](run-modes.md) diff --git a/docs/src/examples/gaussian.md b/docs/src/examples/gaussian.md new file mode 100644 index 0000000..437ff03 --- /dev/null +++ b/docs/src/examples/gaussian.md @@ -0,0 +1,169 @@ +# Gaussian Examples + +All examples locate the triplet/singlet (S=3 / S=1) MECP of the phenylcation +(C₆H₅⁺, charge = 1). See [Overview](overview.md) for the geometry and how to +run. + +--- + +## Example 1 — Default GDIIS + +The simplest production-ready input. Uses the default GDIIS optimizer with +3 warm-up BFGS steps. + +``` +nprocs = 10 +mem = 40GB +method = n b3lyp/6-31g** +charge = 1 +mult_a = 3 +mult_b = 1 +mode = normal +program = gaussian + +*geom +C 0.000000000000 1.396613000000 0.000000000000 +C 1.209503000000 0.698307000000 0.000000000000 +C 1.209503000000 -0.698307000000 0.000000000000 +C 0.000000000000 -1.396613000000 0.000000000000 +C -1.209503000000 -0.698307000000 0.000000000000 +C -1.209503000000 0.698307000000 0.000000000000 +H 2.150882000000 1.241812000000 0.000000000000 +H 2.150882000000 -1.241812000000 0.000000000000 +H 0.000000000000 -2.483625000000 0.000000000000 +H -2.150882000000 -1.241812000000 0.000000000000 +H -2.150882000000 1.241812000000 0.000000000000 +* + +*tail_a +* + +*tail_b +* +``` + +**Key settings**: `switch_step = 3` (default), `hessian = direct_psb` +(default), `use_gediis = false` (default). + +--- + +## Example 2 — Sequential Hybrid (GEDIIS → GDIIS) + +Activates the 3-phase switching strategy of Li & Frisch (*JCTC* 2006). Adds +only two lines to Example 1 and typically converges ~2–4× faster. + +``` +nprocs = 10 +mem = 40GB +method = n b3lyp/6-31g** +charge = 1 +mult_a = 3 +mult_b = 1 +mode = normal +program = gaussian + +# --- optimizer --- +use_gediis = true +use_hybrid_gediis = true + +*geom +C 0.000000000000 1.396613000000 0.000000000000 +C 1.209503000000 0.698307000000 0.000000000000 +C 1.209503000000 -0.698307000000 0.000000000000 +C 0.000000000000 -1.396613000000 0.000000000000 +C -1.209503000000 -0.698307000000 0.000000000000 +C -1.209503000000 0.698307000000 0.000000000000 +H 2.150882000000 1.241812000000 0.000000000000 +H 2.150882000000 -1.241812000000 0.000000000000 +H 0.000000000000 -2.483625000000 0.000000000000 +H -2.150882000000 -1.241812000000 0.000000000000 +H -2.150882000000 1.241812000000 0.000000000000 +* + +*tail_a +* + +*tail_b +* +``` + +**Phase behaviour**: starts with GDIIS, switches to GEDIIS when +`rms_grad ≤ gediis_switch_rms` (0.005 Ha/Å), then back to GDIIS for the +final quadratic convergence when `rms_disp < gediis_switch_step` (0.001 Å). + +--- + +## Example 3 — GDIIS_blend with Trust Radius + +Uses the `blend` optimizer with the `fixed_sequential` blend mode and a live +trust radius. Suitable when the default GDIIS takes excessively large or +oscillating steps. + +``` +nprocs = 10 +mem = 40GB +method = n b3lyp/6-31g** +charge = 1 +mult_a = 3 +mult_b = 1 +mode = normal +program = gaussian + +# --- optimizer --- +use_gediis = blend +use_hybrid_gediis = true +gediis_blend_mode = fixed_sequential + +*geom +C 0.000000000000 1.396613000000 0.000000000000 +C 1.209503000000 0.698307000000 0.000000000000 +C 1.209503000000 -0.698307000000 0.000000000000 +C 0.000000000000 -1.396613000000 0.000000000000 +C -1.209503000000 -0.698307000000 0.000000000000 +C -1.209503000000 0.698307000000 0.000000000000 +H 2.150882000000 1.241812000000 0.000000000000 +H 2.150882000000 -1.241812000000 0.000000000000 +H 0.000000000000 -2.483625000000 0.000000000000 +H -2.150882000000 -1.241812000000 0.000000000000 +H -2.150882000000 1.241812000000 0.000000000000 +* + +*tail_a +* + +*tail_b +* +``` + +**Blend behaviour**: 50 % GDIIS + 50 % EDIIS far from convergence, transitions +to pure GDIIS for the final steps. Trust radius contracts when energy rises +and expands when energy falls. + +> **Note**: `blend` mode requires a direct Hessian method +> (`hessian = direct_psb`, `bofill`, `powell`, or `bfgs_powell_mix`). +> `inverse_bfgs` is incompatible. + +--- + +## Real-World Example — Cu Complex with Solvent + +For a larger, more demanding system the `to-4-tep-1` examples in +`examples/gaussian/` show a 29-atom Cu complex optimised at the +ωB97X-D/def2-SVP level with SMD solvation in benzene: + +``` +nprocs = 48 +mem = 190GB +method = n scf(maxcycle=300,xqc) UWB97XD/DEF2SVPP scrf(smd,solvent=Benzene) +charge = 1 +mult_a = 3 +mult_b = 1 +mode = normal +program = gaussian +use_gediis = blend +use_hybrid_gediis = true +gediis_blend_mode = fixed_sequential +``` + +The geometry is read from the external file `to-4-tep-1-blend-gdiis.xyz` +(included in the repository) via `*geom\n@to-4-tep-1-blend-gdiis.xyz\n*`. diff --git a/docs/src/examples/orca.md b/docs/src/examples/orca.md new file mode 100644 index 0000000..41b42c0 --- /dev/null +++ b/docs/src/examples/orca.md @@ -0,0 +1,135 @@ +# ORCA Examples + +All examples locate the triplet/singlet (S=3 / S=1) MECP of the phenylcation +(C₆H₅⁺, charge = 1). See [Overview](overview.md) for the geometry and how to +run. + +> **ORCA memory**: pass the `MaxCore` value in MB, not the total job memory. +> For example, `mem = 4000` means 4 000 MB per core. + +--- + +## Example 1 — Default GDIIS + +``` +nprocs = 10 +mem = 4000 +method = B3LYP 6-31G(d,p) VeryTightSCF +charge = 1 +mult_a = 3 +mult_b = 1 +mode = normal +program = orca +orca_comm = orca + +*geom +C 0.000000000000 1.396613000000 0.000000000000 +C 1.209503000000 0.698307000000 0.000000000000 +C 1.209503000000 -0.698307000000 0.000000000000 +C 0.000000000000 -1.396613000000 0.000000000000 +C -1.209503000000 -0.698307000000 0.000000000000 +C -1.209503000000 0.698307000000 0.000000000000 +H 2.150882000000 1.241812000000 0.000000000000 +H 2.150882000000 -1.241812000000 0.000000000000 +H 0.000000000000 -2.483625000000 0.000000000000 +H -2.150882000000 -1.241812000000 0.000000000000 +H -2.150882000000 1.241812000000 0.000000000000 +* + +*tail_a +* + +*tail_b +* +``` + +**Key settings**: default GDIIS, `hessian = direct_psb`, `switch_step = 3`. + +> On HPC systems, set `orca_comm` to the full path of the ORCA binary, e.g.: +> ``` +> orca_comm = /apps/orca/6.1.1/orca +> ``` + +--- + +## Example 2 — GDIIS_blend with Gradient-Based Weight + +Uses `use_gediis = blend` with `gediis_blend_mode = gradient`. The blend weight +$w$ varies smoothly as $w = \text{RMS}_g / (\text{RMS}_g + \text{switch\_rms})$, +so the optimizer is EDIIS-heavy far from convergence and GDIIS-heavy close to it. + +``` +nprocs = 10 +mem = 4000 +method = B3LYP 6-31G(d,p) VeryTightSCF +charge = 1 +mult_a = 3 +mult_b = 1 +mode = normal +program = orca +orca_comm = orca + +# --- optimizer --- +use_gediis = blend +use_hybrid_gediis = true +gediis_blend_mode = gradient + +*geom +C 0.000000000000 1.396613000000 0.000000000000 +C 1.209503000000 0.698307000000 0.000000000000 +C 1.209503000000 -0.698307000000 0.000000000000 +C 0.000000000000 -1.396613000000 0.000000000000 +C -1.209503000000 -0.698307000000 0.000000000000 +C -1.209503000000 0.698307000000 0.000000000000 +H 2.150882000000 1.241812000000 0.000000000000 +H 2.150882000000 -1.241812000000 0.000000000000 +H 0.000000000000 -2.483625000000 0.000000000000 +H -2.150882000000 -1.241812000000 0.000000000000 +H -2.150882000000 1.241812000000 0.000000000000 +* + +*tail_a +* + +*tail_b +* +``` + +--- + +## TD-DFT with State Selection + +For excited-state MECPs, add `%tddft` blocks in the tail sections and set +`state_a` / `state_b` to select which excited state to track: + +``` +nprocs = 10 +mem = 4000 +method = B3LYP def2-SVP VeryTightSCF +charge = 0 +mult_a = 1 +mult_b = 1 +state_a = 1 +state_b = 2 +mode = normal +program = orca +orca_comm = orca + +*geom +... +* + +*tail_a +%tddft + nroots 5 + iroot 1 +end +* + +*tail_b +%tddft + nroots 5 + iroot 2 +end +* +``` diff --git a/docs/src/examples/overview.md b/docs/src/examples/overview.md new file mode 100644 index 0000000..e5fd0f0 --- /dev/null +++ b/docs/src/examples/overview.md @@ -0,0 +1,68 @@ +# Examples Overview + +This section provides complete, ready-to-run examples for locating MECPs with +OpenMECP. All examples are also available in the `examples/` directory of the +repository. + +## Test System: Phenylcation (C₆H₅⁺) + +The primary test case used throughout these examples is the **phenylcation**, +a well-studied 11-atom aromatic cation. The goal is to locate the minimum +energy crossing point between the **triplet (S = 3)** and **open-shell singlet +(S = 1)** spin states. + +This system is an excellent benchmark: it is small enough for rapid testing on +any hardware, yet exercises all parts of the MECP optimizer, including +gradient combination, Hessian updates, and DIIS extrapolation. + +### Geometry + +Save the following as `phenylcation.xyz` (or embed it directly in the +`*geom` section of your input): + +``` +11 + +C 0.000000000000 1.396613000000 0.000000000000 +C 1.209503000000 0.698307000000 0.000000000000 +C 1.209503000000 -0.698307000000 0.000000000000 +C 0.000000000000 -1.396613000000 0.000000000000 +C -1.209503000000 -0.698307000000 0.000000000000 +C -1.209503000000 0.698307000000 0.000000000000 +H 2.150882000000 1.241812000000 0.000000000000 +H 2.150882000000 -1.241812000000 0.000000000000 +H 0.000000000000 -2.483625000000 0.000000000000 +H -2.150882000000 -1.241812000000 0.000000000000 +H -2.150882000000 1.241812000000 0.000000000000 +``` + +## How to Run + +```bash +omecp input.inp > output.log +``` + +OpenMECP writes a summary line to stdout at each step. Key fields: + +| Column | Meaning | +|---|---| +| `Step` | Iteration number | +| `ΔE` | Energy difference between the two states (target: → 0) | +| `RMS grad` | RMS effective gradient (target: < `rms_grad` threshold) | +| `RMS disp` | RMS Cartesian displacement from previous step | +| `Max disp` | Largest single atomic displacement | + +## Output Files + +| File | Contents | +|---|---| +| `{basename}_mecp.xyz` | Final optimized MECP geometry | +| `running_dir/` | All intermediate QM input/output files | +| `{basename}_omecp_debug.log` | Step-by-step debug log (if `file_logging = true`) | + +## Available Examples + +| Page | System | Program | Optimizer | +|---|---|---|---| +| [Gaussian Examples](gaussian.md) | C₆H₅⁺ | Gaussian | GDIIS, Sequential Hybrid, GDIIS_blend | +| [ORCA Examples](orca.md) | C₆H₅⁺ | ORCA | GDIIS, GDIIS_blend |