units

Module for all unit definitions and operations

This includes defining units used in MDMC, converting units, and subclassing data strucures (float, array) so that they have a unit attribute. This style follows that of the Atomic Simulation Environment.

As members of units.py are set dynamically, pylintrc excludes member checking for units.py using the generated-members keyword. Care must be taken to ensure members exist when importing from units.py, as these will not be linted.

class MDMC.common.units.Unit(string: str, components: collections.defaultdict[list] = None)[source]

A class for defining unit strings

It possesses additional * and / operands so that combined units can be returned.

Note

NON-INTEGER POWER OPERATIONS ARE CURRENTLY NOT IMPEMENTED

Parameters

  • string (str) – The unit, which can contain / to specify divisors and ^ to specify powers. It can contain int which are used to specify order of magnitude (e.g. 10^6 Pa). It can also contain negative powers, but there must not be a space between the negative sign and the number (e.g. Ang ^ -1 NOT Ang ^ - 1). Brackets and parentheses are not supported, and any of the characters []() will be ignored.

  • components (defaultdict(list), optional) – Sets the components attribute (see Attributes). Default is None.

Examples

Base units can be set:

>>> time_unit = Unit('s')

Compound units can be set with spaces separating base units which are multiplied:

>>> charge_unit = Unit('A s')

Compound units can be set with / separating base units which are divided:

>>> velocity_unit = Unit('m / s')

Units raised to a power can be set with ^:

>>> volume_unit = Unit('Ang ^ 3')

Compound units can be set with a combination of these operands:

>>> force_unit = Unit('kg m / s ^ 2')

To set an inverse unit, the power operation can be applied to a Unit:

>>> frequency = Unit('s') ** -1

Or set with ^ within the string:

>>> frequency = Unit('s ^ -1')

Or with / within the string:

>>> frequency = Unit('1 / s')

Orders of magnitude can also be included:

>>> pressure = Unit('10 ^ 6 Pa')
components

Contains the components of the Unit, separated into two list (numerator and denominator) depending on which side of the fraction each component is on. If the Unit is a base unit i.e. initialized using Unit(), then the components only has a numerator and this is the Unit string. If it a combined Unit (created by either __mul__, __div__ or __pow__) then the Unit objects which combined to form it make up the components.

Type

defaultdict(list)

conversion_factor

The factor by which to multiply a value in order to express it in system units. For example Unit('ps').conversion_factor is 1000. as the system units are femtoseconds.

Type

float

property base: bool

Get whether the Unit is a base or compound Unit

Returns

If True, Unit is a base Unit (only has a single element in the components numerator list)

Return type

bool

property conversion_factor: float

Calculates the factor by which a value with this Unit should be multiplied in order to express it in system units. This takes into account any orders of magnitude and compound units. The conversion_factor for a Unit composed only of system units is therefore always 1.

Returns

The conversion factor to system units for the relevant property.

Return type

float

property physical_property: str

The physical property (e.g. ‘LENGTH’, ‘TIME’, …) that the unit measures.

Note that compound units may not be supported, for the list of supported units see create_units.

Returns

The physical property

Return type

str or None

class MDMC.common.units.UnitFloat(value: float, unit: Union[MDMC.common.units.Unit, str])[source]

Subclasses float so that it contains a unit attribute

unit attribute is returned when __repr__ or __str__ are called.

Parameters

  • value (float) – the value of the UnitFloat.

  • unit (Unit, str) – a Unit or a str representing the unit.

Note

As both __repr__ and __deepcopy__ rely on the float being real, this class is not compatible with complex numbers. This should be immaterial as no quantity which possesses units is complex.

property unit: MDMC.common.units.Unit

Get or set the unit

Either a str or a Unit can be passed to the setter.

Returns

The Unit equivalent to the passed unit parameter.

Return type

Unit

class MDMC.common.units.UnitNDArray(shape, unit, dtype=<class 'float'>, buffer=None, offset=0, strides=None, order=None)[source]

Subclasses ndarray so that it contains a unit attribute

unit attribute is returned when __repr__ or __str__ are called

Parameters

  • shape (tuple of ints) – Shape of created array.

  • unit (Unit, str) – a Unit or a str representing the unit.

  • dtype (data-type, optional) – Any object that can be interpreted as a NumPy data type.

  • buffer (object exposing NumPy buffer interface, optional) – Used to fill the array with data.

  • offset (int, optional) – Offset of array data in buffer.

  • strides (tuple of ints, optional) – Strides of data in memory.

  • order (str, optional) – Either C for row-major or F for column-major. Default is C.

property unit: None

Get or set the unit

Either a str or a Unit can be passed to the setter.

Returns

The Unit equivalent to the passed unit parameter.

Return type

Unit

MDMC.common.units.create_units(codata_version: str) → dict[MDMC.common.units.Unit, float][source]

Creates a dict of Unit based on the CODATA version.

Parameters

codata_version (str) – The CODATA version to be used

Returns

Contains (Unit: conversion factor) pairs

Return type

dict

MDMC.common.units.unit_array(obj, unit: Union[MDMC.common.units.Unit, str], dtype=None) → MDMC.common.units.UnitNDArray[source]

Helper function for creating a UnitNDArray from an array or any nested sequence

This mimics the manner in which NumPy creates arrays (although is in Python not C), except several arguments are excluded.

Also, unlike np.array(None), passing obj=None to unit_array results in None being returned. This allows classes to have properties with units which can be either have a value or be undefined.

Parameters

  • object (None or array_like) – An object derived from collections.Sequence. If None, then None is returned.

  • unit (Unit, str) – a Unit or a str representing the unit.

  • dtype (data-type, optional) – Any object that can be interpreted as a NumPy data type.

Returns

A UnitArray object satisfying the specified requirements.

Return type

UnitArray