ORCA Backend
============

ORCA is a quantum-chemistry backend available through PyAR for calculations
where you want a higher-level electronic-structure method than xTB or a
machine-learning potential.

When to use ORCA
----------------

Use ``orca`` when:

* ORCA is installed and available on your system
* you want DFT-style optimisation or refinement
* you want to refine structures generated by cheaper PyAR searches
* you have validated a small test calculation with your chosen method and basis

Example command
---------------

Reaction search using the registered ORCA energy-gradient route:

.. code-block:: bash

   pyar-cli react A.xyz B.xyz -N 8 -gmin 100 -gmax 1000 --software orca --method B3LYP --basis def2-SVP

Practical notes
---------------

* ORCA must be installed separately and available to PyAR.
* Use a small test molecule first to confirm that the executable, method, basis,
  charge, multiplicity, and gradient output are handled correctly on your
  machine.
* ORCA calculations are usually much slower than xTB or ML-potential runs. For
  exploration, it is often better to generate candidates with xTB/AIMNet2 and
  then refine selected structures with ORCA.

AFIR/geomeTRIC status
---------------------

``orca`` is wired as a registered energy-gradient provider for the
geomeTRIC-backed AFIR reaction route. This means PyAR can construct a combined
``ORCA energy/gradient + AFIR bias`` objective for geomeTRIC. Local validation
is still required because ORCA setup depends on the installed executable and
calculation environment.