..
    : PyBEST: Pythonic Black-box Electronic Structure Tool
    : Copyright (C) 2016-- The PyBEST Development Team
    :
    : This file is part of PyBEST.
    :
    : PyBEST is free software; you can redistribute it and/or
    : modify it under the terms of the GNU General Public License
    : as published by the Free Software Foundation; either version 3
    : of the License, or (at your option) any later version.
    :
    : PyBEST is distributed in the hope that it will be useful,
    : but WITHOUT ANY WARRANTY; without even the implied warranty of
    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    : GNU General Public License for more details.
    :
    : You should have received a copy of the GNU General Public License
    : along with this program; if not, see <http://www.gnu.org/licenses/>
    : --


.. _user_geometry_intro:

Quick Guide
###########

The geometry optimization module provides an interface between PyBEST and the
geomeTRIC optimizer. PyBEST evaluates the electronic energy and analytic nuclear
gradient, while geomeTRIC updates the molecular geometry.

The current version of PyBEST supports geometry optimization for

    - restricted Hartree--Fock wave functions,
    - restricted orbital-optimized pCCD wave functions.

The corresponding classes are

    - :py:class:`~pybest.geometry.geometry_optimizer.RHFGeometryOptimizer`,
    - :py:class:`~pybest.geometry.geometry_optimizer.ROOpCCDGeometryOptimizer`.

If you use this module, please cite [behjou2026a]_.

Supported features
==================

The geometry optimization module currently supports

    - analytic RHF nuclear gradients,
    - analytic ROOpCCD nuclear gradients,
    - dense one- and two-electron integrals,
    - non-relativistic molecular Hamiltonians,
    - unconstrained geometry optimizations,
    - constrained geometry optimizations through geomeTRIC,
    - transition-state searches through geomeTRIC.

Current limitations
===================

The following features are currently not supported:

    - Cholesky-decomposed electron-repulsion integrals,
    - DKH Hamiltonians,
    - X2C Hamiltonians,
    - frozen-core ROOpCCD geometry optimizations.

.. _qg_geometry:

How to: geometry optimization
=============================

Similar to the previous modules, we assume the following names for PyBEST objects

    :lf:        A :py:class:`~pybest.linalg.base.LinalgFactory` instance.
    :occ_model: An occupation model containing the molecular basis and occupations.

For an RHF geometry optimization, initialize the optimizer as follows:

.. code-block:: python

    from pybest.geometry import RHFGeometryOptimizer

    optimizer = RHFGeometryOptimizer(
        lf,
        occ_model,
        maxiter=100,
    )

    result = optimizer()

The optimized Cartesian coordinates are stored in the returned
:py:class:`~pybest.io.iodata.IOData` container,

.. code-block:: python

    result.coordinates

For an ROOpCCD geometry optimization, use

.. code-block:: python

    from pybest.geometry import ROOpCCDGeometryOptimizer

    optimizer = ROOpCCDGeometryOptimizer(
        lf,
        occ_model,
        maxiter=100,
    )

    result = optimizer()

Wave-function keyword arguments
===============================

Wave-function-specific options can be forwarded through nested dictionaries.
For RHF calculations, use ``hf_kwargs``:

.. code-block:: python

    result = optimizer(
        hf_kwargs={
            "threshold": 1.0e-10,
            "maxiter": 128,
        }
    )

For ROOpCCD calculations, use ``hf_kwargs`` for the initial RHF calculation and
``pccd_kwargs`` for the ROOpCCD calculation:

.. code-block:: python

    result = optimizer(
        hf_kwargs={
            "threshold": 1.0e-10,
        },
        pccd_kwargs={
            "threshold": 1.0e-10,
            "localize": True,
        },
    )