From 89797280ad13bb60819802bf3f4125bab87771f7 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert Date: Mon, 2 Mar 2026 11:53:13 +0100 Subject: [PATCH 1/5] Add API reference for GauXC --- docs/conf.py | 2 + docs/gauxc/api/basis.rst | 432 +++++++++++++++++++++++++++++++++ docs/gauxc/api/cmake.rst | 181 ++++++++++++++ docs/gauxc/api/index.rst | 13 + docs/gauxc/api/macros.rst | 83 +++++++ docs/gauxc/api/molecule.rst | 234 ++++++++++++++++++ docs/gauxc/c-library.rst | 4 +- docs/gauxc/cpp-library.rst | 6 +- docs/gauxc/fortran-library.rst | 4 +- docs/gauxc/index.rst | 3 +- docs/gauxc/installation.rst | 130 ++-------- docs/gauxc/standalone.rst | 13 +- pyproject.toml | 2 + 13 files changed, 980 insertions(+), 127 deletions(-) create mode 100644 docs/gauxc/api/basis.rst create mode 100644 docs/gauxc/api/cmake.rst create mode 100644 docs/gauxc/api/index.rst create mode 100644 docs/gauxc/api/macros.rst create mode 100644 docs/gauxc/api/molecule.rst diff --git a/docs/conf.py b/docs/conf.py index bb395ad..501566c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,6 +10,8 @@ "sphinx_design", "sphinx.ext.autodoc", "sphinxcontrib.bibtex", + "sphinxcontrib.moderncmakedomain", + "sphinxfortran.fortran_domain", ] nb_execution_timeout = 300 # 5 minutes, set to -1 for no timeout diff --git a/docs/gauxc/api/basis.rst b/docs/gauxc/api/basis.rst new file mode 100644 index 0000000..b53ad72 --- /dev/null +++ b/docs/gauxc/api/basis.rst @@ -0,0 +1,432 @@ +GauXC Basis Set API +=================== + +This section provides a reference for the GauXC basis set API, including C++ class definitions, C struct definitions, and Fortran derived type definitions for representing basis sets and shells in GauXC. + +C++ definitions +--------------- + +.. cpp:struct:: template \ + GauXC::BasisSet : public std::vector> + + A class to represent a collection of shells in a basis set. + + .. cpp:function:: inline BasisSet(std::vector> shells) + + Construct a BasisSet object from a vector of Shell objects. + + :param shells: A vector of Shell objects representing the shells in the basis set. + :returns: A BasisSet object initialized with the given shells. + + .. cpp:function:: inline int32_t nshells() const + + Get the number of shells in the basis set. + + :returns: The number of shells in the basis set. + + .. cpp:function:: inline int32_t nbf() const + + Get the total number of basis functions in the basis set, calculated as the sum of the sizes of all shells. + + :returns: The total number of basis functions in the basis set. + + +.. cpp:class:: template \ + GauXC::Shell + + A class to represent a shell in a basis set, containing its angular momentum and a vector of primitives. + + .. cpp:type:: prim_array = std::array + + A type to represent an array of primitive exponents or coefficients in a shell. + + .. cpp:type:: cart_array = std::array + + A type to represent an array of Cartesian coordinates for the center of a shell. + + .. cpp:member:: PrimSize nprim_ + + The number of primitives in the shell. + + .. cpp:member:: AngularMomentum l_ + + The angular momentum of the shell. + + .. cpp:member:: SphericalType pure_ + + Whether the shell is pure (spherical) or Cartesian. + + .. cpp:member:: prim_array alpha_ + + The exponents of the primitives in the shell. + + .. cpp:member:: prim_array coeff_ + + The coefficients of the primitives in the shell. + + .. cpp:member:: cart_array O_ + + The Cartesian coordinates of the center of the shell. + + .. cpp:member:: double cutoff_radius_ + + The cutoff radius of the shell, defined as the maximum distance from the center of the shell at which the primitives have non-negligible contributions. + + .. cpp:member:: double tolerance_ + + The tolerance for pruning primitives in the shell. Primitives with coefficients below this value will be pruned. The default value is 1e-10. + + .. cpp:function:: inline void set_shell_tolerance(double tol) + + Set the tolerance for pruning primitives in the shell. + The default value for the tolerance is 1e-10. + + :param tol: The tolerance for pruning primitives. Primitives with coefficients below this value will be pruned. + + .. cpp:function:: inline PrimSize nprim() const + + Get the number of primitives in the shell. + + :returns: The number of primitives in the shell. + + .. cpp:function:: inline AngularMomentum l() const + + Get the angular momentum of the shell. + + :returns: The angular momentum of the shell. + + .. cpp:function:: inline SphericalType pure() const + + Get whether the shell is pure (spherical) or Cartesian. + + :returns: ``1`` if the shell is pure (spherical), ``0`` if the shell is Cartesian. + + .. cpp:function:: inline const F* alpha_data() const + + Get a pointer to the exponents of the primitives in the shell. + + :returns: A pointer to the exponents of the primitives in the shell. + + .. cpp:function:: inline const F* coeff_data() const + + Get a pointer to the coefficients of the primitives in the shell. + + :returns: A pointer to the coefficients of the primitives in the shell. + + .. cpp:function:: inline const double* O_data() const + + Get a pointer to the Cartesian coordinates of the center of the shell. + + :returns: A pointer to the Cartesian coordinates of the center of the shell. + + .. cpp::function:: inline F* alpha_data() + + Get a mutable pointer to the exponents of the primitives in the shell. + + :returns: A mutable pointer to the exponents of the primitives in the shell. + + .. cpp::function:: inline F* coeff_data() + + Get a mutable pointer to the coefficients of the primitives in the shell. + + :returns: A mutable pointer to the coefficients of the primitives in the shell. + + .. cpp::function:: inline double* O_data() + + Get a mutable pointer to the Cartesian coordinates of the center of the shell. + + :returns: A mutable pointer to the Cartesian coordinates of the center of the shell. + + .. cpp:function:: inline double cutoff_radius() const + + Get the cutoff radius of the shell, defined as the maximum distance from the center of the shell at which the primitives have non-negligible contributions. + + :returns: The cutoff radius of the shell. + + .. cpp:function:: inline int32_t cart_size() const + + Get the number of Cartesian functions in the shell. + + :returns: The number of Cartesian functions in the shell. + + .. cpp:function:: inline int32_t pure_size() const + + Get the number of pure (spherical) functions in the shell. + + :returns: The number of pure (spherical) functions in the shell. + + .. cpp:function:: inline int32_t size() const + + Get the total number of functions in the shell, based on whether the shell is pure (spherical) or Cartesian. + + :returns: The total number of functions in the shell. + + .. cpp:function:: inline prim_array& alpha() const + + Get the exponents of the primitives in the shell as an array. + + :returns: An array containing the exponents of the primitives in the shell. + + .. cpp:function:: inline prim_array& coeff() const + + Get the coefficients of the primitives in the shell as an array. + + :returns: An array containing the coefficients of the primitives in the shell. + + .. cpp:function:: inline cart_array& O() const + + Get the Cartesian coordinates of the center of the shell as an array. + + :returns: An array containing the Cartesian coordinates of the center of the shell. + + .. cpp:function:: inline prim_array& alpha() + + Get the exponents of the primitives in the shell as a mutable array. + + :returns: A mutable array containing the exponents of the primitives in the shell. + + .. cpp:function:: inline prim_array& coeff() + + Get the coefficients of the primitives in the shell as a mutable array. + + :returns: A mutable array containing the coefficients of the primitives in the shell. + + .. cpp:function:: inline cart_array& O() + + Get the Cartesian coordinates of the center of the shell as a mutable array. + + :returns: A mutable array containing the Cartesian coordinates of the center of the shell. + + .. cpp:function:: inline void set_pure(bool pure) + + Set whether the shell is pure (spherical) or Cartesian. + + :param pure: ``1`` to set the shell as pure (spherical), ``0`` to set the shell as Cartesian. + + .. cpp:function:: inline bool operator==(const Shell& other) const + + Compare this shell with another shell for equality. + + :param other: Another shell to compare with. + :returns: True if this shell is equal to the other shell, false otherwise. + + +.. cpp:type:: PrimSize = int32_t + + A type to represent the number of primitives in a shell. + +.. cpp:type:: AngularMomentum = int32_t + + A type to represent the angular momentum of a shell. + +.. cpp:type:: SphericalType = int32_t + + A type to represent whether a shell is pure (spherical) or Cartesian. + ``1`` indicates a pure (spherical) shell, while ``0`` indicates a Cartesian shell. + +C bindings +---------- + +.. c:struct:: GauXCBasisSet + + An opaque struct to represent a basis set in the C API. + + .. c:function:: GauXCBasisSet gauxc_basisset_new(GauXCStatus* status) + + Create a new GauXCBasisSet object. + + :param status: A pointer to a GauXCStatus variable to store the status of the operation. + :returns: A new GauXCBasisSet object. + + .. c:function:: GauXCBasisSet gauxc_basisset_new_from_shells(GauXCStatus* status, const GauXCShell* shells, int32_t nshells, bool normalize) + + Create a new GauXCBasisSet object from an array of GauXCShell objects. + + :param status: A pointer to a GauXCStatus variable to store the status of the operation. + :param shells: A pointer to an array of GauXCShell objects representing the shells in the basis set. + :param nshells: The number of shells in the array. + :param normalize: Whether to normalize the primitives in the shells when creating the basis set. + :returns: A new GauXCBasisSet object initialized with the given shells. + + .. c:function:: void gauxc_basisset_delete(GauXCStatus* status, GauXCBasisSet* basis) + + Delete a GauXCBasisSet object and free its associated memory. + + :param status: A pointer to a GauXCStatus variable to store the status of the operation. + :param basis: A pointer to the GauXCBasisSet object to be deleted. + +.. c:struct:: GauXCShell + + Representation of a shell in a basis set for the C API, containing its angular momentum, number of primitives, and pointers to arrays of primitive exponents, coefficients, and Cartesian coordinates. + + .. c:member:: int32_t l + + The angular momentum of the shell. + + .. c:member:: bool pure + + Whether the shell is pure (spherical) or Cartesian. + + .. c:member:: int32_t nprim + + The number of primitives in the shell. + + .. c:member:: double alpha[32] + + An array of exponents of the primitives in the shell. + + .. c:member:: double coeff[32] + + An array of coefficients of the primitives in the shell. + + .. c:member:: double O[3] + + An array of Cartesian coordinates for the center of the shell. + + .. c:member:: double shell_tolerance + + The tolerance for pruning primitives in the shell. + Primitives with coefficients below this value will be pruned. + The default value is 1e-10. + +Fortran bindings +---------------- + +.. f:module:: gauxc_basisset + :synopsis: Fortran bindings for the GauXC basis set API. + +.. f:currentmodule:: gauxc_basisset + +.. f:type:: gauxc_basisset_type + + Opaque type representing a basis set in the GauXC Fortran API. + Available from :f:mod:`gauxc_basisset`. + + .. f:function:: gauxc_basisset_new(status) + + Create a new gauxc_basisset_type object. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :returns type(gauxc_basisset_type): A new gauxc_basisset_type object. + + .. f:function:: gauxc_basisset_new_from_shells(status, shells, nshells, normalize) + + Create a new gauxc_basisset_type object from an array of gauxc_shell_type objects. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_shell_type) shells(*): An array of :f:type:`gauxc_shell_type` objects representing the shells in the basis set. + :param integer(c_int32_t) nshells: The number of shells in the array. + :param logical(c_bool) normalize: Whether to normalize the primitives in the shells when creating the basis set. + :returns type(gauxc_basisset_type): A new gauxc_basisset_type object initialized with the given shells. + +.. f:currentmodule:: gauxc_shell + +.. f:type:: gauxc_shell_type + + A derived type representing a shell in the GauXC Fortran API, containing its angular momentum, number of primitives, and arrays of primitive exponents, coefficients, and Cartesian coordinates. + + :f integer(c_int32_t) l: + The angular momentum of the shell. + + :f logical(c_bool) pure: + Whether the shell is pure (spherical) or Cartesian. + + :f integer(c_int32_t) nprim: + The number of primitives in the shell. + + :f real(c_double) alpha(32): + An array of exponents of the primitives in the shell. + + :f real(c_double) coeff(32): + An array of coefficients of the primitives in the shell. + + :f real(c_double) O(3): + An array of Cartesian coordinates for the center of the shell. + + :f real(c_double) shell_tolerance: + The tolerance for pruning primitives in the shell. + Primitives with coefficients below this value will be pruned. + The default value is 1e-10. + +Serialization to HDF5 +--------------------- + +If GauXC has been built with HDF5 support :c:macro:`GAUXC_HAS_HDF5`, the :cpp:class:`GauXC::BasisSet` class can be serialized to and deserialized from HDF5 files using the provided HDF5 interface. +This allows for easy storage and retrieval of basis set data in a standardized format. + +.. cpp:function:: void GauXC::write_hdf5_record(const BasisSet& basis, const std::string& filename, const std::string& group_name) + + Write a BasisSet object to an HDF5 file. + + :param basis: The BasisSet object to be written to the file. + :param filename: The name of the HDF5 file to write to. + :param group_name: The name of the group in the HDF5 file where the basis set data will be stored. + +.. cpp:function:: void GauXC::read_hdf5_record(BasisSet& basis, const std::string& filename, const std::string& group_name) + + Read a BasisSet object from an HDF5 file. + + :param basis: The BasisSet object to be populated with the data read from the file. + :param filename: The name of the HDF5 file to read from. + :param group_name: The name of the group in the HDF5 file where the basis set data is stored. + +The same functions are available in the GauXC C API. + +.. c:function:: void gauxc_basisset_write_hdf5_record(GauXCBasisSet basis, const char* filename, const char* group_name) + + Write a GauXCBasisSet object to an HDF5 file in C. + + :param basis: The GauXCBasisSet object to be written to the file. + :param filename: The name of the HDF5 file to write to. + :param group_name: The name of the group in the HDF5 file where the basis set data will be stored. + +.. c:function:: void gauxc_basisset_read_hdf5_record(GauXCBasisSet basis, const char* filename, const char* group_name) + + Read a GauXCBasisSet object from an HDF5 file in C. + + :param basis: The GauXCBasisSet object to be populated with the data read from the file. + :param filename: The name of the HDF5 file to read from. + :param group_name: The name of the group in the HDF5 file where the basis set data is stored. + +The same functions are also available in the GauXC Fortran API, available from the module :f:mod:`gauxc_external_hdf5`. + +.. f:module:: gauxc_external_hdf5 + :synopsis: HDF5 serialization functions for GauXC basis set objects. + +.. f:currentmodule:: gauxc_external_hdf5 + +.. f:subroutine:: gauxc_basisset_write_hdf5_record(basis, filename, group_name) + + Write a gauxc_basisset_type object to an HDF5 file in Fortran. + + :param type(gauxc_basisset_type) basis: The gauxc_basisset_type object to be written to the file. + :param character(len=*) filename: The name of the HDF5 file to write to. + :param character(len=*) group_name: The name of the group in the HDF5 file where the basis set data will be stored. + +.. f:subroutine:: gauxc_basisset_read_hdf5_record(basis, filename, group_name) + + Read a gauxc_basisset_type object from an HDF5 file in Fortran. + + :param type(gauxc_basisset_type) basis: The gauxc_basisset_type object to be populated with the data read from the file. + :param character(len=*) filename: The name of the HDF5 file to read from. + :param character(len=*) group_name: The name of the group in the HDF5 file where the basis set data is stored. + + +.. _gauxc-orbital-ordering: + +Orbital Ordering Convention +--------------------------- + +The orbital ordering convention for the shells in GauXC is following the common component architecture (CCA) convention for pure (spherical) shells and the row convention for cartesian ones. +The CCA ordering for pure (spherical) shells is defined as + +- ``s`` (:math:`\ell = 0`): :math:`Y_0^0` +- ``p`` (:math:`\ell = 1`): :math:`Y_1^{-1}`, :math:`Y_1^{0}`, :math:`Y_1^{+1}`, +- ``d`` (:math:`\ell = 2`): :math:`Y_2^{-2}`, :math:`Y_2^{-1}`, :math:`Y_2^{0}`, :math:`Y_2^{+1}`, :math:`Y_2^{+2}` + +The row ordering for cartesian shells is defined as + +- ``s`` (:math:`\ell = 0`): `1` +- ``p`` (:math:`\ell = 1`): ``x``, ``y``, ``z`` +- ``d`` (:math:`\ell = 2`): ``xx``, ``xy``, ``xz``, ``yy``, ``yz``, ``zz`` +- ``f`` (:math:`\ell = 3`): ``xxx``, ``xxy``, ``xxz``, ``xyy``, ``xyz``, ``xzz``, ``yyy``, ``yyz``, ``yzz``, ``zzz`` \ No newline at end of file diff --git a/docs/gauxc/api/cmake.rst b/docs/gauxc/api/cmake.rst new file mode 100644 index 0000000..3a7d414 --- /dev/null +++ b/docs/gauxc/api/cmake.rst @@ -0,0 +1,181 @@ +CMake Configuration Options +=========================== + +This section provides an overview of the available CMake configuration options for building GauXC with Skala support, as well as the required dependencies for each configuration. + + +.. _gauxc-cmake-deps: + +GauXC dependencies +------------------ + +The following dependencies are required for building GauXC with Skala support: + +- C/C++ compiler (with C++17 support) +- CMake (version 3.20 or higher) +- `exchcxx `__\ * (version 1 or higher) +- `libxc `__\ * (version 7 or higher) +- `integratorxx `__\ * (version 1 or higher) +- `gau2grid `__\ * (version 2.0.6 or higher) +- `libtorch `__ (CPU or CUDA version depending on your configuration) +- `nlohmann_json `__\ * (version 3.9.1 or higher) +- BLAS library (like OpenBLAS, MKL, etc.) + +When building with Fortran support via :cmake:variable:`GAUXC_ENABLE_FORTRAN` (default ``off``), a Fortran compiler is also required. + +When building with MPI support via :cmake:variable:`GAUXC_ENABLE_MPI` (default ``off``), the following dependencies are also required: + +- MPI implementation (like OpenMPI, MPICH, etc.) + +When building with CUDA support via :cmake:variable:`GAUXC_ENABLE_CUDA` (default ``off``), the following dependencies are also required: + +- CUDA toolkit +- `cuBLAS library `__ +- `Cutlass library `__\ * +- `CUB library `__\ * + +When building with HDF5 support via :cmake:variable:`GAUXC_ENABLE_HDF5` (default ``on``), the following dependencies are also required: + +- `HDF5 `__ +- `HighFive `__\ * (version 2.4.0 or higher) + +All libraries marked with a * can be automatically fetched by the GauXC build system and do not need to be installed manually. + + +.. _gauxc-cmake-options: + +Available configurations for CMake build +---------------------------------------- + +.. cmake:variable:: GAUXC_ENABLE_OPENMP + + Enable OpenMP support in GauXC (default: ON) + +.. cmake:variable:: GAUXC_ENABLE_MPI + + Enable MPI support in GauXC (default: OFF) + +.. cmake:variable:: GAUXC_ENABLE_ONEDFT + + Enable Skala support in GauXC (default: OFF) + +.. cmake:variable:: GAUXC_ENABLE_CUDA + + Enable CUDA support in GauXC (default: OFF) + Requires ExchCXX to be built with CUDA support as well (:cmake:variable:`EXCHCXX_ENABLE_CUDA` CMake option). + Cannot be enabled with HIP support at the same time. + +.. cmake:variable:: GAUXC_ENABLE_HIP + + Enable HIP support in GauXC (default: OFF) + Requires ExchCXX to be built with HIP support as well (:cmake:variable:`EXCHCXX_ENABLE_HIP` CMake option). + Cannot be enabled with CUDA support at the same time. + +.. cmake:variable:: GAUXC_ENABLE_C + + Enable C bindings for GauXC (default: OFF) + +.. cmake:variable:: GAUXC_ENABLE_FORTRAN + + Enable Fortran bindings for GauXC (default: OFF) + Requires Fortran compiler and :cmake:variable:`GAUXC_ENABLE_C` to be enabled as well. + +.. cmake:variable:: GAUXC_ENABLE_TESTS + + Enable building of GauXC tests (default: ON) + Requires catch2 library to be installed and available. + +.. cmake:variable:: GAUXC_ENABLE_HDF5 + + Enable HDF5 support in GauXC (default: ON) + Requires HDF5 library and HighFive library to be installed and available. + +.. cmake:variable:: GAUXC_ENABLE_MAGMA + + Enable MAGMA support in GauXC (default: OFF) + Requires MAGMA library to be installed and available. + Requires CUDA or HIP support to be enabled as well. + +.. cmake:variable:: GAUXC_ENABLE_NCCL + + Enable NCCL support in GauXC (default: OFF) + Requires NCCL library to be installed and available. + Requires CUDA support to be enabled as well. + +.. cmake:variable:: GAUXC_ENABLE_CUTLASS + + Enable CUTLASS support in GauXC (default: OFF) + Requires CUTLASS library to be installed and available. + Requires CUDA support to be enabled as well. + +.. cmake:variable:: GAUXC_ENABLE_GAU2GRID + + Enable Gau2Grid support in GauXC (default: ON) + Always enabled since Gau2Grid is a required dependency for GauXC. + +.. cmake:variable:: EXCHCXX_ENABLE_CUDA + + Enable CUDA support in ExchCXX (default: OFF) + Required for GauXC CUDA support. + Cannot be enabled with HIP support at the same time. + +.. cmake:variable:: EXCHCXX_ENABLE_HIP + + Enable HIP support in ExchCXX (default: OFF) + Required for GauXC HIP support. + Cannot be enabled with CUDA support at the same time. + + +.. _gauxc-cmake-integration: + +Integrating GauXC into your build system +---------------------------------------- + +Using an installed GauXC +~~~~~~~~~~~~~~~~~~~~~~~~ + +To integrate GauXC into your build system, you can use CMake's ``find_package`` command to locate the GauXC package and link against it in your ``CMakeLists.txt`` file. +Make sure that the ``CMAKE_PREFIX_PATH`` variable includes the path to your GauXC installation (e.g., ``${CONDA_PREFIX}`` if installed via Conda). + +.. code-block:: cmake + + find_package(gauxc CONFIG REQUIRED) + + if(NOT GAUXC_HAS_ONEDFT) + message(FATAL_ERROR "GauXC found but Skala/OneDFT was not enabled during the build") + endif() + + target_link_libraries(my_dft_driver PRIVATE gauxc::gauxc) + +The imported target propagates include directories, compile definitions, and linkage against BLAS, +Torch, and optional MPI/CUDA components. + +.. note:: + + Use the provided CMake variables like ``GAUXC_HAS_ONEDFT`` to check for specific features or configurations in GauXC before linking against it. + + +Embedding GauXC via FetchContent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to vendor GauXC directly from your build, use ``FetchContent`` while mirroring the options chosen above. +A possible approach for fetching GauXC with Skala support during the CMake configuration step is shown below. + +.. literalinclude:: ../../../examples/cpp/gauxc_integration/cmake/skala-gauxc.cmake + :language: cmake + :caption: cmake/skala-gauxc.cmake + +It is recommended to define the GauXC source URL with its SHA256 hash in a separate CMake file (e.g., `skala-gauxc-versions.cmake`). + +.. literalinclude:: ../../../examples/cpp/gauxc_integration/cmake/skala-dep-versions.cmake + :language: cmake + :caption: cmake/skala-dep-versions.cmake + :lines: 1-2 + +In the main ``CMakeLists.txt``, include the version definitions and the GauXC fetching logic. + +.. code-block:: cmake + + include(cmake/skala-gauxc.cmake) + + target_link_libraries(my_dft_driver PRIVATE gauxc::gauxc) \ No newline at end of file diff --git a/docs/gauxc/api/index.rst b/docs/gauxc/api/index.rst new file mode 100644 index 0000000..f34cafb --- /dev/null +++ b/docs/gauxc/api/index.rst @@ -0,0 +1,13 @@ +Reference for GauXC API +======================= + +This section provides a comprehensive reference for the GauXC API which is used to integrate Skala into electronic structure packages. +The API includes C++ class definitions, C bindings, and Fortran bindings for various components of GauXC, and CMake configuration options. + +.. toctree:: + :maxdepth: 2 + + macros + molecule + basis + cmake \ No newline at end of file diff --git a/docs/gauxc/api/macros.rst b/docs/gauxc/api/macros.rst new file mode 100644 index 0000000..9db786c --- /dev/null +++ b/docs/gauxc/api/macros.rst @@ -0,0 +1,83 @@ +Macro definitions +================= + +GauXC provides a number of compile-time macros to indicate available features and configuration options. + +.. c:macro:: GAUXC_HAS_C + + Defines whether C bindings are available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_C` CMake option. + +.. c:macro:: GAUXC_HAS_FORTRAN + + Defines whether Fortran bindings are available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_FORTRAN` CMake option. + +.. c:macro:: GAUXC_HAS_HOST + + Defines whether host support is available in this build of GauXC. + +.. c:macro:: GAUXC_HAS_DEVICE + + Defines whether any device support (CUDA or HIP) is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_CUDA` or :cmake:variable:`GAUXC_ENABLE_HIP` CMake options. + +.. c:macro:: GAUXC_HAS_CUDA + + Defines whether CUDA support is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_CUDA` CMake option. + +.. c:macro:: GAUXC_HAS_HIP + + Defines whether HIP support is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_HIP` CMake option. + +.. c:macro:: GAUXC_HAS_MPI + + Defines whether MPI support is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_MPI` CMake option. + +.. c:macro:: GAUXC_HAS_MAGMA + + Defines whether MAGMA support is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_MAGMA` CMake option. + +.. c:macro:: GAUXC_HAS_NCCL + + Defines whether NCCL support is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_NCCL` CMake option. + +.. c:macro:: GAUXC_HAS_CUTLASS + + Defines whether CUTLASS support is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_CUTLASS` CMake option. + +.. c:macro:: GAUXC_HAS_GAU2GRID + + Defines whether Gau2Grid support is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_GAU2GRID` CMake option. + +.. c:macro:: GAUXC_HAS_HDF5 + + Defines whether HDF5 support is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_HDF5` CMake option. + +.. c:macro:: GAUXC_CPU_XC_MAX_AM + + Maximum angular momentum supported for CPU exchange-correlation calculations. + Default is 6 (i.e., up to i-type functions). + +.. c:macro:: GAUXC_CPU_SNLINK_MAX_AM + + Maximum angular momentum supported for CPU seminumerical exchange calculations. + Default is 6 (i.e., up to i-type functions). + +.. c:macro:: GAUXC_GPU_XC_MAX_AM + + Maximum angular momentum supported for GPU exchange-correlation calculations. + Default is 4 (i.e., up to g-type functions). + +.. c:macro:: GAUXC_GPU_SNLINK_MAX_AM + + Maximum angular momentum supported for GPU seminumerical exchange calculations. + Default is 2 (i.e., up to d-type functions). \ No newline at end of file diff --git a/docs/gauxc/api/molecule.rst b/docs/gauxc/api/molecule.rst new file mode 100644 index 0000000..28ddd48 --- /dev/null +++ b/docs/gauxc/api/molecule.rst @@ -0,0 +1,234 @@ +GauXC Molecule API +================== + +This section provides a reference for the GauXC API related to molecule objects, including C++ class definitions, C bindings, and Fortran bindings. + +C++ defintions +-------------- + +.. cpp:class:: GauXC::Molecule : public std::Vector + + A class to represent a collection of atoms in a molecule. + + .. cpp:function:: inline Molecule(std::vector atoms) + + Construct a Molecule object from a vector of Atom objects. + + :param atoms: A vector of Atom objects representing the atoms in the molecule. + :returns: A Molecule object initialized with the given atoms. + + .. cpp:function:: inline size_t natoms() const + + Get the number of atoms in the molecule. + + :returns: The number of atoms in the molecule. + + .. cpp:function:: inline AtomicNumber maxZ() const + + Get the maximum atomic number among the atoms in the molecule. + + :returns: The maximum atomic number among the atoms in the molecule. + + .. cpp:function:: inline bool operator==(const Molecule& other) const + + Compare this molecule with another molecule for equality. + + :param other: Another molecule to compare with. + :returns: True if this molecule is equal to the other molecule, false otherwise. + +.. cpp:struct:: GauXC::Atom + + Representation of an atom in a molecule, containing its atomic number and Cartesian coordinates. + + .. cpp:member:: AtomicNumber Z + + The atomic number of the atom. + + .. cpp:member:: double x + + The x-coordinate of the atom in Cartesian coordinates. + + .. cpp:member:: double y + + The y-coordinate of the atom in Cartesian coordinates. + + .. cpp:member:: double z + + The z-coordinate of the atom in Cartesian coordinates. + + .. cpp:function:: inline Atom(AtomicNumber Z, double x, double y, double z) + + Construct an Atom object with the given atomic number and coordinates. + + :param Z: The atomic number of the atom. + :param x: The x-coordinate of the atom in Cartesian coordinates. + :param y: The y-coordinate of the atom in Cartesian coordinates. + :param z: The z-coordinate of the atom in Cartesian coordinates. + :returns: An Atom object initialized with the given atomic number and coordinates. + +.. cpp:type:: GauXC::AtomicNumber = int64_t + + A type to represent the atomic number of an atom. + +C bindings +---------- + +.. c:struct:: GauXCMolecule + + Opaque struct representing a molecule in the GauXC C API. + + .. c:function:: GauXCMolecule gauxc_molecule_new(GauXCStatus* status) + + Create a new GauXCMolecule object. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :returns: A new GauXCMolecule object. + + .. c:function:: GauXCMolecule gauxc_molecule_new_from_atoms(GauXCStatus* status, const GauXCAtom* atoms, size_t natoms) + + Create a new GauXCMolecule object from an array of GauXCAtom structs. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param atoms: Pointer to an array of GauXCAtom structs representing the atoms in the molecule. + :param natoms: The number of atoms in the molecule. + :returns: A new GauXCMolecule object initialized with the given atoms. + + .. c:function:: void gauxc_molecule_delete(GauXCStatus* status, GauXCMolecule* molecule) + + Delete a GauXCMolecule object. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param molecule: Pointer to the GauXCMolecule object to be deleted. + +.. c:struct:: GauXCAtom + + Representation of an atom in a molecule for the GauXC C API, containing its atomic number and Cartesian coordinates. + + .. c:member:: int64_t Z + + The atomic number of the atom. + + .. c:member:: double x + + The x-coordinate of the atom in Cartesian coordinates. + + .. c:member:: double y + + The y-coordinate of the atom in Cartesian coordinates. + + .. c:member:: double z + + The z-coordinate of the atom in Cartesian coordinates. + + +Fortran bindings +---------------- + +.. f:module:: gauxc_molecule + :synopsis: Fortran bindings for GauXC molecule objects. + +.. f:currentmodule:: gauxc_molecule + +.. f:type:: gauxc_molecule_type + + Opaque type representing a molecule in the GauXC Fortran API. + Available from the module :f:mod:`gauxc_molecule`. + + .. f:function:: gauxc_molecule_new(status) + + Create a new gauxc_molecule_type object. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :returns type(gauxc_molecule_type): A new gauxc_molecule_type object. + + .. f:function:: gauxc_molecule_new_from_atoms(status, atoms, natoms) + + Create a new gauxc_molecule_type object from an array of gauxc_atom_type objects. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_atom_type) atoms(*): An array of :f:type:`gauxc_atom_type` objects representing the atoms in the molecule. + :param integer(c_int64_t) natoms: The number of atoms in the molecule. + :returns type(gauxc_molecule_type): A new gauxc_molecule_type object initialized with the given atoms. + +.. f:currentmodule:: gauxc_atom + +.. f:type:: gauxc_atom_type + + A derived type representing an atom in the GauXC Fortran API, containing its atomic number and Cartesian coordinates. + + :f integer(c_int64_t) Z: + The atomic number of the atom. + + :f real(c_double) x: + The x-coordinate of the atom in Cartesian coordinates. + + :f real(c_double) y: + The y-coordinate of the atom in Cartesian coordinates. + + :f real(c_double) z: + The z-coordinate of the atom in Cartesian coordinates. + +Serialization to HDF5 +--------------------- + +If GauXC has been built with HDF5 support :c:macro:`GAUXC_HAS_HDF5`, the :cpp:class:`GauXC::Molecule` class can be serialized to and deserialized from HDF5 files using the provided HDF5 interface. +This allows for easy storage and retrieval of molecular data in a standardized format. + +.. cpp:function:: void GauXC::write_hdf5_record(const Molecule& molecule, const std::string& filename, const std::string& group_name) + + Write a Molecule object to an HDF5 file. + + :param molecule: The Molecule object to be written to the file. + :param filename: The name of the HDF5 file to write to. + :param group_name: The name of the group in the HDF5 file where the molecule data will be stored. + +.. cpp:function:: void GauXC::read_hdf5_record(Molecule& molecule, const std::string& filename, const std::string& group_name) + + Read a Molecule object from an HDF5 file. + + :param molecule: The Molecule object to be populated with the data read from the file. + :param filename: The name of the HDF5 file to read from. + :param group_name: The name of the group in the HDF5 file where the molecule data is stored. + +The same functions are available in the GauXC C API. + +.. c:function:: void gauxc_molecule_write_hdf5_record(GauXCMolecule molecule, const char* filename, const char* group_name) + + Write a GauXCMolecule object to an HDF5 file in C. + + :param molecule: The GauXCMolecule object to be written to the file. + :param filename: The name of the HDF5 file to write to. + :param group_name: The name of the group in the HDF5 file where the molecule data will be stored. + +.. c:function:: void gauxc_molecule_read_hdf5_record(GauXCMolecule molecule, const char* filename, const char* group_name) + + Read a GauXCMolecule object from an HDF5 file in C. + + :param molecule: The GauXCMolecule object to be populated with the data read from the file. + :param filename: The name of the HDF5 file to read from. + :param group_name: The name of the group in the HDF5 file where the molecule data is stored. + +The same functions are also available in the GauXC Fortran API, available from the module :f:mod:`gauxc_external_hdf5`. + +.. f:module:: gauxc_external_hdf5 + :synopsis: HDF5 serialization functions for GauXC molecule objects. + +.. f:currentmodule:: gauxc_external_hdf5 + +.. f:subroutine:: gauxc_molecule_write_hdf5_record(molecule, filename, group_name) + + Write a gauxc_molecule_type object to an HDF5 file in Fortran. + + :param type(gauxc_molecule_type) molecule: The gauxc_molecule_type object to be written to the file. + :param character(len=*) filename: The name of the HDF5 file to write to. + :param character(len=*) group_name: The name of the group in the HDF5 file where the molecule data will be stored. + +.. f:subroutine:: gauxc_molecule_read_hdf5_record(molecule, filename, group_name) + + Read a gauxc_molecule_type object from an HDF5 file in Fortran. + + :param type(gauxc_molecule_type) molecule: The gauxc_molecule_type object to be populated with the data read from the file. + :param character(len=*) filename: The name of the HDF5 file to read from. + :param character(len=*) group_name: The name of the group in the HDF5 file where the molecule data is stored. + +.. f:currentmodule:: \ No newline at end of file diff --git a/docs/gauxc/c-library.rst b/docs/gauxc/c-library.rst index e7d382e..e9e2c01 100644 --- a/docs/gauxc/c-library.rst +++ b/docs/gauxc/c-library.rst @@ -311,7 +311,7 @@ For reading the molecule we will use GauXC's built-in functionality to read from The HDF5 wrapper directly maps this struct representation to an HDF5 dataset. -We use ``gauxc_molecule_read_hdf5_record`` function which implements the reading of the molecule data. +We use :c:func:`gauxc_molecule_read_hdf5_record` function which implements the reading of the molecule data. .. literalinclude:: ../../examples/c/gauxc_integration/app/main.c :language: c @@ -350,7 +350,7 @@ For the basis set we will use the same approach as for the molecule and use GauX Again, this allows to directly map the object's representation to an HDF5 dataset. -With GauXC's ``gauxc_basisset_read_hdf5_record`` function we can read the basis set data conveniently from the HDF5 file. +With GauXC's :c:func:`gauxc_basisset_read_hdf5_record` function we can read the basis set data conveniently from the HDF5 file. .. literalinclude:: ../../examples/c/gauxc_integration/app/main.c :language: c diff --git a/docs/gauxc/cpp-library.rst b/docs/gauxc/cpp-library.rst index 2f5b879..15f329e 100644 --- a/docs/gauxc/cpp-library.rst +++ b/docs/gauxc/cpp-library.rst @@ -1,3 +1,5 @@ +.. _gauxc-cpp-library: + GauXC in C++ ============ @@ -224,7 +226,7 @@ For reading the molecule we will use GauXC's built-in functionality to read from This allows to directly map the object's representation to an HDF5 dataset. -We use ``GauXC::read_hdf5_record`` function which implements the reading of the molecule data. +We use :cpp:func:`void GauXC::read_hdf5_record(Molecule&,string,string)` function which implements the reading of the molecule data. .. literalinclude:: ../../examples/cpp/gauxc_integration/app/main.cxx :language: c++ @@ -267,7 +269,7 @@ For the basis set we will use the same approach as for the molecule and use GauX Again, this allows to directly map the object's representation to an HDF5 dataset. -With GauXC's ``GauXC::read_hdf5_record`` function we can read the basis set data conveniently from the HDF5 file. +With GauXC's :cpp:func:`void GauXC::read_hdf5_record(BasisSet&,string,string)` function we can read the basis set data conveniently from the HDF5 file. Additionally, we are setting the basis set tolerance on the loaded basis set data, which will be taken from our input variables, by default we use a tolerance of 1e-10. The basis set tolerance will be used for screening small contributions during the evaluation of the density on the grid points. diff --git a/docs/gauxc/fortran-library.rst b/docs/gauxc/fortran-library.rst index b350887..9ce8994 100644 --- a/docs/gauxc/fortran-library.rst +++ b/docs/gauxc/fortran-library.rst @@ -295,7 +295,7 @@ We use GauXC's built-in HDF5 reader to load the molecule data. The HDF5 wrapper maps this struct representation directly to the HDF5 dataset. -The ``gauxc_read_hdf5_record`` subroutine loads the molecule data: +The :f:func:`gauxc_read_hdf5_record` interface (see :f:func:`gauxc_molecule_read_hdf5_record`) loads the molecule data: .. literalinclude:: ../../examples/fortran/gauxc_integration/app/main.F90 :language: fortran @@ -339,7 +339,7 @@ We load the basis set using the same HDF5 approach as for the molecule. Again, this allows the object's representation to map directly to an HDF5 dataset. -We read the basis set using ``gauxc_read_hdf5_record``: +We read the basis set using :f:func:`gauxc_read_hdf5_record` (see :f:func:`gauxc_basisset_read_hdf5_record`): .. literalinclude:: ../../examples/fortran/gauxc_integration/app/main.F90 :language: fortran diff --git a/docs/gauxc/index.rst b/docs/gauxc/index.rst index db896d3..c11f3b6 100644 --- a/docs/gauxc/index.rst +++ b/docs/gauxc/index.rst @@ -14,4 +14,5 @@ The following sections provide instructions on how to install GauXC with Skala s cpp-library c-library fortran-library - settings \ No newline at end of file + settings + api/index \ No newline at end of file diff --git a/docs/gauxc/installation.rst b/docs/gauxc/installation.rst index 38383c2..77a7593 100644 --- a/docs/gauxc/installation.rst +++ b/docs/gauxc/installation.rst @@ -22,41 +22,10 @@ If you do not have mamba installed, you can download the `miniforge `__\ * (version 1 or higher) - - `libxc `__\ * (version 7 or higher) - - `integratorxx `__\ * (version 1 or higher) - - `gau2grid `__\ * (version 2.0.6 or higher) - - `libtorch `__ (CPU or CUDA version depending on your configuration) - - `nlohmann_json `__\ * (version 3.9.1 or higher) - - BLAS library (like OpenBLAS, MKL, etc.) - - When building with MPI support via ``-DGAUXC_ENABLE_MPI=on`` (default ``off``), - the following dependencies are also required: - - - MPI implementation (like OpenMPI, MPICH, etc.) - - When building with Cuda support via ``-DGAUXC_ENABLE_CUDA=on`` (default ``off``), - the following dependencies are also required: - - - CUDA toolkit - - `cuBLAS library `__ - - `Cutlass library `__\ * - - `CUB library `__\ * - - When building with HDF5 support via ``-DGAUXC_ENABLE_HDF5=on`` (default ``on``), - the following dependencies are also required: +.. note:: - - `HDF5 `__ - - `HighFive `__\ * (version 2.4.0 or higher) + A full list of dependencies can be found at :ref:`gauxc-cmake-deps` in the CMake configuration documentation. - All libraries marked with a * can be automatically fetched by the GauXC build system - and do not need to be installed manually. For this, create a file named `environment.yml` with the following content: @@ -103,7 +72,7 @@ Download the pre-packaged source bundle from the Skala release page: .. code-block:: none - curl -L https://github.com/microsoft/skala/releases/download/v1.1.0/gauxc-skala.tar.gz | tar xzv + curl -L https://github.com/microsoft/skala/releases/download/v1.1.1/gauxc-skala-r1.tar.gz | tar xzv .. tip:: @@ -111,12 +80,20 @@ Download the pre-packaged source bundle from the Skala release page: .. code-block:: none - curl -L https://github.com/microsoft/skala/releases/download/v1.1.0/gauxc-skala.tar.gz > gauxc-skala.tar.gz - curl -L https://github.com/microsoft/skala/releases/download/v1.1.0/gauxc-skala.tar.gz.sha256 | sha256sum -c - tar xzvf gauxc-skala.tar.gz + curl -L https://github.com/microsoft/skala/releases/download/v1.1.1/gauxc-skala-r1.tar.gz > gauxc-skala-r1.tar.gz + curl -L https://github.com/microsoft/skala/releases/download/v1.1.1/gauxc-skala-r1.tar.gz.sha256 | sha256sum -c + tar xzvf gauxc-skala-r1.tar.gz The archive expands into a ``gauxc`` directory that already contains the Skala patches. +.. note:: + + You can also obtain the latest version of GauXC with Skala support by downloading the `skala branch of GauXC `__. + + .. code-block:: none + + curl -L https://github.com/wavefunction91/GauXC/archive/refs/heads/skala.tar.gz | tar xzv + Configure and build ------------------- @@ -159,6 +136,11 @@ Create an out-of-tree build directory and pick the configuration that matches yo -DCMAKE_INSTALL_PREFIX=${CONDA_PREFIX} cmake --build build +.. note:: + + To enable the C or Fortran bindings, set :cmake:variable:`GAUXC_ENABLE_C` or :cmake:variable:`GAUXC_ENABLE_FORTRAN` in your CMake configuration step. + For a full list of available CMake options, see :ref:`gauxc-cmake-options` in the CMake configuration documentation. + .. tip:: If CMake cannot find libtorch, the ``Torch_DIR`` variable can be set to help discover the package. @@ -200,79 +182,11 @@ Install into the active conda environment so downstream projects can pick up the This installs headers, libraries, and CMake config. +.. note:: -Integrate with your codebase ----------------------------- - -Using an installed GauXC -~~~~~~~~~~~~~~~~~~~~~~~~ - -Add the following to your CMake project, ensuring that ``CMAKE_PREFIX_PATH`` contains -``${CONDA_PREFIX}`` (activation scripts typically set this). - -.. code-block:: cmake - - find_package(gauxc CONFIG REQUIRED) - - if(NOT gauxc_HAS_ONEDFT) - message(FATAL_ERROR "GauXC found but Skala/OneDFT was not enabled during the build") - endif() - - target_link_libraries(my_dft_driver PRIVATE gauxc::gauxc) - -The imported target propagates include directories, compile definitions, and linkage against BLAS, -Torch, and optional MPI/CUDA components. - -Embedding GauXC via FetchContent -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to vend GauXC directly from your build, use ``FetchContent`` while mirroring the -options chosen above. - -.. code-block:: cmake - - set(Skala_GauXC_URL "https://github.com/microsoft/skala/releases/download/v1.1.1/gauxc-skala.tar.gz") - set(Skala_GauXC_SHA256 "0a64b2623be99894d3c61bd78aec1759abf3f476656695fab76c5e3fbb372616") - - option(Skala_GauXC_ENABLE_OPENMP "Enable OpenMP support in GauXC" ON) - option(Skala_GauXC_ENABLE_MPI "Enable MPI support in GauXC" OFF) - option(Skala_GauXC_ENABLE_CUDA "Enable CUDA support in GauXC" OFF) - - find_package(gauxc QUIET CONFIG) - if(NOT gauxc_FOUND) - include(FetchContent) - - message(STATUS "Could not find GauXC... Building GauXC from source") - message(STATUS "GAUXC URL: ${Skala_GauXC_URL}") - - set(GAUXC_ENABLE_ONEDFT ON CACHE BOOL "" FORCE) - set(GAUXC_ENABLE_TESTS OFF CACHE BOOL "" FORCE) - set(GAUXC_ENABLE_OPENMP ${Skala_GauXC_ENABLE_OPENMP} CACHE BOOL "" FORCE) - set(GAUXC_ENABLE_MPI ${Skala_GauXC_ENABLE_MPI} CACHE BOOL "" FORCE) - set(GAUXC_ENABLE_CUDA ${Skala_GauXC_ENABLE_CUDA} CACHE BOOL "" FORCE) - - FetchContent_Declare( - gauxc - URL ${Skala_GauXC_URL} - URL_HASH SHA256=${Skala_GauXC_SHA256} - DOWNLOAD_EXTRACT_TIMESTAMP ON - ) - FetchContent_MakeAvailable(gauxc) + For using GauXC in your own CMake project, check out :ref:`gauxc-cmake-integration` in the CMake configuration documentation. + Alternatively, you can follow the instructions in the :ref:`gauxc-cpp-library` tutorial for a full standalone example. - else() - if(NOT ${GAUXC_HAS_ONEDFT}) - message(FATAL_ERROR "GauXC found but without Skala support enabled") - endif() - if(${Skala_GauXC_ENABLE_OPENMP} AND NOT ${GAUXC_HAS_OPENMP}) - message(WARNING "GauXC Found without OpenMP support but Skala_GauXC_ENABLE_OPENMP is ON") - endif() - if(${Skala_GauXC_ENABLE_MPI} AND NOT ${GAUXC_HAS_MPI}) - message(WARNING "GauXC Found without MPI support but Skala_GauXC_ENABLE_MPI is ON") - endif() - if(${Skala_GauXC_ENABLE_CUDA} AND NOT ${GAUXC_HAS_CUDA}) - message(WARNING "GauXC Found without CUDA support but Skala_GauXC_ENABLE_CUDA is ON") - endif() - endif() Troubleshooting --------------- diff --git a/docs/gauxc/standalone.rst b/docs/gauxc/standalone.rst index 5e7d09b..b8918dd 100644 --- a/docs/gauxc/standalone.rst +++ b/docs/gauxc/standalone.rst @@ -166,18 +166,7 @@ Note that the length of exponents in each shell is padded to 16 elements for the .. important:: The orbital ordering convention for the shells in GauXC is following the common component architecture (CCA) convention for pure (spherical) shells and the row convention for cartesian ones. - The CCA ordering for pure (spherical) shells is defined as - - - ``s`` (:math:`\ell = 0`): :math:`Y_0^0` - - ``p`` (:math:`\ell = 1`): :math:`Y_1^{-1}`, :math:`Y_1^{0}`, :math:`Y_1^{+1}`, - - ``d`` (:math:`\ell = 2`): :math:`Y_2^{-2}`, :math:`Y_2^{-1}`, :math:`Y_2^{0}`, :math:`Y_2^{+1}`, :math:`Y_2^{+2}` - - The row ordering for cartesian shells is defined as - - - ``s`` (:math:`\ell = 0`): `1` - - ``p`` (:math:`\ell = 1`): ``x``, ``y``, ``z`` - - ``d`` (:math:`\ell = 2`): ``xx``, ``xy``, ``xz``, ``yy``, ``yz``, ``zz`` - - ``f`` (:math:`\ell = 3`): ``xxx``, ``xxy``, ``xxz``, ``xyy``, ``xyz``, ``xzz``, ``yyy``, ``yyz``, ``yzz``, ``zzz`` + For more details on the orbital ordering convention check :ref:`gauxc-orbital-ordering`. PySCF is using CCA ordering for all pure (spherical) shells except for the p-shell where row ordering is used. Our export accounts for this by exporting p-shells with setting the ``pure`` entry to zero to have GauXC use row ordering. diff --git a/pyproject.toml b/pyproject.toml index e67c2e7..df1f940 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,6 +40,8 @@ optional-dependencies.doc = [ "sphinx-book-theme", "sphinx-design", "sphinxcontrib-bibtex", + "sphinxcontrib-moderncmakedomain", + "sphinxfortran.fortran_domain", ] urls.repository = "https://github.com/microsoft/skala" From ba74019e614a7888b31661a1c80dd03db7c3849b Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert Date: Mon, 2 Mar 2026 12:29:36 +0100 Subject: [PATCH 2/5] Add section on molecular grid --- docs/gauxc/api/index.rst | 1 + docs/gauxc/api/molgrid.rst | 305 +++++++++++++++++++++++++++++++++++++ docs/gauxc/index.rst | 1 - docs/gauxc/settings.rst | 33 ---- 4 files changed, 306 insertions(+), 34 deletions(-) create mode 100644 docs/gauxc/api/molgrid.rst delete mode 100644 docs/gauxc/settings.rst diff --git a/docs/gauxc/api/index.rst b/docs/gauxc/api/index.rst index f34cafb..6567ce1 100644 --- a/docs/gauxc/api/index.rst +++ b/docs/gauxc/api/index.rst @@ -10,4 +10,5 @@ The API includes C++ class definitions, C bindings, and Fortran bindings for var macros molecule basis + molgrid cmake \ No newline at end of file diff --git a/docs/gauxc/api/molgrid.rst b/docs/gauxc/api/molgrid.rst new file mode 100644 index 0000000..6ffbae3 --- /dev/null +++ b/docs/gauxc/api/molgrid.rst @@ -0,0 +1,305 @@ +.. _gauxc_molecular_grid_settings: + +Molecular grid settings +======================= + +This section provides a reference for the settings related to molecular grids in GauXC, including C++ class definitions, C bindings, and Fortran bindings for creating and managing molecular grids used in numerical integration schemes. + +C++ definitions +--------------- + +This section provides C++ class definitions provided by the ``gauxc/molgrid.hpp`` header. + +.. cpp:class:: GauXC::MolGrid + + Molecular integration grid container. + + MolGrid aggregates atom-centered quadrature grids for each atomic number and exposes access to per-element grids and batch sizing information for numerical integration. + + .. cpp:function:: inline MolGrid GauXC::MolGridFactory::create_default_molgrid(const Molecule& mol, PruningScheme scheme, BatchSize bsz, RadialQuad radial_quad, AtomicGridSizeDefault grid_size) + + Create a default MolGrid for the given molecule using the specified pruning scheme, batch size, radial quadrature, and atomic grid size. + This constructor is available from the ``gauxc/molgrid/defaults.hpp`` header. + + :param mol: The molecule for which to create the MolGrid. + :param scheme: The pruning scheme to use for constructing the molecular grid weights from the atomic grids. + :param bsz: The batch size for processing grid points in parallel. + :param radial_quad: The radial quadrature scheme to use for the atomic grids. + :param grid_size: The default atomic grid size to use for the atomic grids. + :returns: A MolGrid object initialized with the specified parameters for the given molecule. + + .. cpp:function:: inline MolGrid GauXC::MolGridFactory::create_default_molgrid(const Molecule& mol, PruningScheme scheme, BatchSize bsz, RadialQuad radial_quad, RadialSize rad_size, AngularSize ang_size) + + Create a default MolGrid for the given molecule using the specified pruning scheme, batch size, radial quadrature, and explicit radial and angular sizes. + This constructor is available from the ``gauxc/molgrid/defaults.hpp`` header. + + :param mol: The molecule for which to create the MolGrid. + :param scheme: The pruning scheme to use for constructing the molecular grid weights from the atomic grids. + :param bsz: The batch size for processing grid points in parallel. + :param radial_quad: The radial quadrature scheme to use for the atomic grids. + :param rad_size: The radial size to use for the atomic grids. + :param ang_size: The angular size to use for the atomic grids. + :returns: A MolGrid object initialized with the specified parameters for the given molecule. + + +The enumerator values are available from the ``gauxc/enums.hpp`` header. + +.. cpp:enum-class:: GauXC::AtomicGridSizeDefault + + Enumeration of default atomic grid sizes for molecular integration. + + The following options are available: + + .. cpp:enumerator:: FineGrid + + A default atomic grid size with 75 angular points and 302 radial points. + + .. cpp:enumerator:: UltraFineGrid + + A default atomic grid size with 99 angular points and 590 radial points. + + .. cpp:enumerator:: SuperFineGrid + + A default atomic grid size with 250 angular points and 974 radial points. + + .. cpp:enumerator:: GM3 + + A default atomic grid size with 35 angular points and 110 radial points. + + .. cpp:enumerator:: GM5 + + A default atomic grid size with 50 angular points and 302 radial points. + + +.. cpp:enum-class:: GauXC::RadialQuad + + Enumeration of radial quadrature schemes for atomic grids. + + The following options are available: + + .. cpp:enumerator:: Becke + + The Becke radial quadrature scheme.\ :footcite:`becke1988` + + .. cpp:enumerator:: MuraKnowles + + The Mura-Knowles radial quadrature scheme.\ :footcite:`mura1996` + + .. cpp:enumerator:: TreutlerAhlrichs + + The Treutler-Ahlrichs radial quadrature scheme.\ :footcite:`treutler1995` + + .. cpp:enumerator:: MurrayHandyLaming + + The Murray-Handy-Laming radial quadrature scheme.\ :footcite:`murray1993` + + +.. cpp:enum-class:: GauXC::PruningScheme + + Enumeration of pruning schemes for constructing molecular grid weights from atomic grids. + + The following options are available: + + .. cpp:enumerator:: Unpruned + + No pruning is applied to the atomic grids when constructing the molecular grid. + + .. cpp:enumerator:: Robust + + Robust pruning scheme from Psi4. + + .. cpp:enumerator:: Treutler + + The Treutler pruning scheme. + + +.. cpp:type:: GauXCRadialSize = int64_t + + Type to represent the number of radial points in an atomic grid. + +.. cpp:type:: GauXCAngularSize = int64_t + + Type to represent the number of angular points in an atomic grid. + +.. cpp:type:: GauXC::BatchSize = int64_t + + Defines the batch size for processing grid points in parallel. + Default is 512 points per batch, however larger values up around 10000 are recommended for better performance. + + +C bindings +---------- + +The following C bindings are available in the ``gauxc/molgrid.h`` header for creating and managing molecular grids in the GauXC C API. + +.. c:struct:: GauXCMolGrid + + Opaque struct representing a molecular grid in the GauXC C API. + + .. c:function:: GauXCMolGrid gauxc_molgrid_new_default(GauXCStatus* status, const GauXCMolecule* molecule, enum GauXC_PruningScheme pruning_scheme, int64_t batch_size, enum GauXC_RadialQuad radial_quad, enum GauXC_AtomicGridSizeDefault grid_size) + + Create a new GauXCMolGrid object with default settings for the given molecule. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param molecule: Pointer to a GauXCMolecule object representing the molecule for which to create the MolGrid. + :param pruning_scheme: The pruning scheme to use for constructing the molecular grid weights from the atomic grids. + :param batch_size: The batch size for processing grid points in parallel. + :param radial_quad: The radial quadrature scheme to use for the atomic grids. + :param grid_size: The default atomic grid size to use for the atomic grids. + :returns: A new GauXCMolGrid object initialized with the specified parameters for the given molecule. + + .. c:function:: void gauxc_molgrid_delete(GauXCStatus* status, GauXCMolGrid* molgrid) + + Delete a GauXCMolGrid object and free its resources. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param molgrid: Pointer to the GauXCMolGrid object to delete. + + +.. c:enum:: GauXC_PruningScheme + + Enumeration of pruning schemes for constructing molecular grid weights from atomic grids in the GauXC C API. + + The following options are available: + + .. c:enumerator:: GauXC_PruningScheme_Unpruned + + No pruning is applied to the atomic grids when constructing the molecular grid. + + .. c:enumerator:: GauXC_PruningScheme_Robust + + Robust pruning scheme from Psi4. + + .. c:enumerator:: GauXC_PruningScheme_Treutler + + The Treutler pruning scheme. + + +.. c:enum:: GauXC_RadialQuad + + Enumeration of radial quadrature schemes for atomic grids in the GauXC C API. + + The following options are available: + + .. c:enumerator:: GauXC_RadialQuad_Becke + + The Becke radial quadrature scheme.\ :footcite:`becke1988` + + .. c:enumerator:: GauXC_RadialQuad_MuraKnowles + + The Mura-Knowles radial quadrature scheme.\ :footcite:`mura1996` + + .. c:enumerator:: GauXC_RadialQuad_TreutlerAhlrichs + + The Treutler-Ahlrichs radial quadrature scheme.\ :footcite:`treutler1995` + + .. c:enumerator:: GauXC_RadialQuad_MurrayHandyLaming + + The Murray-Handy-Laming radial quadrature scheme.\ :footcite:`murray1993` + + +.. c:enum:: GauXC_AtomicGridSizeDefault + + Enumeration of default atomic grid sizes for molecular integration in the GauXC C API. + + The following options are available: + + .. c:enumerator:: GauXC_AtomicGridSizeDefault_FineGrid + + A default atomic grid size with 75 angular points and 302 radial points. + + .. c:enumerator:: GauXC_AtomicGridSizeDefault_UltraFineGrid + + A default atomic grid size with 99 angular points and 590 radial points. + + .. c:enumerator:: GauXC_AtomicGridSizeDefault_SuperFineGrid + + A default atomic grid size with 250 angular points and 974 radial points. + + .. c:enumerator:: GauXC_AtomicGridSizeDefault_GM3 + + A default atomic grid size with 35 angular points and 110 radial points. + + .. c:enumerator:: GauXC_AtomicGridSizeDefault_GM5 + + A default atomic grid size with 50 angular points and 302 radial points. + + +Fortran bindings +---------------- + +.. f:module:: gauxc_molgrid + :synopsis: Fortran bindings for GauXC molecular grid objects. + +.. f:currentmodule:: gauxc_molgrid + +.. f:type:: gauxc_molgrid_type + + Opaque type representing a molecular grid in the GauXC Fortran API. + Available in the module :f:mod:`gauxc_molgrid`. + + .. f:function:: function gauxc_molgrid_new_default(status, molecule, pruning_scheme, batch_size, radial_quad, grid_size) + + :param type(gauxc_status_type) status: Output parameter to store the status of the operation. + :param type(gauxc_molecule_type) molecule: The molecule for which to create the MolGrid. + :param integer(c_int) pruning_scheme: The pruning scheme to use for constructing the molecular grid weights from the atomic grids. + :param integer(c_int64_t) batch_size: The batch size for processing grid points in parallel. + :param integer(c_int) radial_quad: The radial quadrature scheme to use for the atomic grids. + :param integer(c_int) grid_size: The default atomic grid size to use for the atomic grids. + :returns type(gauxc_molgrid_type): A new gauxc_molgrid_type object initialized with the specified parameters for the given molecule. + +.. f:currentmodule:: gauxc_enums + +.. f:type:: gauxc_radialquad + + Parameter instance of a derived type with the respective enumerator values for each member variable. + + :f integer(c_int) becke: + The Becke radial quadrature scheme.\ :footcite:`becke1988` + + :f integer(c_int) muraknowles: + The Mura-Knowles radial quadrature scheme.\ :footcite:`mura1996` + + :f integer(c_int) treutlerahlrichs: + The Treutler-Ahlrichs radial quadrature scheme.\ :footcite:`treutler1995` + + :f integer(c_int) murrayhandylaming: + The Murray-Handy-Laming radial quadrature scheme.\ :footcite:`murray1993` + +.. f:type:: gauxc_pruningscheme + + Parameter instance of a derived type with the respective enumerator values for each member variable. + + :f integer(c_int) unpruned: + No pruning is applied to the atomic grids when constructing the molecular grid. + + :f integer(c_int) robust: + Robust pruning scheme from Psi4. + + :f integer(c_int) treutler: + The Treutler pruning scheme. + +.. f:type:: gauxc_atomicgridsizedefault + + Parameter instance of a derived type with the respective enumerator values for each member variable. + + :f integer(c_int) finegrid: + A default atomic grid size with 75 angular points and 302 radial points. + + :f integer(c_int) ultrafinegrid: + A default atomic grid size with 99 angular points and 590 radial points. + + :f integer(c_int) superfinegrid: + A default atomic grid size with 250 angular points and 974 radial points. + + :f integer(c_int) gm3: + A default atomic grid size with 35 angular points and 110 radial points. + + :f integer(c_int) gm5: + A default atomic grid size with 50 angular points and 302 radial points. + + +References +---------- + +.. footbibliography:: \ No newline at end of file diff --git a/docs/gauxc/index.rst b/docs/gauxc/index.rst index c11f3b6..3e782a2 100644 --- a/docs/gauxc/index.rst +++ b/docs/gauxc/index.rst @@ -14,5 +14,4 @@ The following sections provide instructions on how to install GauXC with Skala s cpp-library c-library fortran-library - settings api/index \ No newline at end of file diff --git a/docs/gauxc/settings.rst b/docs/gauxc/settings.rst deleted file mode 100644 index cce8473..0000000 --- a/docs/gauxc/settings.rst +++ /dev/null @@ -1,33 +0,0 @@ -GauXC settings -============== - -GauXC provides different settings for defining the behavior of the library. -Mainly these settings are used to define the molecular integration scheme and the parallelization strategy. - -.. _gauxc_molecular_grid_settings: - -Molecular grid --------------- - -For creating a ``GauXC::MolGrid`` we need to specify the following parameters: - -``AtomicGridSizeDefault`` - Defines the number of angular and radial points in the atomic grid. - Possible options are ``Fine`` (75, 302), ``UltraFine`` (99, 590), ``SuperFine`` (250, 974), ``GM3`` (35, 110) and ``GM5`` (50, 302). - -``RadialQuad`` - Defines the radial quadrature scheme to be used for the atomic grid. - Possible options are ``Becke``,\ :footcite:`becke1988` ``MuraKnowles``,\ :footcite:`mura1996` ``TreutlerAhlrichs``,\ :footcite:`treutler1995` and ``MurrayHandyLaming``.\ :footcite:`murray1993` - -``PruningScheme`` - Defines the pruning scheme to construct the molecular grid weights from the atomic grids. - Possible options are ``Unpruned``, ``Robust``, and ``Treutler``. - -``BatchSize`` - Defines the batch size for processing grid points in parallel. - Default is 512 points per batch, however larger values up around 10000 are recommended for better performance. - -References ----------- - -.. footbibliography:: \ No newline at end of file From 36fe0eba37abb4d1b07220d89ddd33e817f93cab Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert Date: Mon, 2 Mar 2026 13:00:58 +0100 Subject: [PATCH 3/5] Fix name for sphinx-fortran --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index df1f940..70f6304 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,7 +41,7 @@ optional-dependencies.doc = [ "sphinx-design", "sphinxcontrib-bibtex", "sphinxcontrib-moderncmakedomain", - "sphinxfortran.fortran_domain", + "sphinx-fortran", ] urls.repository = "https://github.com/microsoft/skala" From cb0d01c3979056915afb73eea8df276fd986c884 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert Date: Mon, 2 Mar 2026 15:50:45 +0100 Subject: [PATCH 4/5] Add additional API documentation --- docs/gauxc/api/basis.rst | 8 + docs/gauxc/api/exceptions.rst | 55 +++++ docs/gauxc/api/index.rst | 7 +- docs/gauxc/api/load_balancer.rst | 202 +++++++++++++++++ docs/gauxc/api/macros.rst | 5 + docs/gauxc/api/molecular_weights.rst | 288 +++++++++++++++++++++++ docs/gauxc/api/molecule.rst | 8 + docs/gauxc/api/molgrid.rst | 8 + docs/gauxc/api/runtime_environment.rst | 277 +++++++++++++++++++++++ docs/gauxc/api/xc_integrator.rst | 302 +++++++++++++++++++++++++ 10 files changed, 1159 insertions(+), 1 deletion(-) create mode 100644 docs/gauxc/api/exceptions.rst create mode 100644 docs/gauxc/api/load_balancer.rst create mode 100644 docs/gauxc/api/molecular_weights.rst create mode 100644 docs/gauxc/api/runtime_environment.rst create mode 100644 docs/gauxc/api/xc_integrator.rst diff --git a/docs/gauxc/api/basis.rst b/docs/gauxc/api/basis.rst index b53ad72..9b64319 100644 --- a/docs/gauxc/api/basis.rst +++ b/docs/gauxc/api/basis.rst @@ -319,6 +319,14 @@ Fortran bindings :param logical(c_bool) normalize: Whether to normalize the primitives in the shells when creating the basis set. :returns type(gauxc_basisset_type): A new gauxc_basisset_type object initialized with the given shells. + .. f:function:: gauxc_basisset_delete(status, basis) + + Delete a gauxc_basisset_type object and free its associated memory. + Part of the :f:func:`gauxc_delete` interface. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_basisset_type) basis: The gauxc_basisset_type object to be deleted. + .. f:currentmodule:: gauxc_shell .. f:type:: gauxc_shell_type diff --git a/docs/gauxc/api/exceptions.rst b/docs/gauxc/api/exceptions.rst new file mode 100644 index 0000000..caf8d69 --- /dev/null +++ b/docs/gauxc/api/exceptions.rst @@ -0,0 +1,55 @@ +Error handling in GauXC +======================= + +This section provides a reference for error handling in GauXC, including C++ exceptions, C status handles, and Fortran status handles. + +C++ exceptions +-------------- + +.. cpp:class:: GauXC::generic_gauxc_exception : public std::exception + + Base class for exceptions thrown by GauXC. This class inherits from std::exception and can be used to catch all exceptions thrown by GauXC. + + .. cpp:function:: const char* what() const noexcept override + + Get a human-readable error message describing the exception. + + :returns: A pointer to a null-terminated string containing the error message. + + +C status handle +--------------- + +.. c:struct:: GauXCStatus + + .. c:member:: int code + + The error code of the status. A value of 0 indicates success, while non-zero values indicate different types of errors. + + .. c:member:: char* message + + A human-readable error message providing more details about the error. + This is a null-terminated string that should be freed by the caller when no longer needed. + + +Fortran status handle +--------------------- + +.. f:module:: gauxc_status + :synopsis: Fortran bindings for GauXC status handling + +.. f:currentmodule:: gauxc_status + +.. f:type:: gauxc_status_type + + Representation of a status handle in the GauXC Fortran API, containing an error code and a message. + + :f integer(c_int) code: The error code of the status. A value of 0 indicates success, while non-zero values indicate different types of errors. + :f type(c_ptr) message: A pointer to a null-terminated string containing a human-readable error message providing more details about the error. This string should be freed by the caller when no longer needed. + + .. f:function:: gauxc_status_message(status) + + Get the error message from a GauXCStatus variable. + + :param type(gauxc_status_type) status: The GauXCStatus variable from which to retrieve the error message. + :returns character(len=*): Error message string. \ No newline at end of file diff --git a/docs/gauxc/api/index.rst b/docs/gauxc/api/index.rst index 6567ce1..0b25352 100644 --- a/docs/gauxc/api/index.rst +++ b/docs/gauxc/api/index.rst @@ -7,8 +7,13 @@ The API includes C++ class definitions, C bindings, and Fortran bindings for var .. toctree:: :maxdepth: 2 - macros molecule basis molgrid + runtime_environment + load_balancer + molecular_weights + xc_integrator + macros + exceptions cmake \ No newline at end of file diff --git a/docs/gauxc/api/load_balancer.rst b/docs/gauxc/api/load_balancer.rst new file mode 100644 index 0000000..2dd0a5b --- /dev/null +++ b/docs/gauxc/api/load_balancer.rst @@ -0,0 +1,202 @@ +Load balancer API +================= + +This section provides a reference for the load balancer in GauXC, including C++ class definitions, C bindings, and Fortran bindings for creating and managing load balancers used in GauXC computations. + + +C++ definitions +--------------- + +.. cpp:class:: GauXC::LoadBalancer + + A class representing a load balancer for distributing computational work across multiple processes in GauXC. + + +.. cpp:class:: GauXC::LoadBalancerFactory + + A factory class for creating LoadBalancer objects based on the specified load balancing strategy. + + .. cpp:function:: LoadBalancerFactory(ExecutionSpace ex, std::string kernel_name) + + Construct a LoadBalancerFactory object with the specified execution space and kernel name. + + Currently accepted values for Host execution space: + + :"DEFAULT": + Read as "REPLICATED-PETITE" + :"REPLICATED": + Read as "REPLICATED-PETITE" + :"REPLICATED-PETITE": + Replicate the load balancer function, only keep non negligible basis functions + :"REPLICATED-FILLIN": + Same as "REPLICATED-PETITE" except if two non-adjacent basis functions are kept, the gaps are filled in. + This gurantees contiguous memory access but leads to significantly more work. + Not advised for general usage. + + Currently accepted values for Device execution space: + + :"DEFAULT": + Read as "REPLICATED" + :"REPLICATED": + Same as Host::REPLICATED-PETITE + + :param ex: The execution space for which to create load balancers. + :param kernel_name: The name of the kernel for which to create load balancers. + + .. cpp:function:: LoadBalancer get_instance(const RuntimeEnvironment& rt, const Molecule& mol, const MolGrid& mg, const BasisSet& bs) + + Get a LoadBalancer instance for the specified runtime environment, molecule, molecular grid, and basis set. + + :param rt: The runtime environment for which to get the load balancer instance. + :param mol: The molecule for which to get the load balancer instance. + :param mg: The molecular grid for which to get the load balancer instance. + :param bs: The basis set for which to get the load balancer instance. + + .. cpp:function:: std::shared_ptr get_shared_instance(RuntimeEnvironment& rt, const Molecule& mol, const MolGrid& mg, const BasisSet& bs) + + Get a shared pointer to a LoadBalancer instance for the specified runtime environment, molecule, molecular grid, and basis set. + + :param rt: The runtime environment for which to get the load balancer instance. + :param mol: The molecule for which to get the load balancer instance. + :param mg: The molecular grid for which to get the load balancer instance. + :param bs: The basis set for which to get the load balancer instance. + + +.. cpp:enum-class:: GauXC::ExecutionSpace + + Enumeration of execution spaces for which load balancers can be created in GauXC. + + The following execution spaces are available: + + .. cpp:enumerator:: Host + + Load balancers for execution on the host CPU. + + .. cpp:enumerator:: Device + + Load balancers for execution on a device (e.g., GPU). + + +C bindings +---------- + +.. c:struct:: GauXCLoadBalancer + + Opaque struct representing a load balancer in the GauXC C API. + + .. c:function:: void gauxc_load_balancer_delete(GauXCStatus* status, GauXCLoadBalancer* lb) + + Delete a load balancer instance. + Part of the :f:func:`gauxc_delete` interface. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param lb: Pointer to the GauXCLoadBalancer instance to be deleted. + +.. c:struct:: GauXCLoadBalancerFactory + + Opaque struct representing a load balancer factory in the GauXC C API. + + .. c:function:: GauXCLoadBalancerFactory* gauxc_load_balancer_factory_new(GauXCStatus* status, enum GauXC_ExecutionSpace ex, const char* kernel_name) + + Create a new load balancer factory with the specified execution space and kernel name. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param ex: The execution space for which to create load balancers. + :param kernel_name: The name of the kernel for which to create load balancers. + + .. c:function:: GauXCLoadBalancer gauxc_load_balancer_factory_get_instance(GauXCStatus* status, GauXCLoadBalancerFactory lbf, const GauXCRuntimeEnvironment rt, const GauXCMolecule mol, const GauXCMolGrid mg, const GauXCBasisSet bs) + + Get a load balancer instance for the specified runtime environment, molecule, molecular grid, and basis set. + Part of the :f:func:`gauxc_get_instance` interface. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param lbf: GauXCLoadBalancerFactory struct from which to get the load balancer instance. + :param rt: Pointer to the runtime environment for which to get the load balancer instance. + :param mol: Pointer to the molecule for which to get the load balancer instance. + :param mg: Pointer to the molecular grid for which to get the load balancer instance. + :param bs: Pointer to the basis set for which to get the load balancer instance. + + .. c:function:: void gauxc_load_balancer_factory_delete(GauXCStatus* status, GauXCLoadBalancerFactory* lbf) + + Delete a load balancer factory instance. + Part of the :f:func:`gauxc_delete` interface. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param lbf: Pointer to the GauXCLoadBalancerFactory instance to be deleted. + + +.. c:enum:: GauXC_ExecutionSpace + + Enumeration of execution spaces for which load balancers can be created in the GauXC C API. + + The following execution spaces are available: + + .. c:enumerator:: GauXC_ExecutionSpace_Host + + Load balancers for execution on the host CPU. + + .. c:enumerator:: GauXC_ExecutionSpace_Device + + Load balancers for execution on a device (e.g., GPU). + + +Fortran bindings +---------------- + +.. f:module:: gauxc_load_balancer + :synopsis: Fortran bindings for GauXC LoadBalancer and LoadBalancerFactory + +.. f:currentmodule:: gauxc_load_balancer + +.. f:type:: gauxc_load_balancer_type + + Opaque type representing a load balancer in the GauXC Fortran API. + Available in the module :f:mod:`gauxc_load_balancer`. + + .. f:function:: gauxc_load_balancer_delete(status, lb) + + Delete a load balancer instance. + + :param type(gauxc_status_type) status: Pointer to a GauXCStatus variable to store the status of the operation. + :param type(gauxc_load_balancer_type) lb: The load balancer instance to be deleted. + +.. f:type:: gauxc_load_balancer_factory_type + + Opaque type representing a load balancer factory in the GauXC Fortran API. + Available in the module :f:mod:`gauxc_load_balancer`. + + .. f:function:: gauxc_load_balancer_factory_new(status, ex, kernel_name) + + Create a new load balancer factory with the specified execution space and kernel name. + + :param type(gauxc_status_type) status: Pointer to a GauXCStatus variable to store the status of the operation. + :param integer(c_int) ex: The execution space for which to create load balancers. + :param character(len=*) kernel_name: The name of the kernel for which to create load balancers. + + .. f:function:: gauxc_load_balancer_factory_get_instance(status, lbf, rt, mol, mg, bs) + + Get a load balancer instance for the specified runtime environment, molecule, molecular grid, and basis set. + + :param type(gauxc_status_type) status: Pointer to a GauXCStatus variable to store the status of the operation. + :param type(gauxc_load_balancer_factory_type) lbf: The load balancer factory from which to get the load balancer instance. + :param type(gauxc_runtime_environment_type) rt: The runtime environment for which to get the load balancer instance. + :param type(gauxc_molecule_type) mol: The molecule for which to get the load balancer instance. + :param type(gauxc_mol_grid_type) mg: The molecular grid for which to get the load balancer instance. + :param type(gauxc_basis_set_type) bs: The basis set for which to get the load balancer instance. + + .. f:subroutine:: gauxc_load_balancer_factory_delete(status, lbf) + + Delete a load balancer factory instance. + + :param type(gauxc_status_type) status: Pointer to a GauXCStatus variable to store the status of the operation. + :param type(gauxc_load_balancer_factory_type) lbf: The load balancer factory instance to be deleted. + +.. f:currentmodule:: gauxc_enums + +.. f:type:: gauxc_execution_space + + Parameter instance of a derived type with members corresponding to the execution spaces for which load balancers can be created in the GauXC Fortran API. + + :f integer(c_int) host: Load balancers for execution on the host CPU. + + :f integer(c_int) device: Load balancers for execution on a device (e.g., GPU). \ No newline at end of file diff --git a/docs/gauxc/api/macros.rst b/docs/gauxc/api/macros.rst index 9db786c..d547e9d 100644 --- a/docs/gauxc/api/macros.rst +++ b/docs/gauxc/api/macros.rst @@ -3,6 +3,11 @@ Macro definitions GauXC provides a number of compile-time macros to indicate available features and configuration options. +.. c:macro:: GAUXC_HAS_ONEDFT + + Defines whether Skala support is available in this build of GauXC. + Enabled with :cmake:variable:`GAUXC_ENABLE_ONEDFT` CMake option. + .. c:macro:: GAUXC_HAS_C Defines whether C bindings are available in this build of GauXC. diff --git a/docs/gauxc/api/molecular_weights.rst b/docs/gauxc/api/molecular_weights.rst new file mode 100644 index 0000000..1bfb29a --- /dev/null +++ b/docs/gauxc/api/molecular_weights.rst @@ -0,0 +1,288 @@ +Molecular grid weights API +========================== + +This section provides a reference for the GauXC API related to molecular grid weights, which can be applied to LoadBalancer tasks to modify their weights based on the molecular grid. The API includes C++ class definitions + +C++ definitions +--------------- + +.. cpp:class:: GauXC::MolecularWeights + + A class representing molecular grid weights in GauXC, which can be applied to a LoadBalancer's tasks. + + .. cpp:function:: void modify_weights(LoadBalancer& lb) + + Apply molecular weights to a LoadBalancer's tasks + + :param lb: LoadBalancer instance to which the molecular grid weights will be applied. + +.. cpp:class:: GauXC::MolecularWeightsFactory + + A factory class for creating MolecularWeights instances in GauXC. + + .. cpp:function:: MolecularWeightsFactory(ExecutionSpace ex, std::string local_work_kernel_name, MolecularWeightsSettings settings) + + Construct a MolecularWeightsFactory instance with the specified settings. + + :param ex: The execution space for which to create molecular grid weights. + :param local_work_kernel_name: Name of the local work kernel to be used. + :param settings: A MolecularWeightsSettings struct containing settings for computing molecular grid weights. + :returns: A MolecularWeightsFactory instance initialized with the specified settings. + + .. cpp:function:: MolecularWeights get_instance() + + Get a MolecularWeights instance created by the factory. + + :returns: A MolecularWeights instance created by the factory. + + .. cpp:function:: std::shared_ptr get_shared_instance() + + Get a shared pointer to a MolecularWeights instance created by the factory. + + :returns: A shared pointer to a MolecularWeights instance created by the factory. + +.. cpp:struct:: GauXC::MolecularWeightsSettings + + Struct representing settings for computing molecular grid weights in GauXC. + + .. cpp:member:: XCWeightAlg weight_alg = XCWeightAlg::Becke + + The algorithm to be used for computing molecular grid weights. Possible values are defined in the XCWeightAlg enum. + + .. cpp:member:: bool becke_size_adjustment + + Whether to apply Becke size adjustment to the molecular grid weights. + Default should be true. + +.. cpp:enum:: GauXC::XCWeightAlg + + The following options are available: + + .. cpp:enumerator:: NOTPARTITIONED + + No partitioning. + + .. cpp:enumerator:: Becke + + Becke's original algorithm for computing molecular grid weights. + + .. cpp:enumerator:: SSF + + Stratmann-Scuseria-Frisch algorithm for computing molecular grid weights. + + .. cpp:enumerator:: LKO + + Lauqua-Kuessman-Ochsenfeld algorithm for computing molecular grid weights. + + +C bindings +---------- + +.. c:struct:: GauXCMolecularWeights + + Opaque struct representing molecular grid weights in the GauXC C API. + + .. c:function:: void gauxc_molecular_weights_modify_weights(GauXCStatus* status, GauXCMolecularWeights mw, LoadBalancer lb) + + Apply molecular weights to a LoadBalancer's tasks + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param mw: GauXCMolecularWeights struct from which to get the molecular grid weight. + :param lb: LoadBalancer struct to which the molecular grid weights will be applied. + + .. c:function:: void gauxc_molecular_weights_delete(GauXCStatus* status, GauXCMolecularWeights* mw) + + Delete a molecular grid weights instance. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param mw: Pointer to the GauXCMolecularWeights instance to be deleted. + +.. c:struct:: GauXCMolecularWeightsFactory + + Opaque struct representing a factory for creating molecular grid weights in the GauXC C API. + + .. c:function:: GauXCMolecularWeightsFactory gauxc_molecular_weights_factory_new(GauXCStatus* status, GauXCMolecularWeightsSettings settings) + + Create a new GauXCMolecularWeightsFactory instance with the specified settings. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param settings: GauXCMolecularWeightsSettings struct containing settings for computing molecular grid weights. + :returns: A new GauXCMolecularWeightsFactory instance initialized with the specified settings. + + .. c:function:: GauXCMolecularWeights gauxc_molecular_weights_factory_get_instance(GauXCStatus* status, GauXCMolecularWeightsFactory mwf, enum GauXC_ExecutionSpace ex, char* local_work_kernel_name, GauXCMolecularWeightsSettings settings) + + Get a GauXCMolecularWeights instance created by the factory. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param mwf: GauXCMolecularWeightsFactory struct from which to get the molecular grid weights instance. + :param local_work_kernel_name: Name of the local work kernel to be used. + :param settings: GauXCMolecularWeightsSettings struct containing settings for computing molecular grid weights. + :returns: A GauXCMolecularWeights instance created by the factory. + + .. c:function:: void gauxc_molecular_weights_factory_delete(GauXCStatus* status, GauXCMolecularWeightsFactory* mwf) + + Delete a GauXCMolecularWeightsFactory instance. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param mwf: Pointer to the GauXCMolecularWeightsFactory instance to be deleted. + +.. c:struct:: GauXCMolecularWeightsSettings + + Representation of settings for computing molecular grid weights in the GauXC C API. + + .. c:member:: enum GauXC_XCWeightAlg weight_alg + + The algorithm to be used for computing molecular grid weights. Possible values are defined in the GauXC_XCWeightAlg enum. + + .. c:member:: bool becke_size_adjustment + + Whether to apply Becke size adjustment to the molecular grid weights. + Default should be true. + +.. c:enum:: GauXC_XCWeightAlg + + Enumeration of algorithms for computing molecular grid weights in the GauXC C API. + + The following algorithms are available: + + .. c:enumerator:: GauXC_XCWeightAlg_NOTPARTITIONED + + No partitioning. + + .. c:enumerator:: GauXC_XCWeightAlg_Becke + + Becke's original algorithm for computing molecular grid weights. + + .. c:enumerator:: GauXC_XCWeightAlg_SSF + + Stratmann-Scuseria-Frisch algorithm for computing molecular grid weights. + + .. c:enumerator:: GauXC_XCWeightAlg_LKO + + Lauqua-Kuessman-Ochsenfeld algorithm for computing molecular grid weights. + + +Fortran bindings +---------------- + +.. f:module:: gauxc_molecular_weights + :synopsis: Fortran bindings for GauXC molecular grid weights + +.. f:currentmodule:: gauxc_molecular_weights + +.. f:type:: gauxc_molecular_weights_type + + Opaque type representing molecular grid weights in the GauXC Fortran API. + Available in the module :f:mod:`gauxc_molecular_weights`. + + .. f:function:: gauxc_molecular_weights_modify_weights(status, mw, lb) + + Apply molecular weights to a LoadBalancer's tasks + + :param type(gauxc_status_type) status: Pointer to a GauXCStatus variable to store the status of the operation. + :param type(gauxc_molecular_weights_type) mw: The molecular grid weights instance from which to get the molecular grid weight. + :param type(gauxc_load_balancer_type) lb: The LoadBalancer instance to which the molecular grid weights will be applied. + + .. f:function:: gauxc_molecular_weights_delete(status, mw) + + Delete a molecular grid weights instance. + Part of the :f:func:`gauxc_delete` interface. + + :param type(gauxc_status_type) status: Pointer to a GauXCStatus variable to store the status of the operation. + :param type(gauxc_molecular_weights_type) mw: The molecular grid weights instance to be deleted. + + +.. f:type:: gauxc_molecular_weights_factory_type + + Opaque type representing a factory for creating molecular grid weights in the GauXC Fortran API. + Available in the module :f:mod:`gauxc_molecular_weights`. + + .. f:function:: gauxc_molecular_weights_factory_new(status, ex, local_work_kernel_name, settings) + + Create a new GauXCMolecularWeightsFactory instance with the specified settings. + + :param type(gauxc_status_type) status: Pointer to a GauXCStatus variable to store the status of the operation. + :param integer(c_int) ex: The execution space for which to get the molecular grid weights instance. Possible values are defined in the gauxc_xc_weight_alg type. + :param character(len=*) local_work_kernel_name: Name of the local work kernel to be used. + :param type(gauxc_molecular_weights_settings_type) settings: The settings for computing molecular grid weights. + :returns type(gauxc_molecular_weights_factory_type): A new GauXCMolecularWeightsFactory instance initialized with the specified settings. + + .. f:function:: gauxc_molecular_weights_factory_get_instance(status, mwf) + + Get a GauXCMolecularWeights instance created by the factory. + Part of the :f:func:`gauxc_get_instance` interface. + + :param type(gauxc_status_type) status: Pointer to a GauXCStatus variable to store the status of the operation. + :param type(gauxc_molecular_weights_factory_type) mwf: The GauXCMolecularWeightsFactory instance from which to get the molecular grid weights instance. + :returns type(gauxc_molecular_weights_type): A GauXCMolecularWeights instance created by the factory. + + .. f:function:: gauxc_molecular_weights_factory_delete(status, mwf) + + Delete a GauXCMolecularWeightsFactory instance. + Part of the :f:func:`gauxc_delete` interface. + + :param type(gauxc_status_type) status: Pointer to a GauXCStatus variable to store the status of the operation. + :param type(gauxc_molecular_weights_factory_type) mwf: The GauXCMolecularWeightsFactory instance to be deleted. + + .. code-block:: fortran + :caption: Example + + use gauxc_enums, only : gauxc_executionspace + use gauxc_load_balancer, only : gauxc_load_balancer_type + use gauxc_molecular_weights, only : gauxc_molecular_weights_factory_type, gauxc_molecular_weights_factory_new, & + & gauxc_get_instance, gauxc_molecular_weights_type, gauxc_molecular_weights_modify_weight, gauxc_delete + + type(gauxc_load_balancer_type) :: lb + type(gauxc_status_type) :: status + type(gauxc_molecular_weights_factory_type) :: mwf + type(gauxc_molecular_weights_type) :: mw + + ! setup load balancer here + + main: block + call gauxc_molecular_weights_factory_new(status, gauxc_executionspace%host, & + & "Default", gauxc_molecular_weights_settings()) + if (status%code /= 0) exit main + mw = gauxc_get_instance(status, mwf) + if (status%code /= 0) exit main + call gauxc_molecular_weights_modify_weight(status, mw, lb) + if (status%code /= 0) exit main + end block main + if (status%code /= 0) then + ! handle error + end if + + call gauxc_delete(status, mw) + call gauxc_delete(status, mwf) + + +.. f:type:: gauxc_molecular_weights_settings + + Parameter instance of a derived type representing settings for computing molecular grid weights in the GauXC Fortran API. + Available in the module :f:mod:`gauxc_molecular_weights`. + + :f integer(c_int) weight_alg: The algorithm to be used for computing molecular grid weights. Possible values are defined in the gauxc_xc_weight_alg type. + :f logical(c_bool) becke_size_adjustment: Whether to apply Becke size adjustment to the molecular grid weights. Default should be true. + + .. code-block:: fortran + :caption: Example + + use gauxc_enums, only : gauxc_xcweightalg + use gauxc_molecular_weights, only : gauxc_molecular_weights_settings + type(gauxc_molecular_weights_settings) :: settings + settings%weight_alg = gauxc_xcweightalg%becke + settings%becke_size_adjustment = .true. + +.. f:currentmodule:: gauxc_enums + +.. f:type:: gauxc_xcweightalg + + Parameter instance of a derived type representing the algorithm to be used for computing molecular grid weights in the GauXC Fortran API. + Available in the module :f:mod:`gauxc_enums`. + + The following algorithms are available: + + :f integer(c_int) notpartitioned: No partitioning. + :f integer(c_int) becke: Becke's original algorithm for computing molecular grid weights. + :f integer(c_int) ssf: Stratmann-Scuseria-Frisch algorithm for computing molecular grid weights. + :f integer(c_int) lko: Lauqua-Kuessman-Ochsenfeld algorithm for computing molecular grid weights. \ No newline at end of file diff --git a/docs/gauxc/api/molecule.rst b/docs/gauxc/api/molecule.rst index 28ddd48..85018aa 100644 --- a/docs/gauxc/api/molecule.rst +++ b/docs/gauxc/api/molecule.rst @@ -150,6 +150,14 @@ Fortran bindings :param integer(c_int64_t) natoms: The number of atoms in the molecule. :returns type(gauxc_molecule_type): A new gauxc_molecule_type object initialized with the given atoms. + .. f:function:: gauxc_molecule_delete(status, molecule) + + Delete a gauxc_molecule_type object. + Part of the :f:func:`gauxc_delete` interface. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_molecule_type) molecule: The gauxc_molecule_type object to be deleted. + .. f:currentmodule:: gauxc_atom .. f:type:: gauxc_atom_type diff --git a/docs/gauxc/api/molgrid.rst b/docs/gauxc/api/molgrid.rst index 6ffbae3..86c3ffb 100644 --- a/docs/gauxc/api/molgrid.rst +++ b/docs/gauxc/api/molgrid.rst @@ -248,6 +248,14 @@ Fortran bindings :param integer(c_int) grid_size: The default atomic grid size to use for the atomic grids. :returns type(gauxc_molgrid_type): A new gauxc_molgrid_type object initialized with the specified parameters for the given molecule. + .. f:function:: subroutine gauxc_molgrid_delete(status, molgrid) + + Delete a gauxc_molgrid_type object and free its resources. + Part of the :f:func:`gauxc_delete` interface. + + :param type(gauxc_status_type) status: Output parameter to store the status of the operation. + :param type(gauxc_molgrid_type) molgrid: The gauxc_molgrid_type object to delete. + .. f:currentmodule:: gauxc_enums .. f:type:: gauxc_radialquad diff --git a/docs/gauxc/api/runtime_environment.rst b/docs/gauxc/api/runtime_environment.rst new file mode 100644 index 0000000..8d37c69 --- /dev/null +++ b/docs/gauxc/api/runtime_environment.rst @@ -0,0 +1,277 @@ +Runtime environment +=================== + +This section provides a reference for the runtime environment in GauXC, including C++ class definitions, C bindings, and Fortran bindings for creating and managing runtime environments used in GauXC computations. +The runtime environment encapsulates information about the MPI communicator and device configuration for GauXC computations. + + +C++ definitions +--------------- + +.. cpp:class:: GauXC::RuntimeEnvironment + + A class representing the runtime environment for GauXC computations, including information about the MPI communicator and device configuration. + + .. cpp:function:: RuntimeEnvironment(MPI_Comm comm) + + Construct a RuntimeEnvironment object with the specified MPI communicator. + + .. important:: Signature changes if :c:macro:`GAUXC_HAS_MPI` is defined and :cmake:variable:`GAUXC_ENABLE_MPI` is enabled. + + :param comm: The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC. + + .. cpp:function:: int comm_rank() const + + Get the rank of the current process in the MPI communicator associated with this runtime environment. + + :returns: The rank of the current process in the MPI communicator. + + .. cpp:function:: int comm_size() const + + Get the size of the MPI communicator associated with this runtime environment. + + :returns: The size of the MPI communicator. + + .. cpp:function:: DeviceRuntimeEnvironment as_device_runtime() const + + Convert the current runtime environment to a device runtime environment. + + +.. cpp:class:: GauXC::DeviceRuntimeEnvironment : public RuntimeEnvironment + + A class representing a device runtime environment for GauXC computations, including information about the device configuration and memory usage. + + .. cpp:function:: DeviceRuntimeEnvironment(MPI_Comm comm, double fill_fraction) + + Construct a DeviceRuntimeEnvironment object with the specified MPI communicator and device memory fill fraction. + + .. important:: Signature changes if :c:macro:`GAUXC_HAS_MPI` is defined and :cmake:variable:`GAUXC_ENABLE_MPI` is enabled. + + :param comm: The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC. + :param fill_fraction: The fraction of the device memory to be used for GauXC computations (between 0 and 1). + + .. cpp:function:: DeviceRuntimeEnvironment(MPI_Comm comm, void* mem, size_t mem_size) + + Construct a DeviceRuntimeEnvironment object with the specified MPI communicator and user-provided memory. + + .. important:: Signature changes if :c:macro:`GAUXC_HAS_MPI` is defined and :cmake:variable:`GAUXC_ENABLE_MPI` is enabled. + + :param comm: The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC. + :param mem: Pointer to the user-provided memory to be used for GauXC computations. + :param mem_size: The size of the user-provided memory in bytes. + + .. cpp:function:: void* device_memory() const + + Get a pointer to the device memory associated with this runtime environment. + + :returns: A pointer to the device memory associated with this runtime environment. + + .. cpp:function:: size_t device_memory_size() const + + Get the size of the device memory associated with this runtime environment in bytes. + + :returns: The size of the device memory associated with this runtime environment in bytes. + + .. cpp:function:: bool owns_memory() const + + Check if this runtime environment owns the device memory. + + :returns: True if this runtime environment owns the device memory, false otherwise. + + .. cpp:function:: void release_buffer() + + Release the device memory buffer associated with this runtime environment, if it is owned by this runtime environment. + + .. cpp:function:: void set_buffer(void* mem, size_t mem_size) + + Set the device memory buffer for this runtime environment to the specified user-provided memory. + + :param mem: Pointer to the user-provided memory to be used for GauXC computations. + :param mem_size: The size of the user-provided memory in bytes. + + +C bindings +---------- + +.. c:struct:: GauXCRuntimeEnvironment + + Opaque struct representing the runtime environment in the GauXC C API. + + .. c:function:: GauXCRuntimeEnvironment gauxc_runtime_environment_new(GauXCStatus* status, MPI_Comm comm) + + Create a new GauXCRuntimeEnvironment object. + + .. important:: Signature changes if :c:macro:`GAUXC_HAS_MPI` is defined and :cmake:variable:`GAUXC_ENABLE_MPI` is enabled. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param comm: The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC. + :returns: A new GauXCRuntimeEnvironment object. + + .. c:function:: GauXCRuntimeEnvironment gauxc_device_runtime_environment_new(GauXCStatus* status, MPI_Comm comm, double fill_fraction) + + Create a new GauXCRuntimeEnvironment object for a specific device. + + .. important:: Signature changes if :c:macro:`GAUXC_HAS_MPI` is defined and :cmake:variable:`GAUXC_ENABLE_MPI` is enabled. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param comm: The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC. + :param fill_fraction: The fraction of the device memory to be used for GauXC computations (between 0 and 1). + :returns: A new GauXCRuntimeEnvironment object for the specified device. + + .. c:function:: GauXCRuntimeEnvironment gauxc_runtime_environment_new_mem(GauXCStatus* status, MPI_Comm comm, void* mem, size_t mem_size) + + Create a new GauXCRuntimeEnvironment object using user-provided memory. + + .. important:: Signature changes if :c:macro:`GAUXC_HAS_MPI` is defined and :cmake:variable:`GAUXC_ENABLE_MPI` is enabled. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param comm: The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC. + :param mem: Pointer to the user-provided memory to be used for GauXC computations. + :param mem_size: The size of the user-provided memory in bytes. + :returns: A new GauXCRuntimeEnvironment object using the provided memory. + + .. c:function:: int gauxc_runtime_environment_comm_rank(GauXCStatus* status, GauXCRuntimeEnvironment env) + + Get the rank of the current process in the MPI communicator associated with the GauXCRuntimeEnvironment. + Returns 0 if MPI support is not enabled in GauXC. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param env: The GauXCRuntimeEnvironment object for which to get the MPI rank. + :returns: The rank of the current process in the MPI communicator. + + .. c:function:: int gauxc_runtime_environment_comm_size(GauXCStatus* status, GauXCRuntimeEnvironment env) + + Get the size of the MPI communicator associated with the GauXCRuntimeEnvironment. + Returns 1 if MPI support is not enabled in GauXC. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param env: The GauXCRuntimeEnvironment object for which to get the MPI size. + :returns: The size of the MPI communicator. + + .. c:function:: void gauxc_runtime_environment_delete(GauXCStatus* status, GauXCRuntimeEnvironment* env) + + Delete a GauXCRuntimeEnvironment object. + + :param status: Pointer to a GauXCStatus variable to store the status of the operation. + :param env: Pointer to the GauXCRuntimeEnvironment object to be deleted. + + +Fortran bindings +---------------- + +.. f:module:: gauxc_runtime_environment + :synopsis: Fortran bindings for GauXC runtime environment objects. + +.. f:currentmodule:: gauxc_runtime_environment + +.. f:type:: gauxc_runtime_environment_type + + Opaque type representing the runtime environment in the GauXC Fortran API. + Available in the module :f:mod:`gauxc_runtime_environment`. + + .. f:function:: gauxc_runtime_environment_new(status) + + Create a new GauXCRuntimeEnvironment object. + If MPI support is enabled in GauXC, this function creates a runtime environment with the default MPI communicator (``MPI_COMM_WORLD``). + Part of the :f:func:`gauxc_runtime_environment_new` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :returns type(gauxc_runtime_environment_type): A new GauXCRuntimeEnvironment object. + + .. f:function:: gauxc_runtime_environment_new_mpi(status, comm) + + Create a new GauXCRuntimeEnvironment object. + This function is only available if MPI support is enabled in GauXC and allows specifying the MPI communicator to be used for GauXC computations. + Part of the :f:func:`gauxc_runtime_environment_new` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :param integer comm: The MPI communicator to be used for GauXC computations. + :returns type(gauxc_runtime_environment_type): A new GauXCRuntimeEnvironment object. + + .. f:function:: gauxc_runtime_environment_new_mpi_f08(status, comm) + + Create a new GauXCRuntimeEnvironment object. + This function is only available if MPI support is enabled in GauXC and allows specifying the MPI communicator to be used for GauXC computations. + Part of the :f:func:`gauxc_runtime_environment_new` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :param type(MPI_Comm) comm: The MPI communicator to be used for GauXC computations. + :returns type(gauxc_runtime_environment_type): A new GauXCRuntimeEnvironment object. + + .. f:function:: gauxc_device_runtime_environment_new(status, fill_fraction) + + Create a new GauXCRuntimeEnvironment object for a specific device. + If MPI support is enabled in GauXC, this function creates a runtime environment with the default MPI communicator (``MPI_COMM_WORLD``). + This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the fraction of the device memory to be used for GauXC computations. + Part of the :f:func:`gauxc_device_runtime_environment_new` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :param integer comm: The MPI communicator to be used for GauXC computations. + :param real(c_double) fill_fraction: The fraction of the device memory to be used for GauXC computations (between 0 and 1). + :returns type(gauxc_runtime_environment_type): A new GauXCRuntimeEnvironment object for the specified device. + + .. f:function:: gauxc_device_runtime_environment_new_mpi(status, comm, fill_fraction) + + Create a new GauXCRuntimeEnvironment object for a specific device. + This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the MPI communicator and the fraction of the device memory to be used for GauXC computations. + Part of the :f:func:`gauxc_device_runtime_environment_new` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :param integer comm: The MPI communicator to be used for GauXC computations. + :param real(c_double) fill_fraction: The fraction of the device memory to be used for GauXC computations (between 0 and 1). + :returns type(gauxc_runtime_environment_type): A new GauXCRuntimeEnvironment object for the specified device. + + .. f:function:: gauxc_device_runtime_environment_new_mpi_f08(status, comm, fill_fraction) + + Create a new GauXCRuntimeEnvironment object for a specific device. + This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the MPI communicator and the fraction of the device memory to be used for GauXC computations. + Part of the :f:func:`gauxc_device_runtime_environment_new` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :param type(MPI_Comm) comm: The MPI communicator to be used for GauXC computations. + :param real(c_double) fill_fraction: The fraction of the device memory to be used for GauXC computations (between 0 and 1). + :returns type(gauxc_runtime_environment_type): A new GauXCRuntimeEnvironment object for the specified device. + + .. f:function:: gauxc_device_runtime_environment_new_mem(status, mem, mem_size) + + Create a new GauXCRuntimeEnvironment object using user-provided memory. + If MPI support is enabled in GauXC, this function creates a runtime environment with the default MPI communicator (``MPI_COMM_WORLD``). + This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the user-provided memory to be used for GauXC computations. + Part of the :f:func:`gauxc_device_runtime_environment_new` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :param type(c_ptr) mem: Pointer to the user-provided memory to be used for GauXC computations. + :param integer(c_size_t) mem_size: The size of the user-provided memory in bytes. + :returns type(gauxc_runtime_environment_type): A new GauXCRuntimeEnvironment object using the provided memory. + + .. f:function:: gauxc_device_runtime_environment_new_mem_mpi(status, comm, mem, mem_size) + + Create a new GauXCRuntimeEnvironment object using user-provided memory. + This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the MPI communicator and the user-provided memory to be used for GauXC computations. + Part of the :f:func:`gauxc_device_runtime_environment_new` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :param integer comm: The MPI communicator to be used for GauXC computations. + :param type(c_ptr) mem: Pointer to the user-provided memory to be used for GauXC computations. + :param integer(c_size_t) mem_size: The size of the user-provided memory in bytes. + :returns type(gauxc_runtime_environment_type): A new GauXCRuntimeEnvironment object using the provided memory. + + .. f:function:: gauxc_device_runtime_environment_new_mem_mpi_f08(status, comm, mem, mem_size) + + Create a new GauXCRuntimeEnvironment object using user-provided memory. + This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the MPI communicator and the user-provided memory to be used for GauXC computations. + Part of the :f:func:`gauxc_device_runtime_environment_new` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :param type(MPI_Comm) comm: The MPI communicator to be used for GauXC computations. + :param type(c_ptr) mem: Pointer to the user-provided memory to be used for GauXC computations. + :param integer(c_size_t) mem_size: The size of the user-provided memory in bytes. + :returns type(gauxc_runtime_environment_type): A new GauXCRuntimeEnvironment object using the provided memory. + + .. f:function:: gauxc_runtime_environment_delete(status, env) + + Delete a GauXCRuntimeEnvironment object. + Part of the :f:func:`gauxc_delete` interface. + + :param type(gauxc_status_type) status: Variable to store the status of the operation. + :param type(gauxc_runtime_environment_type) env: The GauXCRuntimeEnvironment object to be deleted. \ No newline at end of file diff --git a/docs/gauxc/api/xc_integrator.rst b/docs/gauxc/api/xc_integrator.rst new file mode 100644 index 0000000..9fbdf92 --- /dev/null +++ b/docs/gauxc/api/xc_integrator.rst @@ -0,0 +1,302 @@ +Exchange-correlation integrator +=============================== + +C bindings +---------- + +.. c:struct:: GauXCIntegrator + + Opaque type representing an exchange-correlation integrator instance. + + .. c:function:: GauXCIntegrator gauxc_integrator_new(GauXCStatus* status, const GauXCFunctional functional, const GauXCLoadBalancer lb, enum GauXC_ExecutionSpace ex, const char* integrator_input_type, const char* integrator_kernel_name, const char* local_work_kernel_name, const char* reduction_kernel_name) + + Create a new exchange-correlation integrator instance with the specified functional, load balancer, execution space, and kernel names. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param functional: The exchange-correlation functional for which to create the integrator. + :param lb: The load balancer to use for the integrator. + :param ex: The execution space for which to create the integrator. + :param integrator_input_type: The type of input data expected by the integrator kernels. + :param integrator_kernel_name: The name of the kernel to use for the main integration step. + :param local_work_kernel_name: The name of the kernel to use for computing local work sizes. + :param reduction_kernel_name: The name of the kernel to use for reduction operations. + :returns: A new GauXCIntegrator instance initialized with the specified parameters. + + .. c:function:: void gauxc_integrator_integrate_den(GauXCStatus* status, GauXCIntegrator integrator, const int64_t m, const int64_t n, const double* density_matrix, const int64_t ldp, double* den) + + Compute the total density to get the number of electrons + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param integrator: The GauXCIntegrator instance to use for the integration. + :param m: The number of rows in the density matrix. + :param n: The number of columns in the density matrix. + :param density_matrix: Pointer to the input density matrix data. + :param ldp: The leading dimension of the density matrix. + :param den: Pointer to the output variable where the computed total density will be stored. + + .. c:function:: void gauxc_integrator_eval_exc_rks(GauXCStatus* status, GauXCIntegrator integrator, const int64_t m, const int64_t n, const double* density_matrix, const int64_t ldp, double* exc) + + Compute the exchange-correlation energy for a given density matrix. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param integrator: The GauXCIntegrator instance to use for the integration. + :param m: The number of rows in the density matrix. + :param n: The number of columns in the density matrix. + :param density_matrix: Pointer to the input density matrix data. + :param ldp: The leading dimension of the density matrix. + :param exc: Pointer to the output variable where the computed exchange-correlation energy will be stored. + + .. c:function:: void gauxc_integrator_eval_exc_uks(GauXCStatus* status, GauXCIntegrator integrator, const int64_t m, const int64_t n, const double* density_matrix_s, const int64_t ldp_s, const double* density_matrix_z, const int64_t ldp_z, double* exc) + + Compute the exchange-correlation energy for a given density matrix. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param integrator: The GauXCIntegrator instance to use for the integration. + :param m: The number of rows in the density matrix. + :param n: The number of columns in the density matrix. + :param density_matrix_s: Pointer to the input density matrix data. + :param ldp_s: The leading dimension of the density matrix. + :param density_matrix_z: Pointer to the input density matrix data. + :param ldp_z: The leading dimension of the density matrix. + :param exc: Pointer to the output variable where the computed exchange-correlation energy will be stored. + + .. c:function:: void gauxc_integrator_eval_exc_gks(GauXCStatus* status, GauXCIntegrator integrator, const int64_t m, const int64_t n, const double* density_matrix_s, const int64_t ldp_s, const double* density_matrix_z, const int64_t ldp_z, const double* density_matrix_y, const int64_t ldp_y, const double* density_matrix_x, const int64_t ldp_x, double* exc) + + Compute the exchange-correlation energy for a given density matrix. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param integrator: The GauXCIntegrator instance to use for the integration. + :param m: The number of rows in the density matrix. + :param n: The number of columns in the density matrix. + :param density_matrix_s: Pointer to the input density matrix data. + :param ldp_s: The leading dimension of the density matrix. + :param density_matrix_z: Pointer to the input density matrix data. + :param ldp_z: The leading dimension of the density matrix. + :param density_matrix_y: Pointer to the input density matrix data. + :param ldp_y: The leading dimension of the density matrix. + :param density_matrix_x: Pointer to the input density matrix data. + :param ldp_x: The leading dimension of the density matrix. + :param exc: Pointer to the output variable where the computed exchange-correlation energy will be stored. + + .. c:function:: void gauxc_integrator_eval_exc_vxc_rks(GauXCStatus* status, GauXCIntegrator integrator, const int64_t m, const int64_t n, const double* density_matrix, const int64_t ldp, double* exc, double* vxc_matrix, const int64_t ldp_vxc) + + Compute the exchange-correlation energy and potential for a given density matrix. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param integrator: The GauXCIntegrator instance to use for the integration. + :param m: The number of rows in the density matrix. + :param n: The number of columns in the density matrix. + :param density_matrix: Pointer to the input density matrix data. + :param ldp: The leading dimension of the density matrix. + :param exc: Pointer to the output variable where the computed exchange-correlation energy will be stored. + :param vxc_matrix: Pointer to the output array where the computed exchange-correlation potential matrix will be stored. + :param ldp_vxc: The leading dimension of the vxc_matrix array. + + .. c:function:: void gauxc_integrator_eval_exc_vxc_uks(GauXCStatus* status, GauXCIntegrator integrator, const int64_t m, const int64_t n, const double* density_matrix_s, const int64_t ldp_s, const double* density_matrix_z, const int64_t ldp_z, double* exc, double* vxc_matrix_s, const int64_t ldp_vxc_s, double* vxc_matrix_z, const int64_t ldp_vxc_z) + + Compute the exchange-correlation energy and potential for a given density matrix. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param integrator: The GauXCIntegrator instance to use for the integration. + :param m: The number of rows in the density matrix. + :param n: The number of columns in the density matrix. + :param density_matrix_s: Pointer to the input density matrix data. + :param ldp_s: The leading dimension of the density matrix. + :param density_matrix_z: Pointer to the input density matrix data. + :param ldp_z: The leading dimension of the density matrix. + :param exc: Pointer to the output variable where the computed exchange-correlation energy will be stored. + :param vxc_matrix_s: Pointer to the output array where the computed exchange-correlation potential matrix for the spin-up component will be stored. + :param ldp_vxc_s: The leading dimension of the vxc_matrix_s array. + :param vxc_matrix_z: Pointer to the output array where the computed exchange-correlation potential matrix for the spin-down component will be stored. + :param ldp_vxc_z: The leading dimension of the vxc_matrix_z array. + + + .. c:function:: void gauxc_integrator_eval_exc_vxc_onedft_uks(GauXCStatus* status, GauXCIntegrator integrator, const int64_t m, const int64_t n, const double* density_matrix_s, const int64_t ldp_s, const double* density_matrix_z, const int64_t ldp_z, const char* model, double* exc, double* vxc_matrix_s, const int64_t ldp_vxc_s, double* vxc_matrix_z, const int64_t ldp_vxc_z) + + Compute the exchange-correlation energy and potential for a given density matrix. + + .. important:: + + This function is available if :c:macro:`GAUXC_HAS_ONEDFT` is defined or the CMake option :cmake:variable:`GAUXC_ENABLE_ONEDFT` is enabled. + It requires a compatible checkpoint for the Skala implementation of the functional, which can be specified with the ``model`` parameter. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param integrator: The GauXCIntegrator instance to use for the integration. + :param m: The number of rows in the density matrix. + :param n: The number of columns in the density matrix. + :param density_matrix_s: Pointer to the input density matrix data. + :param ldp_s: The leading dimension of the density matrix. + :param density_matrix_z: Pointer to the input density matrix data. + :param ldp_z: The leading dimension of the density matrix. + :param model: The model checkpoint to use for evaluating the exchange-correlation energy and potential. + :param exc: Pointer to the output variable where the computed exchange-correlation energy will be stored. + :param vxc_matrix_s: Pointer to the output array where the computed exchange-correlation potential matrix for the spin-up component will be stored. + :param ldp_vxc_s: The leading dimension of the vxc_matrix_s array. + :param vxc_matrix_z: Pointer to the output array where the computed exchange-correlation potential matrix for the spin-down component will be stored. + :param ldp_vxc_z: The leading dimension of the vxc_matrix_z array. + + .. c:function:: void gauxc_integrator_eval_exc_vxc_gks(GauXCStatus* status, GauXCIntegrator integrator, const int64_t m, const int64_t n, const double* density_matrix_s, const int64_t ldp_s, const double* density_matrix_z, const int64_t ldp_z, const double* density_matrix_y, const int64_t ldp_y, const double* density_matrix_x, const int64_t ldp_x, double* exc, double* vxc_matrix_s, const int64_t ldp_vxc_s, double* vxc_matrix_z, const int64_t ldp_vxc_z, double* vxc_matrix_y, const int64_t ldp_vxc_y, double* vxc_matrix_x, const int64_t ldp_vxc_x) + + Compute the exchange-correlation energy and potential for a given density matrix. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param integrator: The GauXCIntegrator instance to use for the integration. + :param m: The number of rows in the density matrix. + :param n: The number of columns in the density matrix. + :param density_matrix_s: Pointer to the input density matrix data. + :param ldp_s: The leading dimension of the density matrix. + :param density_matrix_z: Pointer to the input density matrix data. + :param ldp_z: The leading dimension of the density matrix. + :param density_matrix_y: Pointer to the input density matrix data. + :param ldp_y: The leading dimension of the density matrix. + :param density_matrix_x: Pointer to the input density matrix data. + :param ldp_x: The leading dimension of the density matrix. + :param exc: Pointer to the output variable where the computed exchange-correlation energy will be stored. + :param vxc_matrix_s: Pointer to the output array where the computed exchange-correlation potential matrix for the spin-up component will be stored. + :param ldp_vxc_s: The leading dimension of the vxc_matrix_s array. + :param vxc_matrix_z: Pointer to the output array where the computed exchange-correlation potential matrix for the spin-down component will be stored. + :param ldp_vxc_z: The leading dimension of the vxc_matrix_z array. + :param vxc_matrix_y: Pointer to the output array where the computed exchange-correlation potential matrix for the spin-y component will be stored. + :param ldp_vxc_y: The leading dimension of the vxc_matrix_y array. + :param vxc_matrix_x: Pointer to the output array where the computed exchange-correlation potential matrix for the spin-x component will be stored. + :param ldp_vxc_x: The leading dimension of the vxc_matrix_x array. + + .. c:function:: void gauxc_integrator_delete(GauXCStatus* status, GauXCIntegrator* integrator) + + Delete an exchange-correlation integrator instance. + + :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. + :param integrator: Pointer to the GauXCIntegrator instance to be deleted. + + +Fortran bindings +---------------- + +.. f:module:: gauxc_integrator + :synopsis: Fortran bindings for GauXC exchange-correlation integrator objects. + +.. f:currentmodule:: gauxc_integrator + +.. f:type:: gauxc_integrator_type + + Opaque type representing an exchange-correlation integrator instance in the GauXC Fortran API. + Available in the module :f:mod:`gauxc_integrator`. + + .. f:function:: gauxc_integrator_new(status, functional, lb, ex[, integrator_input_type, integrator_kernel_name, local_work_kernel_name, reduction_kernel_name]) + + Create a new exchange-correlation integrator instance with the specified functional, load balancer, execution space, and kernel names. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_functional_type) functional: The exchange-correlation functional for which to create the integrator. + :param type(gauxc_load_balancer_type) lb: The load balancer to use for the integrator. + :param integer(c_int) ex: The execution space for which to create the integrator. + :optional character(len=*) integrator_input_type: The type of input data expected by the integrator kernels. Default: "Replicated" + :optional character(len=*) integrator_kernel_name: The name of the kernel to use for the main integration step. Default: "Default" + :optional character(len=*) local_work_kernel_name: The name of the kernel to use for computing local work sizes. Default: "Default" + :optional character(len=*) reduction_kernel_name: The name of the kernel to use for reduction operations. Default: "Default" + :returns type(gauxc_integrator_type): A new gauxc_integrator_type object initialized with the specified parameters. + + .. f:subroutine:: gauxc_integrator_integrate_den(status, integrator, density_matrix, den) + + Compute the total density to get the number of electrons. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_integrator_type) integrator: The GauXCIntegrator instance to use for the integration. + :param real(c_double) density_matrix [dimension(:,:)]: The input density matrix data. + :param real(c_double) den: Output variable where the computed total density will be stored. + + .. f:subroutine:: gauxc_integrator_eval_exc_rks(status, integrator, density_matrix, exc) + + Compute the exchange-correlation energy for a given density matrix. + Part of the :f:func:`gauxc_eval_exc` interface. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_integrator_type) integrator: The GauXCIntegrator instance to use for the integration. + :param real(c_double) density_matrix [dimension(:,:)]: The input density matrix data. + :param real(c_double) exc: Output variable where the computed exchange-correlation energy will be stored. + + .. f:subroutine:: gauxc_integrator_eval_exc_uks(status, integrator, density_matrix_s, density_matrix_z, exc) + + Compute the exchange-correlation energy for a given density matrix. + Part of the :f:func:`gauxc_eval_exc` interface. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_integrator_type) integrator: The GauXCIntegrator instance to use for the integration. + :param real(c_double) density_matrix_s [dimension(:,:)]: The input density matrix data for the spin-up component. + :param real(c_double) density_matrix_z [dimension(:,:)]: The input density matrix data for the spin-down component. + :param real(c_double) exc: Output variable where the computed exchange-correlation energy will be stored. + + .. f:subroutine:: gauxc_integrator_eval_exc_gks(status, integrator, density_matrix_s, density_matrix_z, density_matrix_y, density_matrix_x, exc) + + Compute the exchange-correlation energy for a given density matrix. + Part of the :f:func:`gauxc_eval_exc` interface. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_integrator_type) integrator: The GauXCIntegrator instance to use for the integration. + :param real(c_double) density_matrix_s [dimension(:,:)]: The input density matrix data for the spin-up component. + :param real(c_double) density_matrix_z [dimension(:,:)]: The input density matrix data for the spin-down component. + :param real(c_double) density_matrix_y [dimension(:,:)]: The input density matrix data for the spin-y component. + :param real(c_double) density_matrix_x [dimension(:,:)]: The input density matrix data for the spin-x component. + :param real(c_double) exc: Output variable where the computed exchange-correlation energy will be stored. + + .. f:subroutine:: gauxc_integrator_eval_exc_vxc_rks(status, integrator, density_matrix, exc, vxc_matrix, ldp_vxc) + + Compute the exchange-correlation energy and potential for a given density matrix. + Part of the :f:func:`gauxc_eval_exc_vxc` interface. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_integrator_type) integrator: The GauXCIntegrator instance to use for the integration. + :param real(c_double) density_matrix [dimension(:,:)]: The input density matrix data. + :param real(c_double) exc: Output variable where the computed exchange-correlation energy will be stored. + :param real(c_double) vxc_matrix [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix will be stored. + :param integer(c_int64_t) ldp_vxc: The leading dimension of the vxc_matrix array. + + .. f:subroutine:: gauxc_integrator_eval_exc_vxc_uks(status, integrator, density_matrix_s, density_matrix_z, exc, vxc_matrix_s, vxc_matrix_z) + + Compute the exchange-correlation energy and potential for a given density matrix. + Part of the :f:func:`gauxc_eval_exc_vxc` interface. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_integrator_type) integrator: The GauXCIntegrator instance to use for the integration. + :param real(c_double) density_matrix_s [dimension(:,:)]: The input density matrix data for the spin-up component. + :param real(c_double) density_matrix_z [dimension(:,:)]: The input density matrix data for the spin-down component. + :param real(c_double) exc: Output variable where the computed exchange-correlation energy will be stored. + :param real(c_double) vxc_matrix_s [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-up component will be stored. + :param real(c_double) vxc_matrix_z [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-down component will be stored. + + .. f:subroutine:: gauxc_integrator_eval_exc_vxc_onedft_uks(status, integrator, density_matrix_s, density_matrix_z, model, exc, vxc_matrix_s, vxc_matrix_z) + + Compute the exchange-correlation energy and potential for a given density matrix. + Part of the :f:func:`gauxc_eval_exc_vxc` interface. + + .. important:: + + This function is available if :c:macro:`GAUXC_HAS_ONEDFT` is defined or the CMake option :cmake:variable:`GAUXC_ENABLE_ONEDFT` is enabled. + It requires a compatible checkpoint for the Skala implementation of the functional, which can be specified with the ``model`` parameter. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_integrator_type) integrator: The GauXCIntegrator instance to use for the integration. + :param real(c_double) density_matrix_s [dimension(:,:)]: The input density matrix data for the spin-up component. + :param real(c_double) density_matrix_z [dimension(:,:)]: The input density matrix data for the spin-down component. + :param character(len=*) model: The model checkpoint to use for evaluating the exchange-correlation energy and potential. + :param real(c_double) exc: Output variable where the computed exchange-correlation energy will be stored. + :param real(c_double) vxc_matrix_s [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-up component will be stored. + :param real(c_double) vxc_matrix_z [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-down component will be stored. + + .. f:subroutine:: gauxc_integrator_eval_exc_vxc_gks(status, integrator, density_matrix_s, density_matrix_z, density_matrix_y, density_matrix_x, exc, vxc_matrix_s, vxc_matrix_z, vxc_matrix_y, vxc_matrix_x) + + Compute the exchange-correlation energy and potential for a given density matrix. + Part of the :f:func:`gauxc_eval_exc_vxc` interface. + + :param type(gauxc_status_type) status: A variable to store the status of the operation. + :param type(gauxc_integrator_type) integrator: The GauXCIntegrator instance to use for the integration. + :param real(c_double) density_matrix_s [dimension(:,:)]: The input density matrix data for the spin-up component. + :param real(c_double) density_matrix_z [dimension(:,:)]: The input density matrix data for the spin-down component. + :param real(c_double) density_matrix_y [dimension(:,:)]: The input density matrix data for the spin-y component. + :param real(c_double) density_matrix_x [dimension(:,:)]: The input density matrix data for the spin-x component. + :param real(c_double) exc: Output variable where the computed exchange-correlation energy will be stored. + :param real(c_double) vxc_matrix_s [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-up component will be stored. + :param real(c_double) vxc_matrix_z [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-down component will be stored. + :param real(c_double) vxc_matrix_y [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-y component will be stored. + :param real(c_double) vxc_matrix_x [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-x component will be stored. + From bfeee5e19fc10bcc63f5f7d9bba03cf28ffed1a9 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert Date: Mon, 2 Mar 2026 16:15:34 +0100 Subject: [PATCH 5/5] Add full documentation for XC integrator --- docs/gauxc/api/xc_integrator.rst | 136 +++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/docs/gauxc/api/xc_integrator.rst b/docs/gauxc/api/xc_integrator.rst index 9fbdf92..f7f2d59 100644 --- a/docs/gauxc/api/xc_integrator.rst +++ b/docs/gauxc/api/xc_integrator.rst @@ -1,6 +1,133 @@ Exchange-correlation integrator =============================== +C++ definitions +--------------- + +.. cpp:class:: template GauXC::XCIntegrator + + .. cpp:type:: matrix_type = MatrixType + + The type of matrix data expected by the integrator kernels. + + .. cpp:type:: value_type = matrix_type::value_type + + The scalar value type corresponding to the matrix type. + + .. cpp:function:: value_type integrate_den(const MatrixType& density_matrix) const + + Compute the total density to get the number of electrons. + + :param density_matrix: The input density matrix data. + :returns: The computed total density. + + .. cpp:function:: value_type eval_exc(const MatrixType& density_matrix) const + + Compute the exchange-correlation energy for a given density matrix. + + :param density_matrix: The input density matrix data. + :returns: The computed exchange-correlation energy. + + .. cpp:function:: value_type eval_exc(const MatrixType& density_matrix_s, const MatrixType& density_matrix_z) const + + Compute the exchange-correlation energy for a given density matrix. + + :param density_matrix_s: The input density matrix data for the spin-up component. + :param density_matrix_z: The input density matrix data for the spin-down component. + :returns: The computed exchange-correlation energy. + + .. cpp:function:: value_type eval_exc(const MatrixType& density_matrix_s, const MatrixType& density_matrix_z, const MatrixType& density_matrix_y, const MatrixType& density_matrix_x) const + + Compute the exchange-correlation energy for a given density matrix. + + :param density_matrix_s: The input density matrix data for the spin-up component. + :param density_matrix_z: The input density matrix data for the spin-down component. + :param density_matrix_y: The input density matrix data for the spin-y component. + :param density_matrix_x: The input density matrix data for the spin-x component. + :returns: The computed exchange-correlation energy. + + .. cpp:function:: std::tuple eval_exc_vxc(const MatrixType& density_matrix) + + Compute the exchange-correlation energy and potential for a given density matrix. + + :param density_matrix: The input density matrix data. + :returns: The computed exchange-correlation energy and the computed exchange-correlation potential matrix. + + .. cpp:function:: std::tuple eval_exc_vxc(const MatrixType& density_matrix_s, const MatrixType& density_matrix_z) + + Compute the exchange-correlation energy and potential for a given density matrix. + + :param density_matrix_s: The input density matrix data for the spin-up component. + :param density_matrix_z: The input density matrix data for the spin-down component. + :returns: The computed exchange-correlation energy and the computed exchange-correlation potential matrices for the total and spin-polarization components. + + .. cpp:function:: std::tuple eval_exc_vxc_onedft(const MatrixType& density_matrix_s, const MatrixType& density_matrix_z, const OneDFTSettings settings) + + Compute the exchange-correlation energy and potential for a given density matrix. + + .. important:: + + This function is available if :c:macro:`GAUXC_HAS_ONEDFT` is defined or the CMake option :cmake:variable:`GAUXC_ENABLE_ONEDFT` is enabled. + It requires a compatible checkpoint for the Skala implementation of the functional, which can be specified with the ``settings`` parameter. + + :param density_matrix_s: The input density matrix data for the spin-up component. + :param density_matrix_z: The input density matrix data for the spin-down component. + :param settings: The OneDFTSettings struct containing parameters for the Skala evaluation. + :returns: The computed exchange-correlation energy and the computed exchange-correlation potential matrices for the total and spin-polarization components. + + .. cpp:function:: std::tuple eval_exc_vxc(const MatrixType& density_matrix_s, const MatrixType& density_matrix_z, const MatrixType& density_matrix_y, const MatrixType& density_matrix_x) + + Compute the exchange-correlation energy and potential for a given density matrix. + + :param density_matrix_s: The input density matrix data for the spin-up component. + :param density_matrix_z: The input density matrix data for the spin-down component. + :param density_matrix_y: The input density matrix data for the spin-y component. + :param density_matrix_x: The input density matrix data for the spin-x component. + :returns: The computed exchange-correlation energy and the computed exchange-correlation potential matrices for the total and spin-polarization components. + +.. cpp:class:: GauXC::XCIntegratorFactory + + A factory class for creating instances of the XCIntegrator class based on specified parameters. + + .. cpp:function:: XCIntegratorFactory(ExecutionSpace ex, std::string integrator_input_type, std::string integrator_kernel_name, std::string local_work_kernel_name, std::string reduction_kernel_name) + + Create a new XCIntegratorFactory instance with the specified execution space and kernel names. + + :param ex: The execution space for which to create integrators. + :param integrator_input_type: The type of input data expected by the integrator kernels. + :param integrator_kernel_name: The name of the kernel to use for the main integration step. + :param local_work_kernel_name: The name of the kernel to use for computing local work sizes. + :param reduction_kernel_name: The name of the kernel to use for reduction operations. + + .. cpp:function:: XCIntegrator get_instance(const ExchCXX::Functional& func, const LoadBalancer& lb) + + Get an instance of the XCIntegrator class for the specified functional and load balancer. + + :param func: The exchange-correlation functional for which to get the integrator instance. + :param lb: The load balancer to use for the integrator instance. + :returns: An instance of the XCIntegrator class initialized with the specified parameters. + + .. cpp:function:: std::shared_ptr get_shared_instance(const ExchCXX::Functional& func, const LoadBalancer& lb) + + Get a shared pointer to an instance of the XCIntegrator class for the specified functional and load balancer. + + :param func: The exchange-correlation functional for which to get the integrator instance. + :param lb: The load balancer to use for the integrator instance. + :returns: A shared pointer to an instance of the XCIntegrator class initialized with the specified parameters. + +.. cpp:struct:: GauXC::OneDFTSettings + + A struct containing settings for the Skala implementation of the exchange-correlation functional. + + .. cpp:member:: model + + The model checkpoint to use for evaluating the exchange-correlation energy and potential with the Skala implementation. + +.. cpp:class:: ExchCXX::Functional + + A class representing an exchange-correlation functional in the ExchCXX library, which can be used with GauXC integrators. + + C bindings ---------- @@ -168,6 +295,10 @@ C bindings :param status: Pointer to a GauXCStatus struct where the status of the operation will be stored. :param integrator: Pointer to the GauXCIntegrator instance to be deleted. +.. c:struct:: GauXCFunctional + + Opaque type representing an exchange-correlation functional in the GauXC C API, which can be used with GauXC integrators. + Fortran bindings ---------------- @@ -300,3 +431,8 @@ Fortran bindings :param real(c_double) vxc_matrix_y [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-y component will be stored. :param real(c_double) vxc_matrix_x [dimension(:,:)]: Output array where the computed exchange-correlation potential matrix for the spin-x component will be stored. +.. f:currentmodule:: gauxc_xc_functional + +.. f:type:: gauxc_functional_type + + Opaque type representing an exchange-correlation functional in the GauXC Fortran API, which can be used with GauXC integrators. \ No newline at end of file