pyamgx Reference¶

exception pyamgx.AMGXError¶: Exception class for errors returned from calls to AMGX routines.

class pyamgx.Config¶

Config: Class for creating and handling AMGX Config objects.

create(options)¶

Create the underlying AMGX Config object from a configuration string.

Parameters:	options (str or bytes_like) – AMGX configuration string.
Returns:	self
Return type:	Config

create_from_dict(param_file)¶

Create the underlying AMGX Config object from a dictionary.

Parameters:	params (dict) – Dictionary with configuration options.

create_from_file(param_file)¶

Create the underlying AMGX Config object from a configuration file.

Parameters:	param_file (str or bytes_like) – Path to configuration file.

destroy()¶: Destroy the underlying AMGX Config object.

class pyamgx.Matrix¶

Matrix : Class for creating and handling AMGX Matrix objects.

Examples

Uploading the matrix [[1, 2], [3, 4]] using the upload method:

>>> import pyamgx, numpy as np
>>> pyamgx.initialize()
>>> cfg = pyamgx.Config().create("")
>>> rsrc = pyamgx.Resources().create_simple(cfg)
>>> M = pyamgx.Matrix().create(rsrc)
>>> M.upload(
...     row_ptrs=np.array([0, 2, 4], dtype=np.int32),
...     col_indices=np.array([0, 1, 0, 1], dtype=np.int32),
...     data=np.array([1., 2., 3., 4.], dtype=np.float64))
>>> M.destroy()
>>> rsrc.destroy()
>>> cfg.destroy()
>>> pyamgx.finalize()

create(Resources rsrc, mode='dDDI')¶

Create the underlying AMGX Matrix object.

Parameters:	rsrc (Resources) – mode (str, optional) – String representing data modes to use.
Returns:	self
Return type:	Matrix

destroy()¶: Destroy the underlying AMGX Matrix object.

get_nnz()¶

Get the number of non-zero entries of the Matrix.

Returns:	nnz
Return type:	int

get_size()¶

Get the matrix size (in block units), and the block dimensions.

Returns:	n (int) – The matrix size (number of rows/columns) in block units. block_dims (tuple) – A tuple (bx, by) representing the size of the blocks in the x- and y- dimensions.

replace_coefficients(data)¶

Replace matrix coefficients without changing the nonzero structure.

Parameters:	data (array_like) – Array of matrix data.

upload(row_ptrs, col_indices, data, block_dims=[1, 1])¶

Copy data from arrays describing the sparse matrix to the Matrix object.

Parameters:	row_ptrs (array_like) – Array of row pointers. For a description of the arrays row_ptrs, col_indices and data, see here. col_indices (array_like) – Array of column indices. data (array_like) – Array of matrix data. block_dims (tuple_like, optional) – Dimensions of block in x- and y- directions. Currently only square blocks are supported, so block_dims[0] should be equal to block_dims[1].
Returns:	self
Return type:	Matrix

upload_CSR(csr)¶

Copy data from a scipy.sparse.csr_matrix to the Matrix object.

Parameters:	csr (scipy.sparse.csr_matrix) –
Returns:	self
Return type:	Matrix

class pyamgx.Resources¶

Resources: Class for creating and freeing AMGX Resources objects.

create_simple(cfg)¶

Create the underlying AMGX Resources object in a single-threaded application.

Parameters:	cfg (Config) –
Returns:	self
Return type:	Resources

destroy()¶: Destroy the underlying AMGX Resources object.

class pyamgx.Solver¶

Solver: Class for creating and handling AMGX Solver objects.

create(Resources rsrc, Config cfg, mode='dDDI')¶

Create the underlying AMGX Solver object

Parameters:	rsrc (Resources) – cfg (Config) – mode (str, optional) – String representing data modes to use.

destroy()¶: Destroy the underlying AMGX Solver object.

get_residual(iteration, block_idx)¶

Get the value of the residual for a given iteration from the last solve phase.

Parameters:	iteration (int, optional) – The iteration at which to inspect the residual. If not provided, return the residual after the last iteration. block_idx (int, optional) – The index of the entry in the block of the residual to retrieve.
Returns:	res – Value of residual at specified iteration.
Return type:	float

iterations_number¶: The number of iterations that were executed during the last solve phase.

setup(A)¶

Invoke the set up phase.

Parameters:	A (Matrix) – The Matrix representing the coefficient matrix of the equation to be solved.

solve(Vector rhs, Vector sol)¶

Invoke the solve phase.

Parameters:

b (Vector) – The Vector representing the right-hand side of the equation to be solved.
x (Vector) – The Vector representing the solution vector of the equation to be solved. If zero_initial_guess is unspecified, the values in x are used as the initial guess for iterative algorithms.
zero_initial_guess (bool, optional) – If True, use an initial guess of zero for the solution, regardless of the values in x.

status¶: The status from the last solve phase.

class pyamgx.Vector¶

Vector: Class for creating and handling AMGX Vector objects.

Examples

Creating a vector, uploading values from a numpy array, and downloading values back to a numpy array:

>>> import pyamgx, numpy as np
>>> pyamgx.initialize()
>>> cfg = pyamgx.Config().create("")
>>> rsrc = pyamgx.Resources().create_simple(cfg)
>>> v = pyamgx.Vector().create(rsrc)
>>> v.upload(np.array([1., 2., 3.,], dtype=np.float64))
>>> v.download()
array([ 1.,  1.,  1.])
>>> v.destroy()
>>> rsrc.destroy()
>>> cfg.destroy()
>>> pyamgx.finalize()

create(Resources rsrc, mode='dDDI')¶

Create the underlying AMGX Vector object.

Parameters:	rsrc (Resources) – mode (str, optional) – String representing data modes to use.
Returns:	self
Return type:	Vector

destroy()¶: Destroy the underlying AMGX Vector object.

download(data)¶

Copy data from the Vector to an array.

Parameters:	data (array, ndim=1) – Array to copy data to.

download_raw(ptr)¶

Copy data from the Vector to an array, given a raw pointer to the array.

Parameters:	ptr (pointer) – An integer (or long integer, if required) that points to the array containing data

get_size()¶

Get the size of the vector (in block units), and the block size.

Returns:	n (int) – The size of the vector in block units. block_dim (int) – The block size.

set_zero(n=None, block_dim=None)¶

Allocate storage if needed and set all the values in the vector to zero.

Parameters:	n (int, optional) – Number of entries in the vector, in block units. If not provided or None, then the values must have been previously initialized using e.g., v.upload(). block_dim (int, optional) – Number of values per block. If not provided or None, then the values must have been previously initialized using e.g., v.upload().

upload(data, block_dim=1)¶

Copy data to the Vector from an array.

Parameters:	data (array_like, ndim=1) – Array to copy data from. block_dim (int, optional) – Number of values per block.
Returns:	self
Return type:	Vector

upload_raw(ptr, n, block_dim=1)¶

Copy data to the Vector from an array, given a raw pointer to the array.

Parameters:	ptr (pointer) – An integer (or long integer, if required) that points to the array containing data n (int) – Size of the array block_dim (int, optional) – Number of values per block.

pyamgx.check_error(err_code)¶

Raise AMGXError for non-zero values of err_code.

Parameters:	err_code (RC) – Error code returned from call to an AMGX routine.

pyamgx.finalize()¶: Finalize AMGX.

pyamgx.get_api_version()¶

Return the API version of AMGX as a string.

Returns:	version – String continaing major and minor API version information.
Return type:	str

pyamgx.get_error_string(err_code)¶

Return a human-readable error string corresponding to an error code.

Parameters:	err_code (RC) – Error code returned from call to an AMGX routine.
Returns:	err_str – Human-readable error string.
Return type:	str

pyamgx.initialize()¶: Initialize AMGX.

pyamgx.install_signal_handler()¶: Cause AMGX to install its default signal handlers.

pyamgx.pin_memory()¶

Notify the operating system that the underlying buffer of data is to be pinned to reside in physical memory.

Parameters:	data (numpy.ndarray, double) – The array containing data to be pinned.

pyamgx.read_system()¶

Read linear system from a MatrixMarket file.

Parameters:	A (`Matrix`) – rhs (`Vector`) – sol (`Vector`) – fname (str) – Path/name of MatrixMarket file.

pyamgx.register_print_callback(f)¶

Register a user-provided callback function for handling text output from calls to AMGX functions. The callback function should accept a single argument (a string containing the text output).

Parameters:	f (function) – Python function that accepts a string as input

Examples

>>> import pyamgx
>>> import time
>>> import pyamgx
>>> pyamgx.initialize()
>>> pyamgx.register_print_callback(lambda msg: print('{}: {}'.format(time.asctime(), msg)))
>>> cfg = pyamgx.Config().create("")
Fri Aug 10 07:23:25 2018: Cannot read file as JSON object, trying as AMGX config
>>> cfg.destroy()
>>> pyamgx.finalize()

pyamgx.reset_signal_handler()¶: Cause AMGX to restore previous signal handlers.

pyamgx.unpin_memory()¶

Notify the operating system that the underlying buffer of data is to be unpinned

Parameters:	data (numpy.ndarray, double) – The array containing data to be unpinned.