units.py

Classes and functions to support unit conversion.

The module provides a basic set of predefined physical quantities in its built-in library; however, it also supports generation of personal libararies which can be saved and reused. This module is based on the PhysicalQuantities module in Scientific Python, by Konrad Hinsen. Modifications by Justin Gray.

class openmdao.utils.units.NumberDict[source]

Bases: collections.OrderedDict

Dictionary storing numerical values.

An instance of this class acts like an array of numbers with generalized (non-integer) indices. A value of zero is assumed for undefined entries. NumberDict instances support addition and subtraction with other NumberDict instances, and multiplication and division by scalars.

__contains__(key, /)

True if the dictionary has the specified key, else False.

__getitem__(item)[source]

Get the item, or 0.

Parameters
itemkey

key to get the item

Returns
int

value of the given key

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__iter__(/)

Implement iter(self).

__setitem__(key, value, /)

Set self[key] to value.

clear()None.  Remove all items from od.
copy()a shallow copy of od
fromkeys(/, iterable, value=None)

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items()a set-like object providing a view on D’s items
keys()a set-like object providing a view on D’s keys
move_to_end(/, key, last=True)

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

pop(k[, d])v, remove specified key and return the corresponding

value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem(/, last=True)

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(/, key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F)None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()an object providing a view on D’s values
class openmdao.utils.units.PhysicalUnit(names, factor, powers, offset=0)[source]

Bases: object

Physical unit.

A physical unit is defined by a name (possibly composite), a scaling factor, and the exponentials of each of the SI base units that enter into it. Units can be multiplied, divided, and raised to integer powers.

Parameters
namesdict or str

A dictionary mapping each name component to its associated integer power (e.g., C{{‘m’: 1, ‘s’: -1}}) for M{m/s}). As a shorthand, a string may be passed which is assigned an implicit power 1.

factorfloat

A scaling factor.

powerslist of int

The integer powers for each of the nine base units.

offsetfloat

An additive offset to the base unit (used only for temperatures).

Attributes
_namesdict or str

A dictionary mapping each name component to its associated integer power (e.g., C{{‘m’: 1, ‘s’: -1}}) for M{m/s}). As a shorthand, a string may be passed which is assigned an implicit power 1.

_factorfloat

A scaling factor.

_powerslist of int

The integer powers for each of the nine base units.

_offsetfloat

An additive offset to the base unit (used only for temperatures)

__init__(names, factor, powers, offset=0)[source]

Initialize all attributes.

conversion_tuple_to(other)[source]

Compute the tuple of (factor, offset) for conversion.

Parameters
otherPhysicalUnit

Another unit.

Returns
Tuple with two floats

The conversion factor and offset from this unit to another unit.

in_base_units()[source]

Return the base unit equivalent of this unit.

Returns
PhysicalUnit

The equivalent base unit.

is_angle()[source]

Check if this PQ is an Angle.

Returns
bool

Indicates if this an angle type.

is_compatible(other)[source]

Check for compatibility with another unit.

Parameters
otherPhysicalUnit

Another unit.

Returns
bool

Indicates if two units are compatible.

is_dimensionless()[source]

Dimensionless PQ.

Returns
bool

Indicates if this is dimensionless.

name()[source]

Compute the name of this unit.

Returns
str

String representation of the unit.

set_name(name)[source]

Set the name.

Parameters
namestr

The name.

openmdao.utils.units.add_offset_unit(name, baseunit, factor, offset, comment='')[source]

Adding Offset Unit.

Parameters
namestr

The name of the unit.

baseunitstr or instance of PhysicalUnit

The unit upon which this offset unit is based.

factorstr

The scaling factor used to define the new unit w.r.t. base unit.

offsetfloat

Zero offset for new unit.

commentstr

Optional comment to describe unit.

openmdao.utils.units.add_unit(name, unit, comment='')[source]

Adding Unit.

Parameters
namestr

The name of the unit being added. For example: ‘Hz’.

unitstr

Definition of the unit w.r.t. some other unit. For example: ‘1/s’.

commentstr

Optional comment to describe unit.

openmdao.utils.units.conversion_to_base_units(units)[source]

Get the offset and scaler to convert from given units to base units.

Parameters
unitsstr

String representation of the units.

Returns
float

Offset to get to default unit: m (length), s(time), etc.

float

Mult. factor to get to default unit: m (length), s(time), etc.

openmdao.utils.units.convert_units(val, old_units, new_units=None)[source]

Take a given quantity and return in different units.

Parameters
valfloat

Value in original units.

old_unitsstr or None

Original units as a string or None.

new_unitsstr or None

New units to return the value in or None.

Returns
float

Value in new units.

openmdao.utils.units.get_conversion(old_units, new_units)[source]

Return conversion factor and offset between old and new units (deprecated).

Parameters
old_unitsstr

Original units as a string.

new_unitsstr

New units to return the value in.

Returns
(float, float)

Conversion factor and offset.

openmdao.utils.units.import_library(libfilepointer)[source]

Import a units library, replacing any existing definitions.

Parameters
libfilepointerfile

New library file to work with.

Returns
ConfigParser

Newly updated units library for the module.

openmdao.utils.units.is_compatible(old_units, new_units)[source]

Check whether units are compatible in terms of base units.

e.g., m/s is compatible with ft/hr

Parameters
old_unitsstr

Original units as a string.

new_unitsstr or None

New units to return the value in; if None, return in standard units.

Returns
bool

Whether the units are compatible.

openmdao.utils.units.simplify_unit(old_unit_str, msginfo='')[source]

Simplify unit string using built-in naming method.

Unit string ‘ft*s/s’ becomes ‘ft’.

Parameters
old_unit_strstr

Unit string to simplify.

msginfostr

A string prepended to the ValueError which is raised if the units are invalid.

Returns
str

Simplified unit string.

openmdao.utils.units.unit_conversion(old_units, new_units)[source]

Return conversion factor and offset between old and new units.

Parameters
old_unitsstr

Original units as a string.

new_unitsstr

New units to return the value in.

Returns
(float, float)

Conversion factor and offset.

openmdao.utils.units.update_library(filename)[source]

Update units in current library from filename.

Parameters
filenamestr or file

Source of units configuration data.

openmdao.utils.units.valid_units(unit)[source]

Return whether the given units are vaild.

Parameters
unitstr

String representation of the units.

Returns
bool

True for valid, False for invalid.