Examples in docs

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)

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*`.

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
+*
+```

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 |