From 95331b6fc96eab0d98f15353744f8664701ad644 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert Date: Fri, 16 Jan 2026 15:38:44 +0100 Subject: [PATCH 1/3] Add C++ API documentation - add GitHub Actions workflow for deploying pages - add setup for sphinx + breath to format Doxygen generated documentation - add pages for molecule, basis set, grid, runtime environment, load balancer, xc integrator and macros - update header files with doxygen-style comments to display documentation --- .github/workflows/docs.yml | 64 ++++ docs/.gitignore | 1 + docs/Doxyfile | 388 +++++++++++++++++++++ docs/_static/bib/references.bib | 47 +++ docs/api/cxx/basisset.rst | 12 + docs/api/cxx/index.rst | 15 + docs/api/cxx/loadbalancer.rst | 14 + docs/api/cxx/macros.rst | 73 ++++ docs/api/cxx/molecule.rst | 11 + docs/api/cxx/molgrid.rst | 34 ++ docs/api/cxx/runtime.rst | 13 + docs/api/cxx/xc.rst | 20 ++ docs/conf.py | 84 +++++ docs/index.rst | 11 + docs/requirements.txt | 4 + include/gauxc/grid_factory.hpp | 6 +- include/gauxc/molecular_weights.hpp | 102 +++--- include/gauxc/molecule.hpp | 42 ++- include/gauxc/molgrid.hpp | 46 ++- include/gauxc/molgrid/defaults.hpp | 96 ++++- include/gauxc/runtime_environment/decl.hpp | 69 +++- include/gauxc/shell.hpp | 158 ++++++++- include/gauxc/xc_integrator.hpp | 212 +++++++++-- include/gauxc/xc_integrator_settings.hpp | 34 +- 24 files changed, 1452 insertions(+), 104 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/.gitignore create mode 100644 docs/Doxyfile create mode 100644 docs/_static/bib/references.bib create mode 100644 docs/api/cxx/basisset.rst create mode 100644 docs/api/cxx/index.rst create mode 100644 docs/api/cxx/loadbalancer.rst create mode 100644 docs/api/cxx/macros.rst create mode 100644 docs/api/cxx/molecule.rst create mode 100644 docs/api/cxx/molgrid.rst create mode 100644 docs/api/cxx/runtime.rst create mode 100644 docs/api/cxx/xc.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/requirements.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..a9c7bc3e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,64 @@ +name: Docs + +on: + push: + branches: [master, docs] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v5 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: '3.13' + cache: 'pip' + + - name: Install dependencies + run: pip install -r docs/requirements.txt + + - name: Install Doxygen + run: | + sudo apt-get update + sudo apt-get install -y doxygen + + - name: Generate Doxygen + run: | + doxygen Doxyfile + working-directory: ./docs + + - name: Build documentation + run: | + sphinx-build -b dirhtml docs docs/_build/html + touch docs/_build/html/.nojekyll + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/_build/html + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deploy.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deploy + uses: actions/deploy-pages@v4 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..1918ed3f --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_doxygen/ diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 00000000..2b17e7b7 --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,388 @@ +# Doxyfile 1.9.2 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = GauXC +PROJECT_NUMBER = +PROJECT_BRIEF = +PROJECT_LOGO = +OUTPUT_DIRECTORY = _doxygen +CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +JAVADOC_BANNER = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +PYTHON_DOCSTRING = YES +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 4 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = YES +OPTIMIZE_OUTPUT_VHDL = NO +OPTIMIZE_OUTPUT_SLICE = NO +EXTENSION_MAPPING = +MARKDOWN_SUPPORT = YES +TOC_INCLUDE_HEADINGS = 5 +AUTOLINK_SUPPORT = YES +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +GROUP_NESTED_COMPOUNDS = NO +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = NO +LOOKUP_CACHE_SIZE = 0 +NUM_PROC_THREADS = 1 +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_PRIV_VIRTUAL = NO +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +RESOLVE_UNNAMED_PARAMS = YES +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO +SHOW_HEADERFILE = YES +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +LAYOUT_FILE = +CITE_BIB_FILES = +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_IF_INCOMPLETE_DOC = YES +WARN_NO_PARAMDOC = NO +WARN_AS_ERROR = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = ../include/ \ + ../src/ \ + ../README.md +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.idl \ + *.ddl \ + *.odl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.l \ + *.cs \ + *.d \ + *.php \ + *.php4 \ + *.php5 \ + *.phtml \ + *.inc \ + *.m \ + *.markdown \ + *.md \ + *.mm \ + *.dox \ + *.py \ + *.pyw \ + *.f90 \ + *.f95 \ + *.f03 \ + *.f08 \ + *.f18 \ + *.f \ + *.for \ + *.vhd \ + *.vhdl \ + *.ucf \ + *.qsf \ + *.ice +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = ../README.md +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = YES +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = +HTML_EXTRA_FILES = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_TIMESTAMP = NO +HTML_DYNAMIC_MENUS = YES +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = +QHG_LOCATION = +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = NO +GENERATE_TREEVIEW = NO +FULL_SIDEBAR = NO +ENUM_VALUES_PER_LINE = 4 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +HTML_FORMULA_FORMAT = png +FORMULA_FONTSIZE = 10 +FORMULA_TRANSPARENT = YES +FORMULA_MACROFILE = +USE_MATHJAX = NO +MATHJAX_VERSION = MathJax_2 +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = +#--------------------------------------------------------------------------- +# Configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = +MAKEINDEX_CMD_NAME = makeindex +LATEX_MAKEINDEX_CMD = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4 +EXTRA_PACKAGES = +LATEX_HEADER = +LATEX_FOOTER = +LATEX_EXTRA_STYLESHEET = +LATEX_EXTRA_FILES = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +LATEX_BIB_STYLE = plain +LATEX_TIMESTAMP = NO +LATEX_EMOJI_DIRECTORY = +#--------------------------------------------------------------------------- +# Configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# Configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_SUBDIR = +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# Configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = YES +XML_OUTPUT = xml +XML_PROGRAMLISTING = YES +XML_NS_MEMB_FILE_SCOPE = NO +#--------------------------------------------------------------------------- +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- +GENERATE_DOCBOOK = NO +DOCBOOK_OUTPUT = docbook +#--------------------------------------------------------------------------- +# Configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# Configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = GAUXC_HAS_DEVICE \ + GAUXC_HAS_MPI +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration options related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +EXTERNAL_PAGES = YES +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = YES +DIA_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +DOT_NUM_THREADS = 0 +DOT_FONTNAME = Helvetica +DOT_FONTSIZE = 10 +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 +DOT_UML_DETAILS = NO +DOT_WRAP_THRESHOLD = 17 +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO +DOT_PATH = +DOTFILE_DIRS = +MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = +PLANTUML_CFG_FILE = +PLANTUML_INCLUDE_PATH = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES diff --git a/docs/_static/bib/references.bib b/docs/_static/bib/references.bib new file mode 100644 index 00000000..1139e1bb --- /dev/null +++ b/docs/_static/bib/references.bib @@ -0,0 +1,47 @@ +@article{becke1988, + title={A multicenter numerical integration scheme for polyatomic molecules}, + author={Becke, Axel D}, + journal={The Journal of chemical physics}, + volume={88}, + number={4}, + pages={2547--2553}, + year={1988}, + doi={10.1063/1.454033}, + publisher={American Institute of Physics} +} + +@article{mura1996, + title={Improved radial grids for quadrature in molecular density-functional calculations}, + author={Mura, Michael E and Knowles, Peter J}, + journal={The Journal of Chemical Physics}, + volume={104}, + number={24}, + pages={9848--9858}, + year={1996}, + doi={10.1063/1.471749}, + publisher={AIP Publishing} +} + +@article{murray1993, + title={Quadrature schemes for integrals of density functional theory}, + author={Murray, Christopher W and Handy, Nicholas C and Laming, Gregory J}, + journal={Molecular Physics}, + volume={78}, + number={4}, + pages={997--1014}, + year={1993}, + doi={10.1080/00268979300100651}, + publisher={Taylor \& Francis} +} + +@article{treutler1995, + title={Efficient molecular numerical integration schemes}, + author={Treutler, Oliver and Ahlrichs, Reinhart}, + journal={The Journal of Chemical Physics}, + volume={102}, + number={1}, + pages={346--354}, + year={1995}, + doi={10.1063/1.469408}, + publisher={American Institute of Physics} +} diff --git a/docs/api/cxx/basisset.rst b/docs/api/cxx/basisset.rst new file mode 100644 index 00000000..0fda6f80 --- /dev/null +++ b/docs/api/cxx/basisset.rst @@ -0,0 +1,12 @@ +Basis set and shell types +========================= + +These APIs define the core data structures for Gaussian-type orbital (GTO) basis sets. +The :cpp:struct:`GauXC::BasisSet` is an ordered collection of shells that make up a full basis for a molecule or atom set. +A :cpp:class:`GauXC::Shell` represents a contracted Gaussian shell with its exponents, coefficients, origin, and angular momentum. + +.. doxygenstruct:: GauXC::BasisSet + :members: + +.. doxygenclass:: GauXC::Shell + :members: \ No newline at end of file diff --git a/docs/api/cxx/index.rst b/docs/api/cxx/index.rst new file mode 100644 index 00000000..5ddc263a --- /dev/null +++ b/docs/api/cxx/index.rst @@ -0,0 +1,15 @@ +C++ API reference +================= + +This section documents the C++ API of GauXC. + +.. toctree:: + :maxdepth: 2 + + molecule + basisset + molgrid + runtime + loadbalancer + xc + macros \ No newline at end of file diff --git a/docs/api/cxx/loadbalancer.rst b/docs/api/cxx/loadbalancer.rst new file mode 100644 index 00000000..5020e638 --- /dev/null +++ b/docs/api/cxx/loadbalancer.rst @@ -0,0 +1,14 @@ +Load balancing +============== + +The :cpp:class:`GauXC::LoadBalancer` distributes quadrature tasks across processes and provides access to local work units. +To create load balancers, the :cpp:class:`GauXC::LoadBalancerFactory` is provided, which can generate different load balancing strategies based on user-defined settings. +For specifying the execution context, the :cpp:enum:`GauXC::ExecutionSpace` enum is available. + +.. doxygenclass:: GauXC::LoadBalancer + :members: + +.. doxygenclass:: GauXC::LoadBalancerFactory + :members: + +.. doxygenenum:: GauXC::ExecutionSpace \ No newline at end of file diff --git a/docs/api/cxx/macros.rst b/docs/api/cxx/macros.rst new file mode 100644 index 00000000..59e11865 --- /dev/null +++ b/docs/api/cxx/macros.rst @@ -0,0 +1,73 @@ +Macro definitions +================= + +GauXC provides a number of compile-time macros to indicate available features and configuration options. + +.. 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 ``GAUXC_ENABLE_CUDA`` or ``GAUXC_ENABLE_HIP`` CMake options. + +.. c:macro:: GAUXC_HAS_CUDA + + Defines whether CUDA support is available in this build of GauXC. + Enabled with ``GAUXC_ENABLE_CUDA`` CMake option. + +.. c:macro:: GAUXC_HAS_HIP + + Defines whether HIP support is available in this build of GauXC. + Enabled with ``GAUXC_ENABLE_HIP`` CMake option. + +.. c:macro:: GAUXC_HAS_MPI + + Defines whether MPI support is available in this build of GauXC. + Enabled with ``GAUXC_ENABLE_MPI`` CMake option. + +.. c:macro:: GAUXC_HAS_MAGMA + + Defines whether MAGMA support is available in this build of GauXC. + Enabled with ``GAUXC_ENABLE_MAGMA`` CMake option. + +.. c:macro:: GAUXC_HAS_NCCL + + Defines whether NCCL support is available in this build of GauXC. + Enabled with ``GAUXC_ENABLE_NCCL`` CMake option. + +.. c:macro:: GAUXC_HAS_CUTLASS + + Defines whether CUTLASS support is available in this build of GauXC. + Enabled with ``GAUXC_ENABLE_CUTLASS`` CMake option. + +.. c:macro:: GAUXC_HAS_GAU2GRID + + Defines whether Gau2Grid support is available in this build of GauXC. + Enabled with ``GAUXC_ENABLE_GAU2GRID`` CMake option. + +.. c:macro:: GAUXC_HAS_HDF5 + + Defines whether HDF5 support is available in this build of GauXC. + Enabled with ``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/api/cxx/molecule.rst b/docs/api/cxx/molecule.rst new file mode 100644 index 00000000..c564da06 --- /dev/null +++ b/docs/api/cxx/molecule.rst @@ -0,0 +1,11 @@ +Molecule and atom types +======================= + +These APIs describe the basic molecular data structures used throughout GauXC. +The :cpp:class:`GauXC::Molecule` type is a lightweight container of :cpp:struct:`GauXC::Atom` instances, providing methods for handling a collection of atoms. + +.. doxygenclass:: GauXC::Molecule + :members: + +.. doxygenstruct:: GauXC::Atom + :members: \ No newline at end of file diff --git a/docs/api/cxx/molgrid.rst b/docs/api/cxx/molgrid.rst new file mode 100644 index 00000000..ca8828ff --- /dev/null +++ b/docs/api/cxx/molgrid.rst @@ -0,0 +1,34 @@ +Molecular grid types +==================== + +These APIs provide the quadrature grid infrastructure for numerical integration. +The :cpp:class:`GauXC::Grid` class encapsulates an atom-centered spherical quadrature with batching support. +:cpp:class:`GauXC::MolGrid` aggregates per-element grids based on the atomic number to form a complete molecular integration grid. +The :cpp:class:`GauXC::MolGridFactory` creates molecular grids from molecules and basis sets. + +For applying standard grid sizes and pruning schemes, the enums :cpp:enum:`GauXC::AtomicGridSizeDefault`, :cpp:enum:`GauXC::RadialQuad`, and :cpp:enum:`GauXC::PruningScheme` are provided. +Finally, the :cpp:class:`GauXC::MolecularWeights` class provides support for computing molecular integration weights, with configuration via :cpp:struct:`GauXC::MolecularWeightsSettings` and construction through :cpp:class:`GauXC::MolecularWeightsFactory`. + +.. doxygenclass:: GauXC::MolGrid + :members: + +.. doxygenclass:: GauXC::Grid + :members: + +.. doxygenclass:: GauXC::MolGridFactory + :members: + +.. doxygenenum:: GauXC::AtomicGridSizeDefault + +.. doxygenenum:: GauXC::RadialQuad + +.. doxygenenum:: GauXC::PruningScheme + +.. doxygenclass:: GauXC::MolecularWeights + :members: + +.. doxygenclass:: GauXC::MolecularWeightsFactory + :members: + +.. doxygenstruct:: GauXC::MolecularWeightsSettings + :members: \ No newline at end of file diff --git a/docs/api/cxx/runtime.rst b/docs/api/cxx/runtime.rst new file mode 100644 index 00000000..f97da87d --- /dev/null +++ b/docs/api/cxx/runtime.rst @@ -0,0 +1,13 @@ +Runtime environment +=================== + +These APIs manage execution contexts and work distribution for XC integration. +The :cpp:class:`GauXC::RuntimeEnvironment` encapsulates MPI communication and provides +process-local information, while :cpp:class:`GauXC::DeviceRuntimeEnvironment` extends +it with GPU memory management for device-accelerated computations. + +.. doxygenclass:: GauXC::RuntimeEnvironment + :members: + +.. doxygenclass:: GauXC::DeviceRuntimeEnvironment + :members: \ No newline at end of file diff --git a/docs/api/cxx/xc.rst b/docs/api/cxx/xc.rst new file mode 100644 index 00000000..60287b1b --- /dev/null +++ b/docs/api/cxx/xc.rst @@ -0,0 +1,20 @@ +Exchange-correlation integrator +=============================== + +For performing exchange-correlation integration, GauXC provides the :cpp:class:`GauXC::XCIntegrator` interface. +The :cpp:class:`GauXC::XCIntegratorFactory` creates integrators based on user-defined settings encapsulated in :cpp:struct:`GauXC::IntegratorSettingsXC`, :cpp:struct:`GauXC::IntegratorSettingsKS`, and :cpp:struct:`GauXC::IntegratorSettingsEXC_GRAD`. + +.. doxygenclass:: GauXC::XCIntegrator + :members: + +.. doxygenclass:: GauXC::XCIntegratorFactory + :members: + +.. doxygenstruct:: GauXC::IntegratorSettingsXC + :members: + +.. doxygenstruct:: GauXC::IntegratorSettingsKS + :members: + +.. doxygenstruct:: GauXC::IntegratorSettingsEXC_GRAD + :members: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..e8612b75 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,84 @@ +project = "GauXC" +version = "1.1" +release = version + + +extensions = [ + "breathe", + "sphinx.ext.autodoc", + "sphinx.ext.mathjax", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx.ext.extlinks", + "sphinxcontrib.bibtex", +] + +breathe_default_project = project +breathe_projects = { + project: "_doxygen/xml", +} +breathe_domain_by_extension = { + "h": "c", +} +breathe_show_include = True + +bibtex_bibfiles = ["_static/bib/references.bib"] + +cpp_id_attributes = [ + "HOST_DEVICE_ACCESSIBLE", + "GAUXC_MPI_CODE", +] + +templates_path = ["_templates"] +source_suffix = [".rst"] +master_doc = "index" +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +pygments_style = "default" + + +html_theme = "sphinx_book_theme" +html_title = project + +html_theme_options = { + "repository_url": "https://github.com/wavefunction91/gauxc", + "repository_branch": "master", + "use_repository_button": True, + "use_edit_page_button": True, + "use_download_button": False, + "path_to_docs": "docs", +} + +html_static_path = ["_static"] + + +def run_doxygen(folder): + """Run the doxygen make command in the designated folder""" + + import subprocess, sys + + try: + retcode = subprocess.call("set -ex; cd %s; doxygen Doxyfile" % folder, shell=True) + if retcode < 0: + sys.stderr.write("doxygen terminated by signal %s" % (-retcode)) + except OSError as e: + sys.stderr.write("doxygen execution failed: %s" % e) + + +def generate_doxygen_xml(app): + """Run the doxygen make commands if we're on the ReadTheDocs server""" + + import os, os.path + + read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True' + + if read_the_docs_build: + + _dir = os.path.dirname(os.path.abspath(__file__)) + run_doxygen(_dir) + + +def setup(app): + + # Add hook for building doxygen xml when needed + app.connect("builder-inited", generate_doxygen_xml) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..6f3b659a --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,11 @@ +GauXC +===== + +GauXC is a modern, modular C++ library for the evaluation of quantities related to the exchange-correlation (XC) and exact-exchange (K) energy (e.g. potential, etc) in the Gaussian basis set discretization of Kohn-Sham density function theory (KS-DFT). +GauXC provides efficient, scalable distributed memory XC and K integrators for both CPU and +accelerator-based (GPU) architectures. + +.. toctree:: + :maxdepth: 2 + + api/cxx/index diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..68e88c72 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +breathe +sphinx +sphinx-book-theme +sphinxcontrib-bibtex diff --git a/include/gauxc/grid_factory.hpp b/include/gauxc/grid_factory.hpp index ecf65526..e2d612e9 100644 --- a/include/gauxc/grid_factory.hpp +++ b/include/gauxc/grid_factory.hpp @@ -63,9 +63,9 @@ PrunedAtomicGridSpecification treutler_pruning_scheme( /// High-level specification of pruning schemes for atomic quadratures enum class PruningScheme { - Unpruned, /// Unpruned atomic quadrature - Robust, /// The "Robust" scheme of Psi4 - Treutler /// The Treutler-Ahlrichs scheme + Unpruned, ///< Unpruned atomic quadrature + Robust, ///< The "Robust" scheme of Psi4 + Treutler ///< The Treutler-Ahlrichs scheme }; /// Generate a pruning specification from a specificed pruning scheme and diff --git a/include/gauxc/molecular_weights.hpp b/include/gauxc/molecular_weights.hpp index 74f1e922..bc763912 100644 --- a/include/gauxc/molecular_weights.hpp +++ b/include/gauxc/molecular_weights.hpp @@ -17,101 +17,125 @@ namespace GauXC { namespace detail { - // Implementation base class for MolecularWeights + /// Forward declaration of MolecularWeights implementation. class MolecularWeightsImpl; } +/** + * @brief Settings for molecular weight partitioning. + * + * Controls the weight partitioning algorithm and optional size adjustments + * used when computing molecular quadrature weights. + */ struct MolecularWeightsSettings { - XCWeightAlg weight_alg = XCWeightAlg::SSF; ///< Weight partitioning scheme - bool becke_size_adjustment = false; ///< Whether to use Becke size adjustments + XCWeightAlg weight_alg = XCWeightAlg::SSF; ///< Weight partitioning scheme. + bool becke_size_adjustment = false; ///< Whether to use Becke size adjustments. }; -/// A class which applies molecular partition weights to pre-generated quadrature -/// tasks. +/** + * @brief Applies molecular partition weights to pre-generated quadrature tasks. + * + * This class computes and modifies the quadrature weights stored in a + * LoadBalancer according to a specified partitioning scheme (e.g., SSF, Becke). + */ class MolecularWeights { public: - using load_balancer_type = LoadBalancer; - using load_balancer_reference = load_balancer_type&; + using load_balancer_type = LoadBalancer; ///< LoadBalancer type alias. + using load_balancer_reference = load_balancer_type&; ///< Reference to LoadBalancer. private: - using pimpl_type = detail::MolecularWeightsImpl; - using pimpl_ptr_type = std::unique_ptr; - pimpl_ptr_type pimpl_; ///< Pointer to implementation instance + using pimpl_type = detail::MolecularWeightsImpl; ///< Implementation type. + using pimpl_ptr_type = std::unique_ptr; ///< Unique pointer to impl. + pimpl_ptr_type pimpl_; ///< Pointer to implementation instance. public: - // Delete default ctor + /// Deleted default constructor. MolecularWeights() = delete; - // Destructor (default) + /// Destructor. ~MolecularWeights() noexcept; - /// Construct a MolecularWeights instance from preconstructed implementation + /** + * @brief Construct from a pre-built implementation. + * @param ptr Unique pointer to implementation instance. + */ MolecularWeights( pimpl_ptr_type&& ptr ); - // Delete copy ctor + /// Deleted copy constructor. MolecularWeights( const MolecularWeights& ) = delete; - // Move a MolecularWeights instance + /// Move constructor. MolecularWeights( MolecularWeights&& ) noexcept; - /// Apply weight partitioning scheme to pre-generated local quadrature tasks + /** + * @brief Apply weight partitioning to local quadrature tasks. + * @param lb Reference to the LoadBalancer whose weights will be modified. + */ void modify_weights(load_balancer_reference lb) const; - /// Return local timing tracker + /** + * @brief Get the local timing tracker. + * @return Const reference to internal timer. + */ const util::Timer& get_timings() const; }; // class MolecularWeights -/// A factory to generate MolecularWeights instances +/** + * @brief Factory for constructing MolecularWeights instances. + * + * Provides a configurable interface to generate MolecularWeights objects + * for host or device execution spaces with specified settings. + */ class MolecularWeightsFactory { public: - // Delete default ctor + /// Deleted default constructor. MolecularWeightsFactory() = delete; /** - * @brief Construct a factory which generates a specific kind of MolecularWeights - * - * @param[in] ex Execution space for the MolecularWeights phase. - * Acceptable values: - * - Host: Run MolecularWeights on CPU - * - Device: Run MolecularWeights on GPU (if enabled) - * - * @param[in] local_work_kernel_name Specification of the LocalWorkDriver - * kernel underlying the MolecularWeights - * instasnce. - * - * See documentation for LocalWorkDriver for - * details. + * @brief Construct a factory for generating MolecularWeights instances. * - * @param[in] s Settings for the MolecularWeights calculation. + * @param ex Execution space for weight computation. + * Acceptable values: + * - Host: Run on CPU. + * - Device: Run on GPU (if enabled). + * @param local_work_kernel_name Specification of the LocalWorkDriver kernel. + * See LocalWorkDriver documentation for details. + * @param s Settings for the MolecularWeights calculation. */ MolecularWeightsFactory( ExecutionSpace ex, std::string local_work_kernel_name, MolecularWeightsSettings s); - /// Generate a shared-pointer MolecularWeights instance + /** + * @brief Generate a shared-pointer MolecularWeights instance. + * @return Shared pointer to a new MolecularWeights object. + */ std::shared_ptr get_shared_instance(); - /// Generate a MolecularWeights instance + /** + * @brief Generate a MolecularWeights instance. + * @return Newly constructed MolecularWeights object. + */ inline MolecularWeights get_instance(){ return MolecularWeights( std::move( *get_shared_instance() ) ); }; private: - ExecutionSpace ex_; ///< Execution space for the MolecularWeights phase - std::string lwd_kernel_; ///< LocalWorkDriver kernel for the MolecularWeights phase - MolecularWeightsSettings settings_; ///< Settings for the MolecualarWeights phase + ExecutionSpace ex_; ///< Execution space for weight computation. + std::string lwd_kernel_; ///< LocalWorkDriver kernel name. + MolecularWeightsSettings settings_; ///< Settings for weight calculation. -}; // class MolecularWeightsSettings +}; // class MolecularWeightsFactory } diff --git a/include/gauxc/molecule.hpp b/include/gauxc/molecule.hpp index 9f4fe6a7..aca53ddb 100644 --- a/include/gauxc/molecule.hpp +++ b/include/gauxc/molecule.hpp @@ -19,27 +19,53 @@ namespace GauXC { +/** + * @brief A class to represent a collection of atoms in a molecule. + */ class Molecule : public std::vector { private: - /// Tests if the base class can be constructed from @p Args + /// Tests if the base class can be constructed from @p Args. template - static constexpr auto can_construct_base_v = + static constexpr auto can_construct_base_v = std::is_constructible_v, Args...>; public: - - template `. + * @tparam Args Arguments forwarded to the base vector constructor. + */ + template >> Molecule( Args&&... args ) : std::vector( std::forward(args)... ) { } + /** + * @brief Default copy constructor. + */ Molecule( const Molecule& ) = default; + + /** + * @brief Default move constructor. + */ Molecule( Molecule&& ) noexcept = default; + /** + * @brief Default copy assignment. + */ Molecule& operator=( const Molecule& other ) = default; + /** + * @brief Get the number of atoms in the molecule. + * @return The number of atoms stored in the molecule. + */ size_t natoms() const { return this->size(); } + /** + * @brief Get the maximum atomic number / nuclear charge in the molecule. + * @return The largest atomic number among all atoms in the molecule. + * @warning Undefined behavior if the molecule is empty. + */ AtomicNumber maxZ() const { return std::max_element( this->cbegin(), this->cend(), []( const auto& a, const auto& b) { @@ -47,6 +73,14 @@ class Molecule : public std::vector { })->Z; } + /** + * @brief Compare two molecules for equality. + * + * Checks if all atoms are equal in properties and order. + * + * @param other Molecule to compare against. + * @return True if all atoms are equal and in the same order. + */ bool operator==(const Molecule& other) { if(other.size() != this->size()) return false; for( auto i = 0ul; i < this->size(); ++i ) diff --git a/include/gauxc/molgrid.hpp b/include/gauxc/molgrid.hpp index d58dc494..26337cd7 100644 --- a/include/gauxc/molgrid.hpp +++ b/include/gauxc/molgrid.hpp @@ -19,31 +19,75 @@ namespace GauXC { +/// Map from atomic number to concrete atom-centered Grid instances. using atomic_grid_map = std::unordered_map< AtomicNumber, Grid >; +/// Map from atomic number to atom-centered grid specification variants. using atomic_grid_spec_map = std::unordered_map< AtomicNumber, atomic_grid_variant>; namespace detail { + /// Forward declaration of the MolGrid implementation. class MolGridImpl; } +/** + * @brief 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. + */ class MolGrid { + /// Handle for internal implementation details. std::shared_ptr pimpl_; public: + /** + * @brief Construct from pre-built atom-centered grids. + * @param grids Map from atomic number to Grid instances. + */ MolGrid( const atomic_grid_map& ); + + /** + * @brief Construct from grid specification variants. + * @param grid_specs Map from atomic number to grid specification variants. + */ MolGrid( const atomic_grid_spec_map& ); + /// Copy constructor. MolGrid( const MolGrid& ); + + /// Move constructor. MolGrid( MolGrid&& ) noexcept; + /// Destructor. ~MolGrid() noexcept; + /** + * @brief Get the count of unique atomic numbers represented. + * @return Number of distinct atomic numbers in the grid map. + */ size_t natoms_uniq() const; + + /** + * @brief Retrieve the atom-centered grid for a given atomic number. + * @param Z Atomic number to look up. + * @return Const reference to the associated Grid. + */ const Grid& get_grid( AtomicNumber ) const; - Grid& get_grid( AtomicNumber ) ; + /** + * @brief Retrieve the atom-centered grid for a given atomic number (mutable). + * @param Z Atomic number to look up. + * @return Reference to the associated Grid. + */ + Grid& get_grid( AtomicNumber ); + + /** + * @brief Get the maximum batch count across all stored grids. + * @return Largest number of batches among all atom grids. + */ size_t max_nbatches() const; }; diff --git a/include/gauxc/molgrid/defaults.hpp b/include/gauxc/molgrid/defaults.hpp index 0565647d..94a00982 100644 --- a/include/gauxc/molgrid/defaults.hpp +++ b/include/gauxc/molgrid/defaults.hpp @@ -15,30 +15,87 @@ namespace GauXC { + /// Return Slater radius (Bohr) for the given atomic number (64-element table). double slater_radius_64(AtomicNumber); + + /// Return Slater radius (Bohr) for the given atomic number (30-element table). double slater_radius_30(AtomicNumber); + + /// Return Clementi radius (Bohr) for the given atomic number (67-element table). double clementi_radius_67(AtomicNumber); + + /// Return UFF radius (Bohr) for the given atomic number (103-element table). double uff_radius_103(AtomicNumber); + + /// Return the default atomic radius (Bohr) for a given atomic number. double default_atomic_radius(AtomicNumber); + /// Return the default Murray-Handy-Laming radial scaling factor for an atomic number. RadialScale default_mk_radial_scaling_factor( AtomicNumber ); + + /// Return the default Mura-Knowles radial scaling factor for an atomic number. RadialScale default_mhl_radial_scaling_factor( AtomicNumber ); + + /// Return the default Treutler-Ahlrichs radial scaling factor for an atomic number. RadialScale default_ta_radial_scaling_factor( AtomicNumber ); - RadialScale default_radial_scaling_factor( RadialQuad, AtomicNumber ); + /** + * @brief Return the default radial scaling factor for a radial quadrature and atomic number. + * @param rq Radial quadrature type. + * @param Z Atomic number. + * @return Radial scaling factor. + */ + RadialScale default_radial_scaling_factor( RadialQuad rq, AtomicNumber Z ); + + /** + * @brief Return the default radial and angular grid sizes for a given element and quadrature. + * @param Z Atomic number. + * @param rq Radial quadrature type. + * @param gs_def Atomic grid size preset. + * @return Tuple of (RadialSize, AngularSize). + */ std::tuple - default_grid_size(AtomicNumber, RadialQuad, AtomicGridSizeDefault); - + default_grid_size(AtomicNumber Z, RadialQuad rq, AtomicGridSizeDefault gs_def); + + /** + * @brief Factory for constructing molecular grids with default settings. + * + * Provides static methods to generate atomic grid specifications, grid maps, + * and complete MolGrid instances using sensible defaults for radial/angular + * quadratures and pruning schemes. + */ struct MolGridFactory { + /** + * @brief Create an unpruned atomic grid specification with default scaling. + * @param Z Atomic number. + * @param rq Radial quadrature type. + * @param rsize Number of radial points. + * @param asize Number of angular points. + * @return Unpruned atomic grid specification. + */ static UnprunedAtomicGridSpecification create_default_unpruned_grid_spec( - AtomicNumber, RadialQuad, RadialSize, AngularSize + AtomicNumber Z, RadialQuad rq, RadialSize rsize, AngularSize asize ); + /** + * @brief Create an unpruned atomic grid specification using a preset size. + * @param Z Atomic number. + * @param rq Radial quadrature type. + * @param gs_def Atomic grid size preset. + * @return Unpruned atomic grid specification. + */ static UnprunedAtomicGridSpecification create_default_unpruned_grid_spec( - AtomicNumber, RadialQuad, AtomicGridSizeDefault + AtomicNumber Z, RadialQuad rq, AtomicGridSizeDefault gs_def ); + /** + * @brief Create a pruned atomic grid specification. + * @tparam Args Argument types forwarded to create_default_unpruned_grid_spec. + * @param scheme Pruning scheme to apply. + * @param args Arguments for unpruned spec creation. + * @return Pruned or unpruned atomic grid specification variant. + */ template inline static atomic_grid_variant create_default_pruned_grid_spec( PruningScheme scheme, Args&&... args ) { @@ -47,6 +104,14 @@ namespace GauXC { ); } + /** + * @brief Create a map of atomic grid specifications for all unique elements in a molecule. + * @tparam Args Argument types forwarded to create_default_pruned_grid_spec. + * @param mol Molecule containing the atoms. + * @param scheme Pruning scheme to apply. + * @param args Additional arguments for grid specification. + * @return Map from atomic number to grid specification variant. + */ template inline static atomic_grid_spec_map create_default_grid_spec_map( const Molecule& mol, PruningScheme scheme, Args&&... args ) { @@ -63,6 +128,12 @@ namespace GauXC { return molmap; } + /** + * @brief Generate concrete grids from a grid specification map. + * @param gs_map Map from atomic number to grid specification. + * @param bsz Batch size for the generated grids. + * @return Map from atomic number to Grid instances. + */ inline static atomic_grid_map generate_gridmap( const atomic_grid_spec_map& gs_map, BatchSize bsz ) { @@ -74,6 +145,15 @@ namespace GauXC { } + /** + * @brief Create a default grid map for a molecule. + * @tparam Args Argument types forwarded to create_default_grid_spec_map. + * @param mol Molecule containing the atoms. + * @param scheme Pruning scheme to apply. + * @param bsz Batch size for the generated grids. + * @param args Additional arguments for grid specification. + * @return Map from atomic number to Grid instances. + */ template inline static atomic_grid_map create_default_gridmap( const Molecule& mol, PruningScheme scheme, BatchSize bsz, @@ -84,6 +164,12 @@ namespace GauXC { } + /** + * @brief Create a default MolGrid for a molecule. + * @tparam Args Argument types forwarded to create_default_gridmap. + * @param args Arguments passed to create_default_gridmap. + * @return Constructed MolGrid instance. + */ template inline static MolGrid create_default_molgrid( Args&&... args ) { return MolGrid( create_default_gridmap(std::forward(args)...) ); diff --git a/include/gauxc/runtime_environment/decl.hpp b/include/gauxc/runtime_environment/decl.hpp index 424f9d98..cc0a07d3 100644 --- a/include/gauxc/runtime_environment/decl.hpp +++ b/include/gauxc/runtime_environment/decl.hpp @@ -17,12 +17,21 @@ namespace GauXC { namespace detail { + /// Forward declaration of RuntimeEnvironment implementation. class RuntimeEnvironmentImpl; #ifdef GAUXC_HAS_DEVICE + /// Convert a RuntimeEnvironment to a DeviceRuntimeEnvironment. DeviceRuntimeEnvironment as_device_runtime( const RuntimeEnvironment& ); #endif } +/** + * @brief Runtime environment for GauXC computations. + * + * Encapsulates communication context (MPI) and provides process-local + * information such as rank and size. Serves as the base class for + * device-specific runtime environments. + */ class RuntimeEnvironment { protected: @@ -32,28 +41,50 @@ class RuntimeEnvironment { detail::as_device_runtime(const RuntimeEnvironment&); #endif - using pimpl_type = detail::RuntimeEnvironmentImpl; - using pimpl_ptr_type = std::shared_ptr; - pimpl_ptr_type pimpl_; + using pimpl_type = detail::RuntimeEnvironmentImpl; ///< Implementation type. + using pimpl_ptr_type = std::shared_ptr; ///< Shared pointer to impl. + pimpl_ptr_type pimpl_; ///< Handle for implementation object. + + /// Construct from existing implementation pointer. RuntimeEnvironment( pimpl_ptr_type ptr ); public: + /** + * @brief Construct a runtime environment. + * @param comm MPI communicator (if MPI is enabled). + */ explicit RuntimeEnvironment(GAUXC_MPI_CODE(MPI_Comm comm)); + + /// Destructor. virtual ~RuntimeEnvironment() noexcept; + /// Copy constructor. RuntimeEnvironment( const RuntimeEnvironment& ); + /// Move constructor. RuntimeEnvironment( RuntimeEnvironment&& ) noexcept; + /// Get the MPI communicator (if MPI is enabled). GAUXC_MPI_CODE(MPI_Comm comm() const;) + + /// Get the rank of this process in the communicator. int comm_rank() const; + + /// Get the total number of processes in the communicator. int comm_size() const; + /// Get the shared usage count of the implementation. int shared_usage_count() const; }; #ifdef GAUXC_HAS_DEVICE +/** + * @brief Device-enabled runtime environment for GPU computations. + * + * Extends RuntimeEnvironment with device memory management and backend access + * for GPU-accelerated XC integration. + */ class DeviceRuntimeEnvironment : public RuntimeEnvironment { private: @@ -64,24 +95,56 @@ class DeviceRuntimeEnvironment : public RuntimeEnvironment { using parent_type::pimpl_type; using parent_type::pimpl_ptr_type; + + /// Construct from existing implementation pointer. DeviceRuntimeEnvironment( pimpl_ptr_type ptr ); public: + /** + * @brief Construct with explicit device memory buffer. + * @param comm MPI communicator (if MPI is enabled). + * @param mem Pointer to device memory buffer. + * @param mem_sz Size of device memory buffer in bytes. + */ DeviceRuntimeEnvironment(GAUXC_MPI_CODE(MPI_Comm comm,) void* mem, size_t mem_sz); + + /** + * @brief Construct with automatic device memory allocation. + * @param comm MPI communicator (if MPI is enabled). + * @param fill_fraction Fraction of available device memory to allocate. + */ DeviceRuntimeEnvironment(GAUXC_MPI_CODE(MPI_Comm,) double fill_fraction); + /// Destructor. ~DeviceRuntimeEnvironment() noexcept; + + /// Copy constructor. DeviceRuntimeEnvironment( const DeviceRuntimeEnvironment& ); + /// Move constructor. DeviceRuntimeEnvironment( DeviceRuntimeEnvironment&& ) noexcept; + /// Get pointer to device memory buffer. void* device_memory() const ; + + /// Get size of device memory buffer in bytes. size_t device_memory_size() const ; + + /// Check if this environment owns the device memory. bool owns_memory() const; + + /// Get the device backend instance. DeviceBackend* device_backend() const; + /// Release the device memory buffer. void release_buffer(); + + /** + * @brief Set an external device memory buffer. + * @param m Pointer to device memory. + * @param sz Size of device memory buffer in bytes. + */ void set_buffer(void* m, size_t sz); }; #endif diff --git a/include/gauxc/shell.hpp b/include/gauxc/shell.hpp index 7f27170c..af4e01fd 100644 --- a/include/gauxc/shell.hpp +++ b/include/gauxc/shell.hpp @@ -28,8 +28,10 @@ namespace GauXC { namespace detail { + /// Maximum number of primitives allowed per shell. static constexpr size_t shell_nprim_max = 32ul; + /// Double factorial values (K-1)!! used for shell normalization. static constexpr std::array df_Kminus1 = {{ 1LL, 1LL, 1LL, 2LL, 3LL, 8LL, 15LL, 48LL, 105LL, 384LL, 945LL, 3840LL, 10395LL, 46080LL, 135135LL, 645120LL, 2027025LL, 10321920LL, 34459425LL, @@ -37,38 +39,59 @@ namespace detail { 316234143225LL, 1961990553600LL, 7905853580625LL, 51011754393600LL, 213458046676875LL, 1428329123020800LL, 6190283353629375LL }}; + /// Default tolerance for shell contribution evaluation. static constexpr double default_shell_tolerance = 1e-10; } +/// Named type wrapper for the number of primitives in a shell. using PrimSize = detail::NamedType< int32_t, struct PrimSizeType >; +/// Named type wrapper for angular momentum quantum number. using AngularMomentum = detail::NamedType< int32_t, struct AngularMomentumType >; +/// Named type wrapper for spherical/Cartesian flag. using SphericalType = detail::NamedType< int32_t, struct SphericalTypeType >; +/** + * @brief A class to represent the state of contracted Gaussian basis functions. + * + * This class stores the exponents, contraction coefficients, origin, and + * angular momentum for a single shell in a Gaussian basis set. + * + * @tparam F Floating-point type for exponents and coefficients. + */ template class alignas(256) Shell { public: + /// Array type for storing primitive exponents and coefficients. using prim_array = std::array< F, detail::shell_nprim_max >; + /// Array type for storing the 3D Cartesian origin. using cart_array = std::array< double, 3 >; private: - prim_array alpha_; - prim_array coeff_; - cart_array O_; + prim_array alpha_; ///< Exponents of primitives. + prim_array coeff_; ///< Contraction coefficients. + cart_array O_; ///< Origin of the shell (x, y, z). - int32_t nprim_; - int32_t l_; - int32_t pure_; + int32_t nprim_; ///< Number of primitives. + int32_t l_; ///< Angular momentum of the shell. + int32_t pure_; ///< pure=1: spherical Gaussians; pure=0: Cartesian Gaussians. - double cutoff_radius_; - double shell_tolerance_{detail::default_shell_tolerance}; + double cutoff_radius_; ///< Real-space cutoff radius for evaluating shell contributions. + double shell_tolerance_{detail::default_shell_tolerance}; ///< Tolerance for evaluating shell contributions. //double _pad_; // Pad to be a multiple of 16 - // Shamelessly adapted from Libint... + /** + * @brief Normalize the contraction coefficients. + * + * Adjusts contraction coefficients so that the shell is properly normalized. + * Adapted from Libint normalization routines. + * + * @note Assumes that @c nprim_, @c l_, @c alpha_, and @c coeff_ have been set. + */ void normalize() { assert( l_ <= 15 ); @@ -108,6 +131,14 @@ class alignas(256) Shell { } + /** + * @brief Compute the real-space cutoff radius for this shell. + * + * The cutoff radius determines the distance beyond which shell contributions + * are considered negligible according to the shell tolerance. + * + * @note Assumes that @c nprim_, @c l_, @c alpha_, and @c coeff_ have been set. + */ void compute_shell_cutoff() { #if 0 @@ -131,8 +162,21 @@ class alignas(256) Shell { } public: + /// Default constructor. Creates an empty shell with no primitives. + /// @note The cutoff radius is undefined until initialized by other methods. Shell() : nprim_(0), l_(0), pure_(false) { }; + /** + * @brief Construct a shell with specified parameters. + * + * @param nprim Number of primitives in the shell. + * @param l Angular momentum quantum number. + * @param pure Spherical (1) or Cartesian (0) Gaussians. + * @param alpha Array of primitive exponents. + * @param coeff Array of contraction coefficients. + * @param O Cartesian origin of the shell. + * @param _normalize If true, normalize the contraction coefficients (default: true). + */ Shell( PrimSize nprim, AngularMomentum l, SphericalType pure, prim_array alpha, prim_array coeff, cart_array O, bool _normalize = true ) : alpha_( alpha ), coeff_( coeff ), O_( O ), @@ -143,6 +187,13 @@ class alignas(256) Shell { } + /** + * @brief Set tolerance for evaluating shell contributions. + * + * Recomputes the cutoff radius if the tolerance changes. + * + * @param tol New tolerance value. + */ void set_shell_tolerance( double tol ) { if( tol != shell_tolerance_ ) { shell_tolerance_ = tol; @@ -151,67 +202,143 @@ class alignas(256) Shell { } + /// Default destructor. ~Shell() noexcept = default; + /// Default copy constructor. Shell( const Shell& ) = default; + /// Default move constructor. Shell( Shell&& ) noexcept = default; + /// Default copy assignment operator. Shell& operator=(const Shell&) = default; + /// Default move assignment operator. Shell& operator=(Shell&&) noexcept = default; + /// @brief Get the number of primitives. + /// @return Number of primitives in the shell. inline HOST_DEVICE_ACCESSIBLE int32_t nprim() const { return nprim_; } + + /// @brief Get the angular momentum quantum number. + /// @return Angular momentum of the shell. inline HOST_DEVICE_ACCESSIBLE int32_t l() const { return l_; } + + /// @brief Check if the shell uses spherical harmonics. + /// @return 1 for spherical, 0 for Cartesian. + /// @note This flag matches the value stored in @c SphericalType. inline HOST_DEVICE_ACCESSIBLE int32_t pure() const { return pure_; } + /// @brief Get pointer to the exponent data. + /// @return Const pointer to the array of exponents. inline HOST_DEVICE_ACCESSIBLE const F* alpha_data() const { return detail::contiguous_data(alpha_); } + + /// @brief Get pointer to the coefficient data. + /// @return Const pointer to the array of contraction coefficients. inline HOST_DEVICE_ACCESSIBLE const F* coeff_data() const { return detail::contiguous_data(coeff_); } + + /// @brief Get pointer to the origin data. + /// @return Const pointer to the 3D origin array. inline HOST_DEVICE_ACCESSIBLE const double* O_data() const { return detail::contiguous_data(O_); } + + /// @brief Get mutable pointer to the exponent data. + /// @return Pointer to the array of exponents. inline HOST_DEVICE_ACCESSIBLE F* alpha_data() { return detail::contiguous_data(alpha_); } + + /// @brief Get mutable pointer to the coefficient data. + /// @return Pointer to the array of contraction coefficients. inline HOST_DEVICE_ACCESSIBLE F* coeff_data() { return detail::contiguous_data(coeff_); } + + /// @brief Get mutable pointer to the origin data. + /// @return Pointer to the 3D origin array. inline HOST_DEVICE_ACCESSIBLE double* O_data() { return detail::contiguous_data(O_); } + /// @brief Get the cutoff radius. + /// @return Real-space cutoff radius for this shell. inline HOST_DEVICE_ACCESSIBLE double cutoff_radius() const { return cutoff_radius_; } + /// @brief Get the Cartesian size of the shell. + /// @return Number of Cartesian basis functions: (l+1)*(l+2)/2. inline HOST_DEVICE_ACCESSIBLE int32_t cart_size() const { return (l_+1)*(l_+2)/2; } + + /// @brief Get the spherical size of the shell. + /// @return Number of spherical basis functions: 2*l+1. inline HOST_DEVICE_ACCESSIBLE int32_t pure_size() const { return 2*l_ + 1; } - inline HOST_DEVICE_ACCESSIBLE int32_t size() const {; + + /// @brief Get the size of the shell. + /// @return Number of basis functions (spherical or Cartesian based on pure_). + inline HOST_DEVICE_ACCESSIBLE int32_t size() const { return pure_ ? pure_size() : cart_size(); } + /// @brief Get the exponent array (const). + /// @return Const reference to the exponent array. inline const prim_array& alpha() const { return alpha_; } + + /// @brief Get the coefficient array (const). + /// @return Const reference to the contraction coefficient array. inline const prim_array& coeff() const { return coeff_; } + + /// @brief Get the origin array (const). + /// @return Const reference to the origin array. inline const cart_array& O() const { return O_; } + + /// @brief Get the exponent array (mutable). + /// @return Reference to the exponent array. inline prim_array& alpha() { return alpha_; } + + /// @brief Get the coefficient array (mutable). + /// @return Reference to the contraction coefficient array. inline prim_array& coeff() { return coeff_; } + + /// @brief Get the origin array (mutable). + /// @return Reference to the origin array. inline cart_array& O() { return O_; } + /// @brief Set the spherical/Cartesian flag. + /// @param p True for spherical, false for Cartesian. + /// @note This flag matches the value stored in @c SphericalType. inline void set_pure(bool p) { pure_ = p; } + /** + * @brief Serialize the shell for archival storage. + * @tparam Archive Archive type (e.g., cereal). + * @param ar Archive reference. + * @note Includes cached cutoff radius and tolerance. + */ template void serialize( Archive& ar ) { ar( nprim_, l_, pure_, alpha_, coeff_, O_, cutoff_radius_, shell_tolerance_ ); } + /** + * @brief Compare two shells for equality. + * + * Checks that both shells have the same number of primitives, angular momentum, + * spherical flag, origin, exponents, and coefficients. + * + * @param other Shell to compare against. + * @return True if the shells are equal. + */ bool operator==( const Shell& other ) const { if( other.nprim_ != nprim_ ) return false; if( other.l_ != l_ ) return false; @@ -229,6 +356,17 @@ class alignas(256) Shell { }; +/** + * @brief Stream insertion operator for Shell. + * + * Outputs a human-readable representation of the shell including origin, + * angular momentum, spherical flag, and primitive exponents/coefficients. + * + * @tparam T Floating-point type of the shell. + * @param os Output stream. + * @param sh Shell to output. + * @return Reference to the output stream. + */ template inline std::ostream& operator<<( std::ostream& os, const Shell& sh ) { os << "GauXC::Shell:( O={" diff --git a/include/gauxc/xc_integrator.hpp b/include/gauxc/xc_integrator.hpp index 03feaf93..e6225228 100644 --- a/include/gauxc/xc_integrator.hpp +++ b/include/gauxc/xc_integrator.hpp @@ -20,76 +20,220 @@ namespace GauXC { namespace detail { + /// Forward declaration of XCIntegrator implementation. template class XCIntegratorImpl; } - +/** + * @brief High-level interface for exchange-correlation and exact exchange integration. + * + * XCIntegrator provides methods to evaluate XC energies, potentials, gradients, + * and exact exchange contributions using numerical quadrature on a molecular grid. + * + * @tparam MatrixType Matrix type for density and Fock-like matrices. + */ template class XCIntegrator { public: - using matrix_type = MatrixType; - using value_type = typename matrix_type::value_type; - using basisset_type = BasisSet< value_type >; + using matrix_type = MatrixType; ///< Matrix type alias. + using value_type = typename matrix_type::value_type; ///< Scalar type alias. + using basisset_type = BasisSet< value_type >; ///< Basis set type alias. + /// Return type for RKS exc+vxc: (energy, Vxc). using exc_vxc_type_rks = std::tuple< value_type, matrix_type >; - using exc_vxc_type_uks = std::tuple< value_type, matrix_type, matrix_type >; + /// Return type for UKS exc+vxc: (energy, Vxc_alpha, Vxc_beta). + using exc_vxc_type_uks = std::tuple< value_type, matrix_type, matrix_type >; + /// Return type for GKS exc+vxc: (energy, Vxc_scalar, Vxc_x, Vxc_y, Vxc_z). using exc_vxc_type_gks = std::tuple< value_type, matrix_type, matrix_type, matrix_type, matrix_type >; + /// Return type for XC gradient: vector of gradient components. using exc_grad_type = std::vector< value_type >; + /// Return type for exact exchange matrix. using exx_type = matrix_type; + /// Return type for RKS Fxc contraction. using fxc_contraction_type_rks = matrix_type; + /// Return type for UKS Fxc contraction: (Fxc_alpha, Fxc_beta). using fxc_contraction_type_uks = std::tuple< matrix_type, matrix_type >; + /// Return type for dd-Psi evaluation. using dd_psi_type = std::vector< value_type >; + /// Return type for dd-Psi potential. using dd_psi_potential_type = matrix_type; private: - using pimpl_type = detail::XCIntegratorImpl; + using pimpl_type = detail::XCIntegratorImpl; ///< Implementation type. - std::unique_ptr pimpl_; + std::unique_ptr pimpl_; ///< PIMPL handle. public: + /// Default constructor. XCIntegrator() = default; + + /// Destructor. ~XCIntegrator() noexcept; + /** + * @brief Construct from a pre-built implementation. + * @param pimpl Unique pointer to implementation instance. + */ XCIntegrator( std::unique_ptr&& pimpl ); + /// Deleted copy constructor. XCIntegrator( const XCIntegrator& ) = delete; - XCIntegrator( XCIntegrator&& ) noexcept; - - value_type integrate_den( const MatrixType& ); - value_type eval_exc( const MatrixType&, const IntegratorSettingsXC& = IntegratorSettingsXC{} ); - value_type eval_exc( const MatrixType&, const MatrixType&, const IntegratorSettingsXC& = IntegratorSettingsXC{} ); - value_type eval_exc( const MatrixType&, const MatrixType&, const MatrixType&, const MatrixType&, const IntegratorSettingsXC& = IntegratorSettingsXC{} ); - - exc_vxc_type_rks eval_exc_vxc ( const MatrixType&, - const IntegratorSettingsXC& = IntegratorSettingsXC{} ); - exc_vxc_type_uks eval_exc_vxc ( const MatrixType&, const MatrixType&, - const IntegratorSettingsXC& = IntegratorSettingsXC{} ); - exc_vxc_type_gks eval_exc_vxc ( const MatrixType&, const MatrixType&, const MatrixType&, const MatrixType&, - const IntegratorSettingsXC& = IntegratorSettingsXC{}); - - exc_grad_type eval_exc_grad( const MatrixType&, const IntegratorSettingsXC& = IntegratorSettingsXC{} ); - exc_grad_type eval_exc_grad( const MatrixType&, const MatrixType&, const IntegratorSettingsXC& = IntegratorSettingsXC{} ); - - exx_type eval_exx ( const MatrixType&, - const IntegratorSettingsEXX& = IntegratorSettingsEXX{} ); - - fxc_contraction_type_rks eval_fxc_contraction ( const MatrixType&, const MatrixType&, - const IntegratorSettingsXC& = IntegratorSettingsXC{} ); - fxc_contraction_type_uks eval_fxc_contraction ( const MatrixType&, const MatrixType&, const MatrixType&, const MatrixType&, - const IntegratorSettingsXC& = IntegratorSettingsXC{} ); - - dd_psi_type eval_dd_psi( const MatrixType&, unsigned ); - dd_psi_potential_type eval_dd_psi_potential( const MatrixType&, unsigned ); + /// Move constructor. + XCIntegrator( XCIntegrator&& ) noexcept; + /** + * @brief Integrate the electron density. + * @param P Density matrix. + * @return Integrated number of electrons. + */ + value_type integrate_den( const MatrixType& P ); + + /** + * @brief Evaluate the XC energy (RKS). + * @param P Density matrix. + * @param opts Integration settings. + * @return XC energy. + */ + value_type eval_exc( const MatrixType& P, const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate the XC energy (UKS). + * @param Palpha Alpha density matrix. + * @param Pbeta Beta density matrix. + * @param opts Integration settings. + * @return XC energy. + */ + value_type eval_exc( const MatrixType& Palpha, const MatrixType& Pbeta, const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate the XC energy (GKS). + * @param Pscalar Scalar density matrix. + * @param Px X-component spin density matrix. + * @param Py Y-component spin density matrix. + * @param Pz Z-component spin density matrix. + * @param opts Integration settings. + * @return XC energy. + */ + value_type eval_exc( const MatrixType& Pscalar, const MatrixType& Px, const MatrixType& Py, const MatrixType& Pz, const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate XC energy and potential (RKS). + * @param P Density matrix. + * @param opts Integration settings. + * @return Tuple of (energy, Vxc). + */ + exc_vxc_type_rks eval_exc_vxc( const MatrixType& P, + const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate XC energy and potential (UKS). + * @param Palpha Alpha density matrix. + * @param Pbeta Beta density matrix. + * @param opts Integration settings. + * @return Tuple of (energy, Vxc_alpha, Vxc_beta). + */ + exc_vxc_type_uks eval_exc_vxc( const MatrixType& Palpha, const MatrixType& Pbeta, + const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate XC energy and potential (GKS). + * @param Pscalar Scalar density matrix. + * @param Px X-component spin density matrix. + * @param Py Y-component spin density matrix. + * @param Pz Z-component spin density matrix. + * @param opts Integration settings. + * @return Tuple of (energy, Vxc_scalar, Vxc_x, Vxc_y, Vxc_z). + */ + exc_vxc_type_gks eval_exc_vxc( const MatrixType& Pscalar, const MatrixType& Px, const MatrixType& Py, const MatrixType& Pz, + const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate XC gradient (RKS). + * @param P Density matrix. + * @param opts Integration settings. + * @return Vector of gradient components (3*natoms). + */ + exc_grad_type eval_exc_grad( const MatrixType& P, const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate XC gradient (UKS). + * @param Palpha Alpha density matrix. + * @param Pbeta Beta density matrix. + * @param opts Integration settings. + * @return Vector of gradient components (3*natoms). + */ + exc_grad_type eval_exc_grad( const MatrixType& Palpha, const MatrixType& Pbeta, const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate exact exchange matrix (sn-LinK). + * @param P Density matrix. + * @param opts EXX integration settings. + * @return Exact exchange matrix K. + */ + exx_type eval_exx( const MatrixType& P, + const IntegratorSettingsEXX& opts = IntegratorSettingsEXX{} ); + + /** + * @brief Evaluate Fxc contraction (RKS). + * @param P Density matrix. + * @param X Trial vector for contraction. + * @param opts Integration settings. + * @return Contracted Fxc matrix. + */ + fxc_contraction_type_rks eval_fxc_contraction( const MatrixType& P, const MatrixType& X, + const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate Fxc contraction (UKS). + * @param Palpha Alpha density matrix. + * @param Pbeta Beta density matrix. + * @param Xalpha Alpha trial vector. + * @param Xbeta Beta trial vector. + * @param opts Integration settings. + * @return Tuple of (Fxc_alpha, Fxc_beta). + */ + fxc_contraction_type_uks eval_fxc_contraction( const MatrixType& Palpha, const MatrixType& Pbeta, const MatrixType& Xalpha, const MatrixType& Xbeta, + const IntegratorSettingsXC& opts = IntegratorSettingsXC{} ); + + /** + * @brief Evaluate dd-Psi diagnostic. + * @param P Density matrix. + * @param deriv Derivative order. + * @return Vector of dd-Psi values. + */ + dd_psi_type eval_dd_psi( const MatrixType& P, unsigned deriv ); + + /** + * @brief Evaluate dd-Psi potential. + * @param P Density matrix. + * @param deriv Derivative order. + * @return dd-Psi potential matrix. + */ + dd_psi_potential_type eval_dd_psi_potential( const MatrixType& P, unsigned deriv ); + + /** + * @brief Get the internal timing tracker. + * @return Const reference to timer. + */ const util::Timer& get_timings() const; + + /** + * @brief Get the associated load balancer (const). + * @return Const reference to LoadBalancer. + */ const LoadBalancer& load_balancer() const; + + /** + * @brief Get the associated load balancer (mutable). + * @return Reference to LoadBalancer. + */ LoadBalancer& load_balancer(); }; diff --git a/include/gauxc/xc_integrator_settings.hpp b/include/gauxc/xc_integrator_settings.hpp index 1ec26d0e..a081d487 100644 --- a/include/gauxc/xc_integrator_settings.hpp +++ b/include/gauxc/xc_integrator_settings.hpp @@ -13,20 +13,44 @@ namespace GauXC { +/** + * @brief Base settings for exact exchange (EXX) integration. + */ struct IntegratorSettingsEXX { virtual ~IntegratorSettingsEXX() noexcept = default; }; + +/** + * @brief Settings for seminumerical linear exchange (sn-LinK) integration. + * + * Controls screening and tolerance parameters for sn-LinK calculations. + */ struct IntegratorSettingsSNLinK : public IntegratorSettingsEXX { - bool screen_ek = true; - double energy_tol = 1e-10; - double k_tol = 1e-10; + bool screen_ek = true; ///< Whether to apply EK screening. + double energy_tol = 1e-10; ///< Energy convergence tolerance. + double k_tol = 1e-10; ///< Exchange matrix element tolerance. }; +/** + * @brief Base settings for exchange-correlation (XC) integration. + */ struct IntegratorSettingsXC { virtual ~IntegratorSettingsXC() noexcept = default; }; + +/** + * @brief Settings for Kohn-Sham DFT integration. + * + * Controls tolerances for generalized Kohn-Sham (GKS) calculations. + */ struct IntegratorSettingsKS : public IntegratorSettingsXC { - double gks_dtol = 1e-12; + double gks_dtol = 1e-12; ///< Tolerance for GKS density evaluation. }; +/** + * @brief Settings for XC gradient evaluation. + * + * Controls whether grid weight derivatives are included in the gradient + * computation or if only the Hellmann-Feynman contribution is used. + */ struct IntegratorSettingsEXC_GRAD : public IntegratorSettingsKS { - bool include_weight_derivatives= true; // whether to include grid weight contribution and employ translational invariance, or just use Hellmann-Feynman gradient + bool include_weight_derivatives = true; ///< Include grid weight contribution and translational invariance. }; } From 316cb7c9d67babcbf9893c4f6a543ee791711281 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> Date: Fri, 16 Jan 2026 16:05:02 +0100 Subject: [PATCH 2/3] Update docstrings Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- include/gauxc/molgrid/defaults.hpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/gauxc/molgrid/defaults.hpp b/include/gauxc/molgrid/defaults.hpp index 94a00982..14a1b8d8 100644 --- a/include/gauxc/molgrid/defaults.hpp +++ b/include/gauxc/molgrid/defaults.hpp @@ -30,10 +30,10 @@ namespace GauXC { /// Return the default atomic radius (Bohr) for a given atomic number. double default_atomic_radius(AtomicNumber); - /// Return the default Murray-Handy-Laming radial scaling factor for an atomic number. + /// Return the default Mura-Knowles radial scaling factor for an atomic number. RadialScale default_mk_radial_scaling_factor( AtomicNumber ); - /// Return the default Mura-Knowles radial scaling factor for an atomic number. + /// Return the default Murray-Handy-Laming radial scaling factor for an atomic number. RadialScale default_mhl_radial_scaling_factor( AtomicNumber ); /// Return the default Treutler-Ahlrichs radial scaling factor for an atomic number. From 18338e858acb0aba934bd32d8c68a1944155f5f2 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> Date: Fri, 16 Jan 2026 16:06:21 +0100 Subject: [PATCH 3/3] Also document other integrator settings --- docs/api/cxx/xc.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/api/cxx/xc.rst b/docs/api/cxx/xc.rst index 60287b1b..4457bd8a 100644 --- a/docs/api/cxx/xc.rst +++ b/docs/api/cxx/xc.rst @@ -17,4 +17,10 @@ The :cpp:class:`GauXC::XCIntegratorFactory` creates integrators based on user-de :members: .. doxygenstruct:: GauXC::IntegratorSettingsEXC_GRAD + :members: + +.. doxygenstruct:: GauXC::IntegratorSettingsEXX + :members: + +.. doxygenstruct:: GauXC::IntegratorSettingsSNLinK :members: \ No newline at end of file