`numpy` — numpy-compatible array operations¶

The numpy submodule of ulab provides a numpy-compatible API built around the ndarray n-dimensional array type. It implements a curated subset of CPython numpy: array construction, element-wise math, reductions and statistics, linear algebra, FFTs, random number generation, polynomial fitting, and basic I/O.

The submodule is conventionally imported as np:

from ulab import numpy as np

a = np.array([1, 2, 3, 4], dtype=np.float)
b = np.linspace(0, 1, num=5)
c = np.dot(a.reshape((2, 2)), a.reshape((2, 2)))

Each dtype argument is one of the integer constants exposed at module level: numpy.bool, numpy.uint8, numpy.int8, numpy.uint16, numpy.int16, and numpy.float (the default). The result type ndarray refers to numpy.ndarray.

Submodules¶

class `ndarray` — the n-dimensional array¶

The ndarray is the n-dimensional, dtype-aware container at the core of numpy / ulab. The data is stored in a contiguous block whose interpretation is described by a small header (dtype, shape, strides, ndim, itemsize). Many operations – reshape, transpose, slicing – only adjust this header and so are very cheap; methods that allocate new storage (copy, flatten, most arithmetic) return a new dense array.

The same type is reachable as ulab.ndarray, numpy.ndarray, and (within this page) simply ndarray.

class numpy.ndarray(values: ndarray | bytes | list | tuple, *, dtype: int = numpy.float)¶

Create a new ndarray.

Parameters:

values – Source data. Either another ndarray (which is deep-copied, with type conversion if dtype differs) or any MicroPython iterable. Nested iterables produce multi-dimensional arrays; the inner iterables must all have the same length or a ValueError is raised.
dtype – Element type for the new array. One of the type-code integers exposed by numpy (numpy.bool, numpy.uint8, numpy.int8, numpy.uint16, numpy.int16, and numpy.float), or a dtype instance. Defaults to numpy.float.

The factory function numpy.array is the conventional way to create an ndarray; it forwards to this constructor.

byteswap(*, inplace: bool = False) → ndarray¶

Swap the byte order of every element. For uint16, int16, and float arrays this reverses the per-element byte order, which is useful when consuming data from peripherals whose endianness does not match the microcontroller’s. For single-byte dtypes (bool, uint8, int8) this is a no-op that returns a view or copy.

If inplace is False (the default) a new ndarray is returned and the original is left untouched. If inplace is True the bytes of self are swapped in place and a view of self is returned.

copy() → ndarray¶: Return a new dense, deep copy of the array. The copy owns its own data; modifications to it do not affect the original.

flatten(*, order: str = 'C') → ndarray¶

Return a new one-dimensional copy of the array.

Parameters:: order – 'C' (the default) walks the data in C order (last axis varies fastest); 'F' walks it in Fortran order (first axis varies fastest).

reshape(shape: int | tuple[int, ...]) → ndarray¶: Return a view of the array with a new shape. The total number of elements must be unchanged or a ValueError is raised. Only available when ULAB_MAX_DIMS > 1. Equivalent to assigning to shape.

sort(*, axis: int | None = -1) → None¶

Sort the array in place.

Parameters:: axis – Axis along which to sort. -1 (the default) sorts along the last axis; None first flattens the array and then sorts.

tobytes() → bytearray¶: Return a bytearray that aliases the array’s underlying data buffer. Writes through the returned bytearray modify the array in place. Raises ValueError if the array is not dense (e.g. a sliced view).

tolist() → list¶: Return the contents of the array as a (possibly nested) Python list. The nesting depth equals ndim.

transpose() → ndarray¶: Return the transpose of the array (axes reversed). For one-dimensional arrays this returns self. Only available when ULAB_MAX_DIMS > 1. The T attribute is a shorthand for this method.

dtype: dtype | int¶: The data type of the array’s elements. Returns a dtype instance when the firmware is built with ULAB_HAS_DTYPE_OBJECT enabled, otherwise the underlying single-character type code as an integer.

flat: flatiter¶: A flat iterator that yields every element of the array in C order. Unlike flatten(), iterating flat does not allocate a new array.

itemsize: int¶: Size in bytes of a single array element, derived from dtype.

ndim: int¶: Number of array dimensions (length of shape).

shape: tuple[int, ...]¶: Lengths of the array along each axis. Assigning a tuple to shape reshapes the array in place (equivalent to reshape()).

size: int¶: Total number of elements in the array (the product of shape).

strides: tuple[int, ...]¶: Number of bytes to step in memory along each axis to reach the next element along that axis.

T: ndarray¶: The transpose of the array; equivalent to transpose().

Supported operators¶

ndarray instances support the following operators. Binary operators broadcast their operands following standard numpy broadcasting rules and follow numpy’s upcasting rules (e.g. uint8 + int8 => int16, uint16 + int16 => float).

Arithmetic (binary): +, -, *, /, //, %, **. Reflected (right-hand) operands and the in-place variants +=, -=, *=, /=, %=, **= are also supported. Both ndarray-with-ndarray and ndarray-with-scalar forms are accepted.

Comparison: ==, !=, <, <=, >, >=. Each returns a boolean ndarray of the broadcast shape.

Bitwise (integer arrays only): &, |, ^. Applying these to a float array raises TypeError.

Unary: + (returns a copy), - (negation; on unsigned dtypes the values wrap modulo \(2^N\)), abs() (element-wise absolute value; on unsigned dtypes returns a copy without computation), ~ (bitwise inversion, integer dtypes only), len() (returns the length of the first axis).

Indexing and slicing: a[i], a[i, j, ...], a[start:stop:step], boolean-mask indexing (a[mask]) and integer-array (fancy) indexing are all supported on both reads and writes.

Iteration: Iterating over an ndarray yields sub-arrays along the first axis (one element at a time for 1-D arrays). Use flat to iterate over every scalar element regardless of dimensionality.

The matrix-multiplication operator @ is not implemented; use numpy.dot (np.dot(a, b)) instead.

The shift (<<, >>) operators are not implemented at the operator level. Use numpy.left_shift and numpy.right_shift for element-wise integer shifts.

Array construction¶

numpy.array(values: ndarray | list | tuple, *, dtype: int = float) → ndarray¶: Construct a new ndarray from a nested iterable of numbers. Equivalent alternate constructor for numpy.ndarray.

numpy.arange(start: int | float, stop: int | float | None = None, step: int | float = 1, *, dtype: int | None = None) → ndarray¶: Return evenly spaced values over the half-open interval [start, stop). If only one positional argument is given, it is treated as stop with start = 0. If dtype is omitted, it is inferred from the inputs (integer if all of start, stop, step are ints and within range).

numpy.asarray(a: ndarray | list | tuple, *, dtype: int | None = None) → ndarray¶: If a is already an ndarray whose dtype matches dtype (or dtype is None), return a unchanged; otherwise create a new array (with the requested dtype conversion when given). Iterables are converted as in numpy.array.

numpy.concatenate(arrays: tuple, *, axis: int = 0) → ndarray¶: Join a sequence of ndarray along an existing axis. All input arrays must share the same dtype, ndim, and shape on every axis other than axis.

numpy.diag(a: ndarray, *, k: int = 0) → ndarray¶: For a 2-D a, return a 1-D array containing the k-th diagonal. For a 1-D a, return a 2-D square array with a placed on the k-th diagonal. k may be positive (above main diagonal) or negative (below).

numpy.empty(shape: int | tuple[int, ...], *, dtype: int = float) → ndarray¶: Alias for zeros; returns a zero-filled array of shape and dtype. (ulab does not leave the buffer uninitialised.)

numpy.eye(N: int, M: int | None = None, k: int = 0, *, dtype: int = float) → ndarray¶: Return a 2-D N x M array (square N x N if M is None) with ones on the k-th diagonal and zeros elsewhere.

numpy.frombuffer(buffer: bytes, *, dtype: int = float, count: int = -1, offset: int = 0) → ndarray¶: Interpret a buffer-protocol object as a 1-D ndarray of dtype. count is the number of items to read (-1 reads all available items); offset skips that many bytes at the start of the buffer.

numpy.full(shape: int | tuple[int, ...], fill_value: int | float | bool, *, dtype: int = float) → ndarray¶: Return a new array of shape and dtype with every element set to fill_value.

numpy.linspace(start: float, stop: float, num: int = 50, *, endpoint: bool = True, retstep: bool = False, dtype: int = float) → ndarray | tuple[ndarray, float]¶: Return num evenly spaced samples over the closed interval [start, stop] (or half-open if endpoint is False). When retstep is True, return a tuple (samples, step).

numpy.logspace(start: float, stop: float, num: int = 50, *, base: float = 10.0, endpoint: bool = True, dtype: int = float) → ndarray¶: Return num samples spaced evenly on a log scale: the result starts at base ** start and ends at base ** stop.

numpy.meshgrid(*xi: ndarray, indexing: str = 'xy') → tuple[ndarray, ...]¶: Return a tuple of coordinate matrices from a sequence of one-dimensional coordinate arrays. With indexing 'xy' (the default) the first two inputs are treated as Cartesian coordinates and their output axes are swapped; with 'ij' matrix-style indexing is used. The implementation corresponds to the NumPy equivalent with copy=True and sparse=False.

numpy.ones(shape: int | tuple[int, ...], *, dtype: int = float) → ndarray¶: Return a new array of shape and dtype filled with ones.

numpy.zeros(shape: int | tuple[int, ...], *, dtype: int = float) → ndarray¶: Return a new array of shape and dtype filled with zeros.

Inspection / printing¶

numpy.get_printoptions() → dict¶: Return the current array printing options as a dict with keys threshold and edgeitems.

numpy.set_printoptions(*, threshold: int | None = None, edgeitems: int | None = None) → None¶: Set array printing options. threshold is the maximum number of array elements printed in full; edgeitems is the number of items shown at each end of an axis when the array is summarised.

numpy.ndinfo(array: ndarray) → None¶: Print diagnostic information (shape, strides, dtype, itemsize, …) about array.

numpy.size(a: ndarray, *, axis: int | None = None) → int¶: Return the number of elements of a along axis; if axis is None, return the total number of elements (the product of ndarray.shape).

Comparison¶

numpy.clip(a: ndarray | int | float, a_min: ndarray | int | float, a_max: ndarray | int | float) → ndarray | int | float¶: Clip the values of a so that a_min <= result <= a_max. Equivalent to maximum(a_min, minimum(a, a_max)); broadcasting follows the same rules as minimum.

numpy.equal(x1: ndarray | int | float, x2: ndarray | int | float) → ndarray | bool¶: Element-wise x1 == x2; returns a boolean ndarray (or a bool scalar if both inputs are scalars). Provided for portability – the == operator on arrays gives the same result.

numpy.not_equal(x1: ndarray | int | float, x2: ndarray | int | float) → ndarray | bool¶: Element-wise x1 != x2; the boolean counterpart to equal.

numpy.isfinite(x: ndarray | int | float) → ndarray | bool¶: Return a boolean array (or scalar) that is True where the input is finite. Integer inputs are always finite.

numpy.isinf(x: ndarray | int | float) → ndarray | bool¶: Return a boolean array (or scalar) that is True where the input is infinite. Integer inputs are never infinite.

numpy.maximum(x1: ndarray | int | float, x2: ndarray | int | float) → ndarray | int | float¶: Element-wise maximum of two arrays / scalars. The arguments are broadcast together; if dtypes differ, the output is upcast.

numpy.minimum(x1: ndarray | int | float, x2: ndarray | int | float) → ndarray | int | float¶: Element-wise minimum of two arrays / scalars; counterpart to maximum.

numpy.nonzero(a: ndarray) → tuple[ndarray, ...]¶: Return a tuple of ndarray, one per dimension of a, containing the indices of the non-zero elements of a.

numpy.where(condition: ndarray | int | float, x: ndarray | int | float, y: ndarray | int | float) → ndarray¶: Return an ndarray whose elements come from x where condition is truthy, and from y otherwise. The three inputs are broadcast together; the output dtype is the upcast of x and y.

Numerical reductions¶

numpy.all(a: ndarray | list | tuple, *, axis: int | None = None) → ndarray | bool¶: Test whether all elements along axis evaluate to True. With axis=None (the default) the flattened array is tested and a single bool is returned.

numpy.any(a: ndarray | list | tuple, *, axis: int | None = None) → ndarray | bool¶: Test whether any element along axis evaluates to True. With axis=None the flattened array is tested.

numpy.argmax(a: ndarray | list | tuple, *, axis: int | None = None) → ndarray | int¶: Return the index of the maximum element along axis. With axis=None the array is flattened and a single integer is returned.

numpy.argmin(a: ndarray | list | tuple, *, axis: int | None = None) → ndarray | int¶: Return the index of the minimum element along axis. With axis=None the array is flattened and a single integer is returned.

numpy.argsort(a: ndarray, *, axis: int = -1) → ndarray¶: Return an unsigned integer index ndarray whose entries sort a in ascending order along axis. The output dtype is uint16, so no axis may exceed 65535 elements. axis=None is not supported.

numpy.cross(a: ndarray, b: ndarray) → ndarray¶: Return the cross product of two 1-D arrays of length 3.

numpy.diff(a: ndarray, *, n: int = 1, axis: int = -1) → ndarray¶: Return the n-th discrete forward difference of a along axis. n must be in 0..9 (the differentiation stencil is stored in an int8); the length of axis shrinks by n. The numpy prepend and append keywords are not implemented.

numpy.flip(a: ndarray, *, axis: int | None = None) → ndarray¶: Return a new array with the order of elements reversed along axis; with axis=None the array is reversed along every axis.

numpy.max(a: ndarray | list | tuple, *, axis: int | None = None, keepdims: bool = False) → ndarray | int | float¶: Return the maximum element along axis. With axis=None (the default) the flattened array is reduced to a scalar. The numpy out keyword is not implemented.

numpy.min(a: ndarray | list | tuple, *, axis: int | None = None, keepdims: bool = False) → ndarray | int | float¶: Return the minimum element along axis; counterpart to max.

numpy.mean(a: ndarray | list | tuple, *, axis: int | None = None, keepdims: bool = False) → ndarray | float¶: Return the arithmetic mean along axis. With axis=None (the default) the flattened array’s mean is returned as a float.

numpy.median(a: ndarray, *, axis: int | None = None) → ndarray | float¶: Return the median along axis. With axis=None the array is flattened first. The output dtype is always float.

numpy.roll(a: ndarray, shift: int, *, axis: int | None = None) → ndarray¶: Return a with its elements rolled (cyclically shifted) by shift positions. With axis=None (the default) the array is flattened first. Negative shifts roll in the opposite direction.

numpy.sort(a: ndarray, *, axis: int = -1) → ndarray¶: Return a sorted copy of a along axis using heap sort. With axis=None the array is flattened first. The numpy kind and order keywords are not implemented.

numpy.std(a: ndarray | list | tuple, *, axis: int | None = None, ddof: int = 0, keepdims: bool = False) → ndarray | float¶: Return the standard deviation along axis. ddof is the delta degrees of freedom – the divisor used is N - ddof.

numpy.sum(a: ndarray | list | tuple, *, axis: int | None = None, keepdims: bool = False) → ndarray | int | float¶: Return the sum along axis. With axis=None the flattened array’s total is returned as a scalar.

Statistics¶

numpy.bincount(x: ndarray, *, weights: ndarray | None = None, minlength: int | None = None) → ndarray¶: Count the number of occurrences of each value in the one-dimensional, non-negative integer array x. The x dtype must be uint8 or uint16. If weights is given, each entry of x contributes its matching weight rather than 1 and the output is of dtype float; otherwise the output is of dtype uint16. If minlength is given, the output array has at least that many elements (extra entries are zero).

numpy.trace(m: ndarray) → int | float¶: Return the sum of the diagonal elements of the square matrix m. The return type follows the dtype of m (integer arrays produce an int, float arrays a float).

Transform¶

numpy.compress(condition: ndarray | list | tuple, a: ndarray, *, axis: int | None = None) → ndarray¶: Return slices of a selected along axis by the boolean condition. With axis=None the flattened array is used.

numpy.delete(a: ndarray, indices: int | ndarray | list | tuple | range, *, axis: int | None = None) → ndarray¶: Return a copy of a with the entries at indices removed along axis. With axis=None the array is flattened first. Negative indices count from the end of axis; indices is sorted internally before deletion.

numpy.dot(m1: ndarray, m2: ndarray) → ndarray | float¶: Return the dot product of two arrays. For two 1-D arrays this is the inner product (a float scalar). For 2-D arrays this is matrix multiplication; the inner dimensions must match. The result is always of dtype float.

Approximation¶

numpy.interp(x: ndarray, xp: ndarray, fp: ndarray, *, left: float | None = None, right: float | None = None) → ndarray¶: One-dimensional linear interpolation. xp must be a monotonically increasing 1-D array of independent values; fp contains the corresponding dependent values; x are the points at which the interpolant is evaluated. left and right override the value returned for x < xp[0] and x > xp[-1] respectively (defaults: fp[0] and fp[-1]).

numpy.trapz(y: ndarray, x: ndarray | None = None, dx: float = 1.0) → float¶: Integrate y using the composite trapezoidal rule. If x is given it provides the sample positions corresponding to y; otherwise the spacing dx is used. y (and x) must be 1-D.

Selection¶

numpy.take(a: ndarray, indices: ndarray | list | tuple, *, axis: int | None = None, out: ndarray | None = None, mode: str | None = None) → ndarray¶: Take elements from a at the given indices along axis. With axis=None the flattened array is used. mode selects the out-of-bounds behaviour: "raise" (default – raise ValueError), "wrap" (modulo the axis length), or "clip" (clip to the valid range; negative indices are not allowed). If out is given the result is written into it.

Bitwise¶

numpy.bitwise_and(x1: ndarray, x2: ndarray) → ndarray¶: Element-wise bitwise AND of two integer arrays; broadcasting is supported. A non-integer dtype raises an exception.

numpy.bitwise_or(x1: ndarray, x2: ndarray) → ndarray¶: Element-wise bitwise OR of two integer arrays.

numpy.bitwise_xor(x1: ndarray, x2: ndarray) → ndarray¶: Element-wise bitwise XOR of two integer arrays.

numpy.left_shift(x1: ndarray, x2: ndarray) → ndarray¶: Element-wise bitwise shift of x1 left by x2 bits; both arrays must have integer dtype.

numpy.right_shift(x1: ndarray, x2: ndarray) → ndarray¶: Element-wise bitwise shift of x1 right by x2 bits; both arrays must have integer dtype.

Filtering¶

numpy.convolve(a: ndarray, v: ndarray) → ndarray¶: Return the discrete linear convolution of two 1-D arrays. Only "full" mode is supported; the numpy mode keyword is not accepted (other modes can be obtained by slicing the full result). The output length is len(a) + len(v) - 1.

Polynomial¶

numpy.polyfit(x: ndarray | list | tuple, y: ndarray | list | tuple, deg: int) → ndarray¶

numpy.polyfit(y: ndarray | list | tuple, deg: int) → ndarray: Fit a polynomial of degree deg to the data points (x, y) by least squares and return the polynomial coefficients (highest degree first). If x is omitted, range(len(y)) is used. Raises ValueError if the lengths of x and y differ.

numpy.polyval(p: ndarray | list | tuple, x: ndarray | list | tuple | int | float) → ndarray | float¶: Evaluate the polynomial whose coefficients are p (highest degree first) at x. If x is a scalar a float is returned, otherwise an ndarray.

I/O¶

numpy.load(file: str) → ndarray¶: Read an array previously written with save from file (numpy’s platform-independent .npy format). Endianness is converted on the fly if the file’s byte order differs from the host’s.

numpy.loadtxt(file: str, *, delimiter: str | None = None, comments: str = '#', max_rows: int = -1, usecols: int | ndarray | list | tuple | None = None, dtype: int = float, skiprows: int = 0) → ndarray¶: Read numeric data from a text file and return it as an ndarray. delimiter defaults to whitespace; comments is the line-comment marker; max_rows limits the number of data rows read (-1 for all); usecols selects columns by index; skiprows skips that many leading rows. If dtype is not float, values are converted by rounding.

numpy.save(file: str, a: ndarray) → None¶: Save a to file in numpy’s platform-independent .npy format.

numpy.savetxt(file: str, a: ndarray, *, delimiter: str = ' ', header: str | None = None, footer: str | None = None, comments: str = '# ') → None¶: Write a to file as text. delimiter separates values within a row; header and footer, if provided, are written before/after the data, each prefixed by comments. Values are written as floating point.

Universal functions¶

Element-wise math functions. Each accepts a scalar or an ndarray and returns a result of matching shape (a float scalar for scalar input, an ndarray for array input). When called with an ndarray, the result is a new floating point ndarray; an optional out keyword may be passed to write the result into a pre-allocated float ndarray of the same size.

numpy.acos(x: ndarray | float, /) → ndarray | float¶: Compute the inverse cosine (arc cosine) of each element of x; result is in radians.

numpy.acosh(x: ndarray | float, /) → ndarray | float¶: Compute the inverse hyperbolic cosine of each element of x.

numpy.arctan2(y: ndarray | float, x: ndarray | float, /) → ndarray | float¶: Compute the two-argument inverse tangent atan2(y, x) element-wise; supports broadcasting between the two inputs.

numpy.around(x: ndarray, /, decimals: int = 0) → ndarray¶: Round the elements of the ndarray x to the given number of decimals; the first argument must be an ndarray.

numpy.asin(x: ndarray | float, /) → ndarray | float¶: Compute the inverse sine (arc sine) of each element of x; result is in radians.

numpy.asinh(x: ndarray | float, /) → ndarray | float¶: Compute the inverse hyperbolic sine of each element of x.

numpy.atan(x: ndarray | float, /) → ndarray | float¶: Compute the inverse tangent (arc tangent) of each element of x; result is in radians.

numpy.atanh(x: ndarray | float, /) → ndarray | float¶: Compute the inverse hyperbolic tangent of each element of x.

numpy.ceil(x: ndarray | float, /) → ndarray | float¶: Compute the ceiling (smallest integer not less than the value) of each element of x.

numpy.cos(x: ndarray | float, /) → ndarray | float¶: Compute the cosine of each element of x (in radians).

numpy.cosh(x: ndarray | float, /) → ndarray | float¶: Compute the hyperbolic cosine of each element of x.

numpy.degrees(x: ndarray | float, /) → ndarray | float¶: Convert each element of x from radians to degrees.

numpy.exp(x: ndarray | float, /) → ndarray | float¶: Compute the exponential e**x of each element of x.

numpy.expm1(x: ndarray | float, /) → ndarray | float¶: Compute exp(x) - 1 of each element of x with improved precision near zero.

numpy.floor(x: ndarray | float, /) → ndarray | float¶: Compute the floor (largest integer not greater than the value) of each element of x.

numpy.log(x: ndarray | float, /) → ndarray | float¶: Compute the natural logarithm of each element of x.

numpy.log10(x: ndarray | float, /) → ndarray | float¶: Compute the base-10 logarithm of each element of x.

numpy.log2(x: ndarray | float, /) → ndarray | float¶: Compute the base-2 logarithm of each element of x.

numpy.radians(x: ndarray | float, /) → ndarray | float¶: Convert each element of x from degrees to radians.

numpy.sin(x: ndarray | float, /) → ndarray | float¶: Compute the sine of each element of x (in radians).

numpy.sinc(x: ndarray | float, /) → ndarray | float¶: Compute the normalized sinc function sin(pi*x) / (pi*x) of each element of x.

numpy.sinh(x: ndarray | float, /) → ndarray | float¶: Compute the hyperbolic sine of each element of x.

numpy.sqrt(x: ndarray | float, /, *, dtype: int = float) → ndarray | float¶: Compute the square root of each element of x.

numpy.tan(x: ndarray | float, /) → ndarray | float¶: Compute the tangent of each element of x (in radians).

numpy.tanh(x: ndarray | float, /) → ndarray | float¶: Compute the hyperbolic tangent of each element of x.

numpy.vectorize(f: Callable[[float], float], /, *, otypes: int | None = None) → Callable¶: Return a callable that applies the Python function f element-wise to a scalar, iterable, or ndarray; otypes selects the output dtype (default float).

Constants¶

numpy.e: float¶: Euler’s number \(e \approx 2.71828\).

numpy.pi: float¶: \(\pi \approx 3.14159\).

numpy.inf: float¶: IEEE-754 floating-point positive infinity.

numpy.nan: float¶: IEEE-754 floating-point “not a number”.

numpy.bool: int¶: Dtype code for boolean arrays (stored as uint8).

numpy.uint8: int¶: Dtype code for unsigned 8-bit integer arrays.

numpy.int8: int¶: Dtype code for signed 8-bit integer arrays.

numpy.uint16: int¶: Dtype code for unsigned 16-bit integer arrays.

numpy.int16: int¶: Dtype code for signed 16-bit integer arrays.

numpy.float: int¶: Dtype code for 32-bit floating-point arrays.

numpy — numpy-compatible array operations¶