PhysicalQuantity¶

Connects a value with a unit.

>>> from PhysicalQuantities.quantity import PhysicalQuantity
>>> g = PhysicalQuantity(9.81, 'm/s**2')

The value is stored in the attribute .value. It can acutally be any Python object, however when working with units, especially converting between different unit scalings, there can be multiplications with float values to take that into account.

For Numpy arrays, it is better to use PhysicalQuantityArray instead, as it subclasses a ndarray.

Reference¶

PhysicalQuantity class definition

class PhysicalQuantities.quantity.PhysicalQuantity(value: float, unit=None, annotation: str | None = None)[source]¶

Physical quantity with units.

PhysicalQuantity instances allow addition, subtraction, multiplication, and division with each other as well as multiplication, division, and exponentiation with numbers. Addition and subtraction check that the units of the two operands are compatible and return the result in the units of the first operand. A limited set of mathematical functions (from numpy) is applicable as well.

__abs__()[source]¶

Return quantity with absolute value

Returns¶

PhysicalQuantity: Absolute value of quantity

__complex__()[source]¶: Return complex number without units converted to base units

__deepcopy__(memo: dict)[source]¶: Return a copy of the PhysicalQuantity including the value. Needs deepcopy to copy the value

__dir__()[source]¶: List available attributes including conversion to other scaling prefixes

Returns¶

list of units for tab completion

__eq__(other)[source]¶

Test if two quantities are equal

Parameters¶

other: PhysicalQuantity: Quantity to compare against

Returns¶

bool: True if quantities are equal

__float__()[source]¶: Return float number without units converted to base units

__floordiv__(other)[source]¶

Implement integer division: self // other

Parameters¶

other: PhysicalQuantity: Quantity to divide by

__format__(*args, **kw)[source]¶: Default object formatter.

__ge__(other)[source]¶

Test if quantity is greater or equal than other

Parameters¶

other: PhysicalQuantity: Quantity to compare against

Returns¶

bool: True if quantity is greater or equal than other

__getattr__(attr)[source]¶

Convert to different scaling in the same unit.: If a ‘_’ is appended, drop unit (possibly after rescaling) and return value only.

Parameters¶

attrstring: attribute name

Raises¶

AttributeError: If unit is not a valid attribute

Examples¶

>>> from PhysicalQuantities import q
>>> a = 2 * q.mm
>>> a._
2
>>> a.mm_
2
>>> a.m_
0.002

__getitem__(key)[source]¶: Allow indexing if quantities if underlying object is array or list e.g. obj[0] or obj[0:4]

__gt__(other)[source]¶

Test if quantity is greater than other

Parameters¶

other: PhysicalQuantity

Returns¶

bool: true if quantity is greater than other

__hash__ = None¶

__init__(value: float, unit=None, annotation: str | None = None)[source]¶

There are two constructor calling patterns

Parameters¶

value: any: value of the quantity
unit: string or PhysicalUnit class: unit of the quantity

Examples¶

>>> from PhysicalQuantities import PhysicalQuantity
>>> PhysicalQuantity(1, 'V')
1 V

__le__(other)[source]¶

Test if quantity is less or equal than other

Parameters¶

other: PhysicalQuantity: Quantity to compare against

Returns¶

bool

param other:: other PhysicalQuantity
return:: true if quantity is less or equal than other
rtype:: bool

__len__()[source]¶: Return length of quantity if underlying object is array or list e.g. len(obj)

__lt__(other)[source]¶

Test if quantity is less than other

Parameters¶

other: PhysicalQuantity: Quantity to compare against

Returns¶

bool: True if quantity is less than other

__ne__(other)[source]¶

Test if two quantities are not equal

Parameters¶

other: PhysicalQuantity: Quantity to compare against

Returns¶

bool: True if quantities are not equal

__neg__()[source]¶

Return quantity with negative sign

Returns¶

PhysicalQuantity: negative value of quantity

__nonzero__()[source]¶

Test if quantity is not zero

Returns¶

bool: true if quantity is not zero

__pos__()[source]¶

Return quantity with positive sign

Returns¶

PhysicalQuantity: positive value of quantity

__pow__(other)[source]¶

Return power of other for quantity

Parameters¶

other: exponent

Returns¶

PhysicalQuantity: power of other for quantity

__repr__()[source]¶: Return string representation

__rfloordiv__(other)[source]¶: Implement integer division: other // self

Parameters¶

other

__round__(ndigits=0)[source]¶

Return rounded values

Parameters¶

ndigits: int: number of digits to round to

Returns¶

PhysicalQuantity: rounded quantity

__setitem__(key, value)[source]¶: Set quantities if underlying object is array or list e.g. obj[0] = 1m

__str__()[source]¶

Return string representation as ‘value unit’: e.g. str(obj)

Returns¶

string: string representation of PhysicalQuantity

__weakref__¶: list of weak references to the object (if defined)

property autoscale¶

Autoscale to a reasonable unit, if possible

Examples¶

>>> b = PhysicalQuantity(4e-9, 'F')
>>> b.autoscale
4 nF

property base¶

Returns the same quantity converted to SI base units

Returns¶

any: values in base unit

>>> a = PhysicalQuantity(1, 'V')
>>> a.base
1.0 m^2*kg/s^3

convert(unit)[source]¶

Change the unit and adjust the value such that the combination is: equivalent to the original one. The new unit must be compatible with the previous unit of the object.

Parameters¶

unit: PhysicalUnit: Unit to convert to

cos()[source]¶

Return cosine of given PhysicalQuantity with angle unit

Returns¶

Cosine values

Raises¶

UnitError: If quantity is not of unit angle

property dB¶

Convert to dB scaled unit, if possible. Guess if it is a power unit to select 10*log10 or 20*log10

Returns¶

dBQuantity: dB quantity converted from PhysicalQuantity

Examples¶

>>> from PhysicalQuantities import q
>>> (10 q.V).dB
20.0 dBV
>>> (10 q.W).dB
10.0 dBW

static from_dict(quantity_dict: dict)[source]¶

Retrieve PhysicalUnit from dict description

Parameters¶

quantity_dict: PhysicalQuantity stored as dict

Returns¶

PhysicalQuantity: Retrieved PhysicalQuantity

Notes¶

Current implementation: throw exception if unit has not already been defined

static from_json(json_quantity: str)[source]¶

Retrieve PhysicaQuantity from JSON string description

Parameters¶

json_quantity: PhysicalQuantity encoded as JSON string

Returns¶

PhysicalQuantity: New PhysicalQuantity

property imag¶

Return imaginary part of a complex PhysicalQuantity

Returns¶

PhysicalQuantity: imaginary part

Examples¶

>>> b = PhysicalQuantity(2 + 1j, 'V')
>>> b.imag
1.0 V

pow(exponent)[source]¶

Return PhysicalQuantity raised to power of exponent

Parameters¶

exponent: float: Power to be raised

Returns¶

PhysicalQuantity: Raised to power of exponent

property real¶

Return real part of a complex PhysicalQuantity

Returns¶

PhysicalQuantity: real part

Examples¶

>>> b = PhysicalQuantity(2 + 1j, 'V')
>>> b.real
2.0 V

rint()[source]¶

Round elements to the nearest integer

Returns¶

any: rounded elements

sin()[source]¶

Return sine of given PhysicalQuantity with angle unit

Returns¶

Sine values

Raises¶

UnitError: If quantity is not of unit angle

sqrt()[source]¶

Return the positive square-root

Returns¶

PhysicalQuantity: Positive square-root

tan()[source]¶

Return tangens of given PhysicalQuantity with angle unit

Returns¶

Tangens values

Raises¶

UnitError: If quantity is not of unit angle

to(*units)[source]¶

Express the quantity in different units.

Parameters¶

units: str: Name of the unit

Examples¶

>>> b = PhysicalQuantity(4, 'J/s')
>>> b.to('W')
4.0 W
>>> b = PhysicalQuantity(1000, 's')
>>> b.to('h', 'min, ''s')
(0.0 h, 16.0 min, 40.000000000000071 s)

Notes¶

If one unit is specified, a new PhysicalQuantity object is returned that expresses the quantity in that unit. If several units are specified, the return value is a tuple of PhysicalObject instances with one element per unit such that the sum of all quantities in the tuple equals the the original quantity and all the values except for the last one are integers. This is used to convert to irregular unit systems like hour/minute/second.

property to_dict¶

Export as dict

Returns¶

dict: Dict describing PhysicalQuantity

property to_json¶

Export as JSON

Returns¶

str: JSON string describing PhysicalQuantity

class PhysicalQuantities.quantity.PhysicalUnit(names, factor: float, powers: list, offset: float = 0, url: str | None = None, verbosename: str | None = None, unece_code: str | None = None)[source]¶

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.

Attributes¶

prefixed: bool: If instance is a scaled version of a unit
baseunit: PhysicalUnit: Base unit if prefixed, otherwise self
names: NumberDict: A dictionary mapping each name component to its associated integer power (e.g. C{{‘m’: 1, ‘s’: -1}}) for M{m/s})
factor: float: A scaling factor from base units
powers: list: The integer powers for each of the nine base units: [‘m’, ‘kg’, ‘s’, ‘A’, ‘K’, ‘mol’, ‘cd’, ‘rad’, ‘sr’]
offset: float: An additive offset to the unit (used only for temperatures)
url: str: URL describing the unit
verbosename: str: The verbose name of the unit (e.g. Coulomb)
unece_code: str: Official unit code (see https://www.unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20_Rev9e_2014.xls)

__div__(other)[source]¶

Divide two units

Parameters¶

other: PhysicalUnit: Other unit to divide

Returns¶

PhysicalUnit: Divided unit

Examples¶

>>> from PhysicalQuantities import q
>>> q.m.unit / q.s.unit
m/s

__eq__(other)[source]¶

Test if unit is equal than other unit

Parameters¶

other: PhysicalUnit: Other unit to compare with

Returns¶

bool: True, if unit is equal than other unit

__floordiv__(other)[source]¶

Divide two units

Parameters¶

other: PhysicalUnit: Other unit to divide

Returns¶

PhysicalUnit: Divided unit

Examples¶

>>> from PhysicalQuantities import q
>>> q.m.unit / q.s.unit
m/s

__ge__(other)[source]¶

Test if unit is greater or equal than other unit

Parameters¶

other: PhysicalUnit: Other unit to compare with

Returns¶

bool: True, if unit is greater or equal than other unit

__gt__(other)[source]¶

Test if unit is greater than other unit

Parameters¶

other: PhysicalUnit: Other unit to compare with

Returns¶

bool: True, if unit is greater than other unit

__hash__()[source]¶: Custom hash function

__init__(names, factor: float, powers: list, offset: float = 0, url: str | None = None, verbosename: str | None = None, unece_code: str | None = None)[source]¶

Initialize object

Parameters¶

names: NumberDict|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.
factor:: A scaling factor from base units
powers:: The integer powers for each of the nine base units: [‘m’, ‘kg’, ‘s’, ‘A’, ‘K’, ‘mol’, ‘cd’, ‘rad’, ‘sr’]
offset:: An additive offset to the unit (used only for temperatures)
url:: URL describing the unit
verbosename:: The verbose name of the unit (e.g. Coulomb)
unece_code:: Official unit code (see https://www.unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20_Rev9e_2014.xls)

__le__(other)[source]¶

Test if unit is less or equal than other unit

Parameters¶

other: PhysicalUnit: Other unit to compare with

Returns¶

bool: True, if unit is less or equal than other unit

__lt__(other)[source]¶

Test if unit is less than other unit

Parameters¶

other: PhysicalUnit: Other unit to compare with

Returns¶

bool: True, if unit is less than other unit

__mul__(other)[source]¶

Multiply units with other value

Parameters¶

other:: Value or unit to multiply with

Returns¶

PhysicalUnit or PhysicalQuantity: Multiplied unit

Examples¶

>>> from PhysicalQuantities import q
>>> q.m.unit * q.s.unit
m*s

__pow__(exponent)[source]¶

Power of a unit

Parameters¶

exponent: PhysicalUnit: Power exponent

Returns¶

PhysicalUnit: Unit to the power of exponent

Examples¶

>>> from PhysicalQuantities import q
>>> q.m.unit ** 2
m^2

__repr__()[source]¶: Return repr(self).

__rmul__(other)¶

Multiply units with other value

Parameters¶

other:: Value or unit to multiply with

Returns¶

PhysicalUnit or PhysicalQuantity: Multiplied unit

Examples¶

>>> from PhysicalQuantities import q
>>> q.m.unit * q.s.unit
m*s

__str__()[source]¶

Return string text representation of unit

Returns¶

str: Text representation of unit

__truediv__(other)¶

Divide two units

Parameters¶

other: PhysicalUnit: Other unit to divide

Returns¶

PhysicalUnit: Divided unit

Examples¶

>>> from PhysicalQuantities import q
>>> q.m.unit / q.s.unit
m/s

__weakref__¶: list of weak references to the object (if defined)

conversion_factor_to(other)[source]¶

Return conversion factor to another unit

Parameters¶

other: PhysicalUnit: Unit to compute conversion factor for

Returns¶

float: Conversion factor

Examples¶

>>> from PhysicalQuantities import q
>>> q.km.unit.conversion_factor_to(q.m.unit)
1000.0

conversion_tuple_to(other)[source]¶

Return conversion factor and offset to another unit

Parameters¶

other: PhysicalUnit: Unit to compute conversion factor and offset for

Returns¶

float tuple: Tuple (factor, offset)

Examples¶

>>> from PhysicalQuantities import q
>>> q.km.unit.conversion_tuple_to(q.m.unit)
(1000.0, 0.0)

static from_dict(unit_dict)[source]¶

Retrieve PhysicalUnit from dict description

Parameters¶

unit_dict: dict: PhysicalUnit stored as dict

Returns¶

PhysicalUnit: Retrieved PhysicalUnit

Notes¶

Current implementation: throw exception of unit has not already been defined

static from_json(json_unit)[source]¶

Retrieve PhysicalUnit from JSON string description

Parameters¶

json_unit: str: PhysicalUnit encoded as JSON string

Returns¶

PhysicalUnit: New PhysicalUnit

property is_angle¶

Check if unit is an angle

Returns¶

bool: True if unit is an angle

property is_dimensionless¶

Check if no dimension is given

Returns¶

bool: True if dimensionless

property is_power¶

Test if unit is a power unit. Used of dB conversion TODO: basically very dumb right now

Returns¶

bool: True if it is a power unit, i.e. W, J or anything like it

property latex¶

Return unit as a LaTeX formatted string

Returns¶

str: Unit as LaTeX string

property markdown¶

Return unit as a markdown formatted string

Returns¶

str: Unit as LaTeX string

property name¶

Return name of unit

Returns¶

str: Name of unit

set_name(name)[source]¶

Set unit name as NumberDict

Parameters¶

name: str: Unit name

property to_dict¶

Export unit as dict

Returns¶

dict: Dict containing unit description

Notes¶

Give unit and iterate over base units

property to_json¶: Export unit as JSON

Notes¶

Give unit and iterate over base units

exception PhysicalQuantities.quantity.UnitError[source]¶

__weakref__¶: list of weak references to the object (if defined)