Skip to content

Classes & Functions

SIObject(value: float | Any, unit: list[int])

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.
value_in

Return the numeric value expressed in specified unit.
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() -> Self

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() -> Self

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: Self) -> bool

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.
    """
    ...

value_in(unit: Self) -> float | Any

Return the numeric value expressed in specified unit.

The underlying value (float, numpy.ndarray, torch.tensor, ...) is divided by unit and returned without the unit wrapper.

PARAMETER DESCRIPTION
unit

A quantity describing target unit (e.g. KILO * WATT * HOUR).

TYPE: Self

RETURNS DESCRIPTION
float | Any

The numeric value of self expressed in unit.
RAISES DESCRIPTION
RuntimeError

When self and unit have incompatible units.

Examples:

>>> from si_units import JOULE, KILO, WATT, HOUR
>>> energy = 5.4e6 * JOULE
>>> energy.value_in(KILO * WATT * HOUR)
1.5
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
102
103
104
105
106
107
def value_in(self, unit: Self) -> float | Any:
    """Return the numeric value expressed in specified unit.

    The underlying value (float, numpy.ndarray, torch.tensor, ...)
    is divided by unit and returned without the unit wrapper.

    Args:
        unit: A quantity describing target unit (e.g. KILO * WATT * HOUR).

    Returns:
        The numeric value of self expressed in unit.

    Raises:
        RuntimeError: When self and unit have incompatible units.

    Examples:
        >>> from si_units import JOULE, KILO, WATT, HOUR
        >>> energy = 5.4e6 * JOULE
        >>> energy.value_in(KILO * WATT * HOUR)
        1.5
    """
    ...

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.

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 
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
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: SIObject, end: SIObject, n: int) -> SIObject

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 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
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: SIObject, end: SIObject, n: int) -> SIObject

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 
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
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.
    """
    ...