3. Dimensions#

class Dimensions(dim_pwrs: list | ndarray[tuple[int, ...], dtype[_ScalarType_co]])#

Bases: object

Defines relationships between fundamental physical quantities. Provides dimensional information for the main purpose of creating units.

These quantities are derived from three of the SI unit system’s base units [1]: Mass from the kilogram, Length from the meter, and Time from the second. Additionaly, a fourth “dimension” — Angle — is included due to its relevance to many unitary applications despite the inherent non-dimensionality of angles.

Summarily, these quantities are:

  1. Mass

  2. Length

  3. Time

  4. Angle

And their power relations are stored in a 1x4 power vector where each element corresponds to the above dimensions in the same order.

Parameters:

dim_pwrs (list or numpy.ndarray) –

A 1x4 vector of integers representing the power relations to each of the four physical dimensions defined by the Dimensions class as:

[Mass, Length, Time, Angle]

For example, the power vector of force would be given as:

[1, 1, -2, 0]

Where force is defined as Mass multiplied by Length per Time squared. Angles do not contribute to this dimension and so are given a zero power.

See also

scarabaeus.Units

Utilizes Dimensions in its construction.

scarabaeus.ArrayWUnits

Dependent on Units and Dimensions.

Notes

The property name is automatically generated upon intialization as a string that either provides the name of the dimension if one exists (e.g. square length is known as area) or, in the case no name exists, a description of the dimensional relations in words. For example, assume that velocity is not a named dimension: name would then be assigned 'Length per Time' .

Dimensions determines if a name exists by mapping the given power vector to one in its internal library of named dimensional combinations. The method disp_named_dims() displays a formatted list of all existing named dimensions and their respective power vectors.

Even if a list is passed to dim_pwrs as an argument during construction, Dimensions will automatically convert it to an np.array when ingesting and storing to the property powers . This means that when powers is requested, no matter the type passed on construction, a 1x4 np.array will always be returned.

References

Examples

Dimensions objects can be constructed with list or np.array objects:

# initial setup
import scarabaeus as scb
import numpy as np

# initialize with a list...
area_dim = scb.Dimensions([0, 2, 0, 0])

# ... or a numpy array
comp_dim = scb.Dimensions(np.array([3, 0, -2, 1]))

The names of Dimensions objects are automatically generated upong construction. From the above example:

# named dimensions
area_dim.name

>>> 'Area'

# compound dimensions
comp_dim.name

>>> 'Cubic Mass times Angle per Square Time'

Attributes

name

The dimension that the Dimensions object represents.

powers

1x4 vector describing the Dimension object's power relation to each of the four base dimensions.

Methods

def_new_named_dim(name, powers)

Adds a new named dimension to the Dimensions library.

disp_named_dims()

Method to display all existing named dimensions and their respective dimensional power vectors.
classmethod def_new_named_dim(name: str, powers: ndarray | list) → None#

Adds a new named dimension to the Dimensions library.

Parameters:

  • name (str) – The name of the new dimension to be saved in the Dimensions library.

  • powers (numpy array or list) – The dimensional powers corresponding to the given name.

Return type:

None

Notes

When defining a new named dimension, remember to follow the naming convention adopted by the class’ built-in named dimensions: capitalize the first letter of each word in name.

Examples

# initial setup
import scarabaeus as scb

# attach a name to a new dimension
scb.Dimensions.def_new_named_dims('My New Dim', [1, 1, 1, 1])

# create a Dimensions object of the new dimension
new_dim = scb.Dimensions([1 ,1, 1, 1])
>>> My New Dim
classmethod disp_named_dims() → None#

Method to display all existing named dimensions and their respective dimensional power vectors.

Includes base dimensions.

Return type:

None

property name: str#

The dimension that the Dimensions object represents. For named dimensions (e.g. Area or Force), that is their common name. For unnamed dimensions, that is their power relation in words (e.g. Length per Time or Mass times Angle).

property powers: ndarray#

1x4 vector describing the Dimension object’s power relation to each of the four base dimensions.