madgui.util.unit module

Utilities for converting between units of physical quantities, e.g. meters to millimeters, etc. This is done using the Pint library.

Note that we do not use pint to wrap quantities that are passed around within madgui internally, as it would be the idiomatic approach: add units on input, internally work with quantities with units attached, remove units on output.

Instead, we convert units usually only on input and then assume everything is in MAD-X units. The reason is that using quantities internally infects the whole applications and requires unpack/repack operations in hundreds of places. This amount of book-keeping is not justified in a space, where we can almost exclusively rely on MAD-X units being used anyway.

Furthermore, we pass around strings internally and not Unit objects. This simplifies interoperability with external packages and the performance cost for parsing the unit multiple times is negligible (since it rarely needs to be done now anyway).

The most frequent usage of this module is to convert a number between internal (MAD-X) and UI display units. This works as follows:

in_madx_units = from_ui({'energy': textcontrol_energy.text()})

in_ui_units = to_ui({'energy': 450})

Functions

get_unit(quantity)	Return a Quantity object with the same unit as quantity, but magnitude 1 (one).
add_unit(quantity, unit)	Add a unit to the number quantity.
strip_unit(quantity[, unit])	Convert the quantity to a plain float.
change_unit(quantity, from_unit, to_unit)
toquantity(value)
tounit(quantity, unit)	Cast the quantity to a specific unit.
format_quantity(quantity[, num_spec])	Get a nice display string for the quantity.
get_raw_label(quantity)	Get the name of the unit, without enclosing brackets.
from_config(unit)	Parse a config entry for a unit to a pint.unit.Quantity instance.
convert(from_, to, *args)
from_ui(*args)
to_ui(*args)

Classes

UnitConverter(units)

Quantity converter.

class madgui.util.unit.UnitConverter(units)

Bases: object

Quantity converter.

Used to add and remove units from quanitities and evaluate expressions.

Variables

_units (dict) – unit dictionary

Methods

add_unit(name, value)	Add units to a single number.
dict_add_unit(obj)	Add units to all elements in a dictionary.
dict_strip_unit(obj)	Remove units from all elements in a dictionary.
from_config_dict(conf_dict)	Convert a config dict of units to their in-memory representation.
get(name)
label(name[, value])	Get the name of the unit for the specified parameter name.
strip_unit(name, value)	Convert to MAD-X units.

add_unit(name, value)

Add units to a single number.

dict_add_unit(obj)

Add units to all elements in a dictionary.

dict_strip_unit(obj)

Remove units from all elements in a dictionary.

classmethod from_config_dict(conf_dict)

Convert a config dict of units to their in-memory representation.

get(name)

label(name, value=None)

Get the name of the unit for the specified parameter name.

strip_unit(name, value)

Convert to MAD-X units.

madgui.util.unit.add_unit(quantity, unit)

Add a unit to the number quantity. If quantity already has a unit, it will perform unit conversion.

madgui.util.unit.change_unit(quantity, from_unit, to_unit)

madgui.util.unit.convert(from_, to, *args)

madgui.util.unit.format_quantity(quantity, num_spec='')

Get a nice display string for the quantity.

madgui.util.unit.from_config(unit)

Parse a config entry for a unit to a pint.unit.Quantity instance.

The pint parser is quite powerful. Valid examples are:

s / m² microsecond 10 rad m^-2

madgui.util.unit.from_ui(*args)

madgui.util.unit.get_raw_label(quantity)

Get the name of the unit, without enclosing brackets.

madgui.util.unit.get_unit(quantity)

Return a Quantity object with the same unit as quantity, but magnitude 1 (one). Returns None if quantity does not have a unit.

madgui.util.unit.strip_unit(quantity, unit=None)

Convert the quantity to a plain float.

madgui.util.unit.to_ui(*args)

madgui.util.unit.toquantity(value)

madgui.util.unit.tounit(quantity, unit)

Cast the quantity to a specific unit.