Libraries package¶
Libraries contain a collection of functions that all share a signature to be used interchangably. One entry of a library is selected in the corresponding config file.
Algorithms module¶
Collection of (optimization) algorithms. All entries share a common signature with optional arguments.

c3.libraries.algorithms.
adaptive_scan
(x_init, fun=None, fun_grad=None, grad_lookup=None, options={})[source]¶ One dimensional scan of the function values around the initial point, using adaptive sampling
 Parameters
x_init (float) – Initial point
fun (callable) – Goal function
fun_grad (callable) – Function that computes the gradient of the goal function
grad_lookup (callable) – Lookup a previously computed gradient
options (dict) –
Options include
 accuracy_goal: float
Targeted accuracy for the sampling algorithm
 probe_listlist
Points to definitely include in the sampling
 init_pointboolean
Include the initial point in the sampling

c3.libraries.algorithms.
cma_pre_lbfgs
(x_init, fun=None, fun_grad=None, grad_lookup=None, options={})[source]¶ Performs a CMAEs optimization and feeds the result into LBFGS for further refinement.

c3.libraries.algorithms.
cmaes
(x_init, fun=None, fun_grad=None, grad_lookup=None, options={})[source]¶ Wrapper for the pycma implementation of CMAEs. See also:
http://cma.gforge.inria.fr/apidocspycma/
 Parameters
x_init (float) – Initial point.
fun (callable) – Goal function.
fun_grad (callable) – Function that computes the gradient of the goal function.
grad_lookup (callable) – Lookup a previously computed gradient.
options (dict) –
Options of pycma and the following custom options.
 noisefloat
Artificial noise added to a function evaluation.
 init_pointboolean
Force the use of the initial point in the first generation.
 spreadfloat
Adjust the parameter spread of the first generation cloud.
 stop_at_convergenceint
Custom stopping condition. Stop if the cloud shrunk for this number of generations.
 stop_at_sigmafloat
Custom stopping condition. Stop if the cloud shrunk to this standard deviation.
 Returns
Parameters of the best point.
 Return type
np.array

c3.libraries.algorithms.
gcmaes
(x_init, fun=None, fun_grad=None, grad_lookup=None, options={})[source]¶ EXPERIMENTAL CMAEs where every point in the cloud is optimized with LBFGS and the resulting cloud and results are used for the CMA update.

c3.libraries.algorithms.
grid2D
(x_init, fun=None, fun_grad=None, grad_lookup=None, options={})[source]¶ Two dimensional scan of the function values around the initial point.
 Parameters
x_init (float) – Initial point
fun (callable) – Goal function
fun_grad (callable) – Function that computes the gradient of the goal function
grad_lookup (callable) – Lookup a previously computed gradient
options (dict) –
Options include points : int
The number of samples
 boundslist
Range of the scan for both dimensions

c3.libraries.algorithms.
lbfgs
(x_init, fun=None, fun_grad=None, grad_lookup=None, options={})[source]¶ Wrapper for the scipy.optimize.minimize implementation of LBFGS. See also:
https://docs.scipy.org/doc/scipy/reference/optimize.minimizelbfgsb.html
 Parameters
x_init (float) – Initial point
fun (callable) – Goal function
fun_grad (callable) – Function that computes the gradient of the goal function
grad_lookup (callable) – Lookup a previously computed gradient
options (dict) – Options of scipy.optimize.minimize
 Returns
Scipy result object.
 Return type
Result

c3.libraries.algorithms.
single_eval
(x_init, fun=None, fun_grad=None, grad_lookup=None, options={})[source]¶ Return the function value at given point.
 Parameters
x_init (float) – Initial point
fun (callable) – Goal function
fun_grad (callable) – Function that computes the gradient of the goal function
grad_lookup (callable) – Lookup a previously computed gradient
options (dict) – Algorithm specific options

c3.libraries.algorithms.
sweep
(x_init, fun=None, fun_grad=None, grad_lookup=None, options={})[source]¶ One dimensional scan of the function values around the initial point.
 Parameters
x_init (float) – Initial point
fun (callable) – Goal function
fun_grad (callable) – Function that computes the gradient of the goal function
grad_lookup (callable) – Lookup a previously computed gradient
options (dict) –
Options include points : int
The number of samples
 boundslist
Range of the scan

c3.libraries.algorithms.
tf_adadelta
(x_init: numpy.array, fun: Callable = None, fun_grad: Callable = None, grad_lookup: Callable = None, options: dict = {}) → scipy.optimize.optimize.OptimizeResult[source]¶ Optimize using TensorFlow Adadelta https://www.tensorflow.org/api_docs/python/tf/keras/optimizers/Adadelta
 Parameters
x_init (np.array) – starting value of parameter(s)
fun (Callable, optional) – function to minimize, by default None
fun_grad (Callable, optional) – gradient of function to minimize, by default None
grad_lookup (Callable, optional) – lookup stored gradients, by default None
options (dict, optional) – optional parameters for optimizer, by default {}
 Returns
SciPy OptimizeResult type object with final parameters
 Return type
OptimizeResult

c3.libraries.algorithms.
tf_adam
(x_init: numpy.array, fun: Callable = None, fun_grad: Callable = None, grad_lookup: Callable = None, options: dict = {}) → scipy.optimize.optimize.OptimizeResult[source]¶ Optimize using TensorFlow ADAM https://www.tensorflow.org/api_docs/python/tf/keras/optimizers/Adam
 Parameters
x_init (np.array) – starting value of parameter(s)
fun (Callable, optional) – function to minimize, by default None
fun_grad (Callable, optional) – gradient of function to minimize, by default None
grad_lookup (Callable, optional) – lookup stored gradients, by default None
options (dict, optional) – optional parameters for optimizer, by default {}
 Returns
SciPy OptimizeResult type object with final parameters
 Return type
OptimizeResult

c3.libraries.algorithms.
tf_rmsprop
(x_init: numpy.array, fun: Callable = None, fun_grad: Callable = None, grad_lookup: Callable = None, options: dict = {}) → scipy.optimize.optimize.OptimizeResult[source]¶ Optimize using TensorFlow RMSProp https://www.tensorflow.org/api_docs/python/tf/keras/optimizers/RMSprop
 Parameters
x_init (np.array) – starting value of parameter(s)
fun (Callable, optional) – function to minimize, by default None
fun_grad (Callable, optional) – gradient of function to minimize, by default None
grad_lookup (Callable, optional) – lookup stored gradients, by default None
options (dict, optional) – optional parameters for optimizer, by default {}
 Returns
SciPy OptimizeResult type object with final parameters
 Return type
OptimizeResult

c3.libraries.algorithms.
tf_sgd
(x_init: numpy.array, fun: Callable = None, fun_grad: Callable = None, grad_lookup: Callable = None, options: dict = {}) → scipy.optimize.optimize.OptimizeResult[source]¶ Optimize using TensorFlow Stochastic Gradient Descent with Momentum https://www.tensorflow.org/api_docs/python/tf/keras/optimizers/SGD
 Parameters
x_init (np.array) – starting value of parameter(s)
fun (Callable, optional) – function to minimize, by default None
fun_grad (Callable, optional) – gradient of function to minimize, by default None
grad_lookup (Callable, optional) – lookup stored gradients, by default None
options (dict, optional) – optional parameters for optimizer, by default {}
 Returns
SciPy OptimizeResult type object with final parameters
 Return type
OptimizeResult
Constants module¶
All physical constants used in other code.
Envelopes module¶
Library of envelope functions.
All functions assume the input of a time vector.

c3.libraries.envelopes.
flattop_risefall
(t, params)[source]¶ Flattop gaussian with width of length risefall, modelled by error functions.
 Parameters
params (dict) –
 t_upfloat
Center of the ramp up.
 t_downfloat
Center of the ramp down.
 risefallfloat
Length of the ramps.

c3.libraries.envelopes.
fourier_cos
(t, params)[source]¶ Fourier basis of the pulse constant pulse (cos).
 Parameters
params (dict) –
 ampslist
Weights of the fourier components
 freqslist
Frequencies of the fourier components

c3.libraries.envelopes.
fourier_sin
(t, params)[source]¶ Fourier basis of the pulse constant pulse (sin).
 Parameters
params (dict) –
 ampslist
Weights of the fourier components
 freqslist
Frequencies of the fourier components

c3.libraries.envelopes.
gaussian
(t, params)[source]¶ Normalized gaussian with fixed time/sigma ratio.
 Parameters
params (dict) –
 t_finalfloat
Total length of the Gaussian.

c3.libraries.envelopes.
gaussian_der
(t, params)[source]¶ Derivative of the normalized gaussian (ifself not normalized).

c3.libraries.envelopes.
gaussian_der_nonorm
(t, params)[source]¶ Derivative of the normalized gaussian (ifself not normalized).

c3.libraries.envelopes.
gaussian_nonorm
(t, params)[source]¶ Nonnormalized gaussian. Maximum value is 1, area is given by length.
 Parameters
params (dict) –
 t_finalfloat
Total length of the Gaussian.
 sigma: float
Width of the Gaussian.
Estimators module¶
Collection of estimator functions, to compare two sets of (noisy) data.

c3.libraries.estimators.
estimator_reg_deco
(func)[source]¶ Decorator for making registry of functions

c3.libraries.estimators.
mean_dist
(exp_values, sim_values, exp_stds, shots)[source]¶ Return the root mean squared of the differences.

c3.libraries.estimators.
mean_exp_stds_dist
(exp_values, sim_values, exp_stds, shots)[source]¶ Return the mean of the distance in number of exp_stds away.

c3.libraries.estimators.
mean_sim_stds_dist
(exp_values, sim_values, exp_stds, shots)[source]¶ Return the mean of the distance in number of exp_stds away.

c3.libraries.estimators.
median_dist
(exp_values, sim_values, exp_stds, shots)[source]¶ Return the median of the differences.

c3.libraries.estimators.
neg_loglkh_binom
(exp_values, sim_values, exp_stds, shots)[source]¶ Average likelihood of the experimental values with binomial distribution.
Return the likelihood of the experimental values given the simulated values, and given a binomial distribution function.

c3.libraries.estimators.
neg_loglkh_binom_norm
(exp_values, sim_values, exp_stds, shots)[source]¶ Average likelihood of the exp values with normalised binomial distribution.
Return the likelihood of the experimental values given the simulated values, and given a binomial distribution function that is normalised to give probability 1 at the top of the distribution.

c3.libraries.estimators.
neg_loglkh_gauss
(exp_values, sim_values, exp_stds, shots)[source]¶ Likelihood of the experimental values.
The distribution is assumed to be binomial (approximated by a gaussian).

c3.libraries.estimators.
neg_loglkh_gauss_norm
(exp_values, sim_values, exp_stds, shots)[source]¶ Likelihood of the experimental values.
The distribution is assumed to be binomial (approximated by a gaussian) that is normalised to give probability 1 at the top of the distribution.

c3.libraries.estimators.
neg_loglkh_gauss_norm_sum
(exp_values, sim_values, exp_stds, shots)[source]¶ Likelihood of the experimental values.
The distribution is assumed to be binomial (approximated by a gaussian) that is normalised to give probability 1 at the top of the distribution.

c3.libraries.estimators.
neg_loglkh_multinom
(exp_values, sim_values, exp_stds, shots)[source]¶ Average likelihood of the experimental values with multinomial distribution.
Return the likelihood of the experimental values given the simulated values, and given a multinomial distribution function.

c3.libraries.estimators.
neg_loglkh_multinom_norm
(exp_values, sim_values, exp_stds, shots)[source]¶ Average likelihood of the experimental values with multinomial distribution.
Return the likelihood of the experimental values given the simulated values, and given a multinomial distribution function that is normalised to give probability 1 at the top of the distribution.

c3.libraries.estimators.
rms_dist
(exp_values, sim_values, exp_stds, shots)[source]¶ Return the root mean squared of the differences.

c3.libraries.estimators.
rms_exp_stds_dist
(exp_values, sim_values, exp_stds, shots)[source]¶ Return the root mean squared of the differences measured in exp_stds.
Fidelities module¶
Library of fidelity functions.

c3.libraries.fidelities.
RB
(U_dict, min_length: int = 5, max_length: int = 500, num_lengths: int = 20, num_seqs: int = 30, logspace=False, lindbladian=False, padding='')[source]¶

c3.libraries.fidelities.
average_infid
(U_dict: dict, gate: str, index, dims, proj=True)[source]¶ Average fidelity uses the Pauli basis to compare. Thus, perfect gates are always 2x2 (per qubit) and the actual unitary needs to be projected down.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
dims (list) – List of dimensions of qubits
proj (boolean) – Project to computational subspace

c3.libraries.fidelities.
average_infid_seq
(U_dict: dict, index, dims, eval, proj=True)[source]¶ Average sequence fidelity over all gates in U_dict.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
dims (list) – List of dimensions of qubits
proj (boolean) – Project to computational subspace
 Returns
Mean average fidelity
 Return type
tf.float64

c3.libraries.fidelities.
average_infid_set
(U_dict: dict, index, dims, eval, proj=True)[source]¶ Mean average fidelity over all gates in U_dict.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
dims (list) – List of dimensions of qubits
proj (boolean) – Project to computational subspace
 Returns
Mean average fidelity
 Return type
tf.float64

c3.libraries.fidelities.
leakage_RB
(U_dict, min_length: int = 5, max_length: int = 500, num_lengths: int = 20, num_seqs: int = 30, logspace=False, lindbladian=False)[source]¶

c3.libraries.fidelities.
lindbladian_RB_left
(U_dict: dict, gate: str, index, dims, proj: bool = False)[source]¶

c3.libraries.fidelities.
lindbladian_RB_right
(U_dict: dict, gate: str, index, dims, proj: bool)[source]¶

c3.libraries.fidelities.
lindbladian_average_infid
(U_dict: dict, gate: str, index, dims, proj=True)[source]¶ Average fidelity uses the Pauli basis to compare. Thus, perfect gates are always 2x2 (per qubit) and the actual unitary needs to be projected down.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
dims (list) – List of dimensions of qubits
proj (boolean) – Project to computational subspace

c3.libraries.fidelities.
lindbladian_average_infid_set
(U_dict: dict, index, dims, eval, proj=True)[source]¶ Mean average fidelity over all gates in U_dict.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
dims (list) – List of dimensions of qubits
proj (boolean) – Project to computational subspace
 Returns
Mean average fidelity
 Return type
tf.float64

c3.libraries.fidelities.
lindbladian_unitary_infid
(U_dict: dict, gate: str, index, dims, proj: bool)[source]¶ Variant of the unitary fidelity for the Lindbladian propagator.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
gate (str) – One of the keys of U_dict, selects the gate to be evaluated
dims (list) – List of dimensions of qubits
proj (boolean) – Project to computational subspace
 Returns
Overlap fidelity for the Lindblad propagator.
 Return type
tf.float

c3.libraries.fidelities.
lindbladian_unitary_infid_set
(U_dict: dict, index, dims, eval, proj=True)[source]¶ Variant of the mean unitary fidelity for the Lindbladian propagator.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
dims (list) – List of dimensions of qubits
proj (boolean) – Project to computational subspace
 Returns
Mean overlap fidelity for the Lindblad propagator for all gates in U_dict.
 Return type
tf.float

c3.libraries.fidelities.
orbit_infid
(U_dict, RB_number: int = 30, RB_length: int = 20, lindbladian=False, shots: int = None, seqs=None, noise=None)[source]¶

c3.libraries.fidelities.
state_transfer_infid
(U_dict: dict, gate: str, index, dims, psi_0, proj: bool)[source]¶ Single gate state transfer infidelity.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
gate (str) – One of the keys of U_dict, selects the gate to be evaluated
dims (list) – List of dimensions of qubits
psi_0 (tf.Tensor) – Initial state of the device
proj (boolean) – Project to computational subspace
 Returns
State infidelity for the selected gate
 Return type
tf.float

c3.libraries.fidelities.
state_transfer_infid_set
(U_dict: dict, index, dims, psi_0, proj=True)[source]¶ Mean state transfer infidelity.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
dims (list) – List of dimensions of qubits
psi_0 (tf.Tensor) – Initial state of the device
proj (boolean) – Project to computational subspace
 Returns
State infidelity, averaged over the gates in U_dict
 Return type
tf.float

c3.libraries.fidelities.
unitary_infid
(U_dict: dict, gate: str, index, dims, proj: bool)[source]¶ Unitary overlap between ideal and actually performed gate.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
gate (str) – One of the keys of U_dict, selects the gate to be evaluated
dims (list) – List of dimensions of qubits
proj (boolean) – Project to computational subspace
 Returns
Unitary fidelity.
 Return type
tf.float

c3.libraries.fidelities.
unitary_infid_set
(U_dict: dict, index, dims, eval, proj=True)[source]¶ Mean unitary overlap between ideal and actually performed gate for the gates in U_dict.
 Parameters
U_dict (dict) – Contains unitary representations of the gates, identified by a key.
index (int) – Index of the qubit(s) in the Hilbert space to be evaluated
dims (list) – List of dimensions of qubits
proj (boolean) – Project to computational subspace
 Returns
Unitary fidelity.
 Return type
tf.float
Hamiltonians module¶
Library of Hamiltonian functions.

c3.libraries.hamiltonians.
duffing
(a)[source]¶ Anharmonic part of the duffing oscillator.
 Parameters
a (Tensor) – Annihilator.
 Returns
Number operator.
 Return type
Tensor

c3.libraries.hamiltonians.
hamiltonian_reg_deco
(func)[source]¶ Decorator for making registry of functions

c3.libraries.hamiltonians.
int_XX
(anhs)[source]¶ Dipole type coupling.
 Parameters
anhs (Tensor list) – Annihilators.
 Returns
coupling
 Return type
Tensor

c3.libraries.hamiltonians.
int_YY
(anhs)[source]¶ Dipole type coupling.
 Parameters
anhs (Tensor list) – Annihilators.
 Returns
coupling
 Return type
Tensor

c3.libraries.hamiltonians.
resonator
(a)[source]¶ Harmonic oscillator hamiltonian given the annihilation operator.
 Parameters
a (Tensor) – Annihilator.
 Returns
Number operator.
 Return type
Tensor

c3.libraries.hamiltonians.
x_drive
(a)[source]¶ Semiclassical drive.
 Parameters
a (Tensor) – Annihilator.
 Returns
Number operator.
 Return type
Tensor
Sampling module¶
Functions to select samples from a dataset by various criteria.

c3.libraries.sampling.
all
(learn_from, batch_size)[source]¶ Return all points.
 Parameters
learn_from (list) – List of data points
batch_size (int) – Number of points to select
 Returns
All indeces.
 Return type
list

c3.libraries.sampling.
even
(learn_from, batch_size)[source]¶ Select evenly distanced samples across the set.
 Parameters
learn_from (list) – List of data points
batch_size (int) – Number of points to select
 Returns
Selected indices.
 Return type
list

c3.libraries.sampling.
even_fid
(learn_from, batch_size)[source]¶ Select evenly among reached fidelities.
 Parameters
learn_from (list) – List of data points.
batch_size (int) – Number of points to select.
 Returns
Selected indices.
 Return type
list

c3.libraries.sampling.
from_end
(learn_from, batch_size)[source]¶ Select from the end.
 Parameters
learn_from (list) – List of data points
batch_size (int) – Number of points to select
 Returns
Selected indices.
 Return type
list

c3.libraries.sampling.
from_start
(learn_from, batch_size)[source]¶ Select from the beginning.
 Parameters
learn_from (list) – List of data points
batch_size (int) – Number of points to select
 Returns
Selected indices.
 Return type
list

c3.libraries.sampling.
high_std
(learn_from, batch_size)[source]¶ Select points that have a high ratio of standard deviation to mean. Sampling from ORBIT data, points with a high std have the most coherent error, thus might be suitable for model learning. This has yet to be confirmed beyond anecdotal observation.
 Parameters
learn_from (list) – List of data points.
batch_size (int) – Number of points to select.
 Returns
Selected indices.
 Return type
list