Skip to content

Classes & Functions

SIObject(value, unit)

Combination of value and unit.

The value can be any Python object that can be used for arithmetic operations such as a float, numpy.ndarray or torch.tensor.

When a SIObject is divided by its unit, the value is returned. This is usefull to convert units or when operations are needed that are not implemented for SIObject.

Constructs a new quantity.

Don't use the default constructor

This constructor should not be used to construct a quantity. Instead, multiply the value (float or array of floats) by the appropriate unit. See example below.

PARAMETER DESCRIPTION
value

The numerical value(s). Can be a scalar or an array such as a numpy.ndarray or a torch.tensor.

TYPE: float | Any

unit

List of 7 exponents for SI base units.

TYPE: list[int]

RAISES DESCRIPTION
RuntimeError

When unit has the wrong format.

Examples:

>>> import si_units as si
>>> # don't do this:
>>> two_meters_init = si.SIObject(2.0, [1, 0, 0, 0, 0, 0, 0])
>>> # instead, do this:
>>> two_meters_mul = 2.0 * si.METER
>>> assert two_meters_init == two_meters_mul
METHOD DESCRIPTION
cbrt

Calculate the cubic root.
sqrt

Calculates the square root.
has_unit

Tests if the quantity has the same unit as the argument.
Source code in si-units/src/si_units/_core.pyi 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def __init__(self, value: float | Any, unit: list[int]) -> None:
    """Constructs a new quantity.

    Warning: Don't use the default constructor 
        This constructor should not be used to construct a quantity.
        Instead, multiply the value (float or array of floats)
        by the appropriate unit. See example below.

    Args:
        value:
            The numerical value(s). Can be a scalar or an array
            such as a numpy.ndarray or a torch.tensor.
        unit: List of 7 exponents for SI base units.

    Raises:
        RuntimeError: When unit has the wrong format.

    Examples:
        >>> import si_units as si
        >>> # don't do this:
        >>> two_meters_init = si.SIObject(2.0, [1, 0, 0, 0, 0, 0, 0])
        >>> # instead, do this:
        >>> two_meters_mul = 2.0 * si.METER
        >>> assert two_meters_init == two_meters_mul
    """
    ...

cbrt()

Calculate the cubic root.

RETURNS DESCRIPTION
Self

Cubic root of the quantity.
RAISES DESCRIPTION
RuntimeError

When exponents of units are not multiples of three.
AttributeError

When the inner data type has no 'cbrt' method.

Examples:

>>> from si_units import METER
>>> volume = METER**3
>>> length = volume.cbrt()
Source code in si-units/src/si_units/_core.pyi 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def cbrt(self) -> Self:
    """Calculate the cubic root.

    Returns:
        Cubic root of the quantity.

    Raises:
        RuntimeError: When exponents of units are not multiples of three.
        AttributeError: When the inner data type has no 'cbrt' method.

    Examples:
        >>> from si_units import METER
        >>> volume = METER**3
        >>> length = volume.cbrt()
    """
    ...

sqrt()

Calculates the square root.

RETURNS DESCRIPTION
Self

Square root of the quantity.
RAISES DESCRIPTION
RuntimeError

When exponents of units are not multiples of two.
AttributeError

When the inner data type has no 'sqrt' method.

Examples:

>>> from si_units import METER
>>> square = METER**2
>>> length = square.sqrt()
Source code in si-units/src/si_units/_core.pyi 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def sqrt(self) -> Self:
    """Calculates the square root.

    Returns:
        Square root of the quantity.

    Raises:
        RuntimeError: When exponents of units are not multiples of two.
        AttributeError: When the inner data type has no 'sqrt' method.

    Examples:
        >>> from si_units import METER
        >>> square = METER**2
        >>> length = square.sqrt()
    """
    ...

has_unit(other)

Tests if the quantity has the same unit as the argument.

PARAMETER DESCRIPTION
other

The quantity to compare to.

TYPE: Self

RETURNS DESCRIPTION
bool

Wheter the units of the compared quantities are the same or not.
Source code in si-units/src/si_units/_core.pyi 
75
76
77
78
79
80
81
82
83
84
def has_unit(self, other: Self) -> bool:
    """Tests if the quantity has the same unit as the argument.

    Args:
        other: The quantity to compare to.

    Returns:
        Wheter the units of the compared quantities are the same or not.
    """
    ...

array(value)

Build SIObject from scalar or list.

When the input is a scalar, it is stored in an array with a single element.

PARAMETER DESCRIPTION
value

Values to store. Must all have the same unit.

TYPE: SIObject | list[SIObject]

RETURNS DESCRIPTION
SIObject

The quantity with values stored within array, even if value is given as a scalar.
RAISES DESCRIPTION
RuntimeError

If the elements of value have different units.
Source code in si-units/src/si_units/_core.pyi 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def array(value: SIObject | list[SIObject]) -> SIObject:
    """Build SIObject from scalar or list.

    When the input is a scalar, it is stored in an array with a single element.

    Args:
        value: Values to store. Must all have the same unit.

    Returns:
        The quantity with values stored within array, 
            even if value is given as a scalar.

    Raises:
        RuntimeError: If the elements of value have different units.
    """
    ...

linspace(start, end, n)

Linearly spaced quantities.

PARAMETER DESCRIPTION
start

Lowest value.

TYPE: SIObject

end

Highest value.

TYPE: SIObject

n

The (positive) number of points.

TYPE: int

RETURNS DESCRIPTION
SIObject

Linearly spaced values with the same unit.
RAISES DESCRIPTION
RuntimeError

If start and end values are not scalars, if they don't have the same unit, or if n is not positive.
Source code in si-units/src/si_units/_core.pyi 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def linspace(start: SIObject, end: SIObject, n: int) -> SIObject:
    """Linearly spaced quantities.

    Args:
        start: Lowest value.
        end: Highest value.
        n: The (positive) number of points.

    Returns:
        Linearly spaced values with the same unit.

    Raises:
        RuntimeError:
            If start and end values are not scalars, if they don't have
            the same unit, or if n is not positive.
    """
    ...

logspace(start, end, n)

Logarithmically spaced quantities.

PARAMETER DESCRIPTION
start

Lowest value.

TYPE: SIObject

end

Highest value.

TYPE: SIObject

n

The (positive) number of points.

TYPE: int

RETURNS DESCRIPTION
SIObject

Logarithmically spaced values with the same unit.
RAISES DESCRIPTION
RuntimeError

If start and end values are not scalars, if they don't have the same unit, or if n is not positive.
Source code in si-units/src/si_units/_core.pyi 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def logspace(start: SIObject, end: SIObject, n: int) -> SIObject:
    """Logarithmically spaced quantities.

    Args:
        start: Lowest value.
        end: Highest value.
        n: The (positive) number of points.

    Returns:
        Logarithmically spaced values with the same unit.

    Raises:
        RuntimeError:
            If start and end values are not scalars, if they don't have
            the same unit, or if n is not positive.
    """
    ...