From 7fe1f98b2cc26890bb7a1f92ee84f930612cfbcb Mon Sep 17 00:00:00 2001 From: Stefano Battaglia Date: Fri, 20 Mar 2026 19:00:04 +0100 Subject: [PATCH 1/3] General improvements --- docs/gauxc/fortran-library.rst | 57 +++++++++++++++++++++++++++++----- docs/gauxc/installation.rst | 14 ++++++--- docs/gauxc/standalone.rst | 1 + 3 files changed, 61 insertions(+), 11 deletions(-) diff --git a/docs/gauxc/fortran-library.rst b/docs/gauxc/fortran-library.rst index b350887..29c4068 100644 --- a/docs/gauxc/fortran-library.rst +++ b/docs/gauxc/fortran-library.rst @@ -10,6 +10,31 @@ By the end of this tutorial, you will: * Configure the integration grid, load balancer, and XC integrator * Evaluate the exchange-correlation energy and potential +.. _gauxc_fortran_api: + +Before you start +---------------- + +This example assumes that you already have access to a GauXC source tree with Skala support, either because you followed :ref:`gauxc_install` first or because you let this example download GauXC automatically through CMake. +The example CMake files are written to accept either workflow. + +Before configuring the project, make sure you have the following available: + +- a Fortran compiler together with C and C++ compilers +- CMake and Ninja +- HDF5 development libraries +- an installed GauXC with both the C and Fortran APIs enabled, or network access so the example can build GauXC with those APIs enabled for you + +If you want to reproduce the sample ``He_def2-svp.h5`` input file from this guide, you also need the Python ``skala`` package installed. + +For a minimal OpenMP-capable environment for this guide, use the example environment file: + +.. literalinclude:: ../../examples/fortran/gauxc_integration/environment-openmp.yml + :language: yaml + :caption: environment-openmp.yml + +For MPI builds, switch to ``examples/fortran/gauxc_integration/environment-mpi.yml`` so that both MPI and the matching HDF5 variant are available. + Setting up CMake ---------------- @@ -46,7 +71,8 @@ Each dependency gets its own CMake include file. First, we define how to include GauXC, our main dependency. CMake will first attempt to discover an installed GauXC via its config file; if that fails, it will download and build GauXC from source. The options defined in the main CMake file are passed through to GauXC to ensure the library provides the requested features. -After GauXC is available, we verify that our requirements are satisfied—this is especially important for the Skala implementation, which requires the ``GAUXC_HAS_ONEDFT`` feature flag. +After GauXC is available, we verify that our requirements are satisfied. +For the Fortran driver this includes the Skala implementation as well as the C and Fortran APIs, which are checked via ``GAUXC_HAS_ONEDFT``, ``GAUXC_HAS_C``, and ``GAUXC_HAS_FORTRAN``. .. literalinclude:: ../../examples/fortran/gauxc_integration/cmake/skala-gauxc.cmake :language: cmake @@ -58,12 +84,15 @@ For the command-line interface, we use the `FLAP library `__ package manager for setting up the environment and installing dependencies. -If you do not have mamba installed, you can download the `miniforge `__ installer. - -First, we will create a new environment with all the required dependencies for building GauXC with Skala support. +If you do not have mamba installed, you can download the `miniforge `__ installer.First, we will create a new environment with all the required dependencies for building GauXC with Skala support. We provide three different configurations depending on whether you want to build GauXC with OpenMP, MPI, or CUDA support. .. dropdown:: GauXC dependencies @@ -27,6 +25,7 @@ We provide three different configurations depending on whether you want to build The following dependencies are required for building GauXC with Skala support: - C/C++ compiler (with C++17 support) + - Fortran compiler (if Fortran API is enabled via ``-DGAUXC_ENABLE_FORTRAN=on``) - CMake (version 3.15 or higher) - `exchcxx `__\ * (version 1 or higher) - `libxc `__\ * (version 7 or higher) @@ -116,6 +115,13 @@ Download the pre-packaged source bundle from the Skala release page: tar xzvf gauxc-skala.tar.gz The archive expands into a ``gauxc`` directory that already contains the Skala patches. +One convenient layout is + +.. code-block:: text + + work/ + ├── gauxc/ + └── build/ Configure and build diff --git a/docs/gauxc/standalone.rst b/docs/gauxc/standalone.rst index 5e7d09b..e3eb436 100644 --- a/docs/gauxc/standalone.rst +++ b/docs/gauxc/standalone.rst @@ -14,6 +14,7 @@ Create GauXC compatible input We will use the ``skala`` package to write a GauXC compatible input for our calculation. For this we will run a PySCF calculation and write the molecule, basis set and density matrix in the format expected by GauXC. In this example we will use a single one atom system in a small basis set. +Before running the export script, install the Python ``skala`` package together with its dependencies. .. note:: From 9f9188ecadb0e07b6bc3d018f9de09775e09686b Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> Date: Mon, 23 Mar 2026 09:51:44 +0100 Subject: [PATCH 2/3] Update documentation to use c:macro syntax --- docs/gauxc/fortran-library.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/gauxc/fortran-library.rst b/docs/gauxc/fortran-library.rst index d37ac31..0caad81 100644 --- a/docs/gauxc/fortran-library.rst +++ b/docs/gauxc/fortran-library.rst @@ -72,7 +72,7 @@ First, we define how to include GauXC, our main dependency. CMake will first attempt to discover an installed GauXC via its config file; if that fails, it will download and build GauXC from source. The options defined in the main CMake file are passed through to GauXC to ensure the library provides the requested features. After GauXC is available, we verify that our requirements are satisfied. -For the Fortran driver this includes the Skala implementation as well as the C and Fortran APIs, which are checked via ``GAUXC_HAS_ONEDFT``, ``GAUXC_HAS_C``, and ``GAUXC_HAS_FORTRAN``. +For the Fortran driver this includes the Skala implementation as well as the C and Fortran APIs, which are checked via :c:macro:`GAUXC_HAS_ONEDFT`, :c:macro:`GAUXC_HAS_C`, and :c:macro:`GAUXC_HAS_FORTRAN`. .. literalinclude:: ../../examples/fortran/gauxc_integration/cmake/skala-gauxc.cmake :language: cmake @@ -150,7 +150,7 @@ We also declare variables for input parameters and intermediate values: :lines: 45-53 When compiled with MPI support, we initialize MPI at program startup. -The ``gauxc/gauxc_config.f`` header provides the ``GAUXC_HAS_MPI`` preprocessor macro for guarding MPI-specific calls. +The ``gauxc/gauxc_config.f`` header provides the :c:macro:`GAUXC_HAS_MPI` preprocessor macro for guarding MPI-specific calls. .. literalinclude:: ../../examples/fortran/gauxc_integration/app/main.F90 :language: fortran @@ -596,4 +596,4 @@ This guide demonstrated GauXC usage in Fortran applications. We: 1. Created a minimal CMake project with GauXC as a dependency 2. Built a CLI driver that reads molecule, basis set, and density matrix from HDF5 3. Configured the integration grid, load balancer, and XC integrator -4. Evaluated the exchange-correlation energy and potential \ No newline at end of file +4. Evaluated the exchange-correlation energy and potential From 6e389155ba03b59275487a0b0a570b1f21681950 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> Date: Mon, 23 Mar 2026 10:30:33 +0100 Subject: [PATCH 3/3] Fix spacing Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/gauxc/installation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/gauxc/installation.rst b/docs/gauxc/installation.rst index 68d3b05..37fd6d4 100644 --- a/docs/gauxc/installation.rst +++ b/docs/gauxc/installation.rst @@ -17,7 +17,9 @@ Prerequisites ------------- For this tutorial, we will use the `mamba `__ package manager for setting up the environment and installing dependencies. -If you do not have mamba installed, you can download the `miniforge `__ installer.First, we will create a new environment with all the required dependencies for building GauXC with Skala support. +If you do not have mamba installed, you can download the `miniforge `__ installer. + +First, we will create a new environment with all the required dependencies for building GauXC with Skala support. We provide three different configurations depending on whether you want to build GauXC with OpenMP, MPI, or CUDA support. .. note::