Unified interface for AMGX operations with both CPU and GPU data structures. More...

#include <AmgxInterface.hpp>

Static Public Member Functions
static void	initialize ()
	Initialize the AMGX library. More...

static void	finalize ()
	Finalize the AMGX library. More...

static AMGX_config_handle	createConfig (const std::string &config_string)
	Create an AMGX config handle from a configuration string. More...

static AMGX_resources_handle	createResources (AMGX_config_handle config)
	Create AMGX resources from a config. More...

static AMGX_solver_handle	createSolver (AMGX_resources_handle resources, AMGX_Mode mode, AMGX_config_handle config)
	Create an AMGX solver. More...

static AMGX_matrix_handle	createMatrix (AMGX_resources_handle resources, AMGX_Mode mode)
	Create an AMGX matrix. More...

static AMGX_vector_handle	createVector (AMGX_resources_handle resources, AMGX_Mode mode)
	Create an AMGX vector. More...

static void	destroyConfig (AMGX_config_handle config)
	Destroy an AMGX config handle. More...

static void	destroyResources (AMGX_resources_handle resources)
	Destroy an AMGX resources handle. More...

static void	destroySolver (AMGX_solver_handle solver)
	Destroy an AMGX solver handle. More...

template<typename MatrixType >
static void	destroyMatrix (AMGX_matrix_handle amgx_matrix, const MatrixType &matrix)
	Destroy an AMGX matrix handle. More...

static void	destroyVector (AMGX_vector_handle vector)
	Destroy an AMGX vector handle. More...

template<typename T >
static void	updateAmgxFromGpuVector (const GpuVector< T > &gpu_vec, AMGX_vector_handle amgx_vec)
	Update an AMGX vector from a GpuVector (device-to-device transfer) More...

template<typename T >
static void	updateGpuVectorFromAmgx (AMGX_vector_handle amgx_vec, GpuVector< T > &gpu_vec)
	Update a GpuVector from an AMGX vector (device-to-device transfer) More...

template<typename VectorType >
static void	transferVectorToAmgx (const VectorType &vec, AMGX_vector_handle amgx_vec)
	Transfer vector to AMGX from any vector type (CPU or GPU) More...

template<typename VectorType >
static void	transferVectorFromAmgx (AMGX_vector_handle amgx_vec, VectorType &vec)
	Transfer vector from AMGX to any vector type (CPU or GPU) More...

template<typename T >
static void	updateAmgxMatrixFromGpuSparseMatrix (const GpuSparseMatrix< T > &gpuSparseMatrix, AMGX_matrix_handle amgxMatrix)
	Update an AMGX matrix from a GpuSparseMatrix (device-to-device transfer) More...

template<typename T >
static void	updateAmgxMatrixCoefficientsFromGpuSparseMatrix (const GpuSparseMatrix< T > &gpuSparseMatrix, AMGX_matrix_handle amgxMatrix)
	Update only the coefficient values of an AMGX matrix from a GpuSparseMatrix. More...

template<typename T >
static void	updateGpuSparseMatrixFromAmgxMatrix (AMGX_matrix_handle amgxMatrix, GpuSparseMatrix< T > &gpuSparseMatrix)
	Update a GpuSparseMatrix from an AMGX matrix (device-to-device transfer) More...

template<typename MatrixType >
static void	initializeMatrix (const MatrixType &matrix, AMGX_matrix_handle amgx_matrix)
	Initialize an AMGX matrix from any matrix type (CPU or GPU) More...

static void	initializeVector (int N, int block_size, AMGX_vector_handle amgx_vector)
	Initialize an AMGX vector with zeros. More...

template<typename MatrixType >
static void	updateMatrixValues (const MatrixType &matrix, AMGX_matrix_handle amgx_matrix)
	Update matrix values in AMGX. More...

template<typename MatrixFieldType , typename VectorFieldType >
static AMGX_Mode	determineAmgxMode ()
	Determine the appropriate AMGX mode based on matrix and vector field types. More...

Detailed Description

Unified interface for AMGX operations with both CPU and GPU data structures.

This class provides utilities for working with AMGX resources and transferring data between CPU/GPU data structures and AMGX handles. It handles type detection and automatically chooses the most efficient transfer method:

For GPU types: Device-to-device transfers
For CPU types: Host-to-device transfers with memory pinning

Note: Error handling: All methods throw AmgxError exceptions when AMGX operations fail.

Member Function Documentation

◆ createConfig()

static AMGX_config_handle Opm::gpuistl::AmgxInterface::createConfig ( const std::string & config_string )

inlinestatic

Create an AMGX config handle from a configuration string.

Parameters

config_string Configuration string for AMGX

Returns: AMGX_config_handle The created config handle

Exceptions

AmgxError if config creation fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::AmgxPreconditioner().

◆ createMatrix()

static AMGX_matrix_handle Opm::gpuistl::AmgxInterface::createMatrix	(	AMGX_resources_handle	resources,
		AMGX_Mode	mode
	)

inlinestatic

Create an AMGX matrix.

Parameters

resources	AMGX resources handle
mode	AMGX mode (precision configuration)

Returns: AMGX_matrix_handle The created matrix handle

Exceptions

AmgxError if matrix creation fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::AmgxPreconditioner().

◆ createResources()

static AMGX_resources_handle Opm::gpuistl::AmgxInterface::createResources ( AMGX_config_handle config )

inlinestatic

Create AMGX resources from a config.

Parameters

config The AMGX config handle

Returns: AMGX_resources_handle The created resources handle

Exceptions

AmgxError if resource creation fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::AmgxPreconditioner().

◆ createSolver()

static AMGX_solver_handle Opm::gpuistl::AmgxInterface::createSolver	(	AMGX_resources_handle	resources,
		AMGX_Mode	mode,
		AMGX_config_handle	config
	)

inlinestatic

Create an AMGX solver.

Parameters

resources	AMGX resources handle
mode	AMGX mode (precision configuration)
config	AMGX config handle

Returns: AMGX_solver_handle The created solver handle

Exceptions

AmgxError if solver creation fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::AmgxPreconditioner().

◆ createVector()

static AMGX_vector_handle Opm::gpuistl::AmgxInterface::createVector	(	AMGX_resources_handle	resources,
		AMGX_Mode	mode
	)

inlinestatic

Create an AMGX vector.

Parameters

resources	AMGX resources handle
mode	AMGX mode (precision configuration)

Returns: AMGX_vector_handle The created vector handle

Exceptions

AmgxError if vector creation fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::AmgxPreconditioner().

◆ destroyConfig()

static void Opm::gpuistl::AmgxInterface::destroyConfig ( AMGX_config_handle config )

inlinestatic

Destroy an AMGX config handle.

Parameters

config The config handle to destroy

Exceptions

AmgxError if config destruction fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::~AmgxPreconditioner().

◆ destroyMatrix()

template<typename MatrixType >

static void Opm::gpuistl::AmgxInterface::destroyMatrix	(	AMGX_matrix_handle	amgx_matrix,
		const MatrixType &	matrix
	)

inlinestatic

Destroy an AMGX matrix handle.

Parameters

amgx_matrix	The matrix handle to destroy
matrix	The type of the matrix

Exceptions

AmgxError if matrix destruction fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::~AmgxPreconditioner().

◆ destroyResources()

static void Opm::gpuistl::AmgxInterface::destroyResources ( AMGX_resources_handle resources )

inlinestatic

Destroy an AMGX resources handle.

Parameters

resources The resources handle to destroy

Exceptions

AmgxError if resource destruction fails

Note: There is a known issue where destroying resources and then reinitializing AMGX can cause crashes in some versions of the library. If you encounter this issue, consider keeping the resources alive for the entire program lifetime.

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::~AmgxPreconditioner().

◆ destroySolver()

static void Opm::gpuistl::AmgxInterface::destroySolver ( AMGX_solver_handle solver )

inlinestatic

Destroy an AMGX solver handle.

Parameters

solver The solver handle to destroy

Exceptions

AmgxError if solver destruction fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::~AmgxPreconditioner().

◆ destroyVector()

static void Opm::gpuistl::AmgxInterface::destroyVector ( AMGX_vector_handle vector )

inlinestatic

Destroy an AMGX vector handle.

Parameters

vector The vector handle to destroy

Exceptions

AmgxError if vector destruction fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::~AmgxPreconditioner().

◆ determineAmgxMode()

template<typename MatrixFieldType , typename VectorFieldType >

static AMGX_Mode Opm::gpuistl::AmgxInterface::determineAmgxMode ( )

inlinestatic

Determine the appropriate AMGX mode based on matrix and vector field types.

Template Parameters

MatrixFieldType	The field type of the matrix
VectorFieldType	The field type of the vector

Returns: AMGX_Mode The appropriate AMGX mode

Exceptions

std::runtime_error if the type combination is not supported

◆ finalize()

static void Opm::gpuistl::AmgxInterface::finalize ( )

inlinestatic

Finalize the AMGX library.

This should be called once at the end of the program to release AMGX resources.

Exceptions

AmgxError if finalization fails

References OPM_AMGX_SAFE_CALL.

◆ initialize()

static void Opm::gpuistl::AmgxInterface::initialize ( )

inlinestatic

Initialize the AMGX library.

This should be called once at the start of the program before using any AMGX functionality.

Exceptions

AmgxError if initialization fails

References OPM_AMGX_SAFE_CALL.

◆ initializeMatrix()

template<typename MatrixType >

static void Opm::gpuistl::AmgxInterface::initializeMatrix	(	const MatrixType &	matrix,
		AMGX_matrix_handle	amgx_matrix
	)

inlinestatic

Initialize an AMGX matrix from any matrix type (CPU or GPU)

Selects the transfer method based on the matrix type.

Parameters

matrix	Source matrix (typically BCRSMatrix (CPU) or GpuSparseMatrix (GPU))
amgx_matrix	Destination AMGX matrix

Exceptions

AmgxError if initialization fails

References OPM_AMGX_SAFE_CALL, Opm::gpuistl::detail::to_int(), and updateAmgxMatrixFromGpuSparseMatrix().

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::AmgxPreconditioner().

◆ initializeVector()

static void Opm::gpuistl::AmgxInterface::initializeVector	(	int	N,
		int	block_size,
		AMGX_vector_handle	amgx_vector
	)

inlinestatic

Initialize an AMGX vector with zeros.

Creates a zero-initialized vector of the appropriate size.

Parameters

N	Size of the vector
block_size	Block size (typically 1 for scalar vectors)
amgx_vector	The AMGX vector to initialize

Exceptions

AmgxError if initialization fails

References OPM_AMGX_SAFE_CALL.

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::AmgxPreconditioner().

◆ transferVectorFromAmgx()

template<typename VectorType >

static void Opm::gpuistl::AmgxInterface::transferVectorFromAmgx	(	AMGX_vector_handle	amgx_vec,
		VectorType &	vec
	)

inlinestatic

Transfer vector from AMGX to any vector type (CPU or GPU)

Selects the transfer method based on the vector type.

Parameters

amgx_vec	Source AMGX vector
vec	Destination vector (typically BlockVector (CPU) or GpuVector (GPU))

Exceptions

AmgxError if the transfer fails

References OPM_AMGX_SAFE_CALL, and updateGpuVectorFromAmgx().

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::apply().

◆ transferVectorToAmgx()

template<typename VectorType >

static void Opm::gpuistl::AmgxInterface::transferVectorToAmgx	(	const VectorType &	vec,
		AMGX_vector_handle	amgx_vec
	)

inlinestatic

Transfer vector to AMGX from any vector type (CPU or GPU)

Selects the transfer method based on the vector type.

Parameters

vec	Source vector (typically BlockVector (CPU) or GpuVector (GPU))
amgx_vec	Destination AMGX vector

Exceptions

AmgxError if the transfer fails

References OPM_AMGX_SAFE_CALL, and updateAmgxFromGpuVector().

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::apply().

◆ updateAmgxFromGpuVector()

template<typename T >

static void Opm::gpuistl::AmgxInterface::updateAmgxFromGpuVector	(	const GpuVector< T > &	gpu_vec,
		AMGX_vector_handle	amgx_vec
	)

inlinestatic

Update an AMGX vector from a GpuVector (device-to-device transfer)

Updates the AMGX vector with the contents of the GpuVector using direct device memory access. The AMGX vector must already be created with appropriate resources and mode.

Parameters

gpu_vec	The source GpuVector
amgx_vec	The AMGX vector to update

Exceptions

AmgxError if the transfer fails or sizes mismatch

References OPM_AMGX_SAFE_CALL.

Referenced by transferVectorToAmgx().

◆ updateAmgxMatrixCoefficientsFromGpuSparseMatrix()

template<typename T >

static void Opm::gpuistl::AmgxInterface::updateAmgxMatrixCoefficientsFromGpuSparseMatrix	(	const GpuSparseMatrix< T > &	gpuSparseMatrix,
		AMGX_matrix_handle	amgxMatrix
	)

inlinestatic

Update only the coefficient values of an AMGX matrix from a GpuSparseMatrix.

Updates just the coefficient values of an AMGX matrix without changing its sparsity pattern. This is more efficient when the matrix structure remains the same.

Parameters

gpuSparseMatrix	The source GpuSparseMatrix with updated values
amgxMatrix	The AMGX matrix to update

Exceptions

AmgxError if the update fails

References Opm::gpuistl::GpuSparseMatrix< T >::getNonZeroValues(), Opm::gpuistl::GpuSparseMatrix< T >::N(), Opm::gpuistl::GpuSparseMatrix< T >::nonzeroes(), OPM_AMGX_SAFE_CALL, and Opm::gpuistl::detail::to_int().

Referenced by updateMatrixValues().

◆ updateAmgxMatrixFromGpuSparseMatrix()

template<typename T >

static void Opm::gpuistl::AmgxInterface::updateAmgxMatrixFromGpuSparseMatrix	(	const GpuSparseMatrix< T > &	gpuSparseMatrix,
		AMGX_matrix_handle	amgxMatrix
	)

inlinestatic

Update an AMGX matrix from a GpuSparseMatrix (device-to-device transfer)

Uploads the entire matrix structure and values from GpuSparseMatrix to AMGX.

Parameters

gpuSparseMatrix	The source GpuSparseMatrix
amgxMatrix	The AMGX matrix to update

Exceptions

AmgxError if the transfer fails

References Opm::gpuistl::GpuSparseMatrix< T >::blockSize(), Opm::gpuistl::GpuSparseMatrix< T >::getColumnIndices(), Opm::gpuistl::GpuSparseMatrix< T >::getNonZeroValues(), Opm::gpuistl::GpuSparseMatrix< T >::getRowIndices(), Opm::gpuistl::GpuSparseMatrix< T >::N(), Opm::gpuistl::GpuSparseMatrix< T >::nonzeroes(), OPM_AMGX_SAFE_CALL, and Opm::gpuistl::detail::to_int().

Referenced by initializeMatrix().

◆ updateGpuSparseMatrixFromAmgxMatrix()

template<typename T >

static void Opm::gpuistl::AmgxInterface::updateGpuSparseMatrixFromAmgxMatrix	(	AMGX_matrix_handle	amgxMatrix,
		GpuSparseMatrix< T > &	gpuSparseMatrix
	)

inlinestatic

Update a GpuSparseMatrix from an AMGX matrix (device-to-device transfer)

Downloads the matrix data from AMGX and updates the GpuSparseMatrix with the values. The sparsity pattern is assumed to be identical, so only values are updated.

Note: This function is intended primarily for testing purposes and should not be used in performance-critical code paths, as it may involve unnecessary device-to-device transfers and temporary allocations.

Parameters

amgxMatrix	The source AMGX matrix
gpuSparseMatrix	The GpuSparseMatrix to update

Exceptions

AmgxError if the transfer fails

References Opm::gpuistl::GpuSparseMatrix< T >::getNonZeroValues(), OPM_AMGX_SAFE_CALL, and OPM_GPU_SAFE_CALL.

◆ updateGpuVectorFromAmgx()

template<typename T >

static void Opm::gpuistl::AmgxInterface::updateGpuVectorFromAmgx	(	AMGX_vector_handle	amgx_vec,
		GpuVector< T > &	gpu_vec
	)

inlinestatic

Update a GpuVector from an AMGX vector (device-to-device transfer)

Updates the GpuVector with the contents of the AMGX vector using direct device memory access.

Parameters

amgx_vec	The source AMGX vector
gpu_vec	The GpuVector to update

Exceptions

AmgxError if the transfer fails or sizes mismatch

References OPM_AMGX_SAFE_CALL.

Referenced by transferVectorFromAmgx().

◆ updateMatrixValues()

template<typename MatrixType >

static void Opm::gpuistl::AmgxInterface::updateMatrixValues	(	const MatrixType &	matrix,
		AMGX_matrix_handle	amgx_matrix
	)

inlinestatic

Update matrix values in AMGX.

Selects the update method based on the matrix type. Updates the coefficients of an AMGX matrix, without changing its sparsity pattern.

Parameters

matrix	Source matrix with updated values
amgx_matrix	AMGX matrix to update

Exceptions

AmgxError if the update fails

References OPM_AMGX_SAFE_CALL, and updateAmgxMatrixCoefficientsFromGpuSparseMatrix().

Referenced by Amgx::AmgxPreconditioner< M, X, Y >::update().

The documentation for this class was generated from the following file:

AmgxInterface.hpp

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ createConfig()

◆ createMatrix()

◆ createResources()

◆ createSolver()

◆ createVector()

◆ destroyConfig()

◆ destroyMatrix()

◆ destroyResources()

◆ destroySolver()

◆ destroyVector()

◆ determineAmgxMode()

◆ finalize()

◆ initialize()

◆ initializeMatrix()

◆ initializeVector()

◆ transferVectorFromAmgx()

◆ transferVectorToAmgx()

◆ updateAmgxFromGpuVector()

◆ updateAmgxMatrixCoefficientsFromGpuSparseMatrix()

◆ updateAmgxMatrixFromGpuSparseMatrix()

◆ updateGpuSparseMatrixFromAmgxMatrix()

◆ updateGpuVectorFromAmgx()

◆ updateMatrixValues()