Complete API reference

Complete API reference#

class Array(values, dims: Tuple[Dimension, ...], spaces: Tuple[Literal['pos', 'freq'], ...], eager: Tuple[bool, ...], factors_applied: Tuple[bool, ...], xp)[source]

Bases: object

The Array class facilitates the generalized Discrete Fourier transform and all operations on its values while retaining coordinate grid information.

Parameters:

values (Any) – The values array with respect to the dimensions.
dims (Tuple[Dimension, ...]) – Dimensions defining the coordinates of the values.
spaces (Tuple[Space, ...]) – Space of the given values per Dimension.
eager (Tuple[bool, ...]) – Whether the factors should be applied to the internal values after performing a space transition. This mainly influences the behavior of into_space. It also acts as a tie breaker on addition and subtraction when factors_applied=False and factors_applied=True as a result would cost equally many operations.
factors_applied (Tuple[bool, ...]) – Whether the lazy factors have been applied to the given values.
xp (Any) – The array API namespace.

Examples

First, we initialize the dimensions using fa.dim_from_constraints:

>>> import fftarray as fa
>>> x_dim: fa.Dimension = fa.dim_from_constraints("x", pos_min=-1, pos_max=1., n=64, freq_middle=0.)
>>> y_dim: fa.Dimension = fa.dim_from_constraints("y", pos_min=-10, pos_max=10., n=128, freq_middle=0.)

Based on these, the coordinates can be retrieved in form of 1D Arrays. These can be combined to a 2D Array via automatic broadcasting:

>>> x: fa.Array = fa.coords_from_dim(x_dim, "pos")
>>> y: fa.Array = fa.coords_from_dim(y_dim, "pos")
>>> xy = x**2 * fa.sin(y)

The space (as well as other attributes such as xp, eager and factors_applied) can be set via respective into functions:

>>> xy_freq: fa.Array = xy.into_space("freq")

Integrate the Array from x=-0.2 to x=0.2 by indexing the given region before intgrating it via fa.integrate:

>>> res = fa.integrate(xy.sel(x=slice(-0.2,0.2)))

property device: The device of the underlying array.

property dims: Tuple[Dimension, ...]: Tuple of the Array’s Dimensions.

property dims_dict: Dict[str, Dimension]: Dictionary mapping each dimension name to the Array’s Dimension.

property dtype: The dtype of the Array’s values.

property eager: Tuple[bool, ...]

Whether the space transformation should be lazy or not.

eager=False: The fft factors are not directly applied after a space transformation but only when needed, i.e., lazily.
eager=True: The fft factors are always directly applied after a space transformation.

property factors_applied: Tuple[bool, ...]: Whether the lazy fft factors have been applied to the internal values.

into_dtype(dtype, /) → Array[source]

Change the values’ dtype.

Parameters:: dtype (Any) – The new dtype.
Returns:: A new Array whose values have the new dtype.
Return type:: Array

into_eager(eager: bool | Iterable[bool], /) → Array[source]

Change the eager state.

Parameters:: eager (Union[bool, Iterable[bool]]) – New eager state.
Returns:: A new Array with the new eager settings.
Return type:: Array

into_factors_applied(factors_applied: bool | Iterable[bool], /) → Array[source]

Change the factors_applied state. Note that the values of the returned Array will be of dtype complex, no matter if the factors_applied state changed.

Parameters:: factors_applied (Union[bool, Iterable[bool]]) – The new factors_applied state.
Returns:: A new Array whose values correspond to the new factors_applied state.
Return type:: Array

into_space(space: Literal['pos', 'freq'] | Iterable[Literal['pos', 'freq']], /) → Array[source]

Transform the space(s) of the Array’s values.

Parameters:: space (Union[Space, Iterable[Space]]) – The new space(s).
Returns:: A new Array whose values are in the new space.
Return type:: Array
Raises:: ValueError – If the Array does not have a float dtype.

into_xp(xp, /) → Array[source]

Change the array API namespace.

Parameters:: xp (Any) – The new array API namespace.
Returns:: A new Array with the new array API namespace.
Return type:: Array

isel(indexers: Mapping[str, int | slice] | None = None, missing_dims: Literal['raise', 'warn', 'ignore'] = 'raise', **indexers_kwargs: int | slice) → Array[source]

Select specific values along respective dimension names by indices. Inspired by xarray.DataArray.isel.

Parameters:

indexers (Mapping[str, int | slice] | None) – Mappping from Dimension name to the index which can be an int or a slice, by default None
missing_dims (Literal['raise', 'warn', 'ignore']) – Behavior, if selected Dimensions are not part of the Array, by default ‘raise’
indexers_kwargs (int | slice)

Returns:

Indexed Array.

Return type:

Array

property loc: Attribute for location based indexing like xarray.

sel(indexers: Mapping[str, float | slice] | None = None, missing_dims: Literal['raise', 'warn', 'ignore'] = 'raise', method: Literal['nearest', 'pad', 'ffill', 'backfill', 'bfill'] | None = None, **indexers_kwargs: float | slice) → Array[source]

Select specific values along respective dimension names by label/coordinate. Inspired by xarray.DataArray.sel

Parameters:

indexers (Optional[Mapping[str, Union[float, slice]]], optional) – Mappping from Dimension name to the coordinate/label which can be a float or a slice, by default None
missing_dims (Literal['raise', 'warn', 'ignore']) – Behavior, if selected Dimensions are not part of the Array, by default ‘raise’
method (Literal['nearest', 'pad', 'ffill', 'backfill', 'bfill'] | None) –
Method to use for inexact matches
- None (default): only exact matches
- pad / ffill: propagate last valid index value forward
- backfill / bfill: propagate next valid index value backward
- nearest: use nearest valid index value
indexers_kwargs (float | slice)

Returns:

Indexed Array.

Return type:

Array

Notes

In comparison to its xarray implementation, there is an add-on:

Implements missing_dims arg and accordingly raises errors

property shape: Tuple[int, ...]: Shape of the Array’s values.

property sizes: Dict[str, int]: Dictionary mapping each dimension name to the number of grid points.

property spaces: Tuple[Literal['pos', 'freq'], ...]: The spaces in which the values currently are in, per dimension.

values(space: Literal['pos', 'freq'] | Iterable[Literal['pos', 'freq']], /, *, xp: Any | None = None, dtype: Any | None = None) → Any[source]

The raw values with all lazy fft factors applied.

Using xp to make a conversion between array libraries relies on non-standardized behavior. Therefore this function only supports conversions between libraries where the interaction is specifically allowed. It currently supports NumPy, JAX, PyTorch and array-api-strict and is not optimal for performance because it always goes the safe route via NumPy.

Parameters:

space (Union[Space, Iterable[Space]]) – The space in which the values should be returned. Can be specified per dimension.
xp (Any | None) – The array API namespace to use for the returned values. If it is None, the array namespace from self is used.
dtype (Any | None) – The dtype to use for the returned values. If it is None, the dtype of self is used.
self (Array)

Returns:

The Array’s values.

Return type:

Any

property xp: The array API namespace driving the mathematical operations.

class Dimension(name: str, n: int, d_pos: float, pos_min: float, freq_min: float, dynamically_traced_coords: bool)[source]

Bases: object

Properties of an Array grid for one dimension.

This class encapsulates all the properties of the position and frequency coordinate grids for one dimension.

Note that properties associated with the position grid are denoted by pos, whereas the frequency grid properties are denoted with freq. Frequencies are rotational frequencies in cycles as opposed to angular frequencies.

Parameters:

name (str) – Name of the dimension.
n (int) – Number of grid points.
d_pos (float) – Distance between two neighboring position grid points.
pos_min (float) – Smallest position grid point.
freq_min (float) – Smallest frequency grid point
dynamically_traced_coords (bool) – Only relevant for use with JAX tracing. Whether the coordinate values should be dynamically traced such that the grid can be altered inside a jitted function. See also Working with JAX.

Notes

Implementation details

The grid in both spaces (position and frequency) goes from min to max including both points. Therefore d_pos = (pos_max-pos_min)/(n-1). In the case of even n, pos_middle is the sample on the right hand side of the exact center of the grid.

Examples:

n = 4
                pos_middle
     pos_min           pos_max
        |-----|-----|-----|
index:  0     1     2     3
         d_pos d_pos d_pos

n = 5
                pos_middle
     pos_min                 pos_max
        |-----|-----|-----|-----|
index:  0     1     2     3     4
         d_pos d_pos d_pos d_pos

In the case of even n, freq_middle is the sample on the right hand side of the exact center of the grid.

Examples:

n = 4
                  freq_middle
     freq_min             freq_max
        |------|------|------|
index:  0      1      2      3
         d_freq d_freq d_freq

n = 6

     freq_min           freq_middle     freq_max
        |------|------|------|------|------|
index:  0      1      2      3      4      5
         d_freq d_freq d_freq d_freq d_freq

These are the symbolic definitions of all the different names (for even n):

pos_extent = pos_max - pos_min
pos_middle = 0.5 * (pos_min + pos_max + d_pos)
d_pos = pos_extent/(n-1)

freq_extent = freq_max - freq_min
freq_middle = 0.5 * (freq_max + freq_min + d_freq)
d_freq = freq_extent/(n-1)

d_freq * d_pos * n = 1

For odd n the definitions for pos_middle and freq_middle change to ensure that they and the minimum and maximum position and frequency are actually sampled and not in between two samples.:

pos_middle = 0.5 * (pos_min + pos_max)
freq_middle = 0.5 * (freq_max + freq_min)

For performance reasons it is recommended to have n be a power of two.

Individual array coordinates:

pos = np.arange(0, n) * d_pos + pos_min
freq = np.arange(0, n) * d_freq + freq_min

These arrays fulfill the following properties:

np.max(pos) = pos_max
np.min(pos) = pos_min
np.max(freq) = freq_max
np.min(freq) = freq_min

property d_freq: float

Returns:: The distance between frequency grid points.
Return type:: float

property d_pos: float

Returns:: The distance between two neighboring position grid points.
Return type:: float

property freq_extent: float

Returns:: The length of the frequency grid. It is defined as freq_max - freq_min.
Return type:: float

property freq_max: float

Returns:: The largest frequency grid point.
Return type:: float

property freq_middle: float

Returns:: The middle of the frequency grid. If n is even, it is defined as the (n/2+1)’th frequency grid point.
Return type:: float

property freq_min: float

Returns:: The smallest frequency grid point.
Return type:: float

index_from_coord(coord: float | slice, space: Literal['pos', 'freq'], *, method: Literal['nearest', 'pad', 'ffill', 'backfill', 'bfill'] | None = None) → int | slice[source]

For the Dimension, retrieve the index corresponding to a given coordinate in a specified space.

Parameters:

coord (Union[float, slice]) – The coordinate or range of coordinates for which to find the index. If a slice is provided, the function will handle it accordingly.
space (Space) – The space in which the coordinate is defined. It can be either “pos” or “freq”.
method (Optional[Literal["nearest", "pad", "ffill", "backfill", "bfill"]], optional) – The method to use for finding the index when the exact coordinate is not found. Supported methods are: - “nearest”: Find the index representing the nearest coordinate. - “pad” or “ffill”: Forward fill to the next smallest index. - “backfill” or “bfill”: Backward fill to the next highest index. Default is None, which requires an exact match.

Returns:

The index or range of indices corresponding to the given coordinate(s). If a float coord is provided, the function returns an integer index. If a slice object is provided, the function returns a slice object.

Return type:

Union[int, slice]

Raises:

NotImplementedError – If a method is provided for a slice object.
KeyError – If no exact index is found and method is None, or if the coordinate is out of bounds for the specified method.
ValueError – If an unsupported method is specified.

property n: int

Returns:: The number of grid points.
Return type:: float

property name: str

Returns:: The name of his Dimension.
Return type:: float

property pos_extent: float

Returns:: The length of the position grid. It is defined as pos_max - pos_min.
Return type:: float

property pos_max: float

Returns:: The largest position grid point.
Return type:: float

property pos_middle: float

Returns:: The middle of the position grid. If n is even, it is defined as the (n/2+1)’th position grid point.
Return type:: float

property pos_min: float

Returns:: The smallest position grid point.
Return type:: float

values(space: Literal['pos', 'freq'], /, *, xp: Any | None = None, dtype: Any | None = None, device: Any | None = None)[source]

Returns the Dimension values for the respective space.

Parameters:

self (Dimension) – Dimension providing the parameters.
space (Space) – The space for which the values are returned.
xp (Optional[Any], optional) – The Array API namespace to use for the returned values. If it is None, the default namespace from get_default_xp() is used.
dtype (Optional[Any], optional) – The dtype to use for the returned values. If it is None, the default real floating point dtype of the determined xp is used.
device (Any | None)

Returns:

The Dimension’s values.

Return type:

Any

abs(x: Array, /) → Array[source]

Implements abs with a special shortcut to statically eliminate the phase part: of potential phase factors.

Parameters:: x (Array) – input array
Returns:: x with elementwise abs applied.
Return type:: Array

acos(x: Array, /) → Array

Wrapper around the underlying element-wise function acos from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.acos.html

Parameters:: x (Array)
Return type:: Array

acosh(x: Array, /) → Array

Wrapper around the underlying element-wise function acosh from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.acosh.html

Parameters:: x (Array)
Return type:: Array

add(x1, x2, /) → Array

Wrapper around the underlying element-wise function add from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.add.html

Return type:: Array

angle(x: Array) → Array[source]

Return the angle of the floating-point fa.Array values in radians. This implementation follows numpy.angle without the deg argument.

Parameters:: x (Array)
Return type:: Array

array(values, dim: Dimension | Iterable[Dimension], space: Literal['pos', 'freq'] | Iterable[Literal['pos', 'freq']], /, *, xp: Any | None = None, dtype: Any | None = None, device: Any | None = None, defensive_copy: bool = True) → Array[source]

Construct a new instance of Array from raw values.

Parameters:

values – The values to initialize the Array with. They can be of any Python Arrray API v2023.12 compatible library. By default they are copied to make sure an external alias cannot influence the created Array.
dim (Union[Dimension, Iterable[Dimension]]) – The Dimension(s) for each dimension of the passed in values.
space (Union[Space, Iterable[Space]]) – Specify the space(s) of the values with which the returned Array intialized.
xp (Optional[Any]) – The Array API namespace to use for the created Array. If it is None, array_api_compat.array_namespace(values) is used. If that fails the default namespace from get_default_xp() is used.
dtype (Optional[Any]) – Directly passed on to the xp.asarray of the determined xp. If None the dtype of values or the defaults for the passed in scalar of the underlying array library are used.
defensive_copy (bool) – If True the values array is always copied in order to ensure no external alias to it exists. This ensures the immutability of the created Array. If this is unnecessary, this defensive copy can be prevented by setting this argument to False. In this case it has to be ensured that the passed in array is not used externally after creation.
device (Any | None)

Return type:

Array

asin(x: Array, /) → Array

Wrapper around the underlying element-wise function asin from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.asin.html

Parameters:: x (Array)
Return type:: Array

asinh(x: Array, /) → Array

Wrapper around the underlying element-wise function asinh from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.asinh.html

Parameters:: x (Array)
Return type:: Array

atan(x: Array, /) → Array

Wrapper around the underlying element-wise function atan from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.atan.html

Parameters:: x (Array)
Return type:: Array

atan2(x1, x2, /) → Array

Wrapper around the underlying element-wise function atan2 from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.atan2.html

Return type:: Array

atanh(x: Array, /) → Array

Wrapper around the underlying element-wise function atanh from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.atanh.html

Parameters:: x (Array)
Return type:: Array

bitwise_and(x1, x2, /) → Array

Wrapper around the underlying element-wise function bitwise_and from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.bitwise_and.html

Return type:: Array

bitwise_invert(x: Array, /) → Array

Wrapper around the underlying element-wise function bitwise_invert from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.bitwise_invert.html

Parameters:: x (Array)
Return type:: Array

bitwise_left_shift(x1, x2, /) → Array

Wrapper around the underlying element-wise function bitwise_left_shift from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.bitwise_left_shift.html

Return type:: Array

bitwise_or(x1, x2, /) → Array

Wrapper around the underlying element-wise function bitwise_or from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.bitwise_or.html

Return type:: Array

bitwise_right_shift(x1, x2, /) → Array

Wrapper around the underlying element-wise function bitwise_right_shift from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.bitwise_right_shift.html

Return type:: Array

bitwise_xor(x1, x2, /) → Array

Wrapper around the underlying element-wise function bitwise_xor from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.bitwise_xor.html

Return type:: Array

ceil(x: Array, /) → Array

Wrapper around the underlying element-wise function ceil from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.ceil.html

Parameters:: x (Array)
Return type:: Array

clip(x: Array, /, *, min=None, max=None) → Array[source]

Parameters:: x (Array)
Return type:: Array

conj(x: Array, /) → Array

Wrapper around the underlying element-wise function conj from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.conj.html

Parameters:: x (Array)
Return type:: Array

coords_from_arr(x: Array, dim_name: str, space: Literal['pos', 'freq'], /, *, xp: Any | None = None, dtype: Any | None = None, device: Any | None = None) → Array[source]

Constructs an array filled with the coordinates of the specified dimension while keeping all other attributes (Array API namespace, eager) of the specified array.

Parameters:

x (Array) – The array from which to construct the coordinate array.
space (Space) – Specify the space of the returned Array is intialized.
dim_name (str) – The name of the dimension from which to construct the coordinate array.
xp (Optional[Any]) – The array namespace to use for the returned Array. None uses the array namespace of x.
dtype (Optional[Any]) – The dtype to use for the created coordinate array. None uses a real floating point type with the same precision as x.
device (Any | None)

Returns:

The grid coordinates of the chosen space packed into an Array with the dimension of name dim_name. eager of the created array is the same as eager in the selected dimension of x.

Return type:

Array

coords_from_dim(dim: Dimension, space: Literal['pos', 'freq'], /, *, xp: Any | None = None, dtype: Any | None = None, device: Any | None = None) → Array[source]

Parameters:

dim (Dimension) – The dimension from which the coordinate grid should be created.
space (Space) – Specify the space of the coordinates and in which space the returned Array is intialized.
xp (Optional[Any]) – The array namespace to use for the returned Array. None uses default numpy which can be globally changed.
dtype (Optional[Any]) – The dtype to use for the returned Array. None uses the default floating point type of the chosen xp.
device (Any | None)

Returns:

The grid coordinates of the chosen space packed into an Array with self as only dimension.

Return type:

Array

copysign(x1, x2, /) → Array

Wrapper around the underlying element-wise function copysign from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.copysign.html

Return type:: Array

cos(x: Array, /) → Array

Wrapper around the underlying element-wise function cos from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.cos.html

Parameters:: x (Array)
Return type:: Array

cosh(x: Array, /) → Array

Wrapper around the underlying element-wise function cosh from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.cosh.html

Parameters:: x (Array)
Return type:: Array

default_eager(eager: bool) → DefaultEagerContext[source]

Create a context manager to override the default values for eager locally.

Parameters:: eager (bool)
Return type:: DefaultEagerContext

default_xp(xp) → DefaultArrayNamespaceContext[source]

Create a context manager to override the default Array namespace locally.

Return type:: DefaultArrayNamespaceContext

dim(name: str, n: int, d_pos: float, pos_min: float, freq_min: float, *, dynamically_traced_coords: bool = False) → Dimension[source]

Initialize a Dimension firectly from the parameters which are stored internally.

Parameters:

name (str) – Name of the dimension.
n (int) – Number of grid points.
d_pos (float) – Distance between two neighboring position grid points.
pos_min (float) – Smallest position grid point.
freq_min (float) – Smallest frequency grid point
dynamically_traced_coords (bool, optional) – Only relevant for use with JAX tracing. Whether the coordinate values should be dynamically traced such that the grid can be altered inside a jitted function, by default False. See also Working with JAX.

Returns:

Initialized Dimension.

Return type:

Dimension

See also

Dimension

Creates a Dimension from an arbitrary subset of all possible grid parameters using the z3 constraint solver. Note that the specified grid parameters must lead to a unique solution that fulfill the following constraints:

pos_extent = pos_max - pos_min
pos_middle = 0.5 * (pos_min + pos_max + d_pos)
d_pos = pos_extent/(n-1)

freq_extent = freq_max - freq_min
freq_middle = 0.5 * (freq_max + freq_min + d_freq)
d_freq = freq_extent/(n-1)

d_freq * d_pos * n = 1.

If n is not directly specified an exact solution of this constraint system leads in general to a n which is not a natural number. In that case n is rounded up according to the rounding mode. In order to do this some other constraint has to be improved. The constraints which are allowed to change for rounding up are given in loose_params. The value of d_pos, d_freq, pos_min and freq_min would be made smaller while the value of pos_max, pos_extent, freq_max and freq_extent would be made larger. pos_middle and freq_middle do not influence n and are therefore not allowed as parameters in loose_prams.

Parameters:

name (str) – Name identifying the dimension.
n (int | Literal['power_of_two', 'even']) – Number of grid points, either a natural number or the rounding mode, by default “power_of_two”
d_pos (float | None) – Distance between two neighboring position grid points, by default None
d_freq (float | None) – Distance between two neighboring frequency grid points, by default None
pos_min (float | None) – Smallest position grid point, by default None
pos_max (float | None) – Largest position grid point, by default None
pos_middle (float | None) – Middle of the position grid, by default None
pos_extent (float | None) – Length of the position grid, by default None
freq_min (float | None) – Smallest frequency grid point, by default None
freq_max (float | None) – Largest frequency grid point, by default None
freq_extent (float | None) – Length of the frequency grid, by default None
freq_middle (float | None) – Middle of the frequency grid, by default None
loose_params (str | List[str] | None) – List of loose grid parameters (parameters that can be changed by the constraint solver when rounding up n to be even or a power of two), by default None
dynamically_traced_coords (bool) – Only relevant for use with JAX tracing. Whether the coordinate values should be dynamically traced such that the grid can be altered inside a jitted function, for more details see Working with JAX, by default False

Returns:

Dimension initialized using the constraints solved via the z3 constraint solver.

Return type:

Dimension

See also

Dimension

divide(x1, x2, /) → Array

Wrapper around the underlying element-wise function divide from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.divide.html

Return type:: Array

equal(x1, x2, /) → Array

Wrapper around the underlying element-wise function equal from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.equal.html

Return type:: Array

exp(x: Array, /) → Array

Wrapper around the underlying element-wise function exp from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.exp.html

Parameters:: x (Array)
Return type:: Array

expm1(x: Array, /) → Array

Wrapper around the underlying element-wise function expm1 from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.expm1.html

Parameters:: x (Array)
Return type:: Array

floor(x: Array, /) → Array

Wrapper around the underlying element-wise function floor from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.floor.html

Parameters:: x (Array)
Return type:: Array

floor_divide(x1, x2, /) → Array

Wrapper around the underlying element-wise function floor_divide from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.floor_divide.html

Return type:: Array

Parameters:

dim (Union[Dimension, Iterable[Dimension]]) – The dimension(s) of the created array. They also imply the shape.
space (Union[Space, Iterable[Space]]) – Specify the space(s) in which the returned Array is intialized.
xp (Any | None) – The Array API namespace to use for the created Array. If it is None, array_api_compat.array_namespace(fill_value) is used. If that fails the default namespace from get_default_xp() is used.
dtype (Optional[Any]) – The dtype to use for the returned Array. If the value is None, the dtype is inferred from fill_value according to the rules of the underlying Array API.
fill_value (bool | int | float | complex | Any)
device (Any | None)

Returns:

The grid coordinates of the chosen space packed into an Array with self as only dimension.

Return type:

Array

get_default_eager() → bool[source]

Returns:: Current default value for eager in the array creation functions.
Return type:: bool

get_default_xp()[source]

Returns:: Current default Array API namespace in the array creation functions.
Return type:: Any

greater(x1, x2, /) → Array

Wrapper around the underlying element-wise function greater from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.greater.html

Return type:: Array

greater_equal(x1, x2, /) → Array

Wrapper around the underlying element-wise function greater_equal from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.greater_equal.html

Return type:: Array

hypot(x1, x2, /) → Array

Wrapper around the underlying element-wise function hypot from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.hypot.html

Return type:: Array

imag(x: Array, /) → Array

Wrapper around the underlying element-wise function imag from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.imag.html

Parameters:: x (Array)
Return type:: Array

integrate(x: Array, /, *, dim_name: str | Iterable[str] | None = None, dtype=None) → Array[source]

Computes the integral along the specified Dimension(s). The integration is performed using simple rectangle rule integration, also known as Riemann summation [1]. The integration is equivalent to summing up the values along the specified Dimension(s) and multipling them with the integration element given by d_pos or d_freq of the respective Dimension. The integration for each Dimension is performed in the space of the input Array. The actual summation is forwarded to [2].

Parameters:

x (Array) – The input Array.
dim_name (Optional[Union[str, Iterable[str]]], optional) – Dimension name(s) along which the integration is performed. The default, dim_name=None, will reduce over all Dimensions.
dtype (Any, optional) – The dtype of the returned Array, by default None.

Returns:

New Array with the specified dimensions reduced by computing the integration of the elements along those dimensions.

Return type:

Array

See also

sum

References

isfinite(x: Array, /) → Array

Wrapper around the underlying element-wise function isfinite from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.isfinite.html

Parameters:: x (Array)
Return type:: Array

isinf(x: Array, /) → Array

Wrapper around the underlying element-wise function isinf from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.isinf.html

Parameters:: x (Array)
Return type:: Array

isnan(x: Array, /) → Array

Wrapper around the underlying element-wise function isnan from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.isnan.html

Parameters:: x (Array)
Return type:: Array

jax_register_pytree_nodes() → None[source]

Register PyTree implementation for Array and Dimension. For more information see Working with JAX.

Return type:: None

less(x1, x2, /) → Array

Wrapper around the underlying element-wise function less from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.less.html

Return type:: Array

less_equal(x1, x2, /) → Array

Wrapper around the underlying element-wise function less_equal from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.less_equal.html

Return type:: Array

log(x: Array, /) → Array

Wrapper around the underlying element-wise function log from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.log.html

Parameters:: x (Array)
Return type:: Array

log10(x: Array, /) → Array

Wrapper around the underlying element-wise function log10 from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.log10.html

Parameters:: x (Array)
Return type:: Array

log1p(x: Array, /) → Array

Wrapper around the underlying element-wise function log1p from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.log1p.html

Parameters:: x (Array)
Return type:: Array

log2(x: Array, /) → Array

Wrapper around the underlying element-wise function log2 from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.log2.html

Parameters:: x (Array)
Return type:: Array

logaddexp(x1, x2, /) → Array

Wrapper around the underlying element-wise function logaddexp from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.logaddexp.html

Return type:: Array

logical_and(x1, x2, /) → Array

Wrapper around the underlying element-wise function logical_and from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.logical_and.html

Return type:: Array

logical_not(x: Array, /) → Array

Wrapper around the underlying element-wise function logical_not from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.logical_not.html

Parameters:: x (Array)
Return type:: Array

logical_or(x1, x2, /) → Array

Wrapper around the underlying element-wise function logical_or from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.logical_or.html

Return type:: Array

logical_xor(x1, x2, /) → Array

Wrapper around the underlying element-wise function logical_xor from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.logical_xor.html

Return type:: Array

max(x: Array, /, *, dim_name: str | Iterable[str] | None = None) → Array[source]

Computes the maximum of all values along the specified Dimension(s). This is a thin wrapper around [3], refer to its documentation and the documentation of the used array library for detailed information about its semantics.

Parameters:

x (Array) – The input Array.
dim_name (Optional[Union[str, Iterable[str]]], optional) – Dimension name(s) along which the maximum is computed. The default, dim_name=None, will reduce over all Dimensions.

Returns:

New Array with the specified dimensions reduced by computing the maximum of the elements along those dimensions.

Return type:

Array

References

maximum(x1, x2, /) → Array

Wrapper around the underlying element-wise function maximum from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.maximum.html

Return type:: Array

mean(x: Array, /, *, dim_name: str | Iterable[str] | None = None) → Array[source]

Computes the mean of all values along the specified Dimension(s). This is a thin wrapper around [4], refer to its documentation and the documentation of the used array library for detailed information about its semantics.

Parameters:

x (Array) – The input Array.
dim_name (Optional[Union[str, Iterable[str]]], optional) – Dimension name(s) along which the mean is computed. The default, dim_name=None, will reduce over all Dimensions.

Returns:

New Array with the specified dimensions reduced by computing the mean of the elements along those dimensions.

Return type:

Array

See also

numpy.mean, xarray.DataArray.mean

References

min(x: Array, /, *, dim_name: str | Iterable[str] | None = None) → Array[source]

Computes the minimum of all values along the specified Dimension(s). This is a thin wrapper around [5], refer to its documentation and the documentation of the used array library for detailed information about its semantics.

Parameters:

x (Array) – The input Array.
dim_name (Optional[Union[str, Iterable[str]]], optional) – Dimension name(s) along which the minimum is computed. The default, dim_name=None, will reduce over all Dimensions.

Returns:

New Array with the specified dimensions reduced by computing the minimum of the elements along those dimensions.

Return type:

Array

References

minimum(x1, x2, /) → Array

Wrapper around the underlying element-wise function minimum from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.minimum.html

Return type:: Array

multiply(x1, x2, /) → Array

Wrapper around the underlying element-wise function multiply from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.multiply.html

Return type:: Array

negative(x: Array, /) → Array

Wrapper around the underlying element-wise function negative from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.negative.html

Parameters:: x (Array)
Return type:: Array

not_equal(x1, x2, /) → Array

Wrapper around the underlying element-wise function not_equal from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.not_equal.html

Return type:: Array

permute_dims(x: Array, dim_names: Tuple[str, ...], /) → Array[source]

Permutes the dimensions of an Array.

Parameters:

x (Array)
dim_names (Tuple[str, ...])

Return type:

Array

positive(x: Array, /) → Array

Wrapper around the underlying element-wise function positive from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.positive.html

Parameters:: x (Array)
Return type:: Array

pow(x1, x2, /) → Array

Wrapper around the underlying element-wise function pow from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.pow.html

Return type:: Array

prod(x: Array, /, *, dim_name: str | Iterable[str] | None = None, dtype=None) → Array[source]

Computes the product of all values over the specified Dimension(s). This is a thin wrapper around [6], refer to its documentation and the documentation of the used array library for detailed information about its semantics.

Parameters:

x (Array) – The input Array.
dim_name (Optional[Union[str, Iterable[str]]], optional) – Dimension name(s) along which the products are computed. The default, dim_name=None, will reduce over all Dimensions.
dtype (Any, optional) – The dtype of the returned Array, by default None.

Returns:

New Array with the specified dimensions reduced by computing the product of the elements along those dimensions.

Return type:

Array

See also

numpy.prod, xarray.DataArray.prod

References

real(x: Array, /) → Array

Wrapper around the underlying element-wise function real from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.real.html

Parameters:: x (Array)
Return type:: Array

remainder(x1, x2, /) → Array

Wrapper around the underlying element-wise function remainder from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.remainder.html

Return type:: Array

round(x: Array, /) → Array

Wrapper around the underlying element-wise function round from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.round.html

Parameters:: x (Array)
Return type:: Array

set_default_eager(eager: bool) → None[source]

Set the default value for the eager argument of array creation functions. If this is set within a context manager, it gets reset by the context manager on leaving to the value it had before the context manager was entered.

Parameters:: eager (bool) – Value to set as default for eager.
Return type:: None

set_default_xp(xp) → None[source]

Set the default value for the xp argument of array creation functions. If this is set within a context manager, it gets reset by the context manager on leaving to the value it had before the context manager was entered.

Parameters:: xp – Array API namespace to set as default. It gets automatically wrapped with array-api-compat if necessary.
Return type:: None

shift_freq(x: Array, offsets: Dict[str, float], /) → Array[source]

Cyclically shift the Array by a frequency offset via multiplication with a phase factor in position space: \(f \mapsto f - \text{offsets}\).

This operation does not change the domain, it only shifts the values.

Parameters:

x (Array) – The initial Array.
offsets (Dict[str, float]) – The frequency shift for each shifted dimension by name.

Returns:

The Array with its contents shifted in frequency space.

Return type:

Array

shift_pos(x: Array, offsets: Dict[str, float]) → Array[source]

Cyclically shift the Array by a position offset via multiplication with a phase factor in frequency space: \(x \mapsto x - \text{offsets}\).

This operation does not change the domain, it only shifts the values.

Parameters:

x (Array) – The initial Array.
offsets (Dict[str, float]) – The position shift for each shifted dimension by name.

Returns:

The Array with its contents shifted in position space.

Return type:

Array

sign(x: Array, /) → Array

Wrapper around the underlying element-wise function sign from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.sign.html

Parameters:: x (Array)
Return type:: Array

signbit(x: Array, /) → Array

Wrapper around the underlying element-wise function signbit from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.signbit.html

Parameters:: x (Array)
Return type:: Array

sin(x: Array, /) → Array

Wrapper around the underlying element-wise function sin from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.sin.html

Parameters:: x (Array)
Return type:: Array

sinh(x: Array, /) → Array

Wrapper around the underlying element-wise function sinh from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.sinh.html

Parameters:: x (Array)
Return type:: Array

sqrt(x: Array, /) → Array

Wrapper around the underlying element-wise function sqrt from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.sqrt.html

Parameters:: x (Array)
Return type:: Array

square(x: Array, /) → Array

Wrapper around the underlying element-wise function square from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.square.html

Parameters:: x (Array)
Return type:: Array

subtract(x1, x2, /) → Array

Wrapper around the underlying element-wise function subtract from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.subtract.html

Return type:: Array

sum(x: Array, /, *, dim_name: str | Iterable[str] | None = None, dtype=None) → Array[source]

Computes the sum of all values over the specified Dimension(s). This is a thin wrapper around [7], refer to its documentation and the documentation of the used array library for detailed information about its semantics.

Parameters:

x (Array) – The input Array.
dim_name (Optional[Union[str, Iterable[str]]], optional) – Dimension name(s) over which the sum is performed. The default, dim_name=None, will reduce over all Dimensions.
dtype (Any, optional) – The dtype of the returned Array, by default None.

Returns:

New Array with the specified dimensions reduced by computing the sum of the elements along those dimensions.

Return type:

Array

See also

numpy.sum, xarray.DataArray.sum

References

tan(x: Array, /) → Array

Wrapper around the underlying element-wise function tan from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.tan.html

Parameters:: x (Array)
Return type:: Array

tanh(x: Array, /) → Array

Wrapper around the underlying element-wise function tanh from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.tanh.html

Parameters:: x (Array)
Return type:: Array

trunc(x: Array, /) → Array

Wrapper around the underlying element-wise function trunc from the Python Array API standard. See https://data-apis.org/array-api/latest/API_specification/generated/array_api.trunc.html

Parameters:: x (Array)
Return type:: Array