Runtime environment

This section provides a reference for the runtime environment in GauXC, including C++ class definitions, C bindings, and Fortran bindings for creating and managing runtime environments used in GauXC computations. The runtime environment encapsulates information about the MPI communicator and device configuration for GauXC computations.

C++ definitions

class GauXC::RuntimeEnvironment

A class representing the runtime environment for GauXC computations, including information about the MPI communicator and device configuration.

RuntimeEnvironment(MPI_Comm comm)

Construct a RuntimeEnvironment object with the specified MPI communicator.

Important

Signature changes if GAUXC_HAS_MPI is defined and GAUXC_ENABLE_MPI is enabled.

Parameters:

comm – The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC.

int comm_rank() const

Get the rank of the current process in the MPI communicator associated with this runtime environment.

Returns:

The rank of the current process in the MPI communicator.

int comm_size() const

Get the size of the MPI communicator associated with this runtime environment.

Returns:

The size of the MPI communicator.

DeviceRuntimeEnvironment as_device_runtime() const

Convert the current runtime environment to a device runtime environment.

class GauXC::DeviceRuntimeEnvironment : public RuntimeEnvironment

A class representing a device runtime environment for GauXC computations, including information about the device configuration and memory usage.

DeviceRuntimeEnvironment(MPI_Comm comm, double fill_fraction)

Construct a DeviceRuntimeEnvironment object with the specified MPI communicator and device memory fill fraction.

Important

Signature changes if GAUXC_HAS_MPI is defined and GAUXC_ENABLE_MPI is enabled.

Parameters:

• comm – The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC.

• fill_fraction – The fraction of the device memory to be used for GauXC computations (between 0 and 1).

DeviceRuntimeEnvironment(MPI_Comm comm, void *mem, size_t mem_size)

Construct a DeviceRuntimeEnvironment object with the specified MPI communicator and user-provided memory.

Important

Signature changes if GAUXC_HAS_MPI is defined and GAUXC_ENABLE_MPI is enabled.

Parameters:

• comm – The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC.

• mem – Pointer to the user-provided memory to be used for GauXC computations.

• mem_size – The size of the user-provided memory in bytes.

void *device_memory() const

Get a pointer to the device memory associated with this runtime environment.

Returns:

A pointer to the device memory associated with this runtime environment.

size_t device_memory_size() const

Get the size of the device memory associated with this runtime environment in bytes.

Returns:

The size of the device memory associated with this runtime environment in bytes.

bool owns_memory() const

Check if this runtime environment owns the device memory.

Returns:

True if this runtime environment owns the device memory, false otherwise.

void release_buffer()

Release the device memory buffer associated with this runtime environment, if it is owned by this runtime environment.

void set_buffer(void *mem, size_t mem_size)

Set the device memory buffer for this runtime environment to the specified user-provided memory.

Parameters:

• mem – Pointer to the user-provided memory to be used for GauXC computations.

• mem_size – The size of the user-provided memory in bytes.

C bindings

struct GauXCRuntimeEnvironment

Opaque struct representing the runtime environment in the GauXC C API.

GauXCRuntimeEnvironment gauxc_runtime_environment_new(GauXCStatus *status, MPI_Comm comm)

Create a new GauXCRuntimeEnvironment object.

Important

Signature changes if GAUXC_HAS_MPI is defined and GAUXC_ENABLE_MPI is enabled.

Parameters:

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

• comm – The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC.

Returns:

A new GauXCRuntimeEnvironment object.

GauXCRuntimeEnvironment gauxc_device_runtime_environment_new(GauXCStatus *status, MPI_Comm comm, double fill_fraction)

Create a new GauXCRuntimeEnvironment object for a specific device.

Important

Signature changes if GAUXC_HAS_MPI is defined and GAUXC_ENABLE_MPI is enabled.

Parameters:

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

• comm – The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC.

• fill_fraction – The fraction of the device memory to be used for GauXC computations (between 0 and 1).

Returns:

A new GauXCRuntimeEnvironment object for the specified device.

GauXCRuntimeEnvironment gauxc_runtime_environment_new_mem(GauXCStatus *status, MPI_Comm comm, void *mem, size_t mem_size)

Create a new GauXCRuntimeEnvironment object using user-provided memory.

Important

Signature changes if GAUXC_HAS_MPI is defined and GAUXC_ENABLE_MPI is enabled.

Parameters:

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

• comm – The MPI communicator to be used for GauXC computations. Only possible to pass if MPI support is enabled in GauXC.

• mem – Pointer to the user-provided memory to be used for GauXC computations.

• mem_size – The size of the user-provided memory in bytes.

Returns:

A new GauXCRuntimeEnvironment object using the provided memory.

int gauxc_runtime_environment_comm_rank(GauXCStatus *status, GauXCRuntimeEnvironment env)

Get the rank of the current process in the MPI communicator associated with the GauXCRuntimeEnvironment. Returns 0 if MPI support is not enabled in GauXC.

Parameters:

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

• env – The GauXCRuntimeEnvironment object for which to get the MPI rank.

Returns:

The rank of the current process in the MPI communicator.

int gauxc_runtime_environment_comm_size(GauXCStatus *status, GauXCRuntimeEnvironment env)

Get the size of the MPI communicator associated with the GauXCRuntimeEnvironment. Returns 1 if MPI support is not enabled in GauXC.

Parameters:

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

• env – The GauXCRuntimeEnvironment object for which to get the MPI size.

Returns:

The size of the MPI communicator.

void gauxc_runtime_environment_delete(GauXCStatus *status, GauXCRuntimeEnvironment *env)

Delete a GauXCRuntimeEnvironment object.

Parameters:

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

• env – Pointer to the GauXCRuntimeEnvironment object to be deleted.

Fortran bindings

type  gauxc_runtime_environment_type

Opaque type representing the runtime environment in the GauXC Fortran API. Available in the module gauxc_runtime_environment.

function  gauxc_runtime_environment_new(status)

Create a new GauXCRuntimeEnvironment object. If MPI support is enabled in GauXC, this function creates a runtime environment with the default MPI communicator (MPI_COMM_WORLD). Part of the gauxc_runtime_environment_new() interface.

Parameters:

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

Return:

type (gauxc_runtime_environment_type) :: A new GauXCRuntimeEnvironment object.

function  gauxc_runtime_environment_new_mpi(status, comm)

Create a new GauXCRuntimeEnvironment object. This function is only available if MPI support is enabled in GauXC and allows specifying the MPI communicator to be used for GauXC computations. Part of the gauxc_runtime_environment_new() interface.

Parameters:

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

• comm [integer] :: The MPI communicator to be used for GauXC computations.

Return:

type (gauxc_runtime_environment_type) :: A new GauXCRuntimeEnvironment object.

function  gauxc_runtime_environment_new_mpi_f08(status, comm)

Create a new GauXCRuntimeEnvironment object. This function is only available if MPI support is enabled in GauXC and allows specifying the MPI communicator to be used for GauXC computations. Part of the gauxc_runtime_environment_new() interface.

Parameters:

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

• comm [type(MPI_Comm)] :: The MPI communicator to be used for GauXC computations.

Return:

type (gauxc_runtime_environment_type) :: A new GauXCRuntimeEnvironment object.

function  gauxc_device_runtime_environment_new(status, fill_fraction)

Create a new GauXCRuntimeEnvironment object for a specific device. If MPI support is enabled in GauXC, this function creates a runtime environment with the default MPI communicator (MPI_COMM_WORLD). This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the fraction of the device memory to be used for GauXC computations. Part of the gauxc_device_runtime_environment_new() interface.

Parameters:

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

• comm [integer] :: The MPI communicator to be used for GauXC computations.

• fill_fraction [real(c_double)] :: The fraction of the device memory to be used for GauXC computations (between 0 and 1).

Return:

type (gauxc_runtime_environment_type) :: A new GauXCRuntimeEnvironment object for the specified device.

function  gauxc_device_runtime_environment_new_mpi(status, comm, fill_fraction)

Create a new GauXCRuntimeEnvironment object for a specific device. This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the MPI communicator and the fraction of the device memory to be used for GauXC computations. Part of the gauxc_device_runtime_environment_new() interface.

Parameters:

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

• comm [integer] :: The MPI communicator to be used for GauXC computations.

• fill_fraction [real(c_double)] :: The fraction of the device memory to be used for GauXC computations (between 0 and 1).

Return:

type (gauxc_runtime_environment_type) :: A new GauXCRuntimeEnvironment object for the specified device.

function  gauxc_device_runtime_environment_new_mpi_f08(status, comm, fill_fraction)

Create a new GauXCRuntimeEnvironment object for a specific device. This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the MPI communicator and the fraction of the device memory to be used for GauXC computations. Part of the gauxc_device_runtime_environment_new() interface.

Parameters:

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

• comm [type(MPI_Comm)] :: The MPI communicator to be used for GauXC computations.

• fill_fraction [real(c_double)] :: The fraction of the device memory to be used for GauXC computations (between 0 and 1).

Return:

type (gauxc_runtime_environment_type) :: A new GauXCRuntimeEnvironment object for the specified device.

function  gauxc_device_runtime_environment_new_mem(status, mem, mem_size)

Create a new GauXCRuntimeEnvironment object using user-provided memory. If MPI support is enabled in GauXC, this function creates a runtime environment with the default MPI communicator (MPI_COMM_WORLD). This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the user-provided memory to be used for GauXC computations. Part of the gauxc_device_runtime_environment_new() interface.

Parameters:

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

• mem [type(c_ptr)] :: Pointer to the user-provided memory to be used for GauXC computations.

• mem_size [integer(c_size_t)] :: The size of the user-provided memory in bytes.

Return:

type (gauxc_runtime_environment_type) :: A new GauXCRuntimeEnvironment object using the provided memory.

function  gauxc_device_runtime_environment_new_mem_mpi(status, comm, mem, mem_size)

Create a new GauXCRuntimeEnvironment object using user-provided memory. This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the MPI communicator and the user-provided memory to be used for GauXC computations. Part of the gauxc_device_runtime_environment_new() interface.

Parameters:

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

• comm [integer] :: The MPI communicator to be used for GauXC computations.

• mem [type(c_ptr)] :: Pointer to the user-provided memory to be used for GauXC computations.

• mem_size [integer(c_size_t)] :: The size of the user-provided memory in bytes.

Return:

type (gauxc_runtime_environment_type) :: A new GauXCRuntimeEnvironment object using the provided memory.

function  gauxc_device_runtime_environment_new_mem_mpi_f08(status, comm, mem, mem_size)

Create a new GauXCRuntimeEnvironment object using user-provided memory. This function is only available if device support (CUDA or HIP) is enabled in GauXC and allows specifying the MPI communicator and the user-provided memory to be used for GauXC computations. Part of the gauxc_device_runtime_environment_new() interface.

Parameters:

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

• comm [type(MPI_Comm)] :: The MPI communicator to be used for GauXC computations.

• mem [type(c_ptr)] :: Pointer to the user-provided memory to be used for GauXC computations.

• mem_size [integer(c_size_t)] :: The size of the user-provided memory in bytes.

Return:

type (gauxc_runtime_environment_type) :: A new GauXCRuntimeEnvironment object using the provided memory.

function  gauxc_runtime_environment_delete(status, env)

Delete a GauXCRuntimeEnvironment object. Part of the gauxc_delete() interface.

Parameters:

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

• env [type(gauxc_runtime_environment_type)] :: The GauXCRuntimeEnvironment object to be deleted.