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 defintion:

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 – 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}.

Returns:

function

The wrapped function.

synthesizer.units.has_units(x)

Check whether the passed variable has units.

This will check the argument is a unyt_quanity or unyt_array.

Parameters:

x (generic variable) – The variables to check.

Returns:

bool

True if the variable has units, False otherwise.

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 decriptor class controlling dynamicly 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.

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()

Permenantly 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 permenantly 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.