cosapp.ports.units

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 libraries which can be saved and reused. This module is based on the PhysicalQuantities module in Scientific Python, by Konrad Hinsen.

It has been modified by Justin Gray for integration in OpenMDAO 2.2 and by the CoSApp team for integration in CoSApp (mainly remove Python 2 support).

Functions

add_offset_unit(name, baseunit, factor, offset)	Adding Offset PhysicalUnit to the unit library.
add_unit(name, unit[, comment])	Adding PhysicalUnit from its name and string representation to the unit library.
conversion_to_base_units(units)	Get the offset and scaler to convert from given units to base units.
convert_units(val[, old_units, new_units])	Take a given quantity and return in different units.
get_conversion(old_units, new_units)	Return conversion factor and offset between old and new units.
import_library(libfilepointer)	Import a units library, replacing any existing definitions.
is_compatible(old_units, new_units)	Check whether units are compatible in terms of base units.
is_valid_units(unit)	Return whether the given units are valid.
update_library(filename)	Update units in current library from filename.

Classes

NumberDict	Dictionary storing numerical values.
PhysicalUnit(names, factor, powers[, offset])	Physical unit.
UnitConfigParser([defaults, dict_type, ...])	Customized configuration file parser to store physical units.

Exceptions

UnitError(message)

Raised if units are incompatible or unknown.

class cosapp.ports.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.

class cosapp.ports.units.PhysicalUnit(names: str | Dict[str, int], factor: float, powers: List[int], offset: float = 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.

_names

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.

Type:

dict or str

_factor

A scaling factor.

Type:

float

_powers

The integer powers for each of the nine base units.

Type:

list of int

_offset

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

Type:

float

conversion_tuple_to(other: PhysicalUnit) → Tuple[float, float]

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

Parameters:

other (PhysicalUnit) – Another unit.

Returns:

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

Return type:

Tuple with two floats

in_base_units() → PhysicalUnit

Return the base unit equivalent of this unit.

Returns:

the equivalent base unit

Return type:

PhysicalUnit

is_angle() → bool

Check if this PQ is an Angle.

Returns:

indicates if this an angle type

Return type:

bool

is_compatible(other: PhysicalUnit) → bool

Check for compatibility with another unit.

Parameters:

other (PhysicalUnit) – Another unit.

Returns:

indicates if two units are compatible

Return type:

bool

is_dimensionless() → bool

Dimensionless PQ.

Returns:

indicates if this is dimensionless

Return type:

bool

name() → str

Compute the name of this unit.

Returns:

str representation of the unit

Return type:

str

set_name(name: str)

Set the name.

Parameters:

name (str) – the name

class cosapp.ports.units.UnitConfigParser(defaults=None, dict_type=<class 'collections.OrderedDict'>, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section='DEFAULT', interpolation=<object object>)

Bases: RawConfigParser

Customized configuration file parser to store physical units.

optionxform(optionstr: str) → str

Make the RawConfigParser case sensitive.

Defines an optionxform for the units configparser that does nothing, resulting in a case-sensitive parser.

Parameters:

optionstr (str) – The string to be transformed for the RawConfigParser

Returns:

The same string that was given as a parameter.

Return type:

str

exception cosapp.ports.units.UnitError(message: str)

Bases: Exception

Raised if units are incompatible or unknown.

Parameters:

message (str) – Error message

message

Error message

Type:

str

cosapp.ports.units.add_offset_unit(name: str, baseunit: str | PhysicalUnit, factor: float, offset: float, comment: str = '') → None

Adding Offset PhysicalUnit to the unit library.

Parameters:

• name (str) – The name of the unit

• baseunit (str or PhysicalUnit) – The unit upon which this offset unit is based.

• factor (float) – The scaling factor used to define the new unit w.r.t. baseunit

• offset (float) – zero offset for new unit

• comment (str) – optional comment to describe unit

cosapp.ports.units.add_unit(name: str, unit: str, comment: str = '') → None

Adding PhysicalUnit from its name and string representation to the unit library.

Parameters:

• name (str) – The name of the unit being added. For example: ‘Hz’

• unit (str) – definition of the unit w.r.t. some other unit. For example: ‘1/s’

• comment (str) – optional comment to describe unit

cosapp.ports.units.conversion_to_base_units(units: str | PhysicalUnit) → Tuple[float, float]

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

Parameters:

units (str or PhysicalUnit) – Unit or its representation.

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.

cosapp.ports.units.convert_units(val: float, old_units: str | PhysicalUnit | None = None, new_units: str | PhysicalUnit | None = None) → float

Take a given quantity and return in different units.

If there is no current units or no target units, the original value is returned.

Parameters:

• val (Number) – value in original units.

• old_units (str or PhysicalUnit or None) – original units or None.

• new_units (str or PhysicalUnit or None) – new units to return the value in or None.

Returns:

value in new units.

Return type:

float

cosapp.ports.units.get_conversion(old_units: str | PhysicalUnit | None, new_units: str | PhysicalUnit | None) → Tuple[float, float] | None

Return conversion factor and offset between old and new units.

Parameters:

• old_units (str or PhysicalUnit) – original units

• new_units (str or PhysicalUnit) – new units to get the conversion from.

Returns:

Conversion factor and offset or None is no conversion available

Return type:

(float, float) or None

cosapp.ports.units.import_library(libfilepointer) → UnitConfigParser

Import a units library, replacing any existing definitions.

Parameters:

libfilepointer (file) – new library file to work with

Returns:

newly updated units library for the module

Return type:

UnitConfigParser

cosapp.ports.units.is_compatible(old_units: str | PhysicalUnit, new_units: str | PhysicalUnit) → bool

Check whether units are compatible in terms of base units.

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

Parameters:

• old_units (str or PhysicalUnit) – original units

• new_units (str or PhysicalUnit) – new units to check compatibility with

Returns:

whether the units are compatible.

Return type:

bool

cosapp.ports.units.is_valid_units(unit: str | PhysicalUnit) → bool

Return whether the given units are valid.

Parameters:

unit (str or PhysicalUnit) – Unit to test for.

Returns:

True for valid, False for invalid.

Return type:

bool

cosapp.ports.units.update_library(filename: str | Any) → None

Update units in current library from filename.

Parameters:

filename (string or file) – Source of units configuration data.