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.

__contains__(key, /)

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

__getitem__(item)

Get the item, or 0.

Parameters:

itemkey

key to get the item

Returns:

int

value of the given key

__init__(*args, **kwargs)

__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(/, key, default=<unrepresentable>)

If the key is not found, return the default if given; otherwise, raise a KeyError.

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)

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)

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

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

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)

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