sporco.cupy package¶

This subpackage provides GPU acceleration for selected SPORCO modules via copies of these modules that are patched to replace NumPy arrays and operations with the equivalent ones provided by CuPy [38]. The boolean value of attribute sporco.cupy.have_cupy indicates whether CuPy is installed and a GPU device is available. The modules within the sporco.cupy subpackage can still be used when sporco.cupy.have_cupy is False, but they will not be GPU accelerated.

Note that the sporco.cupy subpackage is not supported under versions of Python, such as Python 2.7.x, that do not have the importlib.util module.

Installation and Configuration¶

To use CuPy, first install CUDA and then install CuPy. Note that it may be necessary to set the environment variables as in

export CUDAHOME=/usr/local/cuda-10.2
export PATH=${CUDAHOME}/bin:${PATH}

(substitute the appropriate path to the CUDA installation) to avoid a cupy.cuda.compiler.CompileException when using CuPy. If this does not rectify the problem, the following may also be necessary:

export LD_LIBRARY_PATH=${CUDAHOME}/lib64:$LD_LIBRARY_PATH

Supported Modules¶

The sporco.cupy subpackage currently provides CuPy acceleration of the following standard sporco modules:

`sporco.cupy` module	`sporco` module
`sporco.cupy.cnvrep`	`sporco.cnvrep`
`sporco.cupy.common`	`sporco.common`
`sporco.cupy.linalg`	`sporco.linalg`
`sporco.cupy.metric`	`sporco.metric`
`sporco.cupy.prox`	`sporco.prox`
`sporco.cupy.util`	`sporco.util`
`sporco.cupy.admm.admm`	`sporco.admm.admm`
`sporco.cupy.admm.bpdn`	`sporco.admm.bpdn`
`sporco.cupy.admm.cbpdn`	`sporco.admm.cbpdn`
`sporco.cupy.admm.cbpdntv`	`sporco.admm.cbpdntv`
`sporco.cupy.admm.pdcsc`	`sporco.admm.pdcsc`
`sporco.cupy.admm.rpca`	`sporco.admm.rpca`
`sporco.cupy.admm.tvl1`	`sporco.admm.tvl1`
`sporco.cupy.admm.tvl2`	`sporco.admm.tvl2`
`sporco.cupy.pgm.cbpdn`	`sporco.pgm.cbpdn`
`sporco.cupy.dictlrn.onlinecdl`	`sporco.dictlrn.onlinecdl`

Usage¶

To use the CuPy accelerated version of a SPORCO module:

import the module from sporco.cupy instead of sporco
before calling functions/methods within the sporco.cupy module, convert NumPy arrays to CuPy arrays using np2cp.
after calling functions/methods within the sporco.cupy module, convert CuPy arrays to NumPy arrays using cp2np.

Usage examples are available for sporco.cupy.admm.tvl1, sporco.cupy.dictlrn.onlinecdl and sporco.cupy.admm.cbpdn.

Utility Functions¶

Since it is necessary to explicitly convert between NumPy arrays and CuPy arrays, a number of utility functions in sporco.cupy support this conversion in a way that behaves correctly independent of the value of sporco.cupy.have_cupy, in that conversion is performed when the value is True, and no conversion is perfomed when it is False.

sporco.cupy.array_module(*args)¶: Get the array module (numpy or cupy) of the array argument. This function is an alias for cupy.get_array_module.

sporco.cupy.np2cp(u)¶: Convert a numpy ndarray to a cupy array. This function is an alias for cupy.asarray

sporco.cupy.cp2np(u)¶: Convert a cupy array to a numpy ndarray. This function is an alias for cupy.asnumpy

sporco.cupy.cupy_wrapper(func)¶: A wrapper function that converts numpy ndarray arguments to cupy arrays, and convert any cupy arrays returned by the wrapped function into numpy ndarrays.

Some additional utility functions provide useful functionality when package GPUtil is installed, and return fixed default return values when it is not installed:

sporco.cupy.gpu_info()¶: Return a list of namedtuples representing attributes of each GPU device. Returns an empty list if GPUtil is not installed.

sporco.cupy.gpu_load(wproc=0.5, wmem=0.5)¶: Return a list of namedtuples representing the current load for each GPU device. The processor and memory loads are fractions between 0 and 1. The weighted load represents a weighted average of processor and memory loads using the parameters wproc and wmem respectively. Returns an empty list if GPUtil is not installed.

sporco.cupy.device_by_load(wproc=0.5, wmem=0.5)¶: Get a list of GPU device ids ordered by increasing weighted average of processor and memory load. Returns an empty list if GPUtil is not installed.

sporco.cupy.select_device_by_load(wproc=0.5, wmem=0.5)¶: Set the current device for cupy as the device with the lowest weighted average of processor and memory load. Returns 0 if GPUtil is not installed.

sporco.cupy.available_gpu(*args, **kwargs)¶: Get the device id for an available GPU when multiple GPUs are installed. This function is an alias for GPUtil.getAvailable. Returns 0 if GPUtil is not installed.

The current GPU device can be also selected using cupy.cuda.Device.use, e.g. to select device id 1

cp.cuda.Device(1).use()

CuPy also provides a context manager for GPU device selection.