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, Dict[str, int]], factor, …)	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: 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.

class cosapp.ports.units.PhysicalUnit(names: Union[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: cosapp.ports.units.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() → cosapp.ports.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: cosapp.ports.units.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: configparser.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: Union[str, cosapp.ports.units.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: Union[str, cosapp.ports.units.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: Optional[Union[str, cosapp.ports.units.PhysicalUnit]] = None, new_units: Optional[Union[str, cosapp.ports.units.PhysicalUnit]] = 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: Optional[Union[str, cosapp.ports.units.PhysicalUnit]], new_units: Optional[Union[str, cosapp.ports.units.PhysicalUnit]]) → Optional[Tuple[float, float]]

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) → cosapp.ports.units.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: Union[str, cosapp.ports.units.PhysicalUnit], new_units: Union[str, cosapp.ports.units.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: Union[str, cosapp.ports.units.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: Union[str, Any]) → None

Update units in current library from filename.

Parameters

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