.. _scipy-backend-options:

**************
SciPy keywords
**************

:doc:`Back to the backend overview <../backend>`

About this backend
==================

The ``scipy`` backend builds operators as SciPy
`CSR matrices <https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csr_matrix.html>`__.
``build_op`` and ``get_ops`` return labeled factories that construct these
matrices when called. Pass the factories to public ``ed``, ``xas``, and ``rixs``;
the primary Hamiltonian's ``.backend`` label selects SciPy. The backend calls
each supplied factory at calculation start, including repeated arguments.
See :ref:`lazy-operators`.

The backend-specific ``ed_scipy``, ``xas_scipy``, and ``rixs_scipy`` functions
also require factories. These can return NumPy arrays, SciPy sparse matrices,
or a matrix-free
`LinearOperator <https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.LinearOperator.html>`__.
ED uses SciPy's
`LOBPCG eigensolver <https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.lobpcg.html>`__;
XAS and RIXS use EDRIXS's Lanczos routines, and the RIXS correction-vector
step uses SciPy's
`GMRES solver <https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.gmres.html>`__.

XAS and RIXS use the lowest retained initial energy and the first incident
energy as internal references. Assuming the incident grid is near resonance,
this centers the intermediate Hamiltonian; RIXS also centers the final
Hamiltonian on the initial energy. Dense and sparse diagonals are shifted
before matrix-vector multiplication, without changing the input operators.
The public energy grids and returned RIXS pole energies retain their original
reference. Spectra are evaluated before restoring the pole energies.
For a custom ``LinearOperator``, shifting is necessarily applied after its
matrix-vector product and cannot recover precision lost inside that product.

Options are specific to the stage where they are supplied.

``build_op`` and ``get_ops``
============================

.. backend-options:: scipy get_ops

Here ``tol`` controls operator truncation.  It is separate from the
eigensolver tolerance accepted by ``ed``.

``ed``
======

.. backend-options:: scipy ed

``xas``
=======

.. backend-options:: scipy xas

``rixs``
========

.. backend-options:: scipy rixs

``linsys_tol`` sets GMRES's relative tolerance, passed as ``rtol`` (or ``tol``
in older SciPy). With the ``rtol`` API, EDRIXS sets the absolute tolerance
``atol`` to zero.