array_module

array_module ¶

Array module utilities for CPU/GPU agnostic operations.

This module provides the core functions for writing CPU/GPU agnostic code using the array module pattern. The key function get_array_module() returns either NumPy or CuPy depending on the input array type and configuration.

Supports CPU/GPU agnostic array operations using CuPy, allowing the same code to execute on CPU (via NumPy) or GPU (via CuPy) without modification.

Example

import numpy as np from osipy.common.backend import get_array_module

def compute_mean(data): ... xp = get_array_module(data) ... return xp.mean(data, axis=0)

Works with NumPy arrays¶

np_data = np.random.randn(100, 50) result = compute_mean(np_data) # Uses NumPy

Works with CuPy arrays (if available)¶

gpu_data = cupy.asarray(np_data)¶

result = compute_mean(gpu_data) # Uses CuPy¶

References

.. [1] CuPy array module pattern: https://docs.cupy.dev/en/stable/user_guide/basic.html

get_array_module ¶

get_array_module(*arrays)

Get the array module (NumPy or CuPy) for the given arrays.

This function returns the appropriate array module based on the input array types and the current backend configuration. If any input array is a CuPy array and GPU is not forced to CPU mode, returns CuPy. Otherwise, returns NumPy.

PARAMETER	DESCRIPTION
`*arrays`	Input arrays. Can be NumPy arrays, CuPy arrays, or any array-like. TYPE: `ArrayLike` DEFAULT: `()`

RETURNS	DESCRIPTION
`module`	Either numpy or cupy module, depending on input types and configuration.

Notes

This function checks: 1. If the backend is forced to CPU mode → returns NumPy 2. If any input has __cuda_array_interface__ → returns CuPy 3. If CuPy's get_array_module is available → uses it 4. Otherwise → returns NumPy

Example

import numpy as np data = np.array([1, 2, 3]) xp = get_array_module(data) xp.name 'numpy'

to_numpy ¶

to_numpy(array)

Convert an array to NumPy, transferring from GPU if necessary.

PARAMETER	DESCRIPTION
`array`	Input array. Can be NumPy, CuPy, or any array-like. TYPE: `ArrayLike`

RETURNS	DESCRIPTION
`NDArray`	NumPy array with the same data.

Notes

If the input is already a NumPy array, it is returned as-is (no copy). If the input is a CuPy array, data is transferred from GPU to CPU. For other array-likes, np.asarray is used.

Example

import numpy as np data = np.array([1, 2, 3]) result = to_numpy(data) result is data # No copy for NumPy arrays True

to_gpu ¶

to_gpu(array)

Transfer an array to GPU if available, otherwise return as NumPy.

PARAMETER	DESCRIPTION
`array`	Input array. Can be NumPy, CuPy, or any array-like. TYPE: `ArrayLike`

RETURNS	DESCRIPTION
`array`	CuPy array if GPU is available and not forced to CPU mode, otherwise NumPy array.

Notes

This function respects the global backend configuration: - If force_cpu is True, returns NumPy array - If CuPy is not available, returns NumPy array - If input is already on GPU, returns as-is (no copy)

Example

import numpy as np from osipy.common.backend import to_gpu, is_gpu_available data = np.array([1, 2, 3]) gpu_data = to_gpu(data)

Returns CuPy array if GPU available, else NumPy array¶