API Reference

Quantity

siquant.quantities.make(quantity, units)[source]

Entry point for creating quantities consistently

Parameters:
  • quantity (_T) – The value to tag with specific units.
  • units (SIUnit) – The units of this quantity.
Return type:

_Q = Quantity
siquant.quantities.are_of(dimensions, *quantities)[source]

Check if quantities all match dimensions.

Parameters:
  • dimensions (tuple) – The expected dimensionality.
  • quantities – Variadic. The instances to check against.
Return type:

bool
siquant.quantities.validator(dimensions)[source]

Create a validator function which checks if a value matches expected dimensions.

See also

Predefined dimensions.

Creating new SIDimensions().

Parameters:dimensions (tuple) – The expected dimensions.
Return type:Callable[[Any, ...], bool]
siquant.quantities.converter(units)[source]

Create a converter function which will return Quantities.

Parameters:units (SIUnit) – The units to convert a quantity to.
Return type:Callable[[Any], _Q]
class siquant.quantities.Quantity(quantity, units)[source]

Quantity wraps a value with units and provides arithmetic passthrough operations.

Note

Creation of Quantity directly is discouraged.

The preferred method are:

q = value * si.meters

q = make(value, si.meters)

Both of these methods delegate instantiation to factory in order to more easily support clean extensibility.

Variables:
  • quantity (_T) – The wrapped value. read only.
  • units (SIUnit) – The units of this quantity. read only.
Parameters:
  • quantity (_T) – The quantity to be wrapped.
  • units (SIUnit) – The units the quantity’s value is expressed in.
approx(other, rtol=1e-09, atol=1e-06)[source]
Raises:

TypeError if other is not a Quantity
Parameters:
  • other –
  • rtol –
  • atol –
Returns:
compatible(other)[source]
Parameters:other (_Q = Quantity) – The quantity to check for dimensional compatibility.
Return type:bool
cvt_to(units)[source]

Create an equivalent Quantity expressed in the provided units.

Parameters:units (SIUnit) – The units to express this quantity in.
Returns:_Q = Quantity
get_as(units)[source]

Extract the underlying quantity in express units.

Parameters:units (SIUnit) – The units to express the underlying value in.
Return type:_T
is_of(dimensions)[source]
Parameters:dimensions –
Returns:bool
round_as(units, places=0)[source]

Extract the underlying quantity rounded to express units.

Parameters:
  • units – The units to express the underlying value in.
  • places – The number of decimal places to round to.
Returns:

_T
round_to(units, places=0)[source]

Create an equivalent Quantity rounded in provided units.

Parameters:
  • units (SIUnit) – The units to express the quantity in.
  • places (int) – The number of decimal places to round to.
Return type:

_Q = Quantity

Units

class siquant.units.SIUnit(scale, dimensions)[source]

SIUnit is a scaling of SI base unit dimensions.

Variables:

factory (Callable[[_T, SIUnit], _Q]) –

Parameters:
  • scale (numbers.Real) – The scaling factor of base SI dimensions.
  • dimensions (tuple) – The base SI dimensions.
factory

The factory function which unit instances use to create quantities.

Note

SIUnit.factory is mapped to Quantity in __init__ by default. However, it is not required to be a type, and can be overwritten in client configuration.

It’s purpose is to provide a consistent way to wrap values, and allow simple extensibility.

make() is just a wrapper around this factory.

def ext_factory(q, u):
    if isinstance(q, Vector):
        return VectorQuantity(q, u)
    return Quantity(q, u)

SIUnit.factory = staticmethod(ext_factory)
static Unit(scale=1.0, kg=0, m=0, s=0, k=0, a=0, mol=0, cd=0)[source]

Create a new SIUnit with a scale of provided base units.

Parameters:
  • scale (numbers.Real) – The linear scaling factor of base units.
  • kg (numbers.Real) – The exponent of kilograms.
  • m (numbers.Real) – The exponent of meters.
  • s (numbers.Real) – The exponent of seconds.
  • k (numbers.Real) – The exponent of degrees Kelvin.
  • a (numbers.Real) – The exponent of Amperes.
  • mol (numbers.Real) – The exponent of mols.
  • cd (numbers.Real) – The exponent of candelas.
Return type:

SIUnit
base_units()[source]

Get an SIUnit of equivalent dimensions with a scaling factor of 1.0.

Return type:SIUnit
compatible(units)[source]

Check whether the provided units are of the same dimensions.

Parameters:units (SIUnit) – The units to check.
Return type:bool
quantities(iterable)[source]

Create quantities these units for all arguments.

Parameters:(Iterable[Any]) (args) – The values to tag with units.
Return type:_Q = Quantity

Dimensions

siquant.dimensions.SIDimensions(kg=0, m=0, s=0, k=0, a=0, mol=0, cd=0)[source]

Create a dimensionality tuple with base si units of provided exponents.

Parameters:
  • kg (numbers.Real) – The exponent of Kilograms.
  • m (numbers.Real) – The exponent of Meters.
  • s (numbers.Real) – The exponent of Seconds.
  • k (numbers.Real) – The exponent of Kelvin.
  • a (numbers.Real) – The exponent of Amperes.
  • mol (numbers.Real) – The exponent of Mols.
  • cd (numbers.Real) – The exponent of Candelas.
Return type:

tuple
siquant.dimensions.dim_mul(dims1, dims2)[source]

Create a new dimensionality for the multiplication of dims1 by dims2.

Parameters:
  • dims1 (tuple) – Numerator dimensions.
  • dims2 (tuple) – Other numerator dimensions.
Return type:

tuple
siquant.dimensions.dim_div(dims1, dims2)[source]

Create a new dimensionality tuple for the division of dims1 by dims2.

Parameters:
  • dims1 (tuple) – The numerator dimensions.
  • dims2 (tuple) – The divisor dimensions.
Return type:

tuple
siquant.dimensions.dim_pow(dims, exp)[source]

Create a new dimensionality tuple for the exponentiation of dims by exp.

Parameters:
  • dims (tuple) – The base dimensions.
  • exp (numbers.Real) – The power to raise the base dimensions to.
Return type:

tuple
siquant.dimensions.dim_str(dims)[source]

Express dimensions as a human readable string.

Parameters:dims (tuple) – The base unit dimensions to present.
Return type:str

Helpers

A number of units and dimensions are predefined to make getting started quick and easy.

Provided SI Units

siquant.systems.si.nano = SIUnit(0.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.micro = SIUnit(0.000001, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.milli = SIUnit(0.001000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.centi = SIUnit(0.010000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.deci = SIUnit(0.100000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.unity = SIUnit(1.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.deca = SIUnit(10.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.hecta = SIUnit(100.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.kilo = SIUnit(1000.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.mega = SIUnit(1000000.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.giga = SIUnit(1000000000.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.tera = SIUnit(1000000000000.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.meters = SIUnit(1.000000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.si.kilograms = SIUnit(1.000000, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.si.seconds = SIUnit(1.000000, (0, 0, 1, 0, 0, 0, 0))
siquant.systems.si.kelvin = SIUnit(1.000000, (0, 0, 0, 1, 0, 0, 0))
siquant.systems.si.amperes = SIUnit(1.000000, (0, 0, 0, 0, 1, 0, 0))
siquant.systems.si.mols = SIUnit(1.000000, (0, 0, 0, 0, 0, 1, 0))
siquant.systems.si.candelas = SIUnit(1.000000, (0, 0, 0, 0, 0, 0, 1))
siquant.systems.si.radians = SIUnit(1.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.steradians = SIUnit(1.000000, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.degrees = SIUnit(0.017453, (0, 0, 0, 0, 0, 0, 0))
siquant.systems.si.hertz = SIUnit(1.000000, (0, 0, -1, 0, 0, 0, 0))
siquant.systems.si.newtons = SIUnit(1.000000, (1, 1, -2, 0, 0, 0, 0))
siquant.systems.si.pascals = SIUnit(1.000000, (1, -1, -2, 0, 0, 0, 0))
siquant.systems.si.joules = SIUnit(1.000000, (1, 2, -2, 0, 0, 0, 0))
siquant.systems.si.watts = SIUnit(1.000000, (1, 2, -3, 0, 0, 0, 0))
siquant.systems.si.coulombs = SIUnit(1.000000, (0, 0, 1, 0, 1, 0, 0))
siquant.systems.si.volts = SIUnit(1.000000, (1, 2, -3, 0, -1, 0, 0))
siquant.systems.si.farads = SIUnit(1.000000, (-1, -2, 4, 0, 2, 0, 0))
siquant.systems.si.ohms = SIUnit(1.000000, (1, 2, -3, 0, -2, 0, 0))
siquant.systems.si.siemens = SIUnit(1.000000, (-1, -2, 3, 0, 2, 0, 0))
siquant.systems.si.webers = SIUnit(1.000000, (1, 2, -2, 0, -1, 0, 0))
siquant.systems.si.teslas = SIUnit(1.000000, (1, 0, -2, 0, -1, 0, 0))
siquant.systems.si.henrys = SIUnit(1.000000, (1, 2, -2, 0, -2, 0, 0))
siquant.systems.si.lumens = SIUnit(1.000000, (0, 0, 0, 0, 0, 0, 1))
siquant.systems.si.lux = SIUnit(1.000000, (0, -2, 0, 0, 0, 0, 1))
siquant.systems.si.becquerels = SIUnit(1.000000, (0, 0, -1, 0, 0, 0, 0))
siquant.systems.si.sieverts = SIUnit(1.000000, (0, 2, -2, 0, 0, 0, 0))
siquant.systems.si.grays = SIUnit(1.000000, (0, 2, -2, 0, 0, 0, 0))
siquant.systems.si.katals = SIUnit(1.000000, (0, 0, -1, 0, 0, 1, 0))
siquant.systems.si.nanometers = SIUnit(0.000000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.si.micrometers = SIUnit(0.000001, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.si.millimeters = SIUnit(0.001000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.si.centimeters = SIUnit(0.010000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.si.decimeters = SIUnit(0.100000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.si.decameters = SIUnit(10.000000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.si.hectameters = SIUnit(100.000000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.si.kilometers = SIUnit(1000.000000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.si.liters = SIUnit(0.001000, (0, 3, 0, 0, 0, 0, 0))
siquant.systems.si.milliliters = SIUnit(0.000001, (0, 3, 0, 0, 0, 0, 0))
siquant.systems.si.microliters = SIUnit(0.000000, (0, 3, 0, 0, 0, 0, 0))
siquant.systems.si.grams = SIUnit(0.001000, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.si.milligrams = SIUnit(0.000001, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.si.micrograms = SIUnit(0.000000, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.si.tonnes = SIUnit(1000.000000, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.si.kilotonnes = SIUnit(1000000.000000, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.si.nanoseconds = SIUnit(0.000000, (0, 0, 1, 0, 0, 0, 0))
siquant.systems.si.microseconds = SIUnit(0.000001, (0, 0, 1, 0, 0, 0, 0))
siquant.systems.si.milliseconds = SIUnit(0.001000, (0, 0, 1, 0, 0, 0, 0))
siquant.systems.si.minutes = SIUnit(60.000000, (0, 0, 1, 0, 0, 0, 0))
siquant.systems.si.hours = SIUnit(3600.000000, (0, 0, 1, 0, 0, 0, 0))
siquant.systems.si.days = SIUnit(86400.000000, (0, 0, 1, 0, 0, 0, 0))
siquant.systems.si.weeks = SIUnit(604800.000000, (0, 0, 1, 0, 0, 0, 0))
siquant.systems.si.years = SIUnit(31536000.000000, (0, 0, 1, 0, 0, 0, 0))
siquant.systems.si.gals = SIUnit(0.010000, (0, 1, -2, 0, 0, 0, 0))
siquant.systems.si.g_0 = SIUnit(9.806650, (0, 1, -2, 0, 0, 0, 0))
siquant.systems.si.micropascals = SIUnit(0.000001, (1, -1, -2, 0, 0, 0, 0))
siquant.systems.si.millipascals = SIUnit(0.001000, (1, -1, -2, 0, 0, 0, 0))
siquant.systems.si.kilopascals = SIUnit(1000.000000, (1, -1, -2, 0, 0, 0, 0))
siquant.systems.si.megapascals = SIUnit(1000000.000000, (1, -1, -2, 0, 0, 0, 0))
siquant.systems.si.gigapascals = SIUnit(1000000000.000000, (1, -1, -2, 0, 0, 0, 0))
siquant.systems.si.millijoules = SIUnit(0.001000, (1, 2, -2, 0, 0, 0, 0))
siquant.systems.si.kilojoules = SIUnit(1000.000000, (1, 2, -2, 0, 0, 0, 0))
siquant.systems.si.megajoules = SIUnit(1000000.000000, (1, 2, -2, 0, 0, 0, 0))
siquant.systems.si.gigajoules = SIUnit(1000000000.000000, (1, 2, -2, 0, 0, 0, 0))
siquant.systems.si.terajoules = SIUnit(1000000000000.000000, (1, 2, -2, 0, 0, 0, 0))
siquant.systems.si.milliwatts = SIUnit(0.001000, (1, 2, -3, 0, 0, 0, 0))
siquant.systems.si.kilowatts = SIUnit(1000.000000, (1, 2, -3, 0, 0, 0, 0))
siquant.systems.si.megawatts = SIUnit(1000000.000000, (1, 2, -3, 0, 0, 0, 0))
siquant.systems.si.gigawatts = SIUnit(1000000000.000000, (1, 2, -3, 0, 0, 0, 0))
siquant.systems.si.terawatts = SIUnit(1000000000000.000000, (1, 2, -3, 0, 0, 0, 0))
siquant.systems.si.millivolts = SIUnit(0.001000, (1, 2, -3, 0, -1, 0, 0))
siquant.systems.si.kilovolts = SIUnit(1000.000000, (1, 2, -3, 0, -1, 0, 0))
siquant.systems.si.megavolts = SIUnit(1000000.000000, (1, 2, -3, 0, -1, 0, 0))
siquant.systems.si.gigavolts = SIUnit(1000000000.000000, (1, 2, -3, 0, -1, 0, 0))
siquant.systems.si.teravolts = SIUnit(1000000000000.000000, (1, 2, -3, 0, -1, 0, 0))
siquant.systems.si.micronewtons = SIUnit(0.000001, (1, 1, -2, 0, 0, 0, 0))
siquant.systems.si.millinewtons = SIUnit(0.001000, (1, 1, -2, 0, 0, 0, 0))
siquant.systems.si.kilonewtons = SIUnit(1000.000000, (1, 1, -2, 0, 0, 0, 0))
siquant.systems.si.newton_meters = SIUnit(1.000000, (1, 2, -2, 0, 0, 0, 0))
siquant.systems.si.kilonewton_meters = SIUnit(1000.000000, (1, 2, -2, 0, 0, 0, 0))
siquant.systems.si.meters_per_second = SIUnit(1.000000, (0, 1, -1, 0, 0, 0, 0))

Provided Imperial Units

siquant.systems.imperial.inches = SIUnit(0.025400, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.imperial.thousandths = SIUnit(0.000025, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.imperial.feet = SIUnit(0.304800, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.imperial.yards = SIUnit(0.914400, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.imperial.chains = SIUnit(20.116800, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.imperial.furlongs = SIUnit(201.168000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.imperial.miles = SIUnit(1609.344000, (0, 1, 0, 0, 0, 0, 0))
siquant.systems.imperial.acres = SIUnit(4046.856422, (0, 2, 0, 0, 0, 0, 0))
siquant.systems.imperial.roods = SIUnit(1011.714106, (0, 2, 0, 0, 0, 0, 0))
siquant.systems.imperial.perches = SIUnit(25.292853, (0, 2, 0, 0, 0, 0, 0))
siquant.systems.imperial.fluid_ounces = SIUnit(0.000028, (0, 3, 0, 0, 0, 0, 0))
siquant.systems.imperial.gills = SIUnit(0.000142, (0, 3, 0, 0, 0, 0, 0))
siquant.systems.imperial.pints = SIUnit(0.000568, (0, 3, 0, 0, 0, 0, 0))
siquant.systems.imperial.quarts = SIUnit(0.001137, (0, 3, 0, 0, 0, 0, 0))
siquant.systems.imperial.gallons = SIUnit(0.004546, (0, 3, 0, 0, 0, 0, 0))
siquant.systems.imperial.pounds = SIUnit(0.453592, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.imperial.ounces = SIUnit(0.028350, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.imperial.stones = SIUnit(6.350293, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.imperial.tons = SIUnit(1016.046909, (1, 0, 0, 0, 0, 0, 0))
siquant.systems.imperial.psi = SIUnit(6894.757290, (1, -1, -2, 0, 0, 0, 0))
siquant.systems.imperial.ksi = SIUnit(6894757.290000, (1, -1, -2, 0, 0, 0, 0))

Provided Dimensions

siquant.dimensions.angle_t = (0, 0, 0, 0, 0, 0, 0)
siquant.dimensions.solid_angle_t = (0, 0, 0, 0, 0, 0, 0)
siquant.dimensions.strain_t = (0, 0, 0, 0, 0, 0, 0)
siquant.dimensions.ratio_t = (0, 0, 0, 0, 0, 0, 0)
siquant.dimensions.mass_t = (1, 0, 0, 0, 0, 0, 0)
siquant.dimensions.distance_t = (0, 1, 0, 0, 0, 0, 0)
siquant.dimensions.time_t = (0, 0, 1, 0, 0, 0, 0)
siquant.dimensions.temperature_t = (0, 0, 0, 1, 0, 0, 0)
siquant.dimensions.current_t = (0, 0, 0, 0, 1, 0, 0)
siquant.dimensions.amount_t = (0, 0, 0, 0, 0, 1, 0)
siquant.dimensions.luminosity_t = (0, 0, 0, 0, 0, 0, 1)
siquant.dimensions.frequency_t = (0, 0, -1, 0, 0, 0, 0)
siquant.dimensions.speed_t = (0, 1, -1, 0, 0, 0, 0)
siquant.dimensions.acceleration_t = (0, 1, -2, 0, 0, 0, 0)
siquant.dimensions.jerk_t = (0, 1, -3, 0, 0, 0, 0)
siquant.dimensions.jounce_t = (0, 1, -4, 0, 0, 0, 0)
siquant.dimensions.area_t = (0, 2, 0, 0, 0, 0, 0)
siquant.dimensions.volume_t = (0, 3, 0, 0, 0, 0, 0)
siquant.dimensions.density_t = (1, -3, 0, 0, 0, 0, 0)
siquant.dimensions.volumetric_flow_t = (0, 3, -1, 0, 0, 0, 0)
siquant.dimensions.force_t = (1, 1, -2, 0, 0, 0, 0)
siquant.dimensions.moment_t = (1, 2, -2, 0, 0, 0, 0)
siquant.dimensions.torque_t = (1, 2, -2, 0, 0, 0, 0)
siquant.dimensions.impulse_t = (1, 1, -1, 0, 0, 0, 0)
siquant.dimensions.momentum_t = (1, 1, -1, 0, 0, 0, 0)
siquant.dimensions.stress_t = (1, -1, -2, 0, 0, 0, 0)
siquant.dimensions.pressure_t = (1, -1, -2, 0, 0, 0, 0)
siquant.dimensions.hydrostatic_pressure_t = (1, -1, -2, 0, 0, 0, 0)
siquant.dimensions.stiffness_t = (1, 0, -2, 0, 0, 0, 0)
siquant.dimensions.surface_tension_t = (1, 0, -2, 0, 0, 0, 0)
siquant.dimensions.energy_t = (1, 2, -2, 0, 0, 0, 0)
siquant.dimensions.work_t = (1, 2, -2, 0, 0, 0, 0)
siquant.dimensions.heat_t = (1, 2, -2, 0, 0, 0, 0)
siquant.dimensions.power_t = (1, 2, -3, 0, 0, 0, 0)
siquant.dimensions.charge_t = (0, 0, 1, 0, 1, 0, 0)
siquant.dimensions.potential_t = (1, 2, -2, 0, -1, 0, 0)
siquant.dimensions.capacitance_t = (-1, -2, 3, 0, 2, 0, 0)
siquant.dimensions.resistance_t = (1, 2, -2, 0, -2, 0, 0)
siquant.dimensions.impedance_t = (1, 2, -2, 0, -2, 0, 0)
siquant.dimensions.reactance_t = (1, 2, -2, 0, -2, 0, 0)
siquant.dimensions.conductance_t = (-1, -2, 2, 0, 2, 0, 0)
siquant.dimensions.magnetic_flux_t = (1, 2, -2, 0, -1, 0, 0)
siquant.dimensions.magnetic_flux_density_t = (1, 0, -2, 0, -1, 0, 0)
siquant.dimensions.inductance_t = (1, 2, -1, 0, -2, 0, 0)
siquant.dimensions.luminous_flux_t = (0, 0, 0, 0, 0, 0, 1)
siquant.dimensions.illuminance_t = (0, -2, 0, 0, 0, 0, 1)
siquant.dimensions.molarity_t = (0, -3, 0, 0, 0, 1, 0)
siquant.dimensions.molality_t = (-1, 0, 0, 0, 0, 1, 0)
siquant.dimensions.molar_mass_t = (1, 0, 0, 0, 0, -1, 0)
siquant.dimensions.entropy_t = (1, 2, -2, -1, 0, 0, 0)
siquant.dimensions.heat_capacity_t = (1, 2, -2, -1, 0, 0, 0)
siquant.dimensions.specific_entropy_t = (0, 2, -2, -1, 0, 0, 0)
siquant.dimensions.specific_heat_capacity_t = (0, 2, -2, -1, 0, 0, 0)
siquant.dimensions.temperature_gradient_t = (0, -1, 0, 1, 0, 0, 0)