Examples in docs

[lenhanpham]

No description provided.

[Copilot]

Pull request overview

Adds a new "Examples" section to the mdBook documentation with an overview page and program-specific pages (Gaussian, ORCA) that walk users through ready-to-run MECP inputs for the phenylcation test system, plus a real-world Cu complex example.

Changes:

• Adds an "Examples" group to SUMMARY.md linking three new pages.
• New examples/overview.md describing the phenylcation test system, run instructions, expected output, and an example index.
• New examples/gaussian.md and examples/orca.md with three+ annotated inputs each covering default GDIIS, sequential hybrid, and GDIIS_blend variants.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
docs/src/SUMMARY.md	Adds Examples section with three sub-pages.
docs/src/examples/overview.md	New overview page: test system, geometry, run command, output explanation.
docs/src/examples/gaussian.md	New Gaussian examples (GDIIS, hybrid GEDIIS, blend, Cu complex).
docs/src/examples/orca.md	New ORCA examples (GDIIS, blend with gradient mode, TD-DFT).

Comments suppressed due to low confidence (4)

docs/src/examples/overview.md:53

• The columns listed here (Step, ΔE, RMS grad, RMS disp, Max disp) don't match the actual per-step output that OpenMECP prints. The convergence summary printed by print_convergence_status in src/main.rs (around lines 93–145) uses rows named "Energy difference", "RMS gradient", "Max gradient", "RMS displacement", "Max displacement" with columns "Criteria / Current / Threshold / Pass", and there is no single-line "Step" summary with those compact headers. Users following this guide will not find these column names in output.log, so the table should either be updated to reflect the real output, or marked as a conceptual summary.

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 |

docs/src/examples/gaussian.md:157

• The text describes the method as "ωB97X-D/def2-SVP" but the actual method line below (and in examples/gaussian/to-4-tep-1-blend-gdiis.inp) uses UWB97XD/DEF2SVPP, i.e. the def2-SVPP basis (def2-SVP with polarization on hydrogens), not plain def2-SVP. Either update the prose to "def2-SVPP" or change the method string to def2-SVP to keep them consistent.

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)

**docs/src/examples/gaussian.md:169**
* The final geometry-loading instruction shows the literal string `*geom\n@to-4-tep-1-blend-gdiis.xyz\n*`. As rendered, the `\n` characters appear verbatim rather than as newlines, which can mislead users into typing `\n` into the input file. Consider showing this as a multi-line fenced code block (with real line breaks) like the other examples on this page.

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:8**
* "mem = 4000 means 4 000 MB per core" uses a non-standard digit grouping with a space (and the same "4 000" appears in the explanatory prose). For an English technical document, prefer either no separator ("4000 MB") or a comma ("4,000 MB") to avoid confusing readers and to keep formatting consistent with the rest of the docs.

ORCA memory: pass the MaxCore value in MB, not the total job memory.
For example, mem = 4000 means 4 000 MB per core.

</details>



---

💡 <a href="/lenhanpham/OpenMECP/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.