Basic C API for GauXC

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/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/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/types.h>
+#include <gauxc/status.h>
+#include <gauxc/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,
+   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/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             ///< Treutlet-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,
+  GauXC_SupportedAlg_DEN,
+  GauXC_SupportedAlg_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

include/gauxc/enums.hpp

@@ -11,6 +11,8 @@
  */
 #pragma once
 
+#include <gauxc/enums.h>
+
 namespace GauXC {
 
 /**
@@ -19,10 +21,10 @@ namespace GauXC {
  *  Generally mapped to equivalent enums in IntegratorXX
  */
 enum class RadialQuad {
-  Becke,             ///< Becke radial quadrature
-  MuraKnowles,       ///< Mura-Knowles radial quadrature
-  MurrayHandyLaming, ///< Murray-Handy-Laming radial quadrature
-  TreutlerAhlrichs   ///< Treutler-Ahlrichs radial quadrature
+  Becke = C::GauXC_RadialQuad_Becke,                         ///< Becke radial quadrature
+  MuraKnowles = C::GauXC_RadialQuad_MuraKnowles,             ///< Mura-Knowles radial quadrature
+  MurrayHandyLaming = C::GauXC_RadialQuad_MurrayHandyLaming, ///< Murray-Handy-Laming radial quadrature
+  TreutlerAhlrichs = C::GauXC_RadialQuad_TreutlerAhlrichs    ///< Treutler-Ahlrichs radial quadrature
 };
 
 /**
@@ -31,37 +33,45 @@ enum class RadialQuad {
  *  See https://gaussian.com/integral for specification
  */
 enum class AtomicGridSizeDefault {
-  FineGrid,       ///< Fine grid      (least accurate)
-  UltraFineGrid,  ///< Ultrafine grid (appropriate accuracy)
-  SuperFineGrid,  ///< Superfine grid (most accurate)
-  GM3,            ///< Treutler-Ahlrichs GM3
-  GM5             ///< Treutlet-Ahlrichs GM5
+  FineGrid = C::GauXC_AtomicGridSizeDefault_FineGrid,            ///< Fine grid      (least accurate)
+  UltraFineGrid = C::GauXC_AtomicGridSizeDefault_UltraFineGrid,  ///< Ultrafine grid (appropriate accuracy)
+  SuperFineGrid = C::GauXC_AtomicGridSizeDefault_SuperFineGrid,  ///< Superfine grid (most accurate)
+  GM3 = C::GauXC_AtomicGridSizeDefault_GM3,                      ///< Treutler-Ahlrichs GM3
+  GM5 = C::GauXC_AtomicGridSizeDefault_GM5                       ///< Treutlet-Ahlrichs GM5
 };
 
 /**
  *  @brief Specifications of atomic partitioning scheme for the
  *  molecular integration
  */
 enum class XCWeightAlg {
-  NOTPARTITIONED, ///< Not partitioned
-  Becke, ///< The original Becke weighting scheme
-  SSF,   ///< The Stratmann-Scuseria-Frisch weighting scheme
-  LKO    ///< The Lauqua-Kuessman-Ochsenfeld weighting scheme
+  NOTPARTITIONED = C::GauXC_XCWeightAlg_NOTPARTITIONED, ///< Not partitioned
+  Becke = C::GauXC_XCWeightAlg_Becke,                   ///< The original Becke weighting scheme
+  SSF = C::GauXC_XCWeightAlg_SSF,                       ///< The Stratmann-Scuseria-Frisch weighting scheme
+  LKO = C::GauXC_XCWeightAlg_LKO                        ///< The Lauqua-Kuessman-Ochsenfeld weighting scheme
 };
 
 /**
  *  @brief Specification of the execution space for various operations
  */
 enum class ExecutionSpace {
-  Host,  ///< Execute task on the host
-  Device ///< Execute task on the device (e.g. GPU)
+  Host = C::GauXC_ExecutionSpace_Host,    ///< Execute task on the host
+  Device = C::GauXC_ExecutionSpace_Device ///< Execute task on the device (e.g. GPU)
 };
 
 /// Supported Algorithms / Integrands
 enum class SupportedAlg {
-  XC,
-  DEN,
-  SNLINK
+  XC = C::GauXC_SupportedAlg_XC,
+  DEN = C::GauXC_SupportedAlg_DEN,
+  SNLINK = C::GauXC_SupportedAlg_SNLINK
+};
+
+/// High-level specification of pruning schemes for atomic quadratures
+enum class PruningScheme {
+  Unpruned = C::GauXC_PruningScheme_Unpruned, ///< Unpruned atomic quadrature
+  Robust = C::GauXC_PruningScheme_Robust,     ///< The "Robust" scheme of Psi4
+  Treutler = C::GauXC_PruningScheme_Treutler  ///< The Treutler-Ahlrichs scheme
 };
 
+
 } // namespace GauXC