unitty.base module

Created on Thu Apr 30 18:15:23 2020

@author: Reuben

The base module for the Units class, which creates and contains a full working set of units.

Normally, the user would not instantiate Units objects directly, but would use api functions to load default or custom units files.

Specifying units

Units are often specified in a yaml file, which is a more convenient format to read. That gets converted into a dictionary structure that specifies the units. Here’s a very small example of one such structure:

raw = {'base_types': ['length', 'mass', 'time', 'force'],
   'length': {'_base': 'm',
            'm': [1.0, 'length', 'meter'],
            'mm': [0.001, 'm', 'millimeter']},
   'mass': {'_base': 'kg',
            'kg': [1.0, 'mass', 'kilogram']},
   'time': {'_base': 's',
            's': [1.0, 'time', 'second']},
   'force': {'_base': 'N',
            'N': [1.0, ['kg', 'm', '-s', '-s'], 'newton']}}

The first key needs to be ‘base_types’, and contain a list of the base dimensions that form the basis of all the units. Some base types are irreducable and independent, such as length, mass, and time in the above example. Some base types are derived, such as force in the above example.

After ‘base_types’, each key needs to be one of the base types. The value for each key needs to be another dictionary, which contains:

  • _base: A string indicating which unit should be considered the base unit for this dimension. The data for that unit must be present within the .
  • A key for each unit: They key is the unit abbreviation. The value needs to be a list, which contains everything needed to define the unit as described below.

The list format to specify a unit:

Each unit is defined by a list. The abbreviation is used as a key for the list.

  • Item 0 - Value: The value of the unit. This is the scale factor for the unit, or how large this unit is with respect to the others by which it is defined (see Item 1)

  • Item 1 - Specification: This contains the specification of how this unit is defined. It must be either a string or a list of strings. Each string indicates a unit or base dimension that must be defined earlier in the dictionary! (Note that dictionaries respect ordering in Python 3.6 and above.) In the above example, ‘m’ is defined as 1.0 * length - length is a base dimension. ‘mm’ is defined as 0.001 * ‘m’. ‘N’ is defined as a compound unit (kg.m/s2). The ‘s’ units (seconds) are prefixed by ‘-‘ to indicate they are in the denominator.

  • Item 3 - Name: A string to indicate the full name of the unit.

  • Item 4 [Optional] - Additional dictionary: A dictionary of extra parameters. Currently, one is supported.

    • SI_Prefixes: A list of SI prefixes (each a str) to use for the unit. Units will be created automatically for each prefix specified.
class unitty.base.Units(fname=None, raw=None)

Bases: object

Container for and creator of Unit instances.

Parameters:
  • fname (str) – [Optional] An input definition file in yaml format. If both fname and raw are omitted, the default units are loaded.
  • raw (dict) – [Optional] If passed, while fname is left as None, this data will be used to create the units.

A Units instance stores a set of indices to convert between integers and strings, along with a dictionary of Unit instances. The reason for storing the indices is because Quantity instances use integers for their specification (spec).

Each Unit instance is keyed by its abbreviation (e.g. ‘mm’) and has a match inverse (e.g. ‘1/mm’ Unit instance that prefixes that abbreviation with a ‘-‘ (e.g. ‘-m’). The index number of an inverse unit is the negative of the normal unit (e.g. if ‘mm’ is 13, ‘-mm’ would be -13). To avoid a lot of string manipulation, unitty specifies units and quantities with signed integers. The indices in the Units class helps those integers map to the right units.

It’s the job of the Units class to load in the specified units and set up the units, vectors, and indices for them.

from_str(s)
get_by_index(i)
load(dct)
new(index, value, vector, spec, name, utype)

Create a new unit

TODO: Use of the index here is unnecessary. Could replace with the abbreviation.

safe_set(unit_dct, key, val)
spec_from_str(s, sep=', ')
str(ind)

Return the string for an index number

str_spec(spec)