scico.numpy.util#

Utility functions for working with jax arrays and BlockArrays.

Functions

`broadcast_nested_shapes`(shape_a, shape_b)	Compute the result of broadcasting on array shapes.
`complex_dtype`(dtype)	Construct the corresponding complex dtype for a given real dtype.
`indexed_shape`(shape, idx)	Determine the shape of an array after indexing/slicing.
`is_arraylike`(x)	Check if input is of type `jax.ArrayLike`.
`is_complex_dtype`(dtype)	Determine whether a dtype is complex.
`is_nested`(x)	Check if input is a list/tuple containing at least one list/tuple.
`is_real_dtype`(dtype)	Determine whether a dtype is real.
`is_scalar_equiv`(s)	Determine whether an object is a scalar or is scalar-equivalent.
`no_nan_divide`(x, y)	Return x/y, with 0 instead of `NaN` where y is 0.
`parse_axes`(axes[, shape, default])	Normalize axes to a list and optionally ensure correctness.
`real_dtype`(dtype)	Construct the corresponding real dtype for a given complex dtype.
`shape_to_size`(shape)	Compute array size corresponding to a specified shape.
`slice_length`(length, idx)	Determine the length of an array axis after indexing.

scico.numpy.util.parse_axes(axes, shape=None, default=None)[source]#

Normalize axes to a list and optionally ensure correctness.

Normalize axes to a list and (optionally) ensure that entries refer to axes that exist in shape.

Parameters:

axes (Union[int, Tuple[int, ...]]) – User specification of one or more axes: int, list, tuple, or None.
shape (Optional[Tuple[int, ...]]) – The shape of the array of which axes are being specified. If not None, axes is checked to make sure its entries refer to axes that exist in shape.
default (Optional[List[int]]) – Default value to return if axes is None. By default, list(range(len(shape))).

Return type:

List[int]

Returns:

List of axes (never an int, never None).

scico.numpy.util.slice_length(length, idx)[source]#

Determine the length of an array axis after indexing.

Determine the length of an array axis after slicing. An exception is raised if the indexing expression is an integer that is out of bounds for the specified axis length. A value of None is returned for valid integer indexing expressions as an indication that the corresponding axis shape is an empty tuple; this value should be converted to a unit integer if the axis size is required.

Parameters:

length (int) – Length of axis being sliced.
idx (AxisIndex) – Indexing/slice to be applied to axis.

Return type:

Optional[int]

Returns:

Length of indexed/sliced axis.

Raises:

ValueError – If idx is an integer index that is out bounds for the axis length.

scico.numpy.util.indexed_shape(shape, idx)[source]#

Determine the shape of an array after indexing/slicing.

Parameters:

shape (Tuple[int, ...]) – Shape of array.
idx (ArrayIndex) – Indexing expression.

Return type:

Tuple[int, ...]

Returns:

Shape of indexed/sliced array.

Raises:

ValueError – If idx is longer than shape.

scico.numpy.util.no_nan_divide(x, y)[source]#

Return x/y, with 0 instead of NaN where y is 0.

Parameters:

x (Union[BlockArray, Array]) – Numerator.
y (Union[BlockArray, Array]) – Denominator.

Return type:

Union[BlockArray, Array]

Returns:

x / y with 0 wherever y == 0.

scico.numpy.util.shape_to_size(shape)[source]#

Compute array size corresponding to a specified shape.

Compute array size corresponding to a specified shape, which may be nested, i.e. corresponding to a BlockArray.

Parameters:: shape (Union[Tuple[int, ...], Tuple[Tuple[int, ...], ...]]) – A shape tuple.
Return type:: int
Returns:: The number of elements in an array or BlockArray with shape shape.

scico.numpy.util.is_arraylike(x)[source]#

Check if input is of type jax.ArrayLike.

isinstance(x, jax.typing.ArrayLike) does not work in Python < 3.10, see https://jax.readthedocs.io/en/latest/jax.typing.html#jax-typing-best-practices.

Parameters:: x (Any) – Object to be tested.
Return type:: bool
Returns:: True if x is an ArrayLike, False otherwise.

scico.numpy.util.is_nested(x)[source]#

Check if input is a list/tuple containing at least one list/tuple.

Parameters:: x (Any) – Object to be tested.
Return type:: bool
Returns:: True if x is a list/tuple containing at least one list/tuple, False otherwise.

Example

>>> is_nested([1, 2, 3])
False
>>> is_nested([(1,2), (3,)])
True
>>> is_nested([[1, 2], 3])
True

scico.numpy.util.broadcast_nested_shapes(shape_a, shape_b)[source]#

Compute the result of broadcasting on array shapes.

Compute the result of applying a broadcasting binary operator to (block) arrays with (possibly nested) shapes shape_a and shape_b. Extends numpy.broadcast_shapes to also support the nested tuple shapes of BlockArrays.

Parameters:

shape_a (Union[Tuple[int, ...], Tuple[Tuple[int, ...], ...]]) – First array shape.
shape_b (Union[Tuple[int, ...], Tuple[Tuple[int, ...], ...]]) – Second array shape.

Return type:

Union[Tuple[int, ...], Tuple[Tuple[int, ...], ...]]

Returns:

A (possibly nested) shape tuple.

Example

>>> broadcast_nested_shapes(((1, 1, 3), (2, 3, 1)), ((2, 3,), (2, 1, 4)))
((1, 2, 3), (2, 3, 4))

scico.numpy.util.is_real_dtype(dtype)[source]#

Determine whether a dtype is real.

Parameters:: dtype (DType) – A numpy or scico.numpy dtype (e.g. float32, complex64).
Return type:: bool
Returns:: False if the dtype is complex, otherwise True.

scico.numpy.util.is_complex_dtype(dtype)[source]#

Determine whether a dtype is complex.

Parameters:: dtype (DType) – A numpy or scico.numpy dtype (e.g. float32, complex64).
Return type:: bool
Returns:: True if the dtype is complex, otherwise False.

scico.numpy.util.real_dtype(dtype)[source]#

Construct the corresponding real dtype for a given complex dtype.

Construct the corresponding real dtype for a given complex dtype, e.g. the real dtype corresponding to complex64 is float32.

Parameters:: dtype (DType) – A complex numpy or scico.numpy dtype (e.g. complex64, complex128).
Return type:: DType
Returns:: The real dtype corresponding to the input dtype

scico.numpy.util.complex_dtype(dtype)[source]#

Construct the corresponding complex dtype for a given real dtype.

Construct the corresponding complex dtype for a given real dtype, e.g. the complex dtype corresponding to float32 is complex64.

Parameters:: dtype (DType) – A real numpy or scico.numpy dtype (e.g. float32, float64).
Return type:: DType
Returns:: The complex dtype corresponding to the input dtype.

scico.numpy.util.is_scalar_equiv(s)[source]#

Determine whether an object is a scalar or is scalar-equivalent.

Determine whether an object is a scalar or a singleton array.

Parameters:: s (Any) – Object to be tested.
Return type:: bool
Returns:: True if the object is a scalar or a singleton array, otherwise False.