feedtwin.model.units Namespace Reference

Classes
class	Unit
class	UnknownUnit
class	DimensionMismatch

Functions
Unit	_u (str name, str dimension, float factor, float offset=0.0, bool canonical=False)
Unit	register_unit (str name, str dimension, float factor, float offset=0.0, bool canonical=False)
Unit	get_unit (str name)
list[str]	registered_units ()
str	dimension_of (str unit)
float	to_si (float value, str unit)
float	from_si (float value, str unit)
str	si_unit_of (str dimension)
None	check_dimension (str unit, str expected, str where)

Variables
	_CV_PER_KV = Kv_to_Cv(1.0)
float	_IN = 0.0254
float	_PSI = 6894.757293168361
float	_LBM = 0.45359237
float	_GAL_US = 3.785411784e-3
float	_MIN = 60.0
float	GAUGE_ZERO = 101325.0
dict	_UNITS

Detailed Description

Units, converted once at the boundary and never again.

Two jobs, and the second is the important one.

**Convert.** A team authors line bores in inches, pressures in psi and valve
capacities in Cv, because that is what the datasheets say. The solver works
entirely in SI. Conversion happens exactly once, when a parameter is read, and
what circulates afterwards is a plain float.

**Catch a dimension error.** Every unit declares what it measures, and every
parameter declares what it expects. A pressure written where a length belongs
fails at load with both names in the message. This is the single cheapest guard
in the package: unit confusion is the most expensive class of mistake in this
field, and it is trivially preventable at a schema boundary.

Deliberately not ``pint``. Unit-carrying objects are the right tool for
interactive analysis and the wrong one for a Newton loop -- a Jacobian assembly
that allocates a Quantity per arithmetic operation is orders of magnitude slower
than the physics it is wrapping. Converting at the boundary gets the safety
where it matters and pays nothing where it does not.

Units are data, like everything else here::

    from feedtwin.model.units import register_unit

    register_unit("furlong", "length", 201.168)

Function Documentation

_u()

Unit feedtwin.model.units._u ( str name, str dimension, float factor, float offset = 0.0, bool canonical = False )

protected

Definition at line 82 of file units.py.

check_dimension()

None feedtwin.model.units.check_dimension	(	str	unit,
		str	expected,
		str	where )

Raise :class:`DimensionMismatch` unless ``unit`` measures ``expected``.

Definition at line 309 of file units.py.

References dimension_of().

dimension_of()

str feedtwin.model.units.dimension_of

(

str

unit

)

What a unit measures: ``"pressure"``, ``"length"``, ...

Definition at line 274 of file units.py.

References get_unit().

Referenced by check_dimension().

from_si()

float feedtwin.model.units.from_si	(	float	value,
		str	unit )

Convert out of canonical units, for display.

Definition at line 284 of file units.py.

References from_si(), and get_unit().

Referenced by from_si().

get_unit()

Unit feedtwin.model.units.get_unit

(

str

name

)

Definition at line 263 of file units.py.

Referenced by dimension_of(), from_si(), and to_si().

register_unit()

Unit feedtwin.model.units.register_unit	(	str	name,
		str	dimension,
		float	factor,
		float	offset = 0.0,
		bool	canonical = False )

Add a unit. ``si = value * factor + offset``.

Replacing an existing name is allowed and deliberate: a project that means
something specific by a spelling should be able to say so.

Set ``canonical`` when adding the first unit of a new dimension, or the
reverse lookup used to label output will have nothing to report.

Definition at line 243 of file units.py.

registered_units()

list[str] feedtwin.model.units.registered_units

(

)

Definition at line 270 of file units.py.

si_unit_of()

str feedtwin.model.units.si_unit_of

(

str

dimension

)

The canonical unit name for a dimension, for labelling output.

Prefers a unit explicitly marked canonical; otherwise the unscaled,
unoffset one. Both passes are needed: most dimensions have exactly one unit
with factor 1.0 and need no marking, while a few have two of the same size
and would otherwise resolve by declaration order.

Definition at line 289 of file units.py.

to_si()

float feedtwin.model.units.to_si	(	float	value,
		str	unit )

Convert into this package's canonical unit for that dimension.

Definition at line 279 of file units.py.

References get_unit(), and to_si().

Referenced by to_si().

Variable Documentation

_CV_PER_KV

feedtwin.model.units._CV_PER_KV = Kv_to_Cv(1.0)

protected

Definition at line 43 of file units.py.

_GAL_US

float feedtwin.model.units._GAL_US = 3.785411784e-3

protected

Definition at line 48 of file units.py.

_IN

float feedtwin.model.units._IN = 0.0254

protected

Definition at line 45 of file units.py.

_LBM

float feedtwin.model.units._LBM = 0.45359237

protected

Definition at line 47 of file units.py.

_MIN

float feedtwin.model.units._MIN = 60.0

protected

Definition at line 49 of file units.py.

_PSI

float feedtwin.model.units._PSI = 6894.757293168361

protected

Definition at line 46 of file units.py.

_UNITS

dict feedtwin.model.units._UNITS

protected

Definition at line 97 of file units.py.

GAUGE_ZERO

float feedtwin.model.units.GAUGE_ZERO = 101325.0

Definition at line 53 of file units.py.