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

catgo_view(action: "get_state")

2. Find the Expanse session_id

Session IDs are volatile — they change on every reconnect. Discover the current one:

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)

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).

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.

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):

"params": {"method": "B3LYP", "basis": "def2-TZVP", "dispersion": "D3BJ", "charge": 0, "multiplicity": 1}

For D4 (newer Grimme correction, slightly better for metals):

"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):

"params": {"method": "B3LYP", "basis": "def2-TZVP", "opt_convergence": "TightOpt", "dispersion": "D3BJ", "charge": 0, "multiplicity": 1}

For open-shell radicals:

"params": {"method": "UB3LYP", "basis": "def2-SVP", "charge": 0, "multiplicity": 2}

7. Monitor

catgo_workflow(action: "status", workflow_id: "<wf_id>")

Or query SLURM directly via the live session:

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):

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.

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.

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 `![Opt energy convergence](local_run/opt_energy.png)`

After running this, reply to the user with the markdown link the script printed (e.g. ![Opt energy convergence](local_run/opt_energy.png)) 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