paraqeet package

Subpackages

Submodules

paraqeet.exceptions module

Custom Exception implementations.

exception paraqeet.exceptions.ConfigurationException

Bases: Exception

Raise when configuration issue.

Raised when a layer implementation was not properly configured before running it.

exception paraqeet.exceptions.IncompatibleLayersException

Bases: Exception

Raise when incompatible layers transmission.

Raised when a layer can not handle the form of the result of the previous layer. For example, a unitary fidelity will throw this if the propagation layer only provides the propagated state.

exception paraqeet.exceptions.IncompatibleOptimisationMap

Bases: Exception

Raise when incorrect number of quantities are specified.

Raised when the number of quantities specified in optimisation map doesnt match the number of gradients computed.

exception paraqeet.exceptions.IncompatibleQuantityException

Bases: Exception

Raise when incompatible quantity shape.

Raised when a quantity has an unexpected shape, e.g. a vector quantity if a scalar was expected.

exception paraqeet.exceptions.SerialisationException

Bases: Exception

Raised when reading or writing of a Quantity or an OptimisationMap fails.

paraqeet.file_logger module

Class definition of the file logger object.

class paraqeet.file_logger.FileLogger

Bases: Logger

Logger that writes messages to a file.

Parameters:

logdir (str=".") – Destination directory to store the logs.

__init__(logdir='.')
Parameters:

logdir (str)

Return type:

None

log(params, infidelity)

Write the formatted parameters and the goal to the log file.

Parameters:

  • params (list[Quantity]) – List of quantities to be written to the log file.

  • infidelity (float) – Goal value to be written to the log file.

property logdir: str

Returns the current log directory.

start()

Start logging.

stop(result_message=None)

Stop logging and end the log file with the run information.

Parameters:

result_message (str | None = None) – The message that the user wants to write at the end of the log file.

paraqeet.logger module

Class definition of the Logger model.

class paraqeet.logger.Logger

Bases: object

Abstract base class that can be used as a callback in the optimiser.

log(params, infidelity)

Template function to direct what happens at each log call.

Parameters:

  • params (list[Quantity]) – List of parameters to be logged.

  • infidelity (float) – Goal value to be logged.

start()

Start logging and set starting values to the run parameters.

stop(result_message=None)

Template function to stop logging and set end of log parameters.

Parameters:

result_message (str | None = None) – The message that the user wants to write at the end of the log file.

paraqeet.optimisable module

Class definition for the Optimisable model.

class paraqeet.optimisable.Optimisable

Bases: object

Optimisable parameter model.

This interface must be implemented by any class that provides optimisable parameters. The optimiser will collect all parameters (by reference) and update their values.

Parameters:

  • _name (str | None) – The name of the object.

  • _optimisable_parameters (list[Quantity] = []) – The optimisable parameters associated with the object.

  • _all_optimisable_parameters (list[Quantity] = []) – All the optimisable parameters considered in the optimization. This is needed to set correctly the size of the gradient and its ordering.

property all_optimisable_parameters: list[Quantity]

Get the optimisable parameters

Returns:

The list of all the optimisable parameters considered in the optimization

Return type:

list[Quantity]

abstract get_parameters()

Return all parameters of this class that can be optimised.

Raises:

NotImplementedError – Subclasses derived from this class must implement this method.

Return type:

list[Quantity]

property name: str | None

Get the name of the parameter.

Returns:

Name of the parameter.

Return type:

str | None

property optimisable_parameters: list[Quantity]

Get the optimisable parameters

Returns:

The list of optimisable parameters associated with the object.

Return type:

list[Quantity]

set_all_optimisable_parameters(all_params)

Set all optimisable parameters in the optimisation.

Parameters:

  • params (List[Quantity]) – List of optimisable parameters to be set.

  • all_params (list[Quantity])

Return type:

None

set_optimisable_parameters(params)

Set which parameters associated with the object shall be considered during optimisation.

All quantities that are not in the response of get_parameters will be filtered out. This function is called by the optimiser before gradient based optimisation to tell the layers which gradients to compute.

Parameters:

params (list[Quantity]) – List of optimisable parameters to be set.

Return type:

None

paraqeet.optimisation_map module

Class definition for the Optimisable Map model.

class paraqeet.optimisation_map.OptimisationMap

Bases: object

Optimisation parameter map utility class.

Utility class that collects all parameters that shall be considered during optimisation and associates them with the corresponding Optimisable interface. With this class, Quantities can be traced back to the Optimisable to which they belong. Before optimisation, an instance of this class needs to be filled and passed to the optimiser.

__init__()
add(optimisable, optimisable_quantities=None)

Add an optimisable object and a list of its quantities to the map.

The list contains all parameters of the optimisable object that shall be considered during the optimisation. If the list is empty, all parameters of the class will be used. If the object was already added, the list of quantities will be overwritten.

Parameters:

  • optimisable (Optimisable) – Input Optimisable object for adding to the map.

  • optimisable_quantities (Quantity | list[Quantity] | None = None) – List of all parameters of the optimisable object considered for optimisation.

append(optimisable, optimisable_quantities=None)

Append an optimisable object and a list of its quantities to the map.

This method is similar to the add method, but instead of overwritting the existing entries, this appends the specified list of quantities to the already existing quantities.

Parameters:

  • optimisable (Optimisable) – Input Optimisable object for adding to the map.

  • optimisable_quantities (Quantity | list[Quantity] | None = None) – List of all parameters of the optimisable object considered for optimisation.

filter_by_name(name)

Filter parameters by name of parameter.

Parameters:

name (str) – Name of parameter to be filtered with.

filter_parameters(filter_function)

Filter parameters using filter function.

Updates the list of parameters for all Optimisables in this map using a filter function. Only parameters for which the filter function returns true will remain in this map.

Parameters:

filter_function (Callable) – Filter function that maps quantities to boolean values.

Return type:

None

from_dict(data)

Restores the values of all optimised quantities that are in the dictionary. The format of the dictionary needs to be in the same format as generated by the toDict function.

Parameters:

data (dict) – All quantities that should be restored.

Raises:

SerialisationException – If the dict contains an Optimisable or a Quantity that does not exist in this optimisation map.

Return type:

None

get_all_parameters()

Return all parameters that were added to the system map.

Returns:

All parameters that were added to the map.

Return type:

List[Quantity]

get_optimisables()

Return all optimisable objects that were added to this map.

Returns:

Set of all optimisable objects from the map.

Return type:

set[Optimisable]

get_parameters(optimisable)

Return all quantities associated with the given parameter.

Parameters:

optimisable (Optimisable) – Input optimisable object.

Returns:

List of parameters or None (if the optimisable has not been added yet).

Return type:

list[Quantity] | None

register_params_with_optimisables()

Register optimisable parameters with the system.

Utility function that synchronises the list of parameters with each optimisable class. This needs to be called by the optimiser before gradient based optimisation to tell the layers which gradients to compute.

Return type:

None

remove(optimisable, params=None)

Remove the given optimisable or parameter(s) from the optimisation map.

If params is None, it removes the optimisable from the optimisation map. Else it only removes the specific parameter from the optimisation map.

Parameters:

  • optimisable (Optimisable) – Optimisable to be removed.

  • params (Quantity | list[Quanitity] | None.) – Parameter(s) to be removed from the optimisation map. If None removes the optimisable.

remove_by_name(name)

Remove parameters by name of parameter.

Parameters:

name (str) – Name of parameter to be filtered with.

replace(optimisable, old_parameters, new_parameters)

Perform an in-place substitution of the old and new parameters. This helps to keeps the ordering of parameters the same while replacing parameters.

Parameters:
Return type:

None

to_dict()

Creates a dictionary that contains the values of all quantities that are being optimised, sorted by the Optimisable instances to which they belong. The returned dictionary is meant for export using the serialisation package. It uses the names of Optimisables and Quantities and assumes that those are unique and not None. The format of the dict will be

“optimisable name”: {
“quantity name”: {

“unit”: string, “shape”: tuple[int, …], “twoPi”: bool, “value’: Array, “min”: Array, “max”: Array,

}

}

where the innermost part is generated by Quantity’s toDict function.

Returns:

all optimised quantities in an exportable format

Return type:

dict

Raises:

SerialisationException – If the name of any Optimisable or Quantity is None or not unique.

paraqeet.quantity module

Class definition for the Quantity model.

class paraqeet.quantity.Quantity

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)

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 paramter.

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 fromDict 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.

Module contents

paraqeet: A quantum optimal control toolkit with simple parameter management.