paraqeet.quantity.Quantity

class paraqeet.quantity.Quantity(value, min_value, max_value, unit='', name='', two_pi=False)

Bases: object

Represent any physical quantity used in model or pulse specification.

For arithmetic operations just the numeric value is used. The value itself is stored in an optimizer friendly way as a float between -1 and 1. The conversion is given by scale * (value + 1) / 2 + offset

For convenience, the constructor and setter functions accept primitive floats. However, these will be converted into numpy arrays internally, such that scalar values are represented by arrays of shape (1,). All getter functions only return numpy arrays. If the value is an array and min/max are floats, the latter will be considered constant bounds for all value and will be converted into constant arrays.

Note on python’s operators: equality checks q == p and q != p check for the values of the quantities q and p. For vector or matrix quantities, these check if all values are equal. If you want to be sure that two quantities are the same object (i.e. the same memory address), use q is p. Ordering operators like q > p will only work for scalar quantities and will raise an exception for vector or matrix quantities.

Parameters:

• value (Array | float) – Value of the quantity

• min_value (Array | float) – Minimum this quantity is allowed to take. If this is a float, it will be a default interval around the value will be chosen.

• max_value (Array | float) – Maximum this quantity is allowed to take.

• unit (str) – physical unit

• name (str) – symbol or description of this quantity

• two_pi (bool) – divide by two pi for representation

Raises:

IncompatibleQuantityException – If misconfigured by the user, e.g., bounds are not given or the wrong shape.

__init__(value, min_value, max_value, unit='', name='', two_pi=False)

Parameters:

• value (Array | float)

• min_value (Array | float)

• max_value (Array | float)

• unit (str)

• name (str)

• two_pi (bool)

Methods

__init__(value, min_value, max_value[, ...])
add_relation(other, relation[, check_units])	Add a relation of self to one or more other quantities.
from_dict(data)	Loads the quantity from a dictionary.
get_length()	Get length of parameter.
get_max_value()	Get maximum value of parameter.
get_min_value()	Get minimum value of parameter.
get_name()	Return the symbol or description or this quantity.
get_reduced_value()	Return the value in the reduced representation.
get_scale()	Get scale of parameter.
get_unit()	Get unit of measurement from parameter.
get_value()	Get value of the parameter.
is_scalar()	Check if parameter is scalar.
is_vector()	Check if parameter is vector.
relational(quantities, relation[, unit, ...])	Create a relationally derived parameter.
relational_copy(quantity)	Create a Quantity object that is a one to one copy of a Quantity.
set_limits(min_value, max_value)	Set the allowed minimum and maximum of this quantity.
set_name(name)	Assigns a new name to this quantity.
set_reduced_value(value)	Set reduced value limit for parameter.
set_value(value)	Set the value of this quantity.
set_value_and_limits(value, min_value, max_value)	This can be used to set the value and the limits to new values at the same time.
to_dict()	Creates a dictionary representation of this quantity that can be stored.
update()	Update value of the parameter.

Attributes

dependencies	If dependent, get a list of parameter dependencies.
dependent	The dependency status of the quantity.
dependents	Get a list of parameter dependents.

add_relation(other, relation, check_units=True)

Add a relation of self to one or more other quantities.

Parameters:

• other (Quantity | List[Quantity]) – The quantities from which to calculate the value of self.

• relation (Callable) – Function describing how to calculate the value of self from other Quantities.

• check_units (bool) – If False, the check for equal units is not performed and unequal units are allowed.

Return type:

None

property dependencies: list[Quantity]

If dependent, get a list of parameter dependencies.

If calculated from other quantities by a relation, this method returns the list of parameters that this quantity is calculated from, otherwise an empty list is returned.

Returns:

List of parameter dependencies.

Return type:

list[Quantity]

property dependent

The dependency status of the quantity.

if True:

The value of this quantity is calculated from other quantities

if False:

The value of this quantity is independent of any other quantity

property dependents: list[Quantity]

Get a list of parameter dependents.

This method returns the list of parameters that use this Quantity to calculate its value from. If no other Quantities calculate their value using this quantity, returns an empty list.

Returns:

List of parameter dependencies.

Return type:

list[Quantity]

from_dict(data)

Loads the quantity from a dictionary. The dictionary must have the same form as the one created by the toDict function. All properties of this quantity (value, name, etc.) will be overwritten.

Parameters:

data (dict)

Return type:

None

get_length()

Get length of parameter.

Return type:

int

get_max_value()

Get maximum value of parameter.

Return type:

Array

get_min_value()

Get minimum value of parameter.

Return type:

Array

get_name()

Return the symbol or description or this quantity.

Note that this does not have to be unique. For uniquely identifying a quantity, use getUUID.

Returns:

Value of the name attribute.

Return type:

str

get_reduced_value()

Return the value in the reduced representation.

Returns:

Value from the reduced representation.

Return type:

Array

get_scale()

Get scale of parameter.

Return type:

Array

get_unit()

Get unit of measurement from parameter.

Return type:

str

get_value()

Get value of the parameter.

Return type:

Array

is_scalar()

Check if parameter is scalar.

Return type:

bool

is_vector()

Check if parameter is vector.

Return type:

bool

classmethod relational(quantities, relation, unit=None, name=None, two_pi=False)

Create a relationally derived parameter.

Creates a Quantity object that represents a Quantity that is calculated from other quantities using the relation function.

Parameters:

• quantities (Quantity | list[Quantity]) – The quantities from which to calculate the value of self.

• relation (Callable) – Function describing how to calculate the value of self from other Quantities.

• unit (str | None) – The unit of the resulting Quantity. If ‘None’, then the units of all quantities are assumed the same.

• name (str | None) – A string identifier name of the resulting Quantity. If ‘None’, then a name is generated from the names of the related Quantities.

• two_pi (bool) – Divide by two pi for representation.

Returns:

The Quantity with a relation set up, which recalculates the value of self from all dependencies.

Return type:

Quantity

Raises:

ValueError: – If any quantities do not have the same unit and no special unit is specified.

classmethod relational_copy(quantity)

Create a Quantity object that is a one to one copy of a Quantity.

If the quantity is updated, so is this relational copy.

Parameters:

quantity (Quantity | List[Quantity]) – The quantities from which the relational copy should be created.

Returns:

The Quantity with a relation set up, which recalculates the value of self from all dependencies.

Return type:

Quantity

set_limits(min_value, max_value)

Set the allowed minimum and maximum of this quantity.

Parameters:

• min_value (int) – Input value for setting the minimum limit.

• max_value (int) – Input value for setting the maximum limit.

Return type:

None

set_name(name)

Assigns a new name to this quantity.

Parameters:

name (str)

Return type:

None

set_reduced_value(value)

Set reduced value limit for parameter.

Parameters:

value (Array | float)

Return type:

None

set_value(value)

Set the value of this quantity.

Value needs to be within the range of ‘min_value’ and ‘max_value’.

Parameters:

value (Array | float) – Input value to be used for setting.

Raises:

ValueError – If the value is not within the range of ‘min_value’ and ‘max_value’, if the shape of the value is different from ‘min_value’ or ‘max_value’, or if this is a dependent quantity

Return type:

None

set_value_and_limits(value, min_value, max_value)

This can be used to set the value and the limits to new values at the same time. This function does not raise an exception if the new value is outside of the old limits.

Parameters:

• value (Array | float)

• min_value (Array | float)

• max_value (Array | float)

Return type:

None

to_dict()

Creates a dictionary representation of this quantity that can be stored. The returned dict is compatible with the from_dict function, i.e. the quantity can be fully restored including its bounds, name, unit, etc. Higher dimensional quantities (tensors) will be flattened into a list but their proper shape is stored as well.

Return type:

dict

update()

Update value of the parameter.

Update function that is called if a value that this quantity is dependent on is changed.