unitty.system module

Created on Fri May 1 11:20:07 2020

@author: Reuben

This module is responsible for the unit systems desired by the user. Quantities all share the same underlying base dimensions. For example, a meter and a foot both share the underlying length dimension, although they represent different scaling factors.

A unit system indicates what kinds of units the user would like to use for given types of dimensions. For example, in the length dimension, the metric unit system would specify units like millimeter, meter, and kilometer. On the other hand, the US imperial system would specify units such as inch, foot, and mile.

Unitty allows unit systems to be switched on the fly. This is made possible by the Systems class, which contains a number of System classes and keeps track of which one is currently active.

Normally, the user would not instantiate Systems or System objects directly, but would use api functions.

class unitty.system.System(dct)

Bases: object

base_unitise(val, vector, dimensional=False)
calc_utypes(vector)
unitise(val, spec)
unitise_typed(val, spec)
class unitty.system.Systems(fname=None, raw=None)

Bases: object

Manage multiple unit systems and allow switching between them

Parameters:
  • fname (str) – [Optional] The yaml file from which to read in systems information. If omitted when raw is omitted, the defaults are loaded.
  • raw (dict) – [Optional] If passed when fname is omitted, this data is used to initialise the instance. See the load() method for details on structure.
active

Return the active system

Returns:The active system.
Return type:System
base_unitise(val, vector, dimensional=False)
by_ref(val, ref)
load(raw)

Load raw data

Parameters:
  • raw (dict) – A dictionary containing keys for all base dimensions
  • in the current Units instance (specified) –
  • for details. (notes) –

Notes

The input must be a dictionary containing keys for all base dimensions specified in the current Units instance (e.g. length, time). The corresponding values must be lists of units to use for those dimensions. Unless otherwise directed (e.g. by named references), the unit that results in a value closest to 10 will be used for a given dimension.

Example

Here’s a simple example:

raw = {'metric':
            {'length': ['mm', 'm'', 'km'],
             'mass': ['g', 'kg', 'tonne']},
       'US':
            {'length': ['in', 'ft', 'mile'],
             'mass': ['USoz', 'lbs']}}
set_active(name)

Set the currently active system

Parameters:name (str) – The system name.
set_refs(source)
unitise(val, spec)

Express a value in units specified by the active system.

Parameters:
  • val (float, arraylike) – The value with respect to base dimensions like length, time, etc.
  • spec (list[int]) – A list of integers corresponding to the units in which val is defined. These are used to indicate the dimensionality.
Returns:

A value and unit string tuple.
Return type:

tuple

Notes

The value and unit string returned will depend on which unit system is active. See the system module.

The spec is used because it is sometimes more desirable to expressed a value in derived dimensions (e.g. force), rather than base dimensions (for force, this would be a combination of length, time, and distance).

unitise_typed(val, spec)