chem-dft-orca-optimization

---
name: chem-dft-orca-optimization
description: Run DFT geometry optimization (minimization or TS search) on a molecular structure using ORCA via SCINE/ReaDuct wrapper.
category: [chemistry]
---

# DFT Geometry Optimization with ORCA

## Goal

Optimize the geometry of a molecular structure at the DFT level using the ORCA quantum chemistry program. Supports two modes: **minimization** (finding the nearest local minimum) and **transition state (TS) optimization** (single-ended saddle point search). The calculation uses the SCINE/ReaDuct wrapper for robust optimizer management.

> [!IMPORTANT]
> This skill provides **single-ended TS optimization** only. For reaction pathway methods (NEB, IRC), consider using the MLIP-based [NEB skill](../chem-neb-barrier/SKILL.md) or [IRC skill](../chem-irc-verification/SKILL.md) with MLIP pre-screening, then refine with DFT. For advanced ORCA features, use the [advanced ORCA skill](../chem-dft-orca-advanced-calculation/SKILL.md).

## Background

Geometry optimization iteratively adjusts nuclear positions to minimize (or, for TS search, to find a first-order saddle point of) the potential energy surface $E(\mathbf{R})$. The SCINE/ReaDuct optimizer handles step control, coordinate transformations, and convergence criteria internally.

- **Minimization** seeks a stationary point where $\nabla E = 0$ and the Hessian has all positive eigenvalues.
- **TS optimization** seeks a first-order saddle point where $\nabla E = 0$ and the Hessian has exactly one negative eigenvalue.

## 1. Prerequisites

- **Conda environment:** `orca-agent` with `scine_utilities`, `scine_readuct`, and `ase` installed
- **ORCA binary:** The environment variable `ORCA_BINARY_PATH` must point to the ORCA executable
  ```bash
  export ORCA_BINARY_PATH=/path/to/orca
  ```
- **Input structure:** A molecular structure file readable by ASE (`.xyz`, `.cif`, `.mol`, etc.)
- For **TS optimization:** Provide a reasonable TS guess geometry. Poor initial guesses will likely fail to converge to the correct saddle point.

## 2. Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `--structure` | (required) | Path to input structure file |
| `--opt_type` | `min` | `min` for minimization, `ts` for transition state search |
| `--charge` | `0` | Molecular charge |
| `--spin_multiplicity` | `1` | Spin multiplicity (2S+1) |
| `--functional` | `PBE` | DFT functional (e.g. `PBE`, `B3LYP`, `wB97X-V`) |
| `--basis_set` | `def2-SVP` | Basis set (e.g. `def2-SVP`, `def2-TZVP`) |
| `--dispersion` | None | Dispersion correction (e.g. `D3BJ`, `D4`) |
| `--solvation` | None | Implicit solvation model: `CPCM` or `SMD` |
| `--solvent` | None | Solvent name; required if `--solvation` is set |
| `--special_option` | `NOSOSCF` | ORCA special option passed to SCINE calculator. Set to empty string to disable. |
| `--nprocs` | `1` | Number of CPU cores for ORCA |
| `--convergence_max_iterations` | `200` | Maximum optimization steps |
| `--calculate_final_hessian` | off | Compute Hessian at optimized geometry (for TS verification) |
| `--calculator_settings` | None | Extra SCINE calculator settings as a JSON string (see below) |
| `--optimizer_settings` | None | Extra ReaDuct optimizer kwargs as a JSON string (see below) |
| `--output_dir` | auto | Output directory |

## 3. Running an Optimization

### Geometry minimization

```bash
# Env: orca-agent
python .agent/skills/chem-dft-orca-optimization/scripts/run_optimization.py \
    --structure molecule.xyz \
    --functional B3LYP \
    --basis_set def2-TZVP \
    --dispersion D3BJ \
    --nprocs 4 \
    --output_dir research/my_project/optimization
```

### Transition state optimization

```bash
# Env: orca-agent
python .agent/skills/chem-dft-orca-optimization/scripts/run_optimization.py \
    --structure ts_guess.xyz \
    --opt_type ts \
    --functional B3LYP \
    --basis_set def2-TZVP \
    --dispersion D3BJ \
    --calculate_final_hessian \
    --nprocs 4 \
    --output_dir research/my_project/ts_optimization
```

### With extra settings (calculator + optimizer)

For settings not exposed as dedicated flags, pass JSON strings. `--calculator_settings` applies to the SCINE/ORCA calculator, `--optimizer_settings` applies to the ReaDuct optimization task. SCINE is strict about types, so JSON ensures values are passed with the correct type (int, float, string).

```bash
# Env: orca-agent
python .agent/skills/chem-dft-orca-optimization/scripts/run_optimization.py \
    --structure molecule.xyz \
    --functional B3LYP \
    --basis_set def2-TZVP \
    --calculator_settings '{"max_scf_iterations": 128}' \
    --optimizer_settings '{"convergence_delta_value": 1e-6}' \
    --output_dir research/my_project/opt_custom
```

### With implicit solvation

```bash
# Env: orca-agent
python .agent/skills/chem-dft-orca-optimization/scripts/run_optimization.py \
    --structure molecule.xyz \
    --functional PBE0 \
    --basis_set def2-TZVP \
    --solvation SMD \
    --solvent water \
    --nprocs 4 \
    --output_dir research/my_project/opt_solvated
```

## 4. Output Files

- `optimization_results.json`: Structured results containing:
  - `converged`: Boolean indicating whether the optimization converged
  - `final_energy_hartree`, `final_energy_eV`: Final electronic energy
  - `final_max_force_eV_per_Ang`, `final_rms_force_eV_per_Ang`: Residual force information
  - `opt_type`: Whether this was a minimization or TS search
  - If `--calculate_final_hessian` was used: `hessian_eV_per_Ang2`, `hessian_wave_numbers_cm-1`, and `n_imaginary_modes`
  - All input parameters for reproducibility
- `initial_structure.xyz`: Copy of the input structure
- `optimized_structure.xyz`: The optimized geometry

## 5. Interpreting Results

### Minimization
- Check `converged: true` in the results JSON.
- Residual forces should be small (max force < 0.01 eV/A for typical convergence).
- If convergence fails, try increasing `--convergence_max_iterations` or improving the initial geometry.

### TS Optimization
- Convergence alone does not guarantee a valid TS. After convergence, verify the Hessian has exactly one imaginary frequency:
  - **Recommended:** Use `--calculate_final_hessian` to compute the Hessian directly after optimization. The output will include `n_imaginary_modes` — expect exactly 1 for a valid TS.
  - Alternatively, run a separate single-point Hessian with the [singlepoint skill](../chem-dft-orca-singlepoint/SKILL.md) using `--compute_hessian`.
- Inspect the imaginary mode to confirm it corresponds to the expected reaction coordinate.
- If the optimizer converges to a minimum instead of a saddle point, the initial guess was likely too far from the true TS.

## 6. Constraints

- **Non-periodic systems only:** ORCA does not handle periodic boundary conditions.
- **Single-ended TS:** Only single-ended TS optimization is available. For double-ended methods (NEB), pre-screen with MLIPs.
- **TS guess quality:** The TS optimizer requires a reasonable initial guess. Generate one using constrained scans, interpolation, or MLIP-based TS search methods.
- **ORCA binary:** `ORCA_BINARY_PATH` must be set and point to a working ORCA installation.
- **Environment:** All commands require the `orca-agent` conda environment.
- **Solvation:** When using `--solvation`, you must also provide `--solvent`.

## References

- Neese, F., "Software update: The ORCA program system—Version 5.0", *WIREs Comput. Mol. Sci.*, 2022. [DOI](https://doi.org/10.1002/wcms.1606)
- Unsleber, J.P. et al., "SCINE—Software for Chemical Interaction Networks", *J. Chem. Phys.*, 2024. [DOI](https://doi.org/10.1063/5.0206974)

---

**Author:** Miguel Steiner
**Contact:** [GitHub @steinmig](https://github.com/steinmig)

More agent context in learningmatter-mit/AtomisticSkills

133 other files this repository gives its agents, the first 60 shown.