..
    : 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_gpu:

GPU Acceleration
################

PyBEST can offload selected tensor contractions to an NVIDIA GPU
using either `CuPy <https://cupy.dev>`_ or `PyTorch <https://pytorch.org>`_.
Both libraries must be installed separately — they are not included in the default
PyBEST installation.

If you use GPU acceleration in PyBEST, please cite [kriebel2024]_ and [dobrowolska2026]_.

.. note::

    GPU acceleration applies to tensordot-based contractions only.
    All other contractions are still executed on the CPU.
    If the arrays do not fit in GPU memory despite automatic batching,
    PyBEST falls back to the CPU.

Environment variables
=====================

All GPU settings are configured via environment variables before starting Python.

Selecting a backend
-------------------

To enable a backend, set the corresponding variable to a non-empty value.
To disable it, the variable must be empty or unset.

.. code-block:: bash

    # Enable CuPy backend
    export PYBEST_CUPY_AVAIL=1

    # Disable CuPy backend (variable must be empty)
    export PYBEST_CUPY_AVAIL=

    # Enable PyTorch backend
    export PYBEST_PYTORCH_AVAIL=1

    # Disable PyTorch backend (variable must be empty)
    export PYBEST_PYTORCH_AVAIL=

Both variables can be set at the same time; CuPy will be preferred when both
are available.



Selecting a batching strategy
-----------------------------


For Cholesky-based contractions that do not fit in GPU memory, PyBEST splits
the arrays into smaller batches. Two strategies are available. Exactly one
variable must be set to a non-empty value; the other must be empty.

.. code-block:: bash

    # C-splitting: batch along the Cholesky index (default)
    export PYBEST_C_SPLITTING=1
    export PYBEST_X_SPLITTING=

    # X-splitting: batch along the auxiliary (x) index
    export PYBEST_C_SPLITTING=
    export PYBEST_X_SPLITTING=1

If neither variable is set, or both are set simultaneously, PyBEST defaults to
C-splitting.