Chem Dft Orca Optimization

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

# 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

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

# 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

# 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
• Unsleber, J.P. et al., "SCINE—Software for Chemical Interaction Networks", J. Chem. Phys., 2024. DOI

---

Author: Miguel Steiner Contact: GitHub @steinmig

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: learningmatter-mit
• Source: learningmatter-mit/AtomisticSkills
• License: MIT
• Homepage: https://arxiv.org/abs/2605.24002

Install and usage instructions live in the source repository linked above.