paraqeet package

Subpackages

Submodules

paraqeet.differentiable module

class paraqeet.differentiable.Differentiable

Bases: ABC

An abstract class for differentiable models.

Subclasses must implement the value_and_gradient() method which would return the gradient of the model.

abstract get_value_and_gradient(times)

Calculate the gradient of the model.

Returns:

The value and the gradient of the model.

Return type:

tuple[Array, Array] | tuple[float, Array]

Parameters:

times (Array)

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

Bases: Exception

Raise when incorrect number of quantities are specified.

Raised when the number of quantities specified in optimization 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.SerializationException

Bases: Exception

Raised when reading or writing of a Quantity or an OptimizationMap 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: ABC

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

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.optimizable module

Class definition for the Optimizable model.

class paraqeet.optimizable.Optimizable

Bases: ABC

Optimizable parameter model.

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

Parameters:

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

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

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

property all_optimizable_parameters: list[Quantity]

Get the optimizable parameters

Returns:

The list of all the optimizable parameters considered in the optimization

Return type:

list[Quantity]

abstract get_parameters()

Return all parameters of this class that can be optimized.

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 optimizable_parameters: list[Quantity]

Get the optimizable parameters

Returns:

The list of optimizable parameters associated with the object.

Return type:

list[Quantity]

set_all_optimizable_parameters(all_params)

Set all optimizable parameters in the optimization.

Parameters:

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

  • all_params (list[Quantity])

Return type:

None

set_optimizable_parameters(params)

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

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

Parameters:

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

Return type:

None

paraqeet.optimization_map module

Class definition for the Optimizable Map model.

class paraqeet.optimization_map.OptimizationMap

Bases: object

Optimization parameter map utility class.

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

__init__()
add(optimizable, optimizable_quantities=None)

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

The list contains all parameters of the optimizable object that shall be considered during the optimization. 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:

  • optimizable (Optimizable) – Input Optimizable object for adding to the map.

  • optimizable_quantities (Quantity | list[Quantity] | None = None) – List of all parameters of the optimizable object considered for optimization.

append(optimizable, optimizable_quantities=None)

Append an optimizable 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:

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

  • optimizable_quantities (Quantity | list[Quantity] | None = None) – List of all parameters of the optimizable object considered for optimization.

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 Optimizables 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 optimized 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 Optimizable or a Quantity that does not exist in this optimization 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_optimizables()

Return all optimizable objects that were added to this map.

Returns:

Set of all optimizable objects from the map.

Return type:

set[Optimizable]

get_parameters(optimizable)

Return all quantities associated with the given parameter.

Parameters:

optimizable (Optimizable) – Input optimizable object.

Returns:

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

Return type:

list[Quantity] | None

register_params_with_optimizables()

Register optimizable parameters with the system.

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

Return type:

None

remove(optimizable, params=None)

Remove the given optimizable or parameter(s) from the optimization map.

If params is None, it removes the optimizable from the optimization map. Else it only removes the specific parameter from the optimization map.

Parameters:

  • optimizable (optimizable) – optimizable to be removed.

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

remove_by_name(name)

Remove parameters by name of parameter.

Parameters:

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

replace(optimizable, 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 optimized, sorted by the Optimizable instances to which they belong. The returned dictionary is meant for export using the serialisation package. It uses the names of Optimizables and Quantities and assumes that those are unique and not None. The format of the dict will be

“optimizable 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 optimized quantities in an exportable format

Return type:

dict

Raises:

SerialisationException – If the name of any Optimizable 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 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.

Module contents

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