GauXC Basis Set API

GauXC Basis Set API#

This section provides a reference for the GauXC basis set API, including C++ class definitions, C struct definitions, and Fortran derived type definitions for representing basis sets and shells in GauXC.

C++ definitions#

template<typename F>
struct GauXC::BasisSet : public std::vector<Shell<F>>#

A class to represent a collection of shells in a basis set.

inline BasisSet(std::vector<Shell<F>> shells)#

Construct a BasisSet object from a vector of Shell objects.

Parameters:

shells – A vector of Shell objects representing the shells in the basis set.

Returns:

A BasisSet object initialized with the given shells.

inline int32_t nshells() const#

Get the number of shells in the basis set.

Returns:

The number of shells in the basis set.

inline int32_t nbf() const#

Get the total number of basis functions in the basis set, calculated as the sum of the sizes of all shells.

Returns:

The total number of basis functions in the basis set.

template<typename F>
class GauXC::Shell#

A class to represent a shell in a basis set, containing its angular momentum and a vector of primitives.

using prim_array = std::array<F, 32>#

A type to represent an array of primitive exponents or coefficients in a shell.

using cart_array = std::array<double, 3>#

A type to represent an array of Cartesian coordinates for the center of a shell.

PrimSize nprim_#

The number of primitives in the shell.

AngularMomentum l_#

The angular momentum of the shell.

SphericalType pure_#

Whether the shell is pure (spherical) or Cartesian.

prim_array alpha_#

The exponents of the primitives in the shell.

prim_array coeff_#

The coefficients of the primitives in the shell.

cart_array O_#

The Cartesian coordinates of the center of the shell.

double cutoff_radius_#

The cutoff radius of the shell, defined as the maximum distance from the center of the shell at which the primitives have non-negligible contributions.

double tolerance_#

The tolerance for pruning primitives in the shell. Primitives with coefficients below this value will be pruned. The default value is 1e-10.

inline void set_shell_tolerance(double tol)#

Set the tolerance for pruning primitives in the shell. The default value for the tolerance is 1e-10.

Parameters:

tol – The tolerance for pruning primitives. Primitives with coefficients below this value will be pruned.

inline PrimSize nprim() const#

Get the number of primitives in the shell.

Returns:

The number of primitives in the shell.

inline AngularMomentum l() const#

Get the angular momentum of the shell.

Returns:

The angular momentum of the shell.

inline SphericalType pure() const#

Get whether the shell is pure (spherical) or Cartesian.

Returns:

1 if the shell is pure (spherical), 0 if the shell is Cartesian.

inline const F *alpha_data() const#

Get a pointer to the exponents of the primitives in the shell.

Returns:

A pointer to the exponents of the primitives in the shell.

inline const F *coeff_data() const#

Get a pointer to the coefficients of the primitives in the shell.

Returns:

A pointer to the coefficients of the primitives in the shell.

inline const double *O_data() const#

Get a pointer to the Cartesian coordinates of the center of the shell.

Returns:

A pointer to the Cartesian coordinates of the center of the shell.

inline double cutoff_radius() const#

Get the cutoff radius of the shell, defined as the maximum distance from the center of the shell at which the primitives have non-negligible contributions.

Returns:

The cutoff radius of the shell.

inline int32_t cart_size() const#

Get the number of Cartesian functions in the shell.

Returns:

The number of Cartesian functions in the shell.

inline int32_t pure_size() const#

Get the number of pure (spherical) functions in the shell.

Returns:

The number of pure (spherical) functions in the shell.

inline int32_t size() const#

Get the total number of functions in the shell, based on whether the shell is pure (spherical) or Cartesian.

Returns:

The total number of functions in the shell.

inline prim_array &alpha() const#

Get the exponents of the primitives in the shell as an array.

Returns:

An array containing the exponents of the primitives in the shell.

inline prim_array &coeff() const#

Get the coefficients of the primitives in the shell as an array.

Returns:

An array containing the coefficients of the primitives in the shell.

inline cart_array &O() const#

Get the Cartesian coordinates of the center of the shell as an array.

Returns:

An array containing the Cartesian coordinates of the center of the shell.

inline prim_array &alpha()#

Get the exponents of the primitives in the shell as a mutable array.

Returns:

A mutable array containing the exponents of the primitives in the shell.

inline prim_array &coeff()#

Get the coefficients of the primitives in the shell as a mutable array.

Returns:

A mutable array containing the coefficients of the primitives in the shell.

inline cart_array &O()#

Get the Cartesian coordinates of the center of the shell as a mutable array.

Returns:

A mutable array containing the Cartesian coordinates of the center of the shell.

inline void set_pure(bool pure)#

Set whether the shell is pure (spherical) or Cartesian.

Parameters:

pure – 1 to set the shell as pure (spherical), 0 to set the shell as Cartesian.

inline bool operator==(const Shell &other) const#

Compare this shell with another shell for equality.

Parameters:

other – Another shell to compare with.

Returns:

True if this shell is equal to the other shell, false otherwise.

using PrimSize = int32_t#

A type to represent the number of primitives in a shell.

using AngularMomentum = int32_t#

A type to represent the angular momentum of a shell.

using SphericalType = int32_t#

A type to represent whether a shell is pure (spherical) or Cartesian. 1 indicates a pure (spherical) shell, while 0 indicates a Cartesian shell.

C bindings#

struct GauXCBasisSet#

An opaque struct to represent a basis set in the C API.

GauXCBasisSet gauxc_basisset_new(GauXCStatus *status)#

Create a new GauXCBasisSet object.

Parameters:

  • status – A pointer to a GauXCStatus variable to store the status of the operation.

Returns:

A new GauXCBasisSet object.

GauXCBasisSet gauxc_basisset_new_from_shells(GauXCStatus *status, const GauXCShell *shells, int32_t nshells, bool normalize)#

Create a new GauXCBasisSet object from an array of GauXCShell objects.

Parameters:

  • status – A pointer to a GauXCStatus variable to store the status of the operation.

  • shells – A pointer to an array of GauXCShell objects representing the shells in the basis set.

  • nshells – The number of shells in the array.

  • normalize – Whether to normalize the primitives in the shells when creating the basis set.

Returns:

A new GauXCBasisSet object initialized with the given shells.

void gauxc_basisset_delete(GauXCStatus *status, GauXCBasisSet *basis)#

Delete a GauXCBasisSet object and free its associated memory.

Parameters:

  • status – A pointer to a GauXCStatus variable to store the status of the operation.

  • basis – A pointer to the GauXCBasisSet object to be deleted.

struct GauXCShell#

Representation of a shell in a basis set for the C API, containing its angular momentum, number of primitives, and pointers to arrays of primitive exponents, coefficients, and Cartesian coordinates.

int32_t l#

The angular momentum of the shell.

bool pure#

Whether the shell is pure (spherical) or Cartesian.

int32_t nprim#

The number of primitives in the shell.

double alpha[32]#

An array of exponents of the primitives in the shell.

double coeff[32]#

An array of coefficients of the primitives in the shell.

double O[3]#

An array of Cartesian coordinates for the center of the shell.

double shell_tolerance#

The tolerance for pruning primitives in the shell. Primitives with coefficients below this value will be pruned. The default value is 1e-10.

Fortran bindings#

type  gauxc_basisset_type#

Opaque type representing a basis set in the GauXC Fortran API. Available from gauxc_basisset.

function  gauxc_basisset_new(status)#

Create a new gauxc_basisset_type object.

Parameters:

status [type(gauxc_status_type)] :: A variable to store the status of the operation.

Return:

type (gauxc_basisset_type) :: A new gauxc_basisset_type object.

function  gauxc_basisset_new_from_shells(status, shells, nshells, normalize)#

Create a new gauxc_basisset_type object from an array of gauxc_shell_type objects.

Parameters:

  • status [type(gauxc_status_type)] :: A variable to store the status of the operation.

  • shells (*) [type(gauxc_shell_type)] :: An array of gauxc_shell_type objects representing the shells in the basis set.

  • nshells [integer(c_int32_t)] :: The number of shells in the array.

  • normalize [logical(c_bool)] :: Whether to normalize the primitives in the shells when creating the basis set.

Return:

type (gauxc_basisset_type) :: A new gauxc_basisset_type object initialized with the given shells.

function  gauxc_basisset_delete(status, basis)#

Delete a gauxc_basisset_type object and free its associated memory. Part of the gauxc_delete() interface.

Parameters:

  • status [type(gauxc_status_type)] :: A variable to store the status of the operation.

  • basis [type(gauxc_basisset_type)] :: The gauxc_basisset_type object to be deleted.

type  gauxc_shell_type#

A derived type representing a shell in the GauXC Fortran API, containing its angular momentum, number of primitives, and arrays of primitive exponents, coefficients, and Cartesian coordinates.

Type fields:

  • % l [integer(c_int32_t)] :: The angular momentum of the shell.

  • % pure [logical(c_bool)] :: Whether the shell is pure (spherical) or Cartesian.

  • % nprim [integer(c_int32_t)] :: The number of primitives in the shell.

  • % alpha (32) [real(c_double)] :: An array of exponents of the primitives in the shell.

  • % coeff (32) [real(c_double)] :: An array of coefficients of the primitives in the shell.

  • % O (3) [real(c_double)] :: An array of Cartesian coordinates for the center of the shell.

  • % shell_tolerance [real(c_double)] :: The tolerance for pruning primitives in the shell. Primitives with coefficients below this value will be pruned. The default value is 1e-10.

Serialization to HDF5#

If GauXC has been built with HDF5 support GAUXC_HAS_HDF5, the GauXC::BasisSet class can be serialized to and deserialized from HDF5 files using the provided HDF5 interface. This allows for easy storage and retrieval of basis set data in a standardized format.

void GauXC::write_hdf5_record(const BasisSet &basis, const std::string &filename, const std::string &group_name)#

Write a BasisSet object to an HDF5 file.

Parameters:

  • basis – The BasisSet object to be written to the file.

  • filename – The name of the HDF5 file to write to.

  • group_name – The name of the group in the HDF5 file where the basis set data will be stored.

void GauXC::read_hdf5_record(BasisSet &basis, const std::string &filename, const std::string &group_name)#

Read a BasisSet object from an HDF5 file.

Parameters:

  • basis – The BasisSet object to be populated with the data read from the file.

  • filename – The name of the HDF5 file to read from.

  • group_name – The name of the group in the HDF5 file where the basis set data is stored.

The same functions are available in the GauXC C API.

void gauxc_basisset_write_hdf5_record(GauXCBasisSet basis, const char *filename, const char *group_name)#

Write a GauXCBasisSet object to an HDF5 file in C.

Parameters:

  • basis – The GauXCBasisSet object to be written to the file.

  • filename – The name of the HDF5 file to write to.

  • group_name – The name of the group in the HDF5 file where the basis set data will be stored.

void gauxc_basisset_read_hdf5_record(GauXCBasisSet basis, const char *filename, const char *group_name)#

Read a GauXCBasisSet object from an HDF5 file in C.

Parameters:

  • basis – The GauXCBasisSet object to be populated with the data read from the file.

  • filename – The name of the HDF5 file to read from.

  • group_name – The name of the group in the HDF5 file where the basis set data is stored.

The same functions are also available in the GauXC Fortran API, available from the module gauxc_external_hdf5.

subroutine  gauxc_basisset_write_hdf5_record(basis, filename, group_name)#

Write a gauxc_basisset_type object to an HDF5 file in Fortran.

Parameters:

  • basis [type(gauxc_basisset_type)] :: The gauxc_basisset_type object to be written to the file.

  • filename [character(len=*)] :: The name of the HDF5 file to write to.

  • group_name [character(len=*)] :: The name of the group in the HDF5 file where the basis set data will be stored.

subroutine  gauxc_basisset_read_hdf5_record(basis, filename, group_name)#

Read a gauxc_basisset_type object from an HDF5 file in Fortran.

Parameters:

  • basis [type(gauxc_basisset_type)] :: The gauxc_basisset_type object to be populated with the data read from the file.

  • filename [character(len=*)] :: The name of the HDF5 file to read from.

  • group_name [character(len=*)] :: The name of the group in the HDF5 file where the basis set data is stored.

Orbital Ordering Convention#

The orbital ordering convention for the shells in GauXC is following the common component architecture (CCA) convention for pure (spherical) shells and the row convention for cartesian ones. The CCA ordering for pure (spherical) shells is defined as

  • s (\(\ell = 0\)): \(Y_0^0\)

  • p (\(\ell = 1\)): \(Y_1^{-1}\), \(Y_1^{0}\), \(Y_1^{+1}\),

  • d (\(\ell = 2\)): \(Y_2^{-2}\), \(Y_2^{-1}\), \(Y_2^{0}\), \(Y_2^{+1}\), \(Y_2^{+2}\)

The row ordering for cartesian shells is defined as

  • s (\(\ell = 0\)): 1

  • p (\(\ell = 1\)): x, y, z

  • d (\(\ell = 2\)): xx, xy, xz, yy, yz, zz

  • f (\(\ell = 3\)): xxx, xxy, xxz, xyy, xyz, xzz, yyy, yyz, yzz, zzz

Contents