Python API Reference

Classes

rustynum.NumArray(data, dtype=None)

A high-performance numerical array implementation backed by Rust.

Provides NumPy-like functionality with optimized operations for numerical computing. Supports multiple data types including float32, float64, and uint8.

Examples:

>>> # Create a 2D array
>>> arr = NumArray([[1.0, 2.0], [3.0, 4.0]])
>>> print(arr.shape)
[2, 2]

>>> # Matrix multiplication
>>> result = arr @ arr
>>> print(result.tolist())
[[7.0, 10.0], [15.0, 22.0]]

Initialize a NumArray with data and optional data type.

Parameters:

Name	Type	Description	Default
data	Union[List[Any], NumArray]	Nested list of numerical data or existing NumArray.	required
dtype	Optional[str]	Data type ('float32', 'float64', 'uint8'). If None, dtype is inferred.	None

Raises:

Type	Description
ValueError	If dtype is unsupported or data is invalid.
NotImplementedError	If dtype is not yet implemented.

Examples:

>>> arr = NumArray([[1, 2], [3, 4]], dtype='float32')
>>> arr2 = NumArray([1.0, 2.0, 3.0])  # dtype inferred as float32

shape property

Get the shape of the array.

Returns:

Type	Description
List[int]	List of integers representing the dimensions of the array.

Examples:

>>> arr = NumArray([[1, 2, 3], [4, 5, 6]])
>>> arr.shape
[2, 3]

__getitem__(key)

Get item(s) at the specified index or slice.

Supports single-axis flipping using slice with step=-1.

Parameters:

Name	Type	Description	Default
key	Union[int, slice, Tuple[Any, ...]]	Index, slice, or tuple of indices/slices for access.	required

Returns:

Type	Description
NumArray	New NumArray with the sliced data.

Raises:

Type	Description
IndexError	If index is out of bounds.
TypeError	If index type is unsupported.
NotImplementedError	If slice step is not supported.

__str__()

Return string representation of the array data.

__repr__()

Return detailed string representation of the NumArray.

__matmul__(other)

Matrix multiplication using @ operator.

Parameters:

Name	Type	Description	Default
other	NumArray	Another NumArray for matrix multiplication.	required

Returns:

Type	Description
NumArray	New NumArray containing the result of matrix multiplication.

__rmatmul__(other)

Right matrix multiplication using @ operator.

Parameters:

Name	Type	Description	Default
other	NumArray	Another NumArray for matrix multiplication.	required

Returns:

Type	Description
NumArray	New NumArray containing the result of matrix multiplication.

item()

Extract a scalar from a single-element array.

Returns:

Type	Description
Union[int, float]	The scalar value from the array.

Raises:

Type	Description
ValueError	If array contains more than one element.

Examples:

>>> arr = NumArray([42.0])
>>> arr.item()
42.0

reshape(shape)

Return a new array with the specified shape.

Parameters:

Name	Type	Description	Default
shape	List[int]	New shape for the NumArray.	required

Returns:

Type	Description
NumArray	New NumArray with the reshaped data.

Examples:

>>> arr = NumArray([1, 2, 3, 4])
>>> reshaped = arr.reshape([2, 2])
>>> reshaped.shape
[2, 2]

matmul(other)

Compute matrix multiplication with another NumArray.

Parameters:

Name	Type	Description	Default
other	NumArray	Another NumArray for matrix multiplication.	required

Returns:

Type	Description
NumArray	New NumArray containing the result of matrix multiplication.

Raises:

Type	Description
ValueError	If dtypes don't match or arrays aren't 2D.

Examples:

>>> a = NumArray([[1, 2], [3, 4]])
>>> b = NumArray([[5, 6], [7, 8]])
>>> result = a.matmul(b)
>>> result.tolist()
[[19, 22], [43, 50]]

dot(other)

Compute dot product with another NumArray.

Parameters:

Name	Type	Description	Default
other	NumArray	Another NumArray for dot product computation.	required

Returns:

Type	Description
NumArray	New NumArray containing the result of the dot product.

Raises:

Type	Description
ValueError	If dtypes don't match or operation is unsupported.

mean(axis=None)

Compute the arithmetic mean along specified axis.

Parameters:

Name	Type	Description	Default
axis	Optional[Union[int, Sequence[int]]]	Axis or axes along which to compute the mean. If None, compute mean of all elements.	None

Returns:

Type	Description
Union[NumArray, float]	NumArray with mean values along specified axis, or scalar if axis is None.

Examples:

>>> arr = NumArray([[1, 2], [3, 4]])
>>> arr.mean()  # Mean of all elements
2.5
>>> arr.mean(axis=0).tolist()  # Mean along axis 0
[2.0, 3.0]

median(axis=None)

Compute the median along specified axis.

Parameters:

Name	Type	Description	Default
axis	Optional[Union[int, Sequence[int]]]	Axis or axes along which to compute the median. If None, compute median of all elements.	None

Returns:

Type	Description
Union[NumArray, float]	NumArray with median values along specified axis, or scalar if axis is None.

min(axis=None)

Return the minimum along specified axis.

Parameters:

Name	Type	Description	Default
axis	Optional[Union[int, Sequence[int]]]	Axis or axes along which to find the minimum. If None, return minimum of all elements.	None

Returns:

Type	Description
Union[NumArray, float]	NumArray with minimum values along specified axis, or scalar if axis is None.

max(axis=None)

Return the maximum along specified axis.

Parameters:

Name	Type	Description	Default
axis	Optional[Union[int, Sequence[int]]]	Axis or axes along which to find the maximum. If None, return maximum of all elements.	None

Returns:

Type	Description
Union[NumArray, float]	NumArray with maximum values along specified axis, or scalar if axis is None.

__imul__(scalar)

In-place multiplication by a scalar.

Parameters:

Name	Type	Description	Default
scalar	Union[int, float]	Scalar value to multiply by.	required

Returns:

Type	Description
NumArray	Self (modified in-place).

__add__(other)

Add another NumArray or scalar to this array.

Parameters:

Name	Type	Description	Default
other	Union[NumArray, int, float]	NumArray or scalar to add.	required

Returns:

Type	Description
NumArray	New NumArray with the result of the addition.

Raises:

Type	Description
ValueError	If dtypes don't match between arrays.
TypeError	If operand type is unsupported.

__mul__(other)

Multiply this array by another NumArray or scalar.

Parameters:

Name	Type	Description	Default
other	Union[NumArray, int, float]	NumArray or scalar to multiply by.	required

Returns:

Type	Description
NumArray	New NumArray with the result of the multiplication.

Raises:

Type	Description
ValueError	If dtypes don't match between arrays.
TypeError	If operand type is unsupported.

__sub__(other)

Subtract another NumArray or scalar from this array.

Parameters:

Name	Type	Description	Default
other	Union[NumArray, int, float]	NumArray or scalar to subtract.	required

Returns:

Type	Description
NumArray	New NumArray with the result of the subtraction.

Raises:

Type	Description
ValueError	If dtypes don't match between arrays.
TypeError	If operand type is unsupported.

__truediv__(other)

Divide this array by another NumArray or scalar.

Parameters:

Name	Type	Description	Default
other	Union[NumArray, int, float]	NumArray or scalar to divide by.	required

Returns:

Type	Description
NumArray	New NumArray with the result of the division.

Raises:

Type	Description
ValueError	If dtypes don't match between arrays.
TypeError	If operand type is unsupported.

tolist()

Convert the NumArray to a nested Python list.

Returns:

Type	Description
List[Any]	Nested list representation of the array data.

Examples:

>>> arr = NumArray([[1, 2], [3, 4]])
>>> arr.tolist()
[[1.0, 2.0], [3.0, 4.0]]

exp()

Compute the exponential of all elements.

Returns:

Type	Description
NumArray	New NumArray with exponential of all elements.

Examples:

>>> arr = NumArray([0, 1, 2])
>>> result = arr.exp()
>>> # result contains [1.0, 2.718..., 7.389...]

log()

Compute the natural logarithm of all elements.

Returns:

Type	Description
NumArray	New NumArray with natural logarithm of all elements.

sigmoid()

Compute the sigmoid function of all elements.

Returns:

Type	Description
NumArray	New NumArray with sigmoid of all elements.

Note

Sigmoid function: 1 / (1 + exp(-x))

concatenate(other, axis)

Concatenate with another NumArray along specified axis.

Parameters:

Name	Type	Description	Default
other	NumArray	Another NumArray to concatenate with.	required
axis	int	Axis along which to concatenate.	required

Returns:

Type	Description
NumArray	New NumArray containing the concatenated data.

Raises:

Type	Description
ValueError	If dtypes don't match or shapes are incompatible.

flip(axis)

Flip the array along specified axis or axes.

Parameters:

Name	Type	Description	Default
axis	Union[int, Sequence[int]]	Axis or axes to flip along.	required

Returns:

Type	Description
NumArray	New NumArray with flipped data.

Raises:

Type	Description
TypeError	If axis type is invalid.

slice(axis, start, stop)

Slice the array along a specified axis.

Parameters:

Name	Type	Description	Default
axis	int	Axis to slice along.	required
start	Optional[int]	Starting index of the slice (None for beginning).	required
stop	Optional[int]	Stopping index of the slice (None for end).	required

Returns:

Type	Description
NumArray	New NumArray with sliced data.

norm(p=2, axis=None, keepdims=False)

Compute the matrix or vector norm.

Parameters:

Name	Type	Description	Default
p	int	Order of the norm (default: 2 for Euclidean norm).	2
axis	Optional[List[int]]	Axis or axes along which to compute the norm.	None
keepdims	bool	Whether to keep dimensions in the result.	False

Returns:

Type	Description
NumArray	New NumArray containing the computed norm.

Raises:

Type	Description
ValueError	If dtype is unsupported for norm computation.

Functions

rustynum.zeros(shape, dtype='float32')

Create a new array filled with zeros.

Parameters:

Name	Type	Description	Default
shape	List[int]	Shape of the new array as a list of integers.	required
dtype	str	Data type ('float32' or 'float64').	'float32'

Returns:

Type	Description
NumArray	New NumArray filled with zeros.

Raises:

Type	Description
ValueError	If dtype is unsupported.

Examples:

>>> import rustynum as rn
>>> arr = rn.zeros([2, 3])
>>> arr.shape
[2, 3]
>>> arr.tolist()
[[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]

rustynum.ones(shape, dtype='float32')

Create a new array filled with ones.

Parameters:

Name	Type	Description	Default
shape	List[int]	Shape of the new array as a list of integers.	required
dtype	str	Data type ('float32' or 'float64').	'float32'

Returns:

Type	Description
NumArray	New NumArray filled with ones.

Raises:

Type	Description
ValueError	If dtype is unsupported.

Examples:

>>> import rustynum as rn
>>> arr = rn.ones([2, 2])
>>> arr.tolist()
[[1.0, 1.0], [1.0, 1.0]]

rustynum.arange(start, stop, step=1.0, dtype='float32')

Create an array with evenly spaced values within a given interval.

Parameters:

Name	Type	Description	Default
start	float	Start of the interval (inclusive).	required
stop	float	End of the interval (exclusive).	required
step	float	Spacing between values.	1.0
dtype	str	Data type ('float32' or 'float64').	'float32'

Returns:

Type	Description
NumArray	New NumArray with evenly spaced values.

Raises:

Type	Description
ValueError	If dtype is unsupported.

Examples:

>>> import rustynum as rn
>>> arr = rn.arange(0, 10, 2)
>>> arr.tolist()
[0.0, 2.0, 4.0, 6.0, 8.0]

rustynum.linspace(start, stop, num, dtype='float32')

Create an array with evenly spaced values over a specified interval.

Parameters:

Name	Type	Description	Default
start	float	Start of the interval (inclusive).	required
stop	float	End of the interval (inclusive).	required
num	int	Number of samples to generate.	required
dtype	str	Data type ('float32' or 'float64').	'float32'

Returns:

Type	Description
NumArray	New NumArray with evenly spaced values.

Raises:

Type	Description
ValueError	If dtype is unsupported.

Examples:

>>> import rustynum as rn
>>> arr = rn.linspace(0, 1, 5)
>>> arr.tolist()
[0.0, 0.25, 0.5, 0.75, 1.0]

rustynum.mean(a)

Compute the arithmetic mean of array elements.

Parameters:

Name	Type	Description	Default
a	Union[NumArray, int, float]	Input array or scalar value.	required

Returns:

Type	Description
Union[NumArray, float]	The mean value as NumArray or float.

Raises:

Type	Description
TypeError	If input type is unsupported.

Examples:

>>> import rustynum as rn
>>> arr = rn.NumArray([1, 2, 3, 4])
>>> rn.mean(arr)
2.5

rustynum.median(a)

Compute the median of array elements.

Parameters:

Name	Type	Description	Default
a	Union[NumArray, int, float]	Input array or scalar value.	required

Returns:

Type	Description
Union[NumArray, float]	The median value as NumArray or float.

Raises:

Type	Description
TypeError	If input type is unsupported.

rustynum.min(a)

Return the minimum value of array elements.

Parameters:

Name	Type	Description	Default
a	Union[NumArray, int, float]	Input array or scalar value.	required

Returns:

Type	Description
Union[NumArray, float]	The minimum value as NumArray or float.

Raises:

Type	Description
TypeError	If input type is unsupported.

rustynum.max(a)

Return the maximum value of array elements.

Parameters:

Name	Type	Description	Default
a	Union[NumArray, int, float]	Input array or scalar value.	required

Returns:

Type	Description
Union[NumArray, float]	The maximum value as NumArray or float.

Raises:

Type	Description
TypeError	If input type is unsupported.

rustynum.dot(a, b)

Compute dot product of two arrays or scalars.

Parameters:

Name	Type	Description	Default
a	Union[NumArray, int, float]	First input array or scalar.	required
b	Union[NumArray, int, float]	Second input array or scalar.	required

Returns:

Type	Description
Union[float, NumArray]	Dot product result as NumArray or scalar.

Raises:

Type	Description
TypeError	If input types are unsupported.

Examples:

>>> import rustynum as rn
>>> a = rn.NumArray([1, 2, 3])
>>> b = rn.NumArray([4, 5, 6])
>>> result = rn.dot(a, b)
>>> # result is 1*4 + 2*5 + 3*6 = 32

rustynum.exp(a)

Compute the exponential of all elements in the input.

Parameters:

Name	Type	Description	Default
a	Union[NumArray, int, float]	Input array or scalar value.	required

Returns:

Type	Description
NumArray	New NumArray with exponential of all elements.

Raises:

Type	Description
TypeError	If input type is unsupported.

Examples:

>>> import rustynum as rn
>>> arr = rn.NumArray([0, 1, 2])
>>> result = rn.exp(arr)
>>> # result contains [1.0, 2.718..., 7.389...]

rustynum.log(a)

Compute the natural logarithm of all elements in the input.

Parameters:

Name	Type	Description	Default
a	Union[NumArray, int, float]	Input array or scalar value.	required

Returns:

Type	Description
NumArray	New NumArray with natural logarithm of all elements.

Raises:

Type	Description
TypeError	If input type is unsupported.

rustynum.sigmoid(a)

Compute the sigmoid function of all elements in the input.

The sigmoid function is defined as: 1 / (1 + exp(-x))

Parameters:

Name	Type	Description	Default
a	Union[NumArray, int, float]	Input array or scalar value.	required

Returns:

Type	Description
NumArray	New NumArray with sigmoid of all elements.

Raises:

Type	Description
TypeError	If input type is unsupported.

Examples:

>>> import rustynum as rn
>>> arr = rn.NumArray([-1, 0, 1])
>>> result = rn.sigmoid(arr)
>>> # result contains [0.268..., 0.5, 0.731...]

rustynum.concatenate(arrays, axis=0)

Join a sequence of arrays along an existing axis.

Parameters:

Name	Type	Description	Default
arrays	List[NumArray]	List of NumArray objects to concatenate.	required
axis	int	Axis along which to concatenate (typically 0 or 1).	0

Returns:

Type	Description
NumArray	New NumArray containing the concatenated data.

Raises:

Type	Description
TypeError	If not all elements are NumArray instances.
ValueError	If dtypes don't match or concatenation is unsupported.

Examples:

>>> import rustynum as rn
>>> a = rn.NumArray([[1, 2], [3, 4]])
>>> b = rn.NumArray([[5, 6], [7, 8]])
>>> result = rn.concatenate([a, b], axis=0)
>>> result.shape
[4, 2]

rustynum.norm(a, p=2, axis=None, keepdims=False)

Compute matrix or vector norm.

Parameters:

Name	Type	Description	Default
a	NumArray	Input array.	required
p	int	Order of the norm (default: 2 for Euclidean norm).	2
axis	Optional[List[int]]	Axis or axes along which to compute the norm.	None
keepdims	bool	Whether to keep dimensions in the result.	False

Returns:

Type	Description
NumArray	New NumArray containing the computed norm.

Raises:

Type	Description
ValueError	If dtype is unsupported for norm computation.

Examples:

>>> import rustynum as rn
>>> arr = rn.NumArray([3, 4])
>>> result = rn.norm(arr)  # Euclidean norm
>>> # result is 5.0 (sqrt(3^2 + 4^2))