synthesizer.units

A module for dynamically returning attributes with and without units.

The Units class below acts as a container for the unit system.

The Quantity is a descriptor object which uses the Units class to attach units to attributes of a class. The Quantity descriptor can be used to attach units to class attributes.

Example definition:

class Foo:

bar = Quantity(“spatial”)

def __init__(self, bar):

self.bar = bar

Example usage:

foo = Foo(bar)

bar_with_units = foo.bar bar_no_units = foo._bar

Functions

synthesizer.units.accepts(**units)

Check arguments passed to the wrapped function have compatible units.

This decorator will cross check any of the arguments passed to the wrapped function with the units defined in this decorators kwargs. If units are not compatible or are missing an error will be raised. If the units don’t match the defined units in units then the values will be converted to the correct units.

This is inspired by the accepts decorator in the unyt package, but includes Synthesizer specific errors and conversion functionality.

Parameters:

**units (dict) –

The keyword arguments defined with this decorator. Each takes the form of argument=unit_for_argument. In reality this is a dictionary of the form {“variable”: unyt.unit}.

In addition to normal arguments, this decorator also supports the name of *args and **kwargs parameters. When such a name is supplied, every value stored inside that argument tuple or keyword dictionary will be checked and converted against the provided unit.

Returns:

function

The wrapped function.

synthesizer.units.convert_in_place(arr, unit)

Convert a unyt_array or unyt_quantity to unit in place.

Converting in place avoids duplicating the array. The array carries a record of the conversion in its units, so anything else holding a reference to it stays consistent. Read-only arrays can’t be converted in place, so these (and only these) are copied.

Parameters:

• arr (unyt_array/unyt_quantity) – The array to convert.

• unit (unyt.unit_object.Unit/str) – The unit to convert to.

Returns:

The converted array, which is arr itself unless arr is read-only.

Return type:

unyt_array/unyt_quantity

Raises:

UnitConversionError – If the unit is not compatible with the existing unit.

synthesizer.units.deepcopy_with_shared_units(self, memo)

Deep copy an object while sharing the units of the unyt arrays it holds.

This is assigned as __deepcopy__ on classes holding Quantities. unyt deep copies a Unit by deep copying its entire unit registry (ignoring the memo), which costs milliseconds and a full registry’s worth of memory for every array copied. Units are immutable in practice so sharing them is safe, and it keeps each Quantity’s own unit object so the identity check in _QuantityView still applies to the copy. The array data and every other attribute are deep copied as normal.

Parameters:

• self (object) – The object to copy.

• memo (dict) – The deepcopy memo.

Returns:

The deep copy.

Return type:

object

synthesizer.units.get_array_quantity_view(values, unit)

Wrap a raw ndarray in units without copying data.

Parameters:

• values (np.ndarray) – Raw array buffer to wrap.

• unit (unyt.Unit) – Unit to attach to values.

Returns:

Unit-bearing view of values.

Return type:

unyt_array

synthesizer.units.get_quantity_unit(obj, attr_name)

Get a Quantity descriptor unit without materialising the array.

Parameters:

• obj (object) – Object whose class defines the Quantity descriptor.

• attr_name (str) – Public descriptor name, e.g. "lnu".

Returns:

Unit attached to the descriptor.

Return type:

unyt.Unit

synthesizer.units.has_units(x)

Check whether the passed variable has units.

This will check the argument is a unyt_quantity or unyt_array.

Parameters:

x (generic variable) – The variables to check.

Returns:

bool

True if the variable has units, False otherwise.

synthesizer.units.unit_is_compatible(value, unit)

Check if two values have compatible units.

This function checks that a unyt_quantity or unyt_array or another Unit is compatible with a unit, i.e. it has the same dimensions. If they are not compatible, it raises an exception.

This could also be done wrapping a conversion attempt in a try/except block but this is more efficient as it avoids the overhead of unyt’s conversion system.

I might have missed a method in unyt for this but I couldn’t find one.

Parameters:

• value (unyt_quantity/unyt_array/Unit) – The value to check.

• unit (Unit) – The unit to check against.

Returns:

bool

True if the values have compatible units, False otherwise.

synthesizer.units.unyt_to_ndview(arr, unit=None)

Return the raw buffer of a unyt_array or unyt_quantity.

The point of this helper is to hand downstream NumPy code a plain ndarray so it does not pay unyt’s ufunc dispatch on every operation, and to do so without copying. With no unit, or a unit the array already carries, the buffer comes back untouched, and a unit that differs is converted in place (see convert_in_place) before the buffer is returned.

Converting in place rewrites arr’s values and units, so anything else holding arr sees the conversion recorded in its units. Any unit-free view of arr already handed out (e.g. a Quantity’s private name) is rewritten without that record.

Parameters:

• arr (unyt_array/unyt_quantity) – The unyt_array or unyt_quantity to extract the data from.

• unit (unyt.unit_object.Unit) – The unit to convert to. If None, the existing unit is used. If the unit is not compatible with the existing unit, an error will be raised.

Returns:

The underlying data as a numpy array, without a copy

unless arr is read-only and needs converting.

Return type:

np.ndarray

Raises:

UnitConversionError – If the unit is not compatible with the existing unit.

Classes

class synthesizer.units.DefaultUnits

The DefaultUnits class is a container for the default unit system.

This class is used to store the default unit system for Synthesizer. It contains all the unit categories defined in the default unit system.

...

The unit for each category defined in the default unit system.

Type:

unyt.unit_object.Unit

items()

Return the items of the default unit system.

keys()

Return the keys of the default unit system.

values()

Return the values of the default unit system.

class synthesizer.units.Quantity(category)

A descriptor class controlling dynamically associated attribute units.

Provides the ability to associate attribute values on an object with unyt units defined in the global unit system (Units).

unit

The unit for this Quantity from the global unit system.

Type:

unyt.unit_object.Unit

public_name

The name of the class variable containing Quantity. Used the user wants values with a unit returned.

Type:

str

private_name

The name of the class variable with a leading underscore. Used the mostly internally for (or when the user wants) values without a unit returned. A _QuantityView is installed on the class under this name, and the value with units is stored in the instance dict under this key.

Type:

str

class synthesizer.units.UnitSingleton

A metaclass used to ensure singleton behaviour for the Units class.

A singleton design pattern is used to ensure that only one instance of the class can exist at any one time.

class synthesizer.units.Units(new_units=None, force=False)

Holds the definition of the internal unit system using unyt.

Units is a Singleton, meaning there can only ever be one. Each time a new instance is instantiated the original will be returned. This enforces a consistent unit system is used in a single top level namespace.

All default attributes are hardcoded but these can be modified by instantiating the original Units instance with a dictionary of units of the form {“variable”: unyt.unit}. This must be done before any calculations have been performed, changing the unit system will not retroactively convert computed quantities! In fact, if any quantities have been calculated the original default Units object will have already been instantiated, thus the default Units will be returned regardless of the modifications dictionary due to the rules of a Singleton metaclass. The user can force an update but BE WARNED this is dangerous and should be avoided.

...

The unit for each category defined in the default unit system or any modifications made by the user.

Type:

unyt.unit_object.Unit

overwrite_defaults_yaml()

Permanently overwrite the default unit system with the current one.

This method is used to overwrite the default unit system with the current one. This is to be used when the user wants to permanently modify the default unit system with the current one.

reset_defaults_yaml()

Reset the default unit system to the original one.

This will overwrite the default_units.yml file with the original_units.yml file.