qruise-toolset

qruise.toolset.hamiltonian

Docstring for the hamiltonian.py module.

Anything that is related to the definition of the Hamiltonian of a quantum system.

Hamiltonian

Declaring the Hamiltonian of a system of interest.

This instantiates a Hamiltonian object with time-indepedent part specified by H0 and time-dependent parts drives passed as a list of tuples with the first element the basis and the second element as its time-dependent coefficient.

Parameters:

Name	Type	Description	Default
H0	Array | Qobj	JAX matrix or a Qobj representing the time-independent part of the Hamiltonion.	_A
Ht	List[Tuple[Array | Qobj, Callable]]	List of tuples with the first element being the basis and the second being the time-dependent coefficient.	_A

Attributes:

Name	Type	Description
H0	Array	JAX array signifying the time-independent part of the Hamiltonian.
coeffs	List[Callable]	List of callable functions defining the coefficients of the time-dependent part of the Hamiltonian.
hamils	List[Array]	List of JAX arrays which in combination with coeffs specifies the operators of the time-depenedent parts of the Hamiltonian.

Methods:

Name	Description
add_term	add a time-dependent part to the Hamiltonian

__call__(A, t, params)

Return the Hamiltonian at a given instance of time.

Parameters:

Name	Type	Description	Default
t	float | Array	An instance of time.	required
params	Dict[str, float]	Dictiorary of parameters that is passed to the envelopes of the Hamiltonian's terms.	required

Returns:

Type	Description
Array	The Hamiltonian matrix.

add_term(A, hamil, coeff)

Method to add extra terms to the base Hamiltonian.

Given the basis hamil and its coefficient coeff a new time-depenedent part will be added to the Hamiltonian.

Parameters:

Name	Type	Description	Default
hamil	Array | Qobj	Hamiltonian matrix operator.	required
coeff	Callable	Callable function as the coefficient of the Hamiltonian channel hamil, usually time-dependent.	required

qruise.toolset.control_stack

Docstring for the control_stack.py module.

Module for defining the functional behaviour of different control electronics in a control stack.

Every component falls into two categories: (i) it is either a source, i.e. it produces a signal, or (ii) it transforms the input signal from a source. These components can be represented by a function. The reason we use classes here is due to the fact that some transformations are non-local in time. Therefore some memory kernels or internal states must be tracked.

ADC

Bases: SignalChainComponent

Analogue-to-Digital component.

It discretise the input up to a precision indicated by the number of bits. The ADC component is limited to a range of operation voltage, namely \(V_{min}\) and \(V_{max}\). Mathematically, it transforms an input signal \(f(t)\) via

\[ \begin{gather} \delta = \frac{V_{max} - V_{min}}{2^n - 1}\\ f_{d}(t) = V_{min} + \Big[\frac{f(t) - V_{min}}{\delta}\Big] \delta \end{gather} \]

where \(n\) is the number of bits, and \(f_d(t)\) is the digitised representation of the function \(f(t)\).

Gaussian

Bases: SignalChainComponent

AWG component generating Gaussian pulse.

The mathematical expression is given by

\[ \frac{a}{\sigma\sqrt{2\pi}} \exp [-\frac{(t-\mu)^2}{2\sigma^2}] \]

where \(a\) is a factor that scales the maximum value of the puls, \(\sigma\) is the standard deviation and \(\mu\) is the mean value.

Heaviside

Bases: SignalChainComponent

AWG component generating a Heaviside pulse.

The definition is given by

\[ H(t) = \left\lbrace \begin{aligned} &0\,,\; &t \lt 0 \\ &0\,,\; &t = 0 \\ &1\,,\; &t \gt 0 \end{aligned} \right. \]

LocalOscillator

Bases: SignalChainComponent

AWG component generating pure sine pulse.

The mathematical expression is given by

\[ A \sin(\omega t + \phi) \]

where \(A\) is the amplitude, \(\omega\) is the frequency, and \(\phi\) is a constant phase.

PWCPulse

Bases: SignalChainComponent

Piece-wise constant pulse.

Outputs a piece-wise constant pulse at a certain time instance t on a given time interval [t0, t1] and a given time differential dt, provided that the array of the pulse is known. Mathematically,

\[ n = \lfloor \frac{t - t_0}{dt} \rfloor\\ \mathrm{env}[n] \]

where \(\mathrm{env}\) is the pulse profile and \([n]\) shows the index n of the pulse profile.

Rectangular

Bases: SignalChainComponent

AWG component generating a rectangular pulse.

The definition is given by

\[ \mathrm{rect}(t, \tau_1, \tau_2) = \Theta(t - \tau_1) - \Theta(t - \tau_2) \]

where \(\Theta(t)\) is the Heaviside function. If \(\tau_1 > \tau_2\) then the rectangular pulse has a positive range where as if \(\tau_1 < \tau_2\), the function has a negative range.

SignalChainComponent

Abstract signal chain component.

Parameters:

Name	Type	Description	Default
name	str	Name of the component.	required
params	Dict[str, ArrayOrFloat]	Component parameters.	required
source	Callable | None	The component signifying an external component asthe input source if the component is not a source itself.	_A
**kwargs	Dict	Keyworded arguments.	required

Attributes:

Name	Type	Description
params	Dict[str, ArrayOrFloat]	Default values for a subset of parameters associated with the component.
inactive_params	Set[str]	Set of strings used to let JAX know which parameters do not contribute to the gradient when differentiated.

TransferFunc

Bases: SignalChainComponent

Transfer Function modelled in its space-state representation.

State-space representation of transfer function, also known as Rosenbrock system matrix, for dynamical system of the form

\[ \begin{aligned} \dot{x}(t) &= Ax(t) + Bu(t)\\ y(t) &= Cx(t) + Du(t) \end{aligned} \]

is given by the Rosenbrock system matrix as follows

\[ \begin{aligned} P(s) = \begin{pmatrix} sI - A & -B\\ C & D \end{pmatrix}. \end{aligned} \]

As a linear time-invariant systems, transfer functions have state-space reperestation[1].

Parameters:

Name	Type	Description	Default
name	str	Name of the component.	required
params	Dict[str, ArrayOrFloat]	Component parameters.	required
source	Callable | None	The component signifying an external component asthe input source if the component is not a source itself.	_A
**kwargs	Dict	Keyworded arguments. TransferFunc has two keyworded arguments to tune its behaviour. One is n_max which specifies how finely we create the time grid and second max_squarings which species the maximum power the expm scaling-and-squaring order.	required

Attributes:

Name	Type	Description
params	Dict[str, ArrayOrFloat]	Default values for a subset of parameters associated with the component.
inactive_params	Set[str]	Set of strings used to let JAX know which parameters do not contribute to the gradient when differentiated.

Notes

[1] De Schutter, B., 2000. Minimal state-space realization in linear system theory: an overview. Journal of computational and applied mathematics, 121(1-2), pp.331-354.

freeze_params(freeze_keys)

Decorator to set a set a set of varibales as inactive parameters.

Parameters:

Name	Type	Description	Default
freeze_keys	Set	Set of keys to be set as inactive variables.	required

Returns:

Type	Description
Callable	Decorated function with certain variables set as inactive.

qruise.toolset.parameter

Docstring for the parameter.py module.

The intention is to enable the user to effectively and efficiently keeps track of the parameters involved in the simulation of a quantum system. The only and single source of truth on which the user can rely to get current value of the parameters after any mutable operation. This allows other parts of qruise-toolset to remain static.

ParameterCollection

A collection of parameters.

A single source of truth to keep track of parameters to be optimised or parsed anytime anywhere.

Attributes:

Name	Type	Description
params	Dict[str, float]	A dictionary of parameters.

Methods:

Name	Description
add_param	Add a key-value pair to the collection.
get_val	Get the value of a given key.
add_dict	Adding an input dictionary as a batch of key-pair values.
get_collection	Returns the collection of parameters.

__repr__(B)

Print nicely all the parameters in the collection.

Returns:

Type	Description
str	Nicely formatted string listing all the parameters.

add_dict(A, source_dict)

Add a set of key-value pairs in a batch mode.

Parameters:

Name	Type	Description	Default
source_dict	Dict[str, float]	A dictionary of key-value pairs.	required

add_param(B, key, val)

Add a single key-value pair to the parameter collection.

Parameters:

Name	Type	Description	Default
key	str	A string specifying the name of the parameter.	required
val	float	Value associated with the key.	required

get_collection(A)

Return all the parameters in the collection.

Returns:

Type	Description
Dict[str, float]	Dictionary of key-value pairs of the parameters in the collection.

get_val(A, key)

Get the value of a parameter.

Parameters:

Name	Type	Description	Default
key	str	The name of the parameter.	required

Returns:

Type	Description
float	The value of the parameter.

qruise.toolset.problem

Docstring for the problem.py module.

A Problem defines a set of ordinary differential equations to solve the dynamics of a quantum system given its Hamiltonian. Generally speaking, if the Hamiltonian of a system is known, one can solve the dynamics of a closed quantum system using the Schrödinger equation, or if one deals with an open quantum system, the von Neumann equation or Lindblad equation is the right choice.

EnsembleProblem

Bases: Problem

An ensemble problem.

Parameters:

Name	Type	Description	Default
hamiltonian	Hamiltonion	The Hamiltonian of interest.	required
y0_axis	Tuple[Array, int | None]	Tuple of initial state and the dimension over which the the batching is assumed.	required
params	Tuple[str, ArrayOrFloat]	Simulation parameters provided as an array or a scalar float.	required
time_span	Tuple[ArrayOrFloat, ArrayOrFloat]	Simulation time span indicating the starting and ending times. Each element can be either an array or a scalar float.	required

Attributes:

Name	Type	Description
hamiltonian	Hamiltonian	System's Hamiltonian.
y0	Array	The initial quantum state(s).
params	Dict[str, ArrayOrFloat]	Simulation parameters
time_span	Tuple[ArrayOrFloat, ArrayOrFloat]	Simulation time span; tuple of starting and ending times. Can be either an array or a scalar float.

problem(A)

Provide an AbstractSolver with necessary inputs for a simulation.

Returns:

Name	Type	Description
Tuple	Tuple[Array, Dict[str, ArrayOrFloat], Tuple[ArrayOrFloat, ArrayOrFloat], InAxes]	A tuple with the first element as the initial quantum state, the second as a dictionary of parameters, the third as a simulation time span and the last as the axes description for JAX vectorisation map.

Problem

Generic class for specifying a quantum simulation problem.

Parameters:

Name	Type	Description	Default
hamiltonian	Hamiltonian	The Hamiltonian of interest.	required
y0	Array	The initial state of the quantum system.	required
params	Dict[str, float]	Parameters that uniquely define the Hamiltonian.	required
time_span	Tuple[float, float]	Time interval over which the problem is defined. Basically, the start and end of the simulation.	required

Attributes:

Name	Type	Description
hamiltonian	Hamiltonian	Hamiltonian of the system.
y0	Array	Initial quantum state.
time_span	Tuple[float, float]	Simulation starting and ending times.
dimension	Int	Size of the Hilbert space.

Methods:

Name	Description
problem	Return a tuple of initial condition, parameters and simulation time span.
schroedinger	System of ODEs for the Schrödinger equation.
von_neumann	System of ODEs for the von Neumann master equation.
lindblad	System of ODEs for the Lindblad equation.
sepwc	System of equations for piece-wise constant Schrödinger equation.
mepwc	System of equations for piece-wise constant master equation.

lindblad(E, c_ops)

Return the Lindblad master equation.

The Lindblad master equation is given by

\[ i\frac{\partial}{\partial t}\rho_t = [H_t, \rho_t] + \sum_i \gamma_i \left(L_i \rho_t L_i^\dagger - \frac{1}{2}\left\{L_i^\dagger L_i, \rho_t \right\}\right), \]

where \(i\) is the imaginary number, \(\rho_t\) is the density matrix of the system at time \(t\), and \(H_t\) is the Hamiltonian of the system. The notion \([., .]\) stands on the commutation relation, whereas \(\{., .\}\) stands on anti-commutation. The operators \(L_i\) are called collapse operators. We used the convention of setting \(\hbar = 1\).

Parameters:

Name	Type	Description	Default
c_ops	List[Qobj | Array]	List of collapse operators as QuTiP objects or JAX arrays.	required

Returns:

Type	Description
Callable	ODE defining the Lindblad master equation.

mepwc(A)

Compile an equation for solving a quantum master equation.

Returns:

Name	Type	Description
Callable	Callable	A callable function that solves unitary evolution of a quantum density matrix.

problem(A, **E)

Return the initial condition, parameters and the time span.

Parameters:

Name	Type	Description	Default
**kwargs	Dict	Dictionary of key-value paris. The keys can be the following: 'y0', 'params' and 'time_span'.	required

Returns:

Type	Description
Tuple[Array, Dict[str, float], Tuple[float, float]]:	Tuple with the first element as a initial condition, the second element as the parameter dictionary and the last as a tuple of time span.

remake(A, **D)

Create a new problem with new set of variables.

Parameters:

Name	Type	Description	Default
**kwargs	Dict	Dictionary of key-value pairs. The keys can be 'hamiltonian', 'y0', 'params' and 'time_span'.	required

Returns:

Type	Description
Problem	A new problem that uses variables from an already instantiated Problem if not mentioned in the kwargs.

schroedinger(A)

Return the Schrödinger equation.

The Schrödinger is given by

\[ i\frac{\partial}{\partial t}|\psi(t)\rangle = H(t)|\psi(t)\rangle, \]

where \(i\) is the imaginary number, \(|\psi(t)\rangle\) is the wave-function of the system at time \(t\), and \(H(t)\) is the Hamiltonian of the system. We used the convention of setting \(\hbar = 1\).

Returns:

Type	Description
Callable	ODE defining the Schrödinger equation.

sepwc(A)

Compile an equation for solving the Schrödinger equation.

Returns:

Name	Type	Description
Callable	Callable	A callable function that solves unitary evolution of a quantum state vector.

von_neumann(A)

Return the von Neumann equation.

The von Neumann master equation is given by

\[ i\frac{\partial}{\partial t}\rho(t) = [H(t), \rho(t)], \]

where \(i\) is the imaginary number, \(\rho(t)\) is the density matrix of the system at time \(t\), and \(H(t)\) is the Hamiltonian of the system. The notion \([., .]\) stands on the commutation relation. We used the convention of setting \(\hbar = 1\).

Returns:

Type	Description
Callable	ODE defining the von Neumann master equation.

QOCProblem

Bases: Problem

Specify a Quantum Optimal Control problem.

Parameters:

Name	Type	Description	Default
hamiltonian	Hamiltonian	The Hamiltonian of interest.	required
y0	Array | Qobj	The initial state of the quantum system.	required
params	Dict[str, float]	Parameters that uniquely define the Hamiltonian.	required
time_span	Tuple[float, float]	Time interval over which the problem is defined. Basically, the start and end of the simulation.	required
yt	Array | Qobj	The desired target state.	required
loss	Callable	Loss function used for the minimisation problem.	required

Attributes:

Name	Type	Description
yt	Array | Qobj	The desired target state.
loss	Callable	Loss function used for the minimisation problem.

problem(C, **B)

Return values required as the inputs of an optimiser.

Parameters:

Name	Type	Description	Default
**kwargs	Dict	Dictionary of key-value pairs. The keys can be the following: 'y0', 'params', 'time_span' and 'yt'.	required

Returns:

Type	Description
Tuple[Arr, Dict[str, float], Tuple[float, float], Array]:	Tuple of four elements. The first is the initial state, the second is the set of parameters, the third is the simulation time span and the last is the target state.

remake(A, **D)

Create a new quantum optimal control problem with new set of variables.

Parameters:

Name	Type	Description	Default
**kwargs	Dict	Dictionary of key-value pairs. The keys can be 'hamiltonian', 'y0', 'params', 'time_span', 'yt' and 'loss'.	required

Returns:

Type	Description
Problem	A new quantum optimal control problem that uses variables from an already instantiated Problem if not mentioned in the kwargs.

qruise.toolset.transforms

Docstring for the transforms.py module.

The sole purpose of this module so to provide the user with utilities to handle optimal control problem efficiently by providing the initial and target states. It provides checks and tools to ensure those states are defined in a sane manner.

Transform

Specify the initial and target states of the Quantum Optimal Control Problem.

Parameters:

Name	Type	Description	Default
input_state	Qobj | Array	The initial state.	required
output_state	Qobj | Array	The target state.	required

Attributes:

Name	Type	Description
input_state	Qobj | Array	The initial state.
output_state	Qobj | Array	The target state.
dims	Tuple	Dimension of the initial and target states.

Methods:

Name	Description
get_y0_yt	Get the initial state and the target state as a tuple.

get_y0_yt(A)

Helper method to get the initial and target states.

Returns:

Type	Description
Tuple[Array, Array]:	Tuple of two elements. The first is the initial state and the second is the target state.

qruise.toolset.solvers.abstract_solver

Abstract solvers and abstract minimisers module.

Contains declaration of two major classes for abstract solvers and optimisers.

AbstractSolver

Bases: ABC

Abstract Solver.

Parameters:

Name	Type	Description	Default
eq	Callable	Defines the equation governing the dynamics.	_A

Methods:

Name	Description
set_system	Set the equation governing the dynamics.
evolve	Evolve the dynamics of the system.
ensemble_evolve	Evolve the dynamics of an ensemble of systems.

ensemble_evolve(A, y0, params, t_span, in_axes, cartesian=False, compile=False)

Simulate an ensemble problem.

The ensemble simulation can take place over either an ensemble of initial conditions, parameters or simulation time spans.

Parameters:

Name	Type	Description	Default
y0	Array	A JAX array, a tensor of rank 1, 2 or 3. If the rank is 1, no parallelisation takes place.	required
params	Dict[str, ArrayOrFloat]	Dictionary of parameters with values passed as either JAX arrays or floats.	required
t_span	Tuple[ArrayOrFloat, ArrayOrFloat]	Tuple of the simulation starting and ending points. Passed as either JAX arrays or floats.	required
in_axes	InAxes	Tuple of axes that provides jax.vmap method with a pytree structure for an ensemble simulation.	required
cartesian	bool	If set to true, compiles a vectorised map function to simulate an ensemble problem and return the result as a an array for a set yielded by the Cartesian product of all the parameters , initial conditions and simulation time spans.	False
compile	bool	If the pytree structure of in_axes changes, set to True to compile a new jitted JAX vmapped function that is compatible.	False

Returns:

Name	Type	Description
Array	Array | Solution	Return an \(n\)-dimensional JAX array solution.

evolve(y0, params, t_span) abstractmethod

Solve for the dynamics of a given system.

For a given equation describing the dynamics, this method evolves the state of the system given its initial condition, input parameters and the interval over which the dynamics must be simulated.

Parameters:

Name	Type	Description	Default
y0	Array	Array specifying the initial condition.	required
params	Dict[str, float]:	Set of parameters.	required
t_span	Tuple[float, float]	Tuple indicating the starting and ending times of the simulation.	required

Returns:

Type	Description
Array | Solution:	Result of the dynamics returned as a JAX array or a diffrax solution.

set_system(A, eq)

Set the equation describing the dynamics of the system.

Parameters:

Name	Type	Description	Default
eq	Callable	The equation governing the dynamics of the system.	required

qruise.toolset.solvers.solvers

Solvers Module.

Class definitions for Ordinary Differential Equations and Pice-Wise Constant solvers.

The module is compatible with diffrax for solving ODE'. Piece-wise constant solver used in extreme cases when ODE solvers fail to converge (which is quite rare). It uses matrix exponentiation of the Hamiltonian to generates unitaries that are infinitesimal generators of the system's dynamics.

ODESolver

Bases: AbstractSolver

Solve an ODE equation.

Parameters:

Name	Type	Description	Default
solver	AbstractSolver	A diffrax ODE solver.	required
eq	Callable	An ODE governing the dynamics.	_A
**kwargs	Dict	Keyworded arguments used to set the ODE solver parameters such as relative, absolute tolerance, and etc. See diffrax API documentation for diffeqsolve.	required

Attributes:

Name	Type	Description
solver	AbstractSolver	A diffrax ODE solver.
kwargs	Dict	Keyworded arguments used to set the ODE solver parameters such as relative, absolute tolerance, and etc.

Methods:

Name	Description
set_system	Register the system of ODE's to be solved.
evolve	Solve an ODE for a given initial condition y0 and a set of parameters given by params evaluated at timestamps t_span.

evolve(A, y0, params, t_span)

Solve for the ODE equation.

Simulate the dynamical system given the initial condition y and the time interval t_eval.

Parameters:

Name	Type	Description	Default
y0	Array	The initial condition.	required
params	Dict[str, float] | Dict[str, Array]	A dictionary of parameters where the values can be a scalar or a JAX array. The array form provides the user with the possibility to parallelise for an ensemble simulation.	required
t_span	Tuple[float, float]	The starting and ending time instances.	required

Returns:

Type	Description
Array | Solution	Solution to the ODE equation. If "saveat" keyword has an array type for keyword "ts" the output is a JAX array. Otherwise, the output is an interpolated solution.

PWCSolver

Bases: AbstractSolver

Piece-wise constant solver.

Parameters:

Name	Type	Description	Default
dt	float	The smallest increment of simulation time grid.	required
store	bool	Specify whether to store the result at each timestamp.	False
eq	Callable	Set of equations describing the unitary evolution of the system.	_A

Attributes:

Name	Type	Description
dt	float	The smallest increment of simulation time grid.

Methods:

Name	Description
set_system	Set the desired set of equations used to evolve the initial state of the system.
evolve	Simulate a quantum dynamics problem.

evolve(A, y0, params, t_span)

Propagate the the initial state vector.

Parameters:

Name	Type	Description	Default
y0	Array	JAX array specifying the initial state.	required
params	Dict[str, float]	Simulation parameters.	required
t_span	Tuple[float, float]	Tuple of size two with indicating the starting and ending times of the simulation.	required

Returns:

Type	Description
Array	Array of state vectors or the last state vector.

set_system(A, eq)

Specify the unitary equation to be solved by the solver.

Parameters:

Name	Type	Description	Default
eq	Callable	The unitary equation of interest.	required