Basic C API for GauXC (#172)

 Add C API for GauXC

Author: awvwgk

CMakeLists.txt

@@ -27,6 +27,7 @@ endif()
 
 
 # GauXC Options
+option( GAUXC_ENABLE_C          "Enable C API"                ON  )
 option( GAUXC_ENABLE_HOST       "Enable Host Integrator"      ON  )
 option( GAUXC_ENABLE_CUDA       "Enable CUDA Bindings"        OFF )
 option( GAUXC_ENABLE_HIP        "Enable HIP Bindings"         OFF )
@@ -54,6 +55,7 @@ cmake_dependent_option( GAUXC_ENABLE_CUTLASS
 )
 
 # Default the feature variables
+set( GAUXC_HAS_C          FALSE CACHE BOOL "" FORCE )
 set( GAUXC_HAS_HOST       FALSE CACHE BOOL "" FORCE )
 set( GAUXC_HAS_CUDA       FALSE CACHE BOOL "" FORCE )
 set( GAUXC_HAS_HIP        FALSE CACHE BOOL "" FORCE )
@@ -67,6 +69,7 @@ set( GAUXC_HAS_CUTLASS    FALSE CACHE BOOL "" FORCE )
 set( GAUXC_BLAS_IS_LP64   FALSE CACHE BOOL "" FORCE )
 
 mark_as_advanced( FORCE 
+  GAUXC_HAS_C
   GAUXC_HAS_HOST     
   GAUXC_HAS_CUDA     
   GAUXC_HAS_HIP      

cmake/gauxc-config.cmake.in

@@ -10,6 +10,7 @@ include(CMakeFindDependencyMacro)
 find_dependency( ExchCXX )
 find_dependency( IntegratorXX )
 
+set( GAUXC_HAS_C          @GAUXC_HAS_C@         )
 set( GAUXC_HAS_HOST       @GAUXC_HAS_HOST@      )
 set( GAUXC_HAS_CUDA       @GAUXC_HAS_CUDA@      )
 set( GAUXC_HAS_HIP        @GAUXC_HAS_HIP@       )

include/gauxc/c/atom.h

@@ -0,0 +1,42 @@
+/**
+ * GauXC Copyright (c) 2020-2024, The Regents of the University of California,
+ * through Lawrence Berkeley National Laboratory (subject to receipt of
+ * any required approvals from the U.S. Dept. of Energy).
+ *
+ * (c) 2024-2025, Microsoft Corporation
+ *
+ * All rights reserved.
+ *
+ * See LICENSE.txt for details
+ */
+#pragma once
+
+#ifdef __cplusplus
+#include <cstdint>
+#include <cstdbool>
+#include <cstddef>
+#else
+#include <stdint.h>
+#include <stdbool.h>
+#include <stddef.h>
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+namespace GauXC::C {
+#endif
+
+/**
+ * @brief GauXC C API Atom representation.
+ */
+typedef struct GauXCAtom {
+  int64_t Z;   ///< Atomic number.
+  double  x;   ///< X coordinate (Bohr).
+  double  y;   ///< Y coordinate (Bohr).
+  double  z;   ///< Z coordinate (Bohr).
+} GauXCAtom;
+
+#ifdef __cplusplus
+} // namespace GauXC::C
+} // extern "C"
+#endif

include/gauxc/c/basisset.h

@@ -0,0 +1,72 @@
+/**
+ * GauXC Copyright (c) 2020-2024, The Regents of the University of California,
+ * through Lawrence Berkeley National Laboratory (subject to receipt of
+ * any required approvals from the U.S. Dept. of Energy).
+ *
+ * (c) 2024-2025, Microsoft Corporation
+ *
+ * All rights reserved.
+ *
+ * See LICENSE.txt for details
+ */
+#pragma once
+
+#ifdef __cplusplus
+#include <cstdint>
+#include <cstdbool>
+#include <cstddef>
+#else
+#include <stdint.h>
+#include <stdbool.h>
+#include <stddef.h>
+#endif
+#include <gauxc/c/types.h>
+#include <gauxc/c/status.h>
+#include <gauxc/c/shell.h>
+
+#ifdef __cplusplus
+extern "C" {
+namespace GauXC::C {
+#endif
+
+/**
+ * @brief GauXC C API BasisSet handle.
+ */
+typedef struct GauXCBasisSet {
+  GauXCHeader hdr; ///< Header for internal use.
+  void* ptr; ///< Pointer to the BasisSet instance.
+} GauXCBasisSet;
+
+/**
+ * @brief Create a new BasisSet instance.
+ * @param status Status object to capture any errors.
+ * @return Handle to the created BasisSet.
+ */
+extern GauXCBasisSet gauxc_basisset_new( GauXCStatus* status );
+
+/**
+ * @brief Create a new BasisSet instance from arrays of shells.
+ * @param status Status object to capture any errors.
+ * @param shells Pointer to an array of GauXCShell.
+ * @param nshells Number of shells in the array.
+ * @param normalize Whether to normalize the basis functions.
+ * @return Handle to the created BasisSet.
+ */
+extern GauXCBasisSet gauxc_basisset_new_from_shells(
+   GauXCStatus* status,
+   const GauXCShell* shells,
+   size_t nshells,
+   bool normalize
+);
+
+/**
+ * @brief Delete a BasisSet instance.
+ * @param status Status object to capture any errors.
+ * @param basis Handle to the BasisSet to delete.
+ */
+extern void gauxc_basisset_delete( GauXCStatus* status, GauXCBasisSet* basis );
+
+#ifdef __cplusplus
+} // namespace GauXC::C
+} // extern "C"
+#endif

include/gauxc/c/enums.h

@@ -0,0 +1,81 @@
+/**
+ * GauXC Copyright (c) 2020-2024, The Regents of the University of California,
+ * through Lawrence Berkeley National Laboratory (subject to receipt of
+ * any required approvals from the U.S. Dept. of Energy).
+ *
+ * (c) 2024-2025, Microsoft Corporation
+ *
+ * All rights reserved.
+ *
+ * See LICENSE.txt for details
+ */
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+namespace GauXC::C {
+#endif
+
+/**
+ *  @brief GauXC specific enums for the specification of radial quadratures
+ *
+ *  Generally mapped to equivalent enums in IntegratorXX
+ */
+enum GauXC_RadialQuad {
+  GauXC_RadialQuad_Becke,             ///< Becke radial quadrature
+  GauXC_RadialQuad_MuraKnowles,       ///< Mura-Knowles radial quadrature
+  GauXC_RadialQuad_MurrayHandyLaming, ///< Murray-Handy-Laming radial quadrature
+  GauXC_RadialQuad_TreutlerAhlrichs   ///< Treutler-Ahlrichs radial quadrature
+};
+
+/**
+ *  @brief Specifications of grid defaults for atomic integration
+ *
+ *  See https://gaussian.com/integral for specification
+ */
+enum GauXC_AtomicGridSizeDefault {
+  GauXC_AtomicGridSizeDefault_FineGrid,       ///< Fine grid      (least accurate)
+  GauXC_AtomicGridSizeDefault_UltraFineGrid,  ///< Ultrafine grid (appropriate accuracy)
+  GauXC_AtomicGridSizeDefault_SuperFineGrid,  ///< Superfine grid (most accurate)
+  GauXC_AtomicGridSizeDefault_GM3,            ///< Treutler-Ahlrichs GM3
+  GauXC_AtomicGridSizeDefault_GM5             ///< Treutler-Ahlrichs GM5
+};
+
+/**
+ *  @brief Specifications of atomic partitioning scheme for the
+ *  molecular integration
+ */
+enum GauXC_XCWeightAlg {
+  GauXC_XCWeightAlg_NOTPARTITIONED, ///< Not partitioned
+  GauXC_XCWeightAlg_Becke, ///< The original Becke weighting scheme
+  GauXC_XCWeightAlg_SSF,   ///< The Stratmann-Scuseria-Frisch weighting scheme
+  GauXC_XCWeightAlg_LKO    ///< The Lauqua-Kuessman-Ochsenfeld weighting scheme
+};
+
+/**
+ *  @brief Specification of the execution space for various operations
+ */
+enum GauXC_ExecutionSpace {
+  GauXC_ExecutionSpace_Host,  ///< Execute task on the host
+  GauXC_ExecutionSpace_Device ///< Execute task on the device (e.g. GPU)
+};
+
+/// Supported Algorithms / Integrands
+enum GauXC_SupportedAlg {
+  GauXC_SupportedAlg_XC,     ///< Exchange-correlation integration
+  GauXC_SupportedAlg_DEN,    ///< Density integration
+  GauXC_SupportedAlg_SNLINK  ///< Seminumerical Coulomb/exchange (snLinK)
+};
+
+/// High-level specification of pruning schemes for atomic quadratures
+enum GauXC_PruningScheme {
+  GauXC_PruningScheme_Unpruned, ///< Unpruned atomic quadrature
+  GauXC_PruningScheme_Robust,   ///< The "Robust" scheme of Psi4
+  GauXC_PruningScheme_Treutler  ///< The Treutler-Ahlrichs scheme
+};
+
+
+#ifdef __cplusplus
+} // namespace GauXC::C
+} // extern "C"
+#endif