Hello-QM/catgo-LRG / .claude/skills/orca-opt
orca-opt
VerifiedORCA geometry optimization. Handles method/basis selection, dispersion corrections, solvent models, and convergence settings.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.7 KB |
SKILL.md
View on GitHub---
name: orca-opt
description: ORCA geometry optimization. Handles method/basis selection, dispersion corrections, solvent models, and convergence settings.
---
# ORCA Geometry Optimization Skill
## When to Use
Use this skill when the user wants to:
- Optimize a molecular geometry with ORCA
- Find the minimum energy structure of a molecule
- Relax a molecular cluster or complex
Do NOT use for periodic systems (use VASP or CP2K instead).
## Node Parameters (canonical names — these are what the engine actually reads)
| Parameter | Default | Description |
|---|---|---|
| `method` | B3LYP | DFT functional (e.g. `B3LYP`, `PBE0`, `wB97X-D4`, `r2SCAN-3c`) |
| `basis` | def2-SVP | Basis set (omit for composite methods like `r2SCAN-3c`) |
| `charge` | 0 | Total charge |
| `multiplicity` | 1 | Spin multiplicity (2S+1) |
| `dispersion` | (none) | `D4` \| `D3BJ` \| `D3` \| `none`. **Put D4/D3BJ HERE, not in `method`.** |
| `three_body_dispersion` | false | Adds ABC term (D3-class only; ignored for D4) |
| `grid` | DefGrid2 | `DefGrid1/2/3` — emitted only when ≠ default |
| `wavefunction` | (none) | e.g. `UKS` for unrestricted |
| `uno`, `uco` | false | Unrestricted natural / corresponding orbital tweaks |
| `num_cores` | 4 | `%pal nprocs` |
| `max_core_mb` | 4000 | `%maxcore` |
| `opt_convergence` | (none) | e.g. `TightOpt`, `VeryTightOpt` |
> ⚠️ **`extra_keywords` and `extra_blocks` are NOT read by the ORCA workflow engine.** Earlier versions of this skill recommended them; anything passed via those keys is silently dropped. Use the dedicated fields above. CPCM solvation, `SlowConv`/`SOSCF`, and `NumFreq` currently have no first-class field on the opt/freq/neb_ts/irc nodes — that is a node-def gap, not a usage problem.
## MCP Tool Examples — proven Expanse submission flow
> **Use `catgo_workflow` (graph-based), NOT `catgo_workflow_engine` (task-based).**
> The graph-based tool auto-captures the viewer structure on `create`. The task-based
> tool's `add_task` does not, so jobs fail with "No input structure provided".
> Param keys differ too: graph-based uses `method`/`basis`, task-based uses
> `orca_method`/`orca_basis`.
### 1. Confirm structure is loaded
```json
catgo_view(action: "get_state")
```
### 2. Find the Expanse session_id
Session IDs are volatile — they change on every reconnect. Discover the current one:
```bash
curl -s http://localhost:8000/api/hpc/connections
```
Look for the entry with `host: login.expanse.sdsc.edu` and copy its `session_id`.
### 3. Create the workflow (auto-captures viewer structure)
```json
catgo_workflow(action: "create", name: "Benzene optimization")
```
Returns a workflow with one `structure_input` node containing the current viewer
structure. Note its node ID (e.g., `n1777012885-iode`).
### 4. Add the geo_opt node and connect it
Inject `extra_blocks: "%output jsongbwfile True jsonpropfile True end"` so ORCA
emits the JSON files OPI parses on the way back. Without this, OPI parsing
falls back to grepping `ORCA.out` (still works, just less rich).
```json
catgo_workflow(action: "batch", workflow_id: "<wf_id>", operations: [
{"op": "add_node", "node_type": "geo_opt", "label": "opt",
"params": {
"software": "orca",
"method": "B3LYP",
"basis": "def2-SVP",
"charge": 0,
"multiplicity": 1,
"extra_blocks": "%output jsongbwfile True jsonpropfile True end"
}},
{"op": "connect", "from_id": "<structure_input_id>", "to_id": "opt",
"from_handle": "structure", "to_handle": "structure"}
])
```
### 5. Run with the full HPC run_config
Real opt jobs on non-trivial molecules can run for hours — default to
`partition: "shared"` with a generous walltime. Use `debug` only for tiny
sanity checks (≤ a couple of heavy atoms, single-point or quick test). Read
`server/templates/orca_generic.sh` and pass its contents as `default_template`.
```json
catgo_workflow(action: "run", workflow_id: "<wf_id>", run_config: {
"execution_mode": "hpc",
"default_session_id": "<expanse_session_id>",
"base_work_dir": "/expanse/lustre/projects/sdp126/jyang25/ORCA/catgo",
"default_job_params": {
"nodes": 1, "ntasks": 8, "cpus_per_task": 1,
"walltime": "04:00:00", "partition": "shared"
},
"cluster_configs": {
"<expanse_session_id>": {
"account": "sdp126",
"partition": "shared",
"module_loads": "module load cpu/0.17.3b\nmodule load gcc/10.2.0/npcyll4\nexport PATH=$HOME/openmpi-4.1.8/bin:$PATH\nexport LD_LIBRARY_PATH=$HOME/openmpi-4.1.8/lib:$LD_LIBRARY_PATH",
"orca_dir": "/home/jyang25/orca_6_1_1_RRP8",
"default_template": "<contents of server/templates/orca_generic.sh>",
"default_job_params": {
"nodes": 1, "ntasks": 8, "cpus_per_task": 1,
"walltime": "04:00:00", "partition": "shared"
}
}
}
})
```
For a quick sanity check (e.g., H2O / methane / single small molecule),
override to `partition: "debug"`, `walltime: "00:30:00"`, `ntasks: 4`. The
debug partition caps at 30 min — anything bigger will be rejected after the
limit.
The local-scratch template stages I/O to `$TMPDIR/orca_$SLURM_JOB_ID` and copies
results back to the Lustre work_dir. Required on Expanse — Lustre is bad for
ORCA's many small temp files.
### 6. Common parameter variations
For dispersion (non-covalent systems, dimers, π-stacking, H-bonding):
```json
"params": {"method": "B3LYP", "basis": "def2-TZVP", "dispersion": "D3BJ", "charge": 0, "multiplicity": 1}
```
For D4 (newer Grimme correction, slightly better for metals):
```json
"params": {"method": "B3LYP", "basis": "def2-SVP", "dispersion": "D4", "charge": 0, "multiplicity": 1}
```
For implicit solvation:
> CPCM is currently a node-def gap on opt/freq/neb_ts/irc — there's no first-class `solvation`/`solvent` field, and `extra_keywords` is not read. UV-Vis is the exception (it has dedicated `solvation`/`solvent` fields). Until this is fixed, single-point CPCM on a gas-phase optimized geometry, or running on a non-CatGo input file, is the workaround.
For tight convergence (publication quality, pre-freq):
```json
"params": {"method": "B3LYP", "basis": "def2-TZVP", "opt_convergence": "TightOpt", "dispersion": "D3BJ", "charge": 0, "multiplicity": 1}
```
For open-shell radicals:
```json
"params": {"method": "UB3LYP", "basis": "def2-SVP", "charge": 0, "multiplicity": 2}
```
### 7. Monitor
```json
catgo_workflow(action: "status", workflow_id: "<wf_id>")
```
Or query SLURM directly via the live session:
```bash
curl -s "http://localhost:8000/api/hpc/jobs/<job_id>?session_id=<expanse_session_id>"
```
### 8. Pull results when COMPLETED
Pull the ORCA outputs into a local directory, including the OPI JSON files
(`*.property.json` is the rich structured output OPI parses):
```bash
mkdir -p ./local_run
for f in ORCA.out ORCA.xyz ORCA.engrad ORCA.property.json ORCA.json; do
curl -s -X POST http://localhost:8000/api/hpc/files/read-content \
-H 'Content-Type: application/json' \
-d "{\"session_id\":\"<expanse_session_id>\",\"file_path\":\"<work_dir>/$f\"}" \
> ./local_run/$f
done
```
`ORCA.json` and `ORCA.property.json` only exist if the input had the
`%output jsongbwfile True jsonpropfile True end` block (step 4). If you
omitted it, OPI parsing falls back to grepping `ORCA.out`.
### 9. Parse with OPI
Replaces hand-walking `ORCA.xyz` / `ORCA.engrad`. Requires `pip install orca-pi`.
```python
import sys
sys.path.insert(0, ".claude/skills") # for the _shared helper
from _shared.orca_opi import parse_local
out = parse_local("./local_run")
print("SCF converged: ", out.scf_converged())
print("Geometry converged: ", out.geometry_optimization_converged())
print("Final energy (Eh): ", out.get_final_energy())
print("Optimized XYZ:\n", out.get_structure().to_xyz_block())
# Per-step trajectory (energy curve)
for i, geom in enumerate(out.results_properties.geometries):
print(i, geom.single_point_data.finalenergy)
# Population analyses (any of these are one call now)
mulliken = out.get_mulliken()
print("HOMO/LUMO/gap (eV):", out.get_homo(), out.get_lumo(), out.get_hl_gap())
```
### Viewing the optimization curve in the IDE
Use the shared helper to plot per-step energies and surface the PNG inline.
```python
from _shared.orca_opi import quick_plot_opt_energy, show_png
png = quick_plot_opt_energy(out) # writes ./local_run/opt_energy.png
show_png(png, "Opt energy convergence") # prints ``
```
After running this, **reply to the user with the markdown link** the script printed (e.g. ``) so Claude Code renders the figure inline in chat.
### Submission gotchas (real failures we hit)
- `catgo_workflow_engine.add_task` doesn't auto-attach the viewer structure → "No input structure provided".
- `partition=workq` (Shaheen default) is invalid on Expanse → use `debug` or `shared`.
- Missing `account=sdp126` → "Invalid account or account/partition combination".
- Missing `module_loads` + `orca_dir` → `orca` not on PATH, job runs ORCA-not-found and silently produces nothing.
- After re-connecting to Expanse, the session_id changes — re-discover via `/api/hpc/connections` and update `default_session_id` + `cluster_configs` key.
- Engine doesn't regenerate `submit.sh` on `retry` alone — call `run` with the new `run_config` to get a fresh script with updated SBATCH headers.
## Dispersion Corrections
| Keyword | Method | When to use |
|---|---|---|
| `D3BJ` | Grimme D3 with Becke-Johnson damping | Default choice for dispersion |
| `D3` | Grimme D3 with zero damping | Legacy, use D3BJ instead |
| `D4` | Grimme D4 | Newer, slightly better for metals |
Always include dispersion for: molecular dimers, adsorption complexes,
conformational searches, anything with pi-stacking or H-bonding.
## Basis Set Ladder
| Basis | Quality | Cost | Use |
|---|---|---|---|
| def2-SVP | Double-zeta | Low | Screening, initial opt |
| def2-TZVP | Triple-zeta | Medium | Production geometry |
| def2-TZVPP | Triple-zeta+pol | High | Accurate energetics |
| def2-QZVPP | Quadruple-zeta | Very high | Benchmark only |
Strategy: optimize with def2-SVP, then single-point with def2-TZVP for energy.
## SCF Convergence Issues
ORCA SCF tweaks like `SlowConv`, `VerySlowConv`, `SOSCF`, `SmearTemp 5000` are not exposed as first-class node params (gap in the engine). For now: pre-optimize with a smaller basis (def2-SVP) and feed that geometry to a larger-basis run, or run ORCA directly on a hand-edited input file outside the workflow engine.
## Common Mistakes
- Forgetting dispersion for non-covalent systems (huge geometry errors)
- Using restricted (R) method for open-shell (use UB3LYP, not B3LYP)
- Basis set too large for optimization (optimize with SVP, refine energy with TZVP)
- Not checking for imaginary frequencies after optimization
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |