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

Bases: 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.

Methods

clear(/)
copy(/)
fromkeys(/, iterable[, value])	Create a new ordered dictionary with keys from iterable and values set to value.
get(key[, default])	Return the value for key if key is in the dictionary, else default.
items(/)	Return a set-like object providing a view on the dict's items.
keys(/)	Return a set-like object providing a view on the dict's keys.
move_to_end(/, key[, last])	Move an existing element to the end (or beginning if last is false).
pop(/, key[, default])	If the key is not found, return the default if given; otherwise, raise a KeyError.
popitem(/[, last])	Remove and return a (key, value) pair from the dictionary.
setdefault(/, key[, default])	Insert key with a value of default if key is not in the dictionary.
update([E, ]**F)	If E is present and has a .keys() method, then does: for k in E.keys(): 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(/)	Return an object providing a view on the dict's values.

__getitem__(item)

Get the item, or 0.

Parameters:

itemkey

key to get the item

Returns:

int

value of the given key

class openmdao.utils.units.PhysicalUnit(names, factor, powers, offset=0)

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)

Methods

conversion_tuple_to(other)	Compute the tuple of (factor, offset) for conversion.
in_base_units()	Return the base unit equivalent of this unit.
is_angle()	Check if this PQ is an Angle.
is_compatible(other)	Check for compatibility with another unit.
is_dimensionless()	Dimensionless PQ.
name()	Compute the name of this unit.
set_name(name)	Set the name.

__init__(names, factor, powers, offset=0)

Initialize all attributes.

conversion_tuple_to(other)

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()

Return the base unit equivalent of this unit.

Returns:

PhysicalUnit

The equivalent base unit.

is_angle()

Check if this PQ is an Angle.

Returns:

bool

Indicates if this an angle type.

is_compatible(other)

Check for compatibility with another unit.

Parameters:

otherPhysicalUnit

Another unit.

Returns:

bool

Indicates if two units are compatible.

is_dimensionless()

Dimensionless PQ.

Returns:

bool

Indicates if this is dimensionless.

name()

Compute the name of this unit.

Returns:

str

String representation of the unit.

set_name(name)

Set the name.

Parameters:

namestr

The name.

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

Add 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='')

Add 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’. This can reference prefixed units like ‘km’, which will be automatically resolved.

commentstr

Optional comment to describe unit.

openmdao.utils.units.conversion_to_base_units(units)

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)

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.has_val_mismatch(units1, val1, units2, val2, rtol=1e-10)

Return True if values differ after unit conversion or if values differ when units are None.

Parameters:

units1str or None

Units for first value.

val1float or ndarray

First value.

units2str or None

Units for second value.

val2float or ndarray

Second value.

rtolfloat

Tolerance for relative difference.

openmdao.utils.units.import_library(libfilepointer)

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)

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='')

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)

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)

Update units in current library from filename.

Parameters:

filenamestr or file

Source of units configuration data.

openmdao.utils.units.valid_units(unit)

Return whether the given units are vaild.

Parameters:

unitstr

String representation of the units.

Returns:

bool

True for valid, False for invalid.