Basic C API for GauXC by awvwgk · Pull Request #172 · wavefunction91/GauXC

awvwgk · 2026-01-19T12:30:49Z

Closes #171

Copilot

Pull request overview

This pull request adds a comprehensive C API for the GauXC library, enabling integration with C codebases and other languages that interface with C. The implementation wraps core GauXC C++ functionality including molecular structures, basis sets, integration grids, load balancing, and XC integrators.

Changes:

Added C API bindings for core classes (Molecule, Atom, BasisSet, Shell, etc.)
Implemented factory patterns for runtime environments, load balancers, molecular weights, and XC integrators
Created C/C++ compatible enum definitions with mappings between C and C++ versions
Added HDF5 I/O support for C API
Refactored configuration headers to separate C and C++ concerns

Reviewed changes

Copilot reviewed 47 out of 47 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
include/gauxc/*.h	New C API header files defining opaque handles and functions for core types
include/gauxc/util/c_*.hpp	Helper headers for casting between C handles and C++ objects
src/c_*.cxx	C API implementation files wrapping C++ functionality
include/gauxc/enum.h	C-compatible enum definitions
include/gauxc/enums.hpp	C++ enum class definitions mapped to C enums
include/gauxc/gauxc_config.h.in	C-compatible configuration header
include/gauxc/gauxc_config.hpp	C++ configuration header including C header
tests/moltypes_test.cxx	Basic C API interoperability test
src/CMakeLists.txt	CMake integration for conditional C API compilation
src/external/c_hdf5_*.cxx	HDF5 I/O functions for C API

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/c-api/c_xc_integrator.cxx

include/gauxc/load_balancer.h

src/c-api/c_molecule.cxx

src/external/c_hdf5_write.cxx

include/gauxc/c/molecule.h

tests/moltypes_test.cxx

include/gauxc/xc_integrator.h

src/c-api/c_functional.cxx

src/c-api/c_xc_integrator.cxx

Copilot

Pull request overview

Copilot reviewed 48 out of 48 changed files in this pull request and generated 17 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

include/gauxc/xc_integrator.h

src/c_molecule.cxx

include/gauxc/c/hdf5.h

src/CMakeLists.txt

src/c_molgrid.cxx

src/c-api/c_matrix.hpp

src/c-api/c_basisset.hpp

src/c-api/c_matrix.cxx

src/c-api/c_functional.cxx

include/gauxc/types.h

- provide C enums - add atom and molecule types - add basis set and shell definitions - add molecule grid and runtime environment - add load balancer to C API - add molecular weights for C API - add functional class wrapping ExchCXX - add xc integrator and matrix type - add references for functionals - add support for reading and writing from HDF5 in C

include/gauxc/c/hdf5.h

src/c-api/c_basisset.hpp

include/gauxc/util/c_basisset.hpp

include/gauxc/util/c_status.hpp

include/gauxc/c/mpi.h

include/gauxc/c/basisset.h

include/gauxc/c/functional.h

include/gauxc/gauxc_config.h.in

src/c-api/c_matrix.hpp

Copilot

Pull request overview

Copilot reviewed 49 out of 49 changed files in this pull request and generated 10 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/c_xc_integrator.cxx

include/gauxc/c/status.h

tests/moltypes_test.cxx

src/c-api/c_matrix.cxx

src/c-api/c_functional.cxx

src/c_xc_integrator.cxx

tests/moltypes_test.cxx

src/c-api/c_types.cxx

- remove matrix class - directly expose ReplicatedXCIntegrator API

Copilot

Pull request overview

Copilot reviewed 49 out of 49 changed files in this pull request and generated 13 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-31T19:55:45Z

src/c-api/c_status.hpp

+static inline void gauxc_status_init(C::GauXCStatus* status) {
+   if (status != nullptr) {
+     status->code = 0;
+     status->message = nullptr;
+   }


gauxc_status_init overwrites status->message with nullptr without freeing any previously allocated message. This will leak if callers reuse a GauXCStatus across multiple API calls after an error. Consider freeing status->message in gauxc_status_init (or calling gauxc_status_delete internally) before resetting fields.

Copilot · 2026-03-31T19:55:45Z

src/c-api/c_status.hpp

+#include <cstring>
+
+#include <gauxc/c/status.h>
+
+#include <gauxc/exceptions.hpp>
+
+namespace GauXC::detail {
+
+static inline void gauxc_status_init(C::GauXCStatus* status) {
+   if (status != nullptr) {
+     status->code = 0;
+     status->message = nullptr;
+   }
+}
+
+static inline void gauxc_status_handle(C::GauXCStatus* status, int code, const char* message) {
+   if (status != nullptr) {
+     status->code = code;
+     if (status->message != nullptr) {
+       std::free(status->message);
+     }
+     status->message = (char*)std::malloc(std::strlen(message) + 1);
+     std::strcpy(status->message, message);


This header uses std::malloc/std::free but does not include <cstdlib>, relying on transitive includes for declarations. Add the proper include to make the header self-contained and avoid build failures under stricter compilers.

Copilot · 2026-03-31T19:55:45Z

src/c-api/c_types.cxx

+void gauxc_object_delete(GauXCStatus* status, void** obj) {
+   detail::gauxc_status_init(status);
+   if(obj == nullptr) return;
+
+   struct GauXCObject {
+      GauXCHeader hdr;
+   };
+
+   GauXCHeader* header = &reinterpret_cast<struct GauXCObject*>(*obj)->hdr;
+


gauxc_object_delete dereferences *obj unconditionally (reinterpret_cast<...>(*obj)), so passing a non-null obj whose value is nullptr will segfault. Add a if (*obj == nullptr) return; (or set an error) before reading the header.

Copilot · 2026-03-31T19:55:45Z

include/gauxc/c/types.h

+ * @param status Status object to capture any errors.
+ * @param ptr Pointer to the GauXC object to delete.
+ */
+extern void gauxc_object_delete(
+  GauXCStatus* status,
+  void** ptr
+);
+
+/**
+ * @brief Delete all GauXC objects.
+ * @param status Status object to capture any errors.
+ * @param ptrs Array of pointers to GauXC objects.
+ * @param nptrs Number of pointers in the array.
+ */
+extern void gauxc_objects_delete(
+  GauXCStatus* status,
+  void** ptrs,


The API docs for gauxc_object_delete are misleading: the implementation expects void** where *ptr points to a handle struct (e.g., GauXCMolecule*), not the underlying handle.ptr. Please clarify the documentation (and ideally the parameter name) to reflect the required calling convention, otherwise consumers are likely to pass the wrong pointer type and crash.

Suggested change

* @param status Status object to capture any errors.

* @param ptr Pointer to the GauXC object to delete.

*/

extern void gauxc_object_delete(

GauXCStatus* status,

void** ptr

);

/**

* @brief Delete all GauXC objects.

* @param status Status object to capture any errors.

* @param ptrs Array of pointers to GauXC objects.

* @param nptrs Number of pointers in the array.

*/

extern void gauxc_objects_delete(

GauXCStatus* status,

void** ptrs,

*

* This function expects a pointer to a GauXC handle object pointer. For example,

* for a molecule handle `GauXCMolecule* mol`, you must pass `&mol` to this

* function (type `void**` after implicit conversion), not the underlying

* implementation pointer stored inside the handle.

*

* The function will delete the underlying GauXC object associated with the

* handle and may set the handle to `NULL` on success.

*

* @param status Status object to capture any errors.

* @param handle Address of the GauXC handle object pointer to delete

* (e.g., `(void**)&mol` where `mol` is a `GauXCMolecule*`).

*/

extern void gauxc_object_delete(

GauXCStatus* status,

void** handle

);

/**

* @brief Delete all GauXC objects.

*

* This function is the batched counterpart of ::gauxc_object_delete. It expects

* an array of pointers to GauXC handle object pointers. Each element of

* `handles` should be the address of a handle object pointer (e.g., entries of

* type `GauXCMolecule**`, passed as `void**`).

*

* For each element, the underlying GauXC object will be deleted and the

* corresponding handle pointer may be set to `NULL` on success.

*

* @param status Status object to capture any errors.

* @param handles Array of addresses of GauXC handle object pointers.

* @param nptrs Number of pointers in the array.

*/

extern void gauxc_objects_delete(

GauXCStatus* status,

void** handles,

Copilot · 2026-03-31T19:55:46Z

src/c-api/c_runtime_environment.cxx

+void gauxc_runtime_environment_delete(GauXCStatus* status, GauXCRuntimeEnvironment* env) {
+  detail::gauxc_status_init(status);
+  if (env == nullptr) return;
+  if (env->ptr != nullptr)
+    delete detail::get_runtime_environment_ptr(*env);
+  env->ptr = nullptr;
+#ifdef GAUXC_HAS_DEVICE
+  if (env->device_ptr != nullptr)
+    delete detail::get_device_runtime_environment_ptr(*env);
+  env->device_ptr = nullptr;
+#endif


gauxc_runtime_environment_delete deletes get_runtime_environment_ptr(*env), but get_runtime_environment_ptr prefers device_ptr when set. If a consumer ever populates both ptr and device_ptr (the handle struct is public in the C header), this can lead to deleting device_ptr twice (once via ptr path and once via the explicit device_ptr delete). Delete env->ptr and env->device_ptr independently without routing through the selector helper.

Copilot · 2026-03-31T19:55:47Z

include/gauxc/c/hdf5.h

+#include <gauxc/c/gauxc_config.h>
+#ifdef GAUXC_HAS_HDF5
+#include <gauxc/c/status.h>
+#include <gauxc/c/basisset.h>
+#include <gauxc/c/molecule.h>
+


This header is missing an include guard (#pragma once or #ifndef/#define). Without it, including gauxc/c/hdf5.h from multiple translation units (or indirectly via other headers) can cause duplicate declaration / redefinition issues depending on build settings. Please add #pragma once (consistent with the other C headers).

Copilot · 2026-03-31T19:55:47Z

src/external/c_hdf5_write.cxx

+void gauxc_molecule_write_hdf5_record(
+  GauXCStatus* status,
+  GauXCMolecule mol,
+  const char* fname,
+  const char* dset
+) {
+  detail::gauxc_status_init(status);
+  try {
+    write_hdf5_record( *detail::get_molecule_ptr(mol), std::string(fname), std::string(dset) );
+  } catch(std::exception& e) {
+    detail::gauxc_status_handle(status, 1, e.what());


These HDF5 C-API functions dereference the internal mol.ptr/basis.ptr and construct std::string(fname) / std::string(dset) without validating inputs. Passing a default/invalid handle or a null fname/dset will crash/UB rather than setting status. Please add explicit null checks and fail via gauxc_status_handle before dereferencing or constructing strings.

Copilot · 2026-03-31T19:55:47Z

src/external/c_hdf5_read.cxx

+void gauxc_molecule_read_hdf5_record(
+  GauXCStatus* status,
+  GauXCMolecule mol,
+  const char* fname,
+  const char* dset
+) {
+  detail::gauxc_status_init(status);
+  try {
+    read_hdf5_record( *detail::get_molecule_ptr(mol), std::string(fname), std::string(dset) );
+  } catch(std::exception& e) {
+    detail::gauxc_status_handle(status, 1, e.what());


These HDF5 C-API functions dereference the internal mol.ptr/basis.ptr and construct std::string(fname) / std::string(dset) without validating inputs. Passing a default/invalid handle or a null fname/dset will crash/UB rather than setting status. Please add explicit null checks and fail via gauxc_status_handle before dereferencing or constructing strings.

Copilot · 2026-03-31T19:55:47Z

include/gauxc/c/molecule.h

+ * @param atoms Pointer to an array of GauXCAtom.
+ * @param natoms Number of atoms in the array.
+ * @return Handle to the created Molecule.
+ */
+extern GauXCMolecule gauxc_molecule_new_from_atoms(GauXCStatus* status, GauXCAtom* atoms, size_t natoms );


gauxc_molecule_new_from_atoms does not modify the atoms array, but the API takes a non-const GauXCAtom*. Consider making this const GauXCAtom* (and updating the implementation signature) to better express ownership/immutability and allow callers to pass const data.

Suggested change

* @param atoms Pointer to an array of GauXCAtom.

* @param natoms Number of atoms in the array.

* @return Handle to the created Molecule.

*/

extern GauXCMolecule gauxc_molecule_new_from_atoms(GauXCStatus* status, GauXCAtom* atoms, size_t natoms );

* @param atoms Pointer to an array of GauXCAtom (not modified).

* @param natoms Number of atoms in the array.

* @return Handle to the created Molecule.

*/

extern GauXCMolecule gauxc_molecule_new_from_atoms(GauXCStatus* status, const GauXCAtom* atoms, size_t natoms );

Copilot · 2026-03-31T19:55:48Z

include/gauxc/c/basisset.h

+ */
+extern GauXCBasisSet gauxc_basisset_new_from_shells(
+   GauXCStatus* status,
+   GauXCShell* shells,


gauxc_basisset_new_from_shells does not modify the shells array, but the API takes a non-const GauXCShell*. Consider making this const GauXCShell* (and updating the implementation signature) to improve const-correctness for C callers.

Suggested change

GauXCShell* shells,

const GauXCShell* shells,

awvwgk self-assigned this Jan 19, 2026

awvwgk force-pushed the c-api branch 3 times, most recently from dd396c2 to 5881a76 Compare January 26, 2026 09:54

awvwgk mentioned this pull request Jan 26, 2026

Add guide for using GauXC from C and Fortran microsoft/skala#23

Merged

awvwgk force-pushed the c-api branch 3 times, most recently from 1d61b38 to 83841ad Compare January 27, 2026 10:05

awvwgk changed the title ~~[WIP] Basic C API for GauXC~~ Basic C API for GauXC Jan 27, 2026

awvwgk requested review from Copilot and wavefunction91 January 27, 2026 10:59

awvwgk added the enhancement New feature or request label Jan 27, 2026

Copilot started reviewing on behalf of awvwgk January 27, 2026 11:00 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

awvwgk force-pushed the c-api branch from f006bbd to 16abe8f Compare January 28, 2026 13:43

awvwgk added the C API Related to the C API label Jan 28, 2026

awvwgk requested a review from Copilot January 29, 2026 07:46

Copilot started reviewing on behalf of awvwgk January 29, 2026 07:46 View session

Copilot AI reviewed Jan 29, 2026

View reviewed changes

awvwgk force-pushed the c-api branch from 16abe8f to 1c87794 Compare January 30, 2026 13:36

Fix check for number of primitives

ff16199

awvwgk force-pushed the c-api branch from cf0bb8a to ff16199 Compare February 6, 2026 14:24

wavefunction91 requested changes Feb 6, 2026

View reviewed changes

wavefunction91 requested a review from Copilot February 6, 2026 22:55

Copilot started reviewing on behalf of wavefunction91 February 6, 2026 22:55 View session

Copilot AI reviewed Feb 6, 2026

View reviewed changes

awvwgk added 3 commits February 11, 2026 15:51

Move C API to separate directory

a7d430e

Restructure C API

07b1eb1

- remove matrix class - directly expose ReplicatedXCIntegrator API

Merge remote-tracking branch 'upstream/master' into c-api

407ff08

awvwgk requested a review from wavefunction91 February 23, 2026 10:52

awvwgk force-pushed the c-api branch 2 times, most recently from 4c63cdc to 4d683b7 Compare March 2, 2026 16:31

Move C headers

30267be

awvwgk force-pushed the c-api branch from 4d683b7 to 30267be Compare March 2, 2026 16:37

wavefunction91 requested a review from Copilot March 31, 2026 19:49

Copilot started reviewing on behalf of wavefunction91 March 31, 2026 19:49 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

Conversation

awvwgk commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

awvwgk commented Jan 19, 2026 •

edited

Loading