1. ArrayWUnits#

class ArrayWUnits(values: int | float | list | ndarray[tuple[int, ...], dtype[_ScalarType_co]], units: Units | list[Units] | ndarray[Units] | None)#

Bases: object

Defines a representation of numerical values and their associated units.

The values and units are attached and computed together during mathematical operations. Supports scalar and matrix definitions.

Note that “scalar” definitions are still treated as 1x1 matrices internally.

Parameters:

  • values (int | float | list | numpy.ndarray) –

    The numerical value or values of the associated object. Accepts scalar or matrix/vector inputs:

    • int or float - a scalar value

    • np.ndarray - a matrix or vector of values

  • units (Unit | list[Unit] | numpy.ndarray[Units]) –

    The units associated with the given numerical value or values. If a single Unit object is passed, then all numerical values are assumed to be the same unit.

    To assign separate units to individual elements in a given numerical matrix/vector, pass either a list or np.ndarray with the same size as the numerical values. Each element of this list or np.ndarray should be the desired Unit of the corresponding element in the given numerical values.

See also

scarabaeus.Unit

Scarabaeus-defined representation of physical units.

scarabaeus.Dimensions

Scarabaeus-defined representation of physical dimensions.

Notes

While both values and units can optionally be given as multiple different object types, internally they are always converted to np.ndarray objects to ensure numpy functionality.

Examples

Create a scalar value with associated units:

# initial setup
import scarabaeus as scb
import numpy as np

# generate units
km = scb.Units.get_units('km')

# 10 kilometers
km_10 = scb.ArrayWUnits(10, km)

>>> print(km_10)
10 km

Create a vector of values with different units:

# generate units
km, sec, rad = scb.Units.get_units(['km', 'sec', 'rad'])

# define values
vals = [[1], [2], [3]]

# and units
units = [[km], [sec], [rad]]

# column vector representing [1 km; 2 sec; 3 rad]
col_vec = scb.ArrayWUnits(vals, units)

>>> print(col_vec)
[[1]  [[km]
 [2]   [sec]
 [3]]  [rad]]

Attributes

homogeneous_units

Boolean flag indicating whether or not all units are homogeneous or not.

shape

The number of columns and rows within the ArrayWUnits object.

size

The number of elements contained within the ArrayWUnits object.

units

The unit or units associated with the object.

values

The numerical value or values associated with the object.

Methods

angle_between(other)

CONSIDER REMOVING THIS FROM AWU AS IT IS NOT DEPENDENT ON AWU

append(other[, axis])

Return an ArrayWUnits object with given ArrayWUnits object appended to the back.

are_shapes_compatible(other)

Check if the shapes of self and other are compatible to perform operations between them.

atleast_1d(awu_in)

WORK IN PROGRESS

atleast_2d([awu_in])

Rescast the ArrayWUnits object as arrays with atleast two dimensions.

atleast_3d(awu_in)

NOT YET IMPLEMENTED

convert_to(to_convert_to)

Convert all elements of an ArrayWUnits object to the given units.

cos()

Trigonometric cosine operator for ArrayWUnits objects.

cross(other)

Cross product operation between two ArrayWUnits objects.

empty(shape)

Initializes a new ArrayWUnits object of the given shape without initializing value entries.

exp()

Exponential operator for ArrayWUnits objects.

exp2()

Exponential base 2 operator for ArrayWUnits objects.

eye(n[, units, diag_units, m, k])

NOT YET IMPLEMENTED

get_shape()

Retrieve the shape of an input ArrayWUnits.

inverse()

Inverse operator for ArrayWUnits objects.

is_array_numerical(array_in)

Checks if a given array contains numerical values or not.

log()

Natural log operator for ArrayWUnits objects.

log10()

Log base 10 operator for ArrayWUnits objects.

log2()

Log base 2 operator for ArrayWUnits objects.

max(other)

WORK IN PROGRESS

norm()

Matrix or vector norm operator for ArrayWUnits objects.

pseudo_inverse()

Pseudo-inverse operator for ArrayWUnits objects.

sin()

Trigonometric sine operator for ArrayWUnits objects.

summation()

Sum all elements in the ArrayWUnits object, if units allow.

tan()

Trigonometric tangent operator for ArrayWUnits objects.

to_homog_units()

WORK IN PROGRESS

transpose()

Transpose operator for ArrayWUnits objects.

unitary()

Converts a given ArrayWUnits vector into a unit vector with the same units.

units_arithmetic(other, operation)

Internal method holding all
static empty(shape: int | tuple[int, int]) → Self#

Initializes a new ArrayWUnits object of the given shape without initializing value entries. Units are set as unitless.

ArrayWUnits equivalent of Numpy empty() function.

Parameters:

shape (int | tuple[int, int]) – The shape of the empty ArrayWUnits. One-dimensional arrays should be given as integers while n-dimensional arrays should be given as a tuple of integers.

Returns:

out – An ArrayWUnits object of given shape with empty values and unitless units.

Return type:

ArrayWUnits

References

https://numpy.org/doc/2.1/reference/generated/numpy.empty.html

static eye(n: int, units: Units | list[Units] | ndarray[Units] = None, diag_units: Units | list[Units] | ndarray[Units] = None, m: int = None, k: int = None) → Self#

NOT YET IMPLEMENTED

ArrayWUnits equivalent of Numpy eye() function.

Parameters:

  • n (int) – NEED DESC

  • units (Units | list[Units] | np.array[Units], optional) –

    Units assigned to all elements in the ArrayWUnits object. Dependent on object type given:

    • Units: Homogeneously united ArrayWUnits object of the given unit.

    • list or np.array of Units:

  • diag_units (Units | list[Units] | np.array[Units], optional) – Units assigned to the diagonal only. If diag_units are given, all other units are assigned unitless.

Returns:

out – NEED DESC

Return type:

ArrayWUnits

References

https://numpy.org/devdocs/reference/generated/numpy.eye.html

static is_array_numerical(array_in: ndarray) → bool#

Checks if a given array contains numerical values or not.

Parameters:

array_in (np.ndarray) – The array to examine.

Returns:

is_numerical – The numerical status of the examined array. Returns True if the array is numerical and False if it is not.

Return type:

bool

angle_between(other)#

CONSIDER REMOVING THIS FROM AWU AS IT IS NOT DEPENDENT ON AWU

Angle between two vectors

append(other: Self, axis: int = None) → Self#

Return an ArrayWUnits object with given ArrayWUnits object appended to the back.

ArrayWUnits equivalent of Numpy append() function.

Parameters:

  • other (ArrayWUnits) – The ArrayWUnits object to be appended.

  • axis (int, optional) – The axis along which given ArrayWUnits objects are added. If not given, both self and given ArrayWUnits object are flattened before appending. Defaults to None.

Returns:

out – ArrayWUnits object with given ArrayWUnits appended to the end. If axis is None, out is is a flattened ArrayWUnits object.

Return type:

ArrayWUnits

References

Examples

Append two ArrayWUnits objects without specifying axis:

# initial setup
import scarabaeus as scb
import numpy as np

kg = scb.Units.get_units('kg')             # generate units

one = scb.ArrayWUnits([[1], [2], [3]], kg) # initialize AWU's
two = scb.ArrayWUnits(4, kg)

# no axis specified
one = one.append(two)

>>> print(one)
[1. 2. 3. 4.] [kg ... kg]              # flat AWU

Notice that, despite appending to a column vector, since no axis was given the return ArrayWUnits is a flattened row vector.

Append row vector to compatible matrix:

 1# initial setup
 2km, unitless = scb.Units.get_units(['km', 'unitless'])
 3
 4three_mat = np.array([[km      , unitless, unitless],
 5                      [unitless, km      , unitless],
 6                      [unitless, unitless, km      ]])
 7three     = scb.ArrayWUnits(np.eye(3), three_mat)
 8
 9four_row  = scb.ArrayWUnits(np.ones((1, 3)), km * np.ones((1, 3)))
10
11# equal rows -> append to first axis
12three_ax_0 = three.append(four_row, 0)
13
14>>> print(three_ax_0)
15[[1. 0. 0.]
16 [0. 1. 0.]
17 [0. 0. 1.]
18 [1. 1. 1.]] [non-homogeneous]

Append column vector to compatible matrix:

 1# initial setup
 2four_col  = scb.ArrayWUnits(np.ones((3, 1)), km * np.ones((3, 1)))
 3
 4# equal columns -> append to second axis
 5three_ax_1 = three.append(four_col, 1)
 6
 7>>> print(three_ax_1)
 8[[1. 0. 0. 1.]
 9 [0. 1. 0. 1.]
10 [0. 0. 1. 1.]] [non-homogeneous]
are_shapes_compatible(other) → bool#

Check if the shapes of self and other are compatible to perform operations between them.

Currently, ArrayWUnits supports three cases of operations:

  1. Operations between N-D arrays with the same shape

  2. Operations between an N-D array and a scalar

  3. Operations between a N-D array and a 1-D array whose size is equal to the size of the last dimension of the N-D array. This case comes in handy, for instance, to perform operations between a 3x1 array and a 3xN matrix.

Returns:

compatible – True if shapes are compatible, False if not.

Return type:

bool

atleast_1d(awu_in) → Self#

WORK IN PROGRESS

atleast_2d(awu_in: Self = None) → Self#

Rescast the ArrayWUnits object as arrays with atleast two dimensions.

ArrayWUnits equivalent of Numpy atleast_2d() function.

Parameters:

awu_in (ArrayWUnits, optional) – The AWU to recast.

Returns:

out – The recast AWU.

Return type:

ArrayWUnits

References

https://numpy.org/doc/stable/reference/generated/numpy.atleast_2d.html

atleast_3d(awu_in) → Self#

NOT YET IMPLEMENTED

convert_to(to_convert_to: Units) → Self#

Convert all elements of an ArrayWUnits object to the given units.

Valid for ArrayWUnits objects containing non-homogeneous units as long as those units are all of the same dimension.

Parameters:

to_convert_to (Units) – The desired unit the ArrayWUnits is to be converted to.

Returns:

converted – The ArrayWUnits object with converted units.

Return type:

ArrayWUnits

Examples

Convert a week (7 days) to seconds and back to days:

# initial setup
import scarabaeus as scb

day, sec = scb.Units.get_units(['day', 'sec'])

week = scb.ArrayWUnits(7.0, day)

>>> print(week)
7.0 day

# convert days to seconds
week_sec = week.convert_to(sec)

>>> print(week_sec)
604800.0 sec

# and seconds back to days
week_days = week_sec.convert_to(day)

>>> print(week_days)
7.0 day

Convert a row vector [1 cm, 1 m, 1 km] to the equivalent values all defined in km [0.00001 km, 0.001 km, 1 km]:

# initial setup
cm, m, km = scb.Units.get_units(['cm', 'm', 'km'])

# array of different units with same dimensions
cm_m_km = scb.ArrayWUnits([1, 1, 1], [cm, m, km])

# convert all to kilometers
all_km = cm_m_km.convert_to(km)

>>> print(all_km)
[1.e-05 1.e-03 1.e+00] [km ... km]
cos() → Self#

Trigonometric cosine operator for ArrayWUnits objects.

cross(other: Self) → Self#

Cross product operation between two ArrayWUnits objects.

exp() → Self#

Exponential operator for ArrayWUnits objects.

exp2() → Self#

Exponential base 2 operator for ArrayWUnits objects.

get_shape()#

Retrieve the shape of an input ArrayWUnits.

inverse() → Self#

Inverse operator for ArrayWUnits objects.

Only valid for square matrices.

log() → Self#

Natural log operator for ArrayWUnits objects.

log10() → Self#

Log base 10 operator for ArrayWUnits objects.

log2() → Self#

Log base 2 operator for ArrayWUnits objects.

max(other)#

WORK IN PROGRESS

norm() → Self#

Matrix or vector norm operator for ArrayWUnits objects.

pseudo_inverse() → Self#

Pseudo-inverse operator for ArrayWUnits objects.

sin() → Self#

Trigonometric sine operator for ArrayWUnits objects.

summation() → Self#

Sum all elements in the ArrayWUnits object, if units allow.

tan() → Self#

Trigonometric tangent operator for ArrayWUnits objects.

to_homog_units() → None#

WORK IN PROGRESS

transpose() → Self#

Transpose operator for ArrayWUnits objects.

unitary() → Self#

Converts a given ArrayWUnits vector into a unit vector with the same units.

Only valid for vectorial ArrayWUnits.

units_arithmetic(other, operation)#

Internal method holding all

property homogeneous_units: bool#

Boolean flag indicating whether or not all units are homogeneous or not.

True if all units are homogeneous. Otherwise False.

property shape: tuple[int, int]#

The number of columns and rows within the ArrayWUnits object.

property size: int#

The number of elements contained within the ArrayWUnits object.

property units: Units | ndarray[Units]#

The unit or units associated with the object.

The type is dependent on the homogeneity of the associated units:

  • Units object if the object is a scalar value or all values in the numerical matrix/vector are assigned the same units.

  • Numpy array of Units objects if the values in the numerical matrix/vector are not assigned the same units.

property values: ndarray#

The numerical value or values associated with the object.