Classes¶
Qobj¶

class
Qobj
(inpt=None, dims=None, shape=None, type=None, isherm=None, copy=True, fast=False, superrep=None, isunitary=None)[source]¶ A class for representing quantum objects, such as quantum operators and states.
The Qobj class is the QuTiP representation of quantum operators and state vectors. This class also implements math operations +,,* between Qobj instances (and / by a Cnumber), as well as a collection of common operator/state operations. The Qobj constructor optionally takes a dimension
list
and/or shapelist
as arguments. Parameters
 inptarray_like
Data for vector/matrix representation of the quantum object.
 dimslist
Dimensions of object used for tensor products.
 shapelist
Shape of underlying data structure (matrix shape).
 copybool
Flag specifying whether Qobj should get a copy of the input data, or use the original.
 fastbool
Flag for fast qobj creation when running ode solvers. This parameter is used internally only.
 Attributes
 dataarray_like
Sparse matrix characterizing the quantum object.
 dimslist
List of dimensions keeping track of the tensor structure.
 shapelist
Shape of the underlying data array.
 typestr
Type of quantum object: ‘bra’, ‘ket’, ‘oper’, ‘operatorket’, ‘operatorbra’, or ‘super’.
 superrepstr
Representation used if type is ‘super’. One of ‘super’ (Liouville form) or ‘choi’ (Choi matrix with tr = dimension).
 ishermbool
Indicates if quantum object represents Hermitian operator.
 isunitarybool
Indictaes if quantum object represents unitary operator.
 iscpbool
Indicates if the quantum object represents a map, and if that map is completely positive (CP).
 ishpbool
Indicates if the quantum object represents a map, and if that map is hermicity preserving (HP).
 istpbool
Indicates if the quantum object represents a map, and if that map is trace preserving (TP).
 iscptpbool
Indicates if the quantum object represents a map that is completely positive and trace preserving (CPTP).
 isketbool
Indicates if the quantum object represents a ket.
 isbrabool
Indicates if the quantum object represents a bra.
 isoperbool
Indicates if the quantum object represents an operator.
 issuperbool
Indicates if the quantum object represents a superoperator.
 isoperketbool
Indicates if the quantum object represents an operator in column vector form.
 isoperbrabool
Indicates if the quantum object represents an operator in row vector form.
Methods
copy()
Create copy of Qobj
conj()
Conjugate of quantum object.
cosm()
Cosine of quantum object.
dag()
Adjoint (dagger) of quantum object.
dnorm()
Diamond norm of quantum operator.
dual_chan()
Dual channel of quantum object representing a CP map.
eigenenergies(sparse=False, sort=’low’, eigvals=0, tol=0, maxiter=100000)
Returns eigenenergies (eigenvalues) of a quantum object.
eigenstates(sparse=False, sort=’low’, eigvals=0, tol=0, maxiter=100000)
Returns eigenenergies and eigenstates of quantum object.
expm()
Matrix exponential of quantum object.
full(order=’C’)
Returns dense array of quantum object data attribute.
groundstate(sparse=False, tol=0, maxiter=100000)
Returns eigenvalue and eigenket for the groundstate of a quantum object.
inv()
Return a Qobj corresponding to the matrix inverse of the operator.
matrix_element(bra, ket)
Returns the matrix element of operator between bra and ket vectors.
norm(norm=’tr’, sparse=False, tol=0, maxiter=100000)
Returns norm of a ket or an operator.
permute(order)
Returns composite qobj with indices reordered.
proj()
Computes the projector for a ket or bra vector.
ptrace(sel)
Returns quantum object for selected dimensions after performing partial trace.
sinm()
Sine of quantum object.
sqrtm()
Matrix square root of quantum object.
tidyup(atol=1e12)
Removes small elements from quantum object.
tr()
Trace of quantum object.
trans()
Transpose of quantum object.
transform(inpt, inverse=False)
Performs a basis transformation defined by inpt matrix.
trunc_neg(method=’clip’)
Removes negative eigenvalues and returns a new Qobj that is a valid density operator.
unit(norm=’tr’, sparse=False, tol=0, maxiter=100000)
Returns normalized quantum object.

check_herm
()[source]¶ Check if the quantum object is hermitian.
 Returns
 ishermbool
Returns the new value of isherm property.

cosm
()[source]¶ Cosine of a quantum operator.
Operator must be square.
 Returns
 oper
qutip.Qobj
Matrix cosine of operator.
 oper
 Raises
 TypeError
Quantum object is not square.
Notes
Uses the Q.expm() method.

diag
()[source]¶ Diagonal elements of quantum object.
 Returns
 diagsarray
Returns array of
real
values if operators is Hermitian, otherwisecomplex
values are returned.

dnorm
(B=None)[source]¶ Calculates the diamond norm, or the diamond distance to another operator.
 Parameters
 B
qutip.Qobj
or None If B is not None, the diamond distance d(A, B) = dnorm(A  B) between this operator and B is returned instead of the diamond norm.
 B
 Returns
 dfloat
Either the diamond norm of this operator, or the diamond distance from this operator to B.

eigenenergies
(sparse=False, sort='low', eigvals=0, tol=0, maxiter=100000)[source]¶ Eigenenergies of a quantum object.
Eigenenergies (eigenvalues) are defined for operators or superoperators only.
 Parameters
 sparsebool
Use sparse Eigensolver
 sortstr
Sort eigenvalues ‘low’ to high, or ‘high’ to low.
 eigvalsint
Number of requested eigenvalues. Default is all eigenvalues.
 tolfloat
Tolerance used by sparse Eigensolver (0=machine precision). The sparse solver may not converge if the tolerance is set too low.
 maxiterint
Maximum number of iterations performed by sparse solver (if used).
 Returns
 eigvalsarray
Array of eigenvalues for operator.
Notes
The sparse eigensolver is much slower than the dense version. Use sparse only if memory requirements demand it.

eigenstates
(sparse=False, sort='low', eigvals=0, tol=0, maxiter=100000, phase_fix=None)[source]¶ Eigenstates and eigenenergies.
Eigenstates and eigenenergies are defined for operators and superoperators only.
 Parameters
 sparsebool
Use sparse Eigensolver
 sortstr
Sort eigenvalues (and vectors) ‘low’ to high, or ‘high’ to low.
 eigvalsint
Number of requested eigenvalues. Default is all eigenvalues.
 tolfloat
Tolerance used by sparse Eigensolver (0 = machine precision). The sparse solver may not converge if the tolerance is set too low.
 maxiterint
Maximum number of iterations performed by sparse solver (if used).
 phase_fixint, None
If not None, set the phase of each kets so that ket[phase_fix,0] is real positive.
 Returns
 eigvalsarray
Array of eigenvalues for operator.
 eigvecsarray
Array of quantum operators representing the oprator eigenkets. Order of eigenkets is determined by order of eigenvalues.
Notes
The sparse eigensolver is much slower than the dense version. Use sparse only if memory requirements demand it.

eliminate_states
(states_inds, normalize=False)[source]¶ Creates a new quantum object with states in state_inds eliminated.
 Parameters
 states_indslist of integer
The states that should be removed.
 normalizeTrue / False
Weather or not the new Qobj instance should be normalized (default is False). For Qobjs that represents density matrices or state vectors normalized should probably be set to True, but for Qobjs that represents operators in for example an Hamiltonian, normalize should be False.
 Returns
 q
qutip.Qobj
A new instance of
qutip.Qobj
that contains only the states corresponding to indices that are not in state_inds.
 q
Notes
Experimental.

static
evaluate
(qobj_list, t, args)[source]¶ Evaluate a timedependent quantum object in list format. For example,
qobj_list = [H0, [H1, func_t]]
is evaluated to
Qobj(t) = H0 + H1 * func_t(t, args)
and
qobj_list = [H0, [H1, ‘sin(w * t)’]]
is evaluated to
Qobj(t) = H0 + H1 * sin(args[‘w’] * t)
 Parameters
 qobj_listlist
A nested list of Qobj instances and corresponding timedependent coefficients.
 tfloat
The time for which to evaluate the timedependent Qobj instance.
 argsdictionary
A dictionary with parameter values required to evaluate the timedependent Qobj intance.
 Returns
 output
qutip.Qobj
A Qobj instance that represents the value of qobj_list at time t.
 output

expm
(method='dense')[source]¶ Matrix exponential of quantum operator.
Input operator must be square.
 Parameters
 methodstr {‘dense’, ‘sparse’}
Use set method to use to calculate the matrix exponentiation. The available choices includes ‘dense’ and ‘sparse’. Since the exponential of a matrix is nearly always dense, method=’dense’ is set as default.s
 Returns
 oper
qutip.Qobj
Exponentiated quantum operator.
 oper
 Raises
 TypeError
Quantum operator is not square.

extract_states
(states_inds, normalize=False)[source]¶ Qobj with states in state_inds only.
 Parameters
 states_indslist of integer
The states that should be kept.
 normalizeTrue / False
Weather or not the new Qobj instance should be normalized (default is False). For Qobjs that represents density matrices or state vectors normalized should probably be set to True, but for Qobjs that represents operators in for example an Hamiltonian, normalize should be False.
 Returns
 q
qutip.Qobj
A new instance of
qutip.Qobj
that contains only the states corresponding to the indices in state_inds.
 q
Notes
Experimental.

full
(order='C', squeeze=False)[source]¶ Dense array from quantum object.
 Parameters
 orderstr {‘C’, ‘F’}
Return array in C (default) or Fortran ordering.
 squeezebool {False, True}
Squeeze output array.
 Returns
 dataarray
Array of complex data from quantum objects data attribute.

groundstate
(sparse=False, tol=0, maxiter=100000, safe=True)[source]¶ Ground state Eigenvalue and Eigenvector.
Defined for quantum operators or superoperators only.
 Parameters
 sparsebool
Use sparse Eigensolver
 tolfloat
Tolerance used by sparse Eigensolver (0 = machine precision). The sparse solver may not converge if the tolerance is set too low.
 maxiterint
Maximum number of iterations performed by sparse solver (if used).
 safebool (default=True)
Check for degenerate ground state
 Returns
 eigvalfloat
Eigenvalue for the ground state of quantum operator.
 eigvec
qutip.Qobj
Eigenket for the ground state of quantum operator.
Notes
The sparse eigensolver is much slower than the dense version. Use sparse only if memory requirements demand it.

inv
(sparse=False)[source]¶ Matrix inverse of a quantum operator
Operator must be square.
 Returns
 oper
qutip.Qobj
Matrix inverse of operator.
 oper
 Raises
 TypeError
Quantum object is not square.

matrix_element
(bra, ket)[source]¶ Calculates a matrix element.
Gives the matrix element for the quantum object sandwiched between a bra and ket vector.
 Parameters
 bra
qutip.Qobj
Quantum object of type ‘bra’ or ‘ket’
 ket
qutip.Qobj
Quantum object of type ‘ket’.
 bra
 Returns
 elemcomplex
Complex valued matrix element.
Notes
It is slightly more computationally efficient to use a ket vector for the ‘bra’ input.

norm
(norm=None, sparse=False, tol=0, maxiter=100000)[source]¶ Norm of a quantum object.
Default norm is L2norm for kets and tracenorm for operators. Other ket and operator norms may be specified using the norm and argument.
 Parameters
 normstr
Which norm to use for ket/bra vectors: L2 ‘l2’, max norm ‘max’, or for operators: trace ‘tr’, Frobius ‘fro’, one ‘one’, or max ‘max’.
 sparsebool
Use sparse eigenvalue solver for trace norm. Other norms are not affected by this parameter.
 tolfloat
Tolerance for sparse solver (if used) for trace norm. The sparse solver may not converge if the tolerance is set too low.
 maxiterint
Maximum number of iterations performed by sparse solver (if used) for trace norm.
 Returns
 normfloat
The requested norm of the operator or state quantum object.
Notes
The sparse eigensolver is much slower than the dense version. Use sparse only if memory requirements demand it.

overlap
(other)[source]¶ Overlap between two state vectors or two operators.
Gives the overlap (inner product) between the current bra or ket Qobj and and another bra or ket Qobj. It gives the HilbertSchmidt overlap when one of the Qobj is an operator/density matrix.
 Parameters
 other
qutip.Qobj
Quantum object for a state vector of type ‘ket’, ‘bra’ or density matrix.
 other
 Returns
 overlapcomplex
Complex valued overlap.
 Raises
 TypeError
Can only calculate overlap between a bra, ket and density matrix quantum objects.
Notes
Since QuTiP mainly deals with ket vectors, the most efficient inner product call is the ketket version that computes the product <selfother> with both vectors expressed as kets.

permute
(order)[source]¶ Permutes a composite quantum object.
 Parameters
 orderlist/array
List specifying new tensor order.
 Returns
 P
qutip.Qobj
Permuted quantum object.
 P

proj
()[source]¶ Form the projector from a given ket or bra vector.
 Parameters
 Q
qutip.Qobj
Input bra or ket vector
 Q
 Returns
 P
qutip.Qobj
Projection operator.
 P

ptrace
(sel, sparse=None)[source]¶ Partial trace of the quantum object.
 Parameters
 selint/list
An
int
orlist
of components to keep after partial trace. The order is unimportant; no transposition will be done and the spaces will remain in the same order in the output.
 Returns
 oper
qutip.Qobj
Quantum object representing partial trace with selected components remaining.
 oper
Notes
This function is identical to the
qutip.qobj.ptrace
function that has been deprecated.

purity
()[source]¶ Calculate purity of a quantum object.
 Returns
 state_purityfloat
Returns the purity of a quantum object. For a pure state, the purity is 1. For a mixed state of dimension d, 1/d<=purity<1.

sinm
()[source]¶ Sine of a quantum operator.
Operator must be square.
 Returns
 oper
qutip.Qobj
Matrix sine of operator.
 oper
 Raises
 TypeError
Quantum object is not square.
Notes
Uses the Q.expm() method.

sqrtm
(sparse=False, tol=0, maxiter=100000)[source]¶ Sqrt of a quantum operator.
Operator must be square.
 Parameters
 sparsebool
Use sparse eigenvalue/vector solver.
 tolfloat
Tolerance used by sparse solver (0 = machine precision).
 maxiterint
Maximum number of iterations used by sparse solver.
 Returns
 oper
qutip.Qobj
Matrix square root of operator.
 oper
 Raises
 TypeError
Quantum object is not square.
Notes
The sparse eigensolver is much slower than the dense version. Use sparse only if memory requirements demand it.

tidyup
(atol=1e12)[source]¶ Removes small elements from the quantum object.
 Parameters
 atolfloat
Absolute tolerance used by tidyup. Default is set via qutip global settings parameters.
 Returns
 oper
qutip.Qobj
Quantum object with small elements removed.
 oper

trans
()[source]¶ Transposed operator.
 Returns
 oper
qutip.Qobj
Transpose of input operator.
 oper

transform
(inpt, inverse=False, sparse=True)[source]¶ Basis transform defined by input array.
Input array can be a
matrix
defining the transformation, or alist
of kets that defines the new basis. Parameters
 inptarray_like
A
matrix
orlist
of kets defining the transformation. inversebool
Whether to return inverse transformation.
 sparsebool
Use sparse matrices when possible. Can be slower.
 Returns
 oper
qutip.Qobj
Operator in new basis.
 oper
Notes
This function is still in development.

trunc_neg
(method='clip')[source]¶ Truncates negative eigenvalues and renormalizes.
Returns a new Qobj by removing the negative eigenvalues of this instance, then renormalizing to obtain a valid density operator.
 Parameters
 methodstr
Algorithm to use to remove negative eigenvalues. “clip” simply discards negative eigenvalues, then renormalizes. “sgs” uses the SGS algorithm (doi:10/bb76) to find the positive operator that is nearest in the Shatten 2norm.
 Returns
 oper
qutip.Qobj
A valid density operator.
 oper

unit
(inplace=False, norm=None, sparse=False, tol=0, maxiter=100000)[source]¶ Operator or state normalized to unity.
Uses norm from Qobj.norm().
 Parameters
 inplacebool
Do an inplace normalization
 normstr
Requested norm for states / operators.
 sparsebool
Use sparse eigensolver for trace norm. Does not affect other norms.
 tolfloat
Tolerance used by sparse eigensolver.
 maxiterint
Number of maximum iterations performed by sparse eigensolver.
 Returns
 oper
qutip.Qobj
Normalized quantum object if not inplace, else None.
 oper
QobjEvo¶

class
QobjEvo
(Q_object=[], args={}, copy=True, tlist=None, state0=None, e_ops=[])[source]¶ A class for representing timedependent quantum objects, such as quantum operators and states.
Basic math operations are defined:
This object is constructed by passing a list of
Qobj
instances, each of which may have an associated scalar time dependence. The list is summed to produce the final result. In other words, if an instance of this class is \(Q(t)\), then it is constructed from a set of constantQobj
\(\{Q_k\}\) and timedependent scalars \(f_k(t)\) by\[Q(t) = \sum_k f_k(t) Q_k\]If a scalar \(f_k(t)\) is not passed with a given
Qobj
, then that term is assumed to be constant. The next section contains more detail on the allowed forms of the constants, and gives several examples for how to build instances of this class.Timedependence formats
There are three major formats for specifying a timedependent scalar:
Python function
string
array
For function format, the function signature must be
f(t: float, args: dict) > complex
, for exampledef f1_t(t, args): return np.exp(1j * t * args["w1"]) def f2_t(t, args): return np.cos(t * args["w2"]) H = QobjEvo([H0, [H1, f1_t], [H2, f2_t]], args={"w1":1., "w2":2.})
For stringbased coeffients, the string must be a compilable python code resulting in a complex. The following symbols are defined:
pi exp log log10 erf zerf norm proj real imag conj abs arg sin sinh asin asinh cos cosh acos acosh tan tanh atan atanh numpy as np scipy.special as spe
A couple more simple examples:
H = QobjEvo([H0, [H1, 'exp(1j*w1*t)'], [H2, 'cos(w2*t)']], args={"w1":1.,"w2":2.})
For numpy array format, the array must be an 1d of dtype
np.float64
ornp.complex128
. A list of times (np.float64
) at which the coeffients must be given astlist
. The coeffients array must have the same length as the tlist. The times of the tlist do not need to be equidistant, but must be sorted. By default, a cubic spline interpolation will be used for the coefficient at time t. If the coefficients are to be treated as step functions, use the argumentsargs = {"_step_func_coeff": True}
. Examples of arrayformat usage are:tlist = np.logspace(5,0,100) H = QobjEvo([H0, [H1, np.exp(1j*tlist)], [H2, np.cos(2.*tlist)]], tlist=tlist)
Mixing time formats is allowed. It is not possible to create a single
QobjEvo
that contains differenttlist
values, however.Passing arguments
args
is a dict of (name: object). The name must be a valid Python identifier string, and in general the object can be any type that is supported by the code to be compiled in the string.There are some “magic” names that can be specified, whose objects will be overwritten when used within
sesolve
,mesolve
andmcsolve
. This allows access to the solvers’ internal states, and they are updated at every call. The initial values of these dictionary elements is unimportant. The magic names available are:"state"
: the current state as aQobj
"state_vec"
: the current state as a columnstacked 1Dnp.ndarray
"state_mat"
: the current state as a 2Dnp.ndarray
"expect_op_<n>"
: the current expectation value of the elemente_ops[n]
, which is an argument to the solvers. Replace<n>
with an integer literal, e.g."expect_op_0"
. This will be either real or complexvalued, depending on whether the state and operator are both Hermitian or not."collapse"
: (mcsolve
only) a list of the collapses that have occurred during the evolution. Each element of the list is a 2tuple(time: float, which: int)
, wheretime
is the time this collapse happened, andwhich
is an integer indexing thec_ops
argument tomcsolve
.
 Parameters
 Q_objectlist,
Qobj
orQobjEvo
The timedependent description of the quantum object. This is of the same format as the first parameter to the general ODE solvers; in general, it is a list of
[Qobj, time_dependence]
pairs that are summed to make the whole object. Thetime_dependence
can be any of the formats discussed in the previous section. If a particular term has no timedependence, then you should just give theQobj
instead of the 2element list. argsdict, optional
Mapping of
{str: object}
, discussed in greater detail above. The strings can be any valid Python identifier, and the objects are of the consumable types. See the previous section for details on the “magic” names used to access solver internals. tlistarray_like, optional
List of the times any numpyarray coefficients describe. This is used only in at least one of the time dependences in
Q_object
is given in Numpyarray format. The times must be sorted, but need not be equidistant. Values inbetween will be interpolated.
 Q_objectlist,
 Attributes
 cte
Qobj
Constant part of the QobjEvo.
 opslist of
EvoElement
Internal representation of the timedependence structure of the elements.
 argsdict
The current value of the
args
dictionary passed into the constructor. dynamics_argslist
Names of the dynamic arguments that the solvers will generate. These are the magic names that were found in the
args
parameter. tlistarray_like
List of times at which the numpyarray coefficients are applied.
 compiledstr
A string representing the properties of the lowlevel Cython class backing this object (may be empty).
 compiled_qobjevo
CQobjCte
orCQobjEvoTd
Cython version of the QobjEvo.
 coeff_getcallable
Object called to obtain a list of all the coefficients at a particular time.
 coeff_fileslist
Runtime created files to delete with the instance.
 dummy_ctebool
Is self.cte an empty Qobj
 constbool
Indicates if quantum object is constant
 type{“cte”, “string”, “func”, “array”, “spline”, “mixed_callable”, “mixed_compilable”}
Information about the type of coefficients used in the entire object.
 num_objint
Number of
Qobj
in the QobjEvo. use_cythonbool
Flag to compile string to Cython or Python
 safePicklebool
Flag to not share pointers between thread.
 cte

apply
(function, *args, **kw_args)[source]¶ Apply the linear function
function
to everyQobj
included in this timedependent object, and return a newQobjEvo
with the result.Any additional arguments or keyword arguments will be appended to every function call.

apply_decorator
(function, *args, str_mod=None, inplace_np=False, **kw_args)[source]¶ Apply the given function to every timedependent coefficient in the quantum object, and return a new object with the result.
Any additional arguments and keyword arguments will be appended to the function calls.
 Parameters
 functioncallable
(time_dependence, *args, **kwargs) > time_dependence
. Called on each timedependent coefficient to produce a new coefficient. The additional arguments and keyword arguments are the ones given to this function. str_modlist
A 2element list of strings, that will additionally wrap any string timedependences. An existing timedependence string
x
will becomestr_mod[0] + x + str_mod[1]
. inplace_npbool, default False
Whether this function should modify Numpy arrays inplace, or be used like a regular decorator. Some decorators create incorrect arrays as some transformations
f'(t) = f(g(t))
create a mismatch between the array and the associated time list.

compile
(code=False, matched=False, dense=False, omp=0)[source]¶ Create an associated Cython object for faster usage. This function is called automatically by the solvers.
 Parameters
 codebool, default False
Return the code string generated by compilation of any strings.
 matchedbool, default False
If True, the underlying sparse matrices used to represent each element of the type will have their structures unified. This may include adding explicit zeros to sparse matrices, but can be faster in some cases due to not having to deal with repeated structural mismatches.
 densebool, default False
Whether to swap to using dense matrices to back the data.
 ompint, optional
The number of OpenMP threads to use when doing matrix multiplications, if QuTiP was compiled with OpenMP.
 Returns
 compiled_strstr
(Only if code was set to True). The codegenerated string of compiled calling code.

compress
()[source]¶ Merge together elements that share the same timedependence, to reduce the number of matrix multiplications and additions that need to be done to evaluate this object.
Modifies the object inplace.

expect
(t, state, herm=False)[source]¶ Calculate the expectation value of this operator on the given (timeindependent) state at a particular time.
This is more efficient than
expect(QobjEvo(t), state)
. Parameters
 tfloat
The time to evaluate this operator at.
 stateQobj or np.ndarray
The state to take the expectation value around.
 hermbool, default False
Whether this operator and the state are both Hermitian. If True, only the real part of the result will be returned.
See also
expect
Generalpurpose expectation values.

mul_mat
(t, mat)[source]¶ Multiply this object evaluated at time t by a matrix (from the right).
 Parameters
 tfloat
The time to evaluate this object at.
 matQobj or np.ndarray
The matrix that is multiplied by this object.
 Returns
 mat: Qobj or np.ndarray
The matrix result in the same type as the input.

mul_vec
(t, vec)[source]¶ Multiply this object evaluated at time t by a vector.
 Parameters
 tfloat
The time to evaluate this object at.
 vecQobj or np.ndarray
The statevector to multiply this object by.
 Returns
 vec: Qobj or np.ndarray
The vector result in the same type as the input.

permute
(order)[source]¶ Permute the tensor structure of the underlying matrices into a new format.
See also
Qobj.permute
the same operation on constant quantum objects.
eseries¶

class
eseries
(q=None, s=array([], dtype=float64))[source]¶ Class representation of an exponentialseries expansion of timedependent quantum objects.
Deprecated since version 4.6.0:
eseries
will be removed in QuTiP 5. Please useQobjEvo
for general timedependence. Attributes
 amplndarray
Array of amplitudes for exponential series.
 ratesndarray
Array of rates for exponential series.
 dimslist
Dimensions of exponential series components
 shapelist
Shape corresponding to exponential series components
Methods
value(tlist)
Evaluate an exponential series at the times listed in tlist
spec(wlist)
Evaluate the spectrum of an exponential series at frequencies in wlist.
tidyup()
Returns a tidier version of the exponential series
Bloch sphere¶

class
Bloch
(fig=None, axes=None, view=None, figsize=None, background=False)[source]¶ Class for plotting data on the Bloch sphere. Valid data can be either points, vectors, or Qobj objects.
 Attributes
 axesmatplotlib.axes.Axes
User supplied Matplotlib axes for Bloch sphere animation.
 figmatplotlib.figure.Figure
User supplied Matplotlib Figure instance for plotting Bloch sphere.
 font_colorstr, default ‘black’
Color of font used for Bloch sphere labels.
 font_sizeint, default 20
Size of font used for Bloch sphere labels.
 frame_alphafloat, default 0.1
Sets transparency of Bloch sphere frame.
 frame_colorstr, default ‘gray’
Color of sphere wireframe.
 frame_widthint, default 1
Width of wireframe.
 point_colorlist, default [“b”, “r”, “g”, “#CC6600”]
List of colors for Bloch sphere point markers to cycle through, i.e. by default, points 0 and 4 will both be blue (‘b’).
 point_markerlist, default [“o”, “s”, “d”, “^”]
List of point marker shapes to cycle through.
 point_sizelist, default [25, 32, 35, 45]
List of point marker sizes. Note, not all point markers look the same size when plotted!
 sphere_alphafloat, default 0.2
Transparency of Bloch sphere itself.
 sphere_colorstr, default ‘#FFDDDD’
Color of Bloch sphere.
 figsizelist, default [7, 7]
Figure size of Bloch sphere plot. Best to have both numbers the same; otherwise you will have a Bloch sphere that looks like a football.
 vector_colorlist, [“g”, “#CC6600”, “b”, “r”]
List of vector colors to cycle through.
 vector_widthint, default 5
Width of displayed vectors.
 vector_stylestr, default ‘>’
Vector arrowhead style (from matplotlib’s arrow style).
 vector_mutationint, default 20
Width of vectors arrowhead.
 viewlist, default [60, 30]
Azimuthal and Elevation viewing angles.
 xlabellist, default [“$x$”, “”]
List of strings corresponding to +x and x axes labels, respectively.
 xlposlist, default [1.1, 1.1]
Positions of +x and x labels respectively.
 ylabellist, default [“$y$”, “”]
List of strings corresponding to +y and y axes labels, respectively.
 ylposlist, default [1.2, 1.2]
Positions of +y and y labels respectively.
 zlabellist, default [‘$\left0\right>$’, ‘$\left1\right>$’]
List of strings corresponding to +z and z axes labels, respectively.
 zlposlist, default [1.2, 1.2]
Positions of +z and z labels respectively.

add_annotation
(state_or_vector, text, **kwargs)[source]¶ Add a text or LaTeX annotation to Bloch sphere, parametrized by a qubit state or a vector.
 Parameters
 state_or_vectorQobj/array/list/tuple
Position for the annotaion. Qobj of a qubit or a vector of 3 elements.
 textstr
Annotation text. You can use LaTeX, but remember to use raw string e.g. r”$langle x rangle$” or escape backslashes e.g. “$\langle x \rangle$”.
 kwargs :
Options as for mplot3d.axes3d.text, including: fontsize, color, horizontalalignment, verticalalignment.

add_points
(points, meth='s')[source]¶ Add a list of data points to bloch sphere.
 Parameters
 pointsarray_like
Collection of data points.
 meth{‘s’, ‘m’, ‘l’}
Type of points to plot, use ‘m’ for multicolored, ‘l’ for points connected with a line.

add_states
(state, kind='vector')[source]¶ Add a state vector Qobj to Bloch sphere.
 Parameters
 stateQobj
Input state vector.
 kind{‘vector’, ‘point’}
Type of object to plot.

add_vectors
(vectors)[source]¶ Add a list of vectors to Bloch sphere.
 Parameters
 vectorsarray_like
Array with vectors of unit length or smaller.

render
(fig=None, axes=None)[source]¶ Render the Bloch sphere and its data sets in on given figure and axes.

save
(name=None, format='png', dirc=None, dpin=None)[source]¶ Saves Bloch sphere to file of type
format
in directorydirc
. Parameters
 namestr
Name of saved image. Must include path and format as well. i.e. ‘/Users/Paul/Desktop/bloch.png’ This overrides the ‘format’ and ‘dirc’ arguments.
 formatstr
Format of output image.
 dircstr
Directory for output images. Defaults to current working directory.
 dpinint
Resolution in dots per inch.
 Returns
 File containing plot of Bloch sphere.

set_label_convention
(convention)[source]¶ Set x, y and z labels according to one of conventions.
 Parameters
 conventionstring
One of the following:
“original”
“xyz”
“sx sy sz”
“01”
“polarization jones”
“polarization jones letters” see also: https://en.wikipedia.org/wiki/Jones_calculus
“polarization stokes” see also: https://en.wikipedia.org/wiki/Stokes_parameters

vector_mutation
¶ Sets the width of the vectors arrowhead

vector_style
¶ Style of Bloch vectors, default = ‘>’ (or ‘simple’)

vector_width
¶ Width of Bloch vectors, default = 5
Cubic Spline¶

class
Cubic_Spline
(a, b, y, alpha=0, beta=0)[source]¶ Calculates coefficients for a cubic spline interpolation of a given data set.
This function assumes that the data is sampled uniformly over a given interval.
 Parameters
 afloat
Lower bound of the interval.
 bfloat
Upper bound of the interval.
 yndarray
Function values at interval points.
 alphafloat
Secondorder derivative at a. Default is 0.
 betafloat
Secondorder derivative at b. Default is 0.
Notes
This object can be called like a normal function with a single or array of input points at which to evaluate the interplating function.
Habermann & Kindermann, “Multidimensional Spline Interpolation: Theory and Applications”, Comput Econ 30, 153 (2007).
 Attributes
 afloat
Lower bound of the interval.
 bfloat
Upper bound of the interval.
 coeffsndarray
Array of coeffcients defining cubic spline.
NonMarkovian Solvers¶

class
HEOMSolver
[source]¶ This is superclass for all solvers that use the HEOM method for calculating the dynamics evolution. There are many references for this. A good introduction, and perhaps closest to the notation used here is: DOI:10.1103/PhysRevLett.104.250401 A more canonical reference, with full derivation is: DOI: 10.1103/PhysRevA.41.6676 The method can compute open system dynamics without using any Markovian or rotating wave approximation (RWA) for systems where the bath correlations can be approximated to a sum of complex eponentials. The method builds a matrix of linked differential equations, which are then solved used the same ODE solvers as other qutip solvers (e.g. mesolve)
This class should be treated as abstract. Currently the only subclass implemented is that for the DrudeLorentz spectral density. This covers the majority of the work that has been done using this model, and there are some performance advantages to assuming this model where it is appropriate.
There are opportunities to develop a more general spectral density code.
 Attributes
 H_sysQobj
System Hamiltonian
 coup_opQobj
Operator describing the coupling between system and bath.
 coup_strengthfloat
Coupling strength.
 temperaturefloat
Bath temperature, in units corresponding to planck
 N_cutint
Cutoff parameter for the bath
 N_expint
Number of exponential terms used to approximate the bath correlation functions
 planckfloat
reduced Planck constant
 boltzmannfloat
Boltzmann’s constant
 options
qutip.solver.Options
Generic solver options. If set to None the default options will be used
 progress_bar: BaseProgressBar
Optional instance of BaseProgressBar, or a subclass thereof, for showing the progress of the simulation.
 stats
qutip.solver.Stats
optional container for holding performance statitics If None is set, then statistics are not collected There may be an overhead in collecting statistics
 exp_coefflist of complex
Coefficients for the exponential series terms
 exp_freqlist of complex
Frequencies for the exponential series terms

configure
(H_sys, coup_op, coup_strength, temperature, N_cut, N_exp, planck=None, boltzmann=None, renorm=None, bnd_cut_approx=None, options=None, progress_bar=None, stats=None)[source]¶ Configure the solver using the passed parameters The parameters are described in the class attributes, unless there is some specific behaviour
 Parameters
 options
qutip.solver.Options
Generic solver options. If set to None the default options will be used
 progress_bar: BaseProgressBar
Optional instance of BaseProgressBar, or a subclass thereof, for showing the progress of the simulation. If set to None, then the default progress bar will be used Set to False for no progress bar
 stats: :class:`qutip.solver.Stats`
Optional instance of solver.Stats, or a subclass thereof, for storing performance statistics for the solver If set to True, then the default Stats for this class will be used Set to False for no stats
 options

class
HSolverDL
(H_sys, coup_op, coup_strength, temperature, N_cut, N_exp, cut_freq, planck=1.0, boltzmann=1.0, renorm=True, bnd_cut_approx=True, options=None, progress_bar=None, stats=None)[source]¶ HEOM solver based on the DrudeLorentz model for spectral density. DrudeLorentz bath the correlation functions can be exactly analytically expressed as an infinite sum of exponentials which depend on the temperature, these are called the Matsubara terms or Matsubara frequencies
For practical computation purposes an approximation must be used based on a small number of Matsubara terms (typically < 4).
 Attributes
 cut_freqfloat
Bath spectral density cutoff frequency.
 renormbool
Apply renormalisation to coupling terms Can be useful if using SI units for planck and boltzmann
 bnd_cut_approxbool
Use boundary cut off approximation Can be

configure
(H_sys, coup_op, coup_strength, temperature, N_cut, N_exp, cut_freq, planck=None, boltzmann=None, renorm=None, bnd_cut_approx=None, options=None, progress_bar=None, stats=None)[source]¶ Calls configure from
HEOMSolver
and sets any attributes that are specific to this subclass

run
(rho0, tlist)[source]¶ Function to solve for an open quantum system using the HEOM model.
 Parameters
 rho0Qobj
Initial state (density matrix) of the system.
 tlistlist
Time over which system evolves.
 Returns
 results
qutip.solver.Result
Object storing all results from the simulation.
 results

class
MemoryCascade
(H_S, L1, L2, S_matrix=None, c_ops_markov=None, integrator='propagator', parallel=False, options=None)[source]¶ Class for running memory cascade simulations of open quantum systems with timedelayed coherent feedback.
 Attributes
 H_S
qutip.Qobj
System Hamiltonian (can also be a Liouvillian)
 L1
qutip.Qobj
/ list ofqutip.Qobj
System operators coupling into the feedback loop. Can be a single operator or a list of operators.
 L2
qutip.Qobj
/ list ofqutip.Qobj
System operators coupling out of the feedback loop. Can be a single operator or a list of operators. L2 must have the same length as L1.
 S_matrix: *array*
S matrix describing which operators in L1 are coupled to which operators in L2 by the feedback channel. Defaults to an n by n identity matrix where n is the number of elements in L1/L2.
 c_ops_markov
qutip.Qobj
/ list ofqutip.Qobj
Decay operators describing conventional Markovian decay channels. Can be a single operator or a list of operators.
 integratorstr {‘propagator’, ‘mesolve’}
Integrator method to use. Defaults to ‘propagator’ which tends to be faster for long times (i.e., large Hilbert space).
 parallelbool
Run integrator in parallel if True. Only implemented for ‘propagator’ as the integrator method.
 options
qutip.solver.Options
Generic solver options.
 H_S

outfieldcorr
(rho0, blist, tlist, tau, c1=None, c2=None)[source]¶ Compute output field expectation value <O_n(tn)…O_2(t2)O_1(t1)> for times t1,t2,… and O_i = I, b_out, b_out^dagger, b_loop, b_loop^dagger
 Parameters
 rho0
qutip.Qobj
initial density matrix or state vector (ket).
 blistarray_like
List of integers specifying the field operators: 0: I (nothing) 1: b_out 2: b_out^dagger 3: b_loop 4: b_loop^dagger
 tlistarray_like
list of corresponding times t1,..,tn at which to evaluate the field operators
 taufloat
timedelay
 c1
qutip.Qobj
system collapse operator that couples to the inloop field in question (only needs to be specified if self.L1 has more than one element)
 c2
qutip.Qobj
system collapse operator that couples to the output field in question (only needs to be specified if self.L2 has more than one element)
 rho0
 Returns
 : complex
expectation value of field correlation function

outfieldpropagator
(blist, tlist, tau, c1=None, c2=None, notrace=False)[source]¶ Compute propagator for computing output field expectation values <O_n(tn)…O_2(t2)O_1(t1)> for times t1,t2,… and O_i = I, b_out, b_out^dagger, b_loop, b_loop^dagger
 Parameters
 blistarray_like
List of integers specifying the field operators: 0: I (nothing) 1: b_out 2: b_out^dagger 3: b_loop 4: b_loop^dagger
 tlistarray_like
list of corresponding times t1,..,tn at which to evaluate the field operators
 taufloat
timedelay
 c1
qutip.Qobj
system collapse operator that couples to the inloop field in question (only needs to be specified if self.L1 has more than one element)
 c2
qutip.Qobj
system collapse operator that couples to the output field in question (only needs to be specified if self.L2 has more than one element)
 notracebool {False}
If this optional is set to True, a propagator is returned for a cascade of k systems, where \((k1) tau < t < k tau\). If set to False (default), a generalized partial trace is performed and a propagator for a single system is returned.
 Returns
 :
qutip.Qobj
timepropagator for computing field correlation function
 :

propagator
(t, tau, notrace=False)[source]¶ Compute propagator for time t and timedelay tau
 Parameters
 tfloat
current time
 taufloat
timedelay
 notracebool {False}
If this optional is set to True, a propagator is returned for a cascade of k systems, where \((k1) tau < t < k tau\). If set to False (default), a generalized partial trace is performed and a propagator for a single system is returned.
 Returns
 ——
 : :class:`qutip.Qobj`
timepropagator for reduced system dynamics

rhot
(rho0, t, tau)[source]¶ Compute the reduced system density matrix \(\rho(t)\)
 Parameters
 rho0
qutip.Qobj
initial density matrix or state vector (ket)
 tfloat
current time
 taufloat
timedelay
 rho0
 Returns
 :
qutip.Qobj
density matrix at time \(t\)
 :

class
TTMSolverOptions
(dynmaps=None, times=[], learningtimes=[], thres=0.0, options=None)[source]¶ Class of options for the Transfer Tensor Method solver.
 Attributes
 dynmapslist of
qutip.Qobj
List of precomputed dynamical maps (superoperators), or a callback function that returns the superoperator at a given time.
 timesarray_like
List of times \(t_n\) at which to calculate \(\rho(t_n)\)
 learningtimesarray_like
List of times \(t_k\) to use as learning times if argument dynmaps is a callback function.
 thresfloat
Threshold for halting. Halts if \(T_{n}T_{n1}\) is below treshold.
 options
qutip.solver.Options
Generic solver options.
 dynmapslist of
Solver Options and Results¶

class
Options
(atol=1e08, rtol=1e06, method='adams', order=12, nsteps=1000, first_step=0, max_step=0, min_step=0, average_expect=True, average_states=False, tidy=True, num_cpus=0, norm_tol=0.001, norm_t_tol=1e06, norm_steps=5, rhs_reuse=False, rhs_filename=None, ntraj=500, gui=False, rhs_with_state=False, store_final_state=False, store_states=False, steady_state_average=False, seeds=None, normalize_output=True, use_openmp=None, openmp_threads=None)[source]¶ Class of options for evolution solvers such as
qutip.mesolve
andqutip.mcsolve
. Options can be specified either as arguments to the constructor:opts = Options(order=10, ...)
or by changing the class attributes after creation:
opts = Options() opts.order = 10
Returns options class to be used as options in evolution solvers.
 Attributes
 atolfloat {1e8}
Absolute tolerance.
 rtolfloat {1e6}
Relative tolerance.
 methodstr {‘adams’,’bdf’}
Integration method.
 orderint {12}
Order of integrator (<=12 ‘adams’, <=5 ‘bdf’)
 nstepsint {2500}
Max. number of internal steps/call.
 first_stepfloat {0}
Size of initial step (0 = automatic).
 min_stepfloat {0}
Minimum step size (0 = automatic).
 max_stepfloat {0}
Maximum step size (0 = automatic)
 tidybool {True,False}
Tidyup Hamiltonian and initial state by removing small terms.
 num_cpusint
Number of cpus used by mcsolver (default = # of cpus).
 norm_tolfloat
Tolerance used when finding wavefunction norm in mcsolve.
 norm_stepsint
Max. number of steps used to find wavefunction norm to within norm_tol in mcsolve.
 average_statesbool {False}
Average states values over trajectories in stochastic solvers.
 average_expectbool {True}
Average expectation values over trajectories for stochastic solvers.
 mc_corr_epsfloat {1e10}
Arbitrarily small value for eliminating any dividebyzero errors in correlation calculations when using mcsolve.
 ntrajint {500}
Number of trajectories in stochastic solvers.
 openmp_threadsint
Number of OPENMP threads to use. Default is number of cpu cores.
 rhs_reusebool {False,True}
Reuse Hamiltonian data.
 rhs_with_statebool {False,True}
Whether or not to include the state in the Hamiltonian function callback signature.
 rhs_filenamestr
Name for compiled Cython file.
 seedsndarray
Array containing random number seeds for mcsolver.
 store_final_statebool {False, True}
Whether or not to store the final state of the evolution in the result class.
 store_statesbool {False, True}
Whether or not to store the state vectors or density matrices in the result class, even if expectation values operators are given. If no expectation are provided, then states are stored by default and this option has no effect.
 use_openmpbool {True, False}
Use OPENMP for sparse matrix vector multiplication. Default None means auto check.

class
Result
[source]¶ Class for storing simulation results from any of the dynamics solvers.
 Attributes
 solverstr
Which solver was used [e.g., ‘mesolve’, ‘mcsolve’, ‘brmesolve’, …]
 timeslist/array
Times at which simulation data was collected.
 expectlist/array
Expectation values (if requested) for simulation.
 statesarray
State of the simulation (density matrix or ket) evaluated at
times
. num_expectint
Number of expectation value operators in simulation.
 num_collapseint
Number of collapse operators in simualation.
 ntrajint/list
Number of trajectories (for stochastic solvers). A list indicates that averaging of expectation values was done over a subset of total number of trajectories.
 col_timeslist
Times at which state collpase occurred. Only for Monte Carlo solver.
 col_whichlist
Which collapse operator was responsible for each collapse in
col_times
. Only for Monte Carlo solver.

class
Stats
(section_names=None)[source]¶ Statistical information on the solver performance Statistics can be grouped into sections. If no section names are given in the the contructor, then all statistics will be added to one section ‘main’
 Parameters
 section_nameslist
list of keys that will be used as keys for the sections These keys will also be used as names for the sections The text in the output can be overidden by setting the header property of the section If no names are given then one section called ‘main’ is created
 Attributes
 sectionsOrderedDict of _StatsSection
These are the sections that are created automatically on instantiation or added using add_section
 headerstring
Some text that will be used as the heading in the report By default there is None
 total_timefloat
Time in seconds for the solver to complete processing Can be None, meaning that total timing percentages will be reported

add_count
(key, value, section=None)[source]¶ Add value to count. If key does not already exist in section then it is created with this value. If key already exists it is increased by the give value value is expected to be an integer
 Parameters
 keystring
key for the section.counts dictionary reusing a key will result in numerical addition of value
 valueint
Initial value of the count, or added to an existing count
 sectionstring or
_StatsSection
Section which to add the count to. If None given, the default (first) section will be used

add_message
(key, value, section=None, sep=';')[source]¶ Add value to message. If key does not already exist in section then it is created with this value. If key already exists the value is added to the message The value will be converted to a string
 Parameters
 keystring
key for the section.messages dictionary reusing a key will result in concatenation of value
 valueint
Initial value of the message, or added to an existing message
 sepstring
Message will be prefixed with this string when concatenating
 section: string or `class`_StatsSection
Section which to add the message to. If None given, the default (first) section will be used

add_section
(name)[source]¶ Add another section with the given name
 Parameters
 namestring
will be used as key for sections dict will also be the header for the section
 Returns
 section
_StatsSection
The new section
 section

add_timing
(key, value, section=None)[source]¶ Add value to timing. If key does not already exist in section then it is created with this value. If key already exists it is increased by the give value value is expected to be a float, and given in seconds.
 Parameters
 keystring
key for the section.timings dictionary reusing a key will result in numerical addition of value
 valueint
Initial value of the timing, or added to an existing timing
 section: string or `class`_StatsSection
Section which to add the timing to. If None given, the default (first) section will be used

report
(output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf8'>)[source]¶ Report the counts, timings and messages from the sections. Sections are reported in the order that the names were supplied in the constructor. The counts, timings and messages are reported in the order that they are added to the sections The output can be written to anything that supports a write method, e.g. a file or the console (default) The output is intended to in markdown format
 Parameters
 outputstream
file or console stream  anything that support write  where the output will be written

set_total_time
(value, section=None)[source]¶ Sets the total time for the complete solve or for a specific section value is expected to be a float, and given in seconds
 Parameters
 valuefloat
Time in seconds to complete the solver section
 sectionstring or class
Section which to set the total_time for If None given, the total_time for complete solve is set

class
StochasticSolverOptions
(me, H=None, c_ops=[], sc_ops=[], state0=None, e_ops=[], m_ops=None, store_all_expect=False, store_measurement=False, dW_factors=None, solver=None, method='homodyne', normalize=None, times=None, nsubsteps=1, ntraj=1, tol=None, generate_noise=None, noise=None, progress_bar=None, map_func=None, map_kwargs=None, args={}, options=None, noiseDepth=20)[source]¶ Class of options for stochastic solvers such as
qutip.stochastic.ssesolve
,qutip.stochastic.smesolve
, etc.The stochastic solvers
qutip.stochastic.general_stochastic
,qutip.stochastic.ssesolve
,qutip.stochastic.smesolve
,qutip.stochastic.photocurrent_sesolve
andqutip.stochastic.photocurrent_mesolve
all take the same keyword arguments as the constructor of these class, and internally they use these arguments to construct an instance of this class, so it is rarely needed to explicitly create an instance of this class.Within the attribute list, a
time_dependent_object
is eitherQobj
: a constant term2element list of
[Qobj, time_dependence]
: a timedependent term where theQobj
will be multiplied by the timedependent scalar.
For more details on all allowed timedependent objects, see the documentation for
QobjEvo
. Attributes
 Htime_dependent_object or list of time_dependent_object
System Hamiltonian in standard timedependent list format. This is the same as the argument that (e.g.)
mesolve
takes. If this is a list of elements, they are summed. state0
qutip.Qobj
Initial state vector (ket) or density matrix.
 timesarray_like of float
List of times for \(t\). Must be uniformly spaced.
 c_opslist of time_dependent_object
List of deterministic collapse operators. Each element of the list is a separate operator; unlike the Hamiltonian, there is no implicit summation over the terms.
 sc_opslist of time_dependent_object
List of stochastic collapse operators. Each stochastic collapse operator will give a deterministic and stochastic contribution to the equation of motion according to how the d1 and d2 functions are defined. Each element of the list is a separate operator, like
c_ops
. e_opslist of
qutip.Qobj
Single operator or list of operators for which to evaluate expectation values.
 m_opslist of
qutip.Qobj
List of operators representing the measurement operators. The expected format is a nested list with one measurement operator for each stochastic increament, for each stochastic collapse operator.
 argsdict
Dictionary of parameters for time dependent systems.
 tolfloat
Tolerance of the solver for implicit methods.
 ntrajint
Number of trajectors.
 nsubstepsint
Number of sub steps between each timespep given in times.
 dW_factorsarray
Array of length len(sc_ops), containing scaling factors for each measurement operator in m_ops.
 solverstring
Name of the solver method to use for solving the stochastic equations. Valid values are:
order 1/2 algorithms: ‘eulermaruyama’, ‘pceuler’, ‘pceulerimp’
order 1 algorithms: ‘milstein’, ‘platen’, ‘milsteinimp’, ‘rouchon’
order 3/2 algorithms: ‘taylor1.5’, ‘taylor1.5imp’, ‘explicit1.5’
order 2 algorithms: ‘taylor2.0’
See the documentation of
stochastic_solvers
for a description of the solvers. Implicit methods can adjust tolerance via the kw ‘tol’. Default is {‘tol’: 1e6} methodstring (‘homodyne’, ‘heterodyne’)
The name of the type of measurement process that give rise to the stochastic equation to solve.
 store_all_expectbool (default False)
Whether or not to store the e_ops expect values for all paths.
 store_measurementbool (default False)
Whether or not to store the measurement results in the
qutip.solver.Result
instance returned by the solver. noiseint, or 1D array of int, or 4D array of float
int : seed of the noise
1D array : length = ntraj, seeds for each trajectories.
4D array :
(ntraj, len(times), nsubsteps, len(sc_ops)*[12])
. Vector for the noise, the len of the last dimensions is doubled for solvers of order 1.5. This corresponds to results.noise.
 noiseDepthint
Number of terms kept of the truncated series used to create the noise used by taylor2.0 solver.
 normalizebool
(default True for (photo)ssesolve, False for (photo)smesolve) Whether or not to normalize the wave function during the evolution. Normalizing density matrices introduce numerical errors.
 options
qutip.solver.Options
Generic solver options. Only options.average_states and options.store_states are used.
 map_func: function
A map function or managing the calls to singletrajactory solvers.
 map_kwargs: dictionary
Optional keyword arguments to the map_func function function.
 progress_bar
qutip.ui.BaseProgressBar
Optional progress bar class instance.
Permutational Invariance¶

class
Dicke
(N, hamiltonian=None, emission=0.0, dephasing=0.0, pumping=0.0, collective_emission=0.0, collective_dephasing=0.0, collective_pumping=0.0)[source]¶ The Dicke class which builds the Lindbladian and Liouvillian matrix.
 Parameters
 N: int
The number of twolevel systems.
 hamiltonian
qutip.Qobj
A Hamiltonian in the Dicke basis.
The matrix dimensions are (nds, nds), with nds being the number of Dicke states. The Hamiltonian can be built with the operators given by the jspin functions.
 emission: float
Incoherent emission coefficient (also nonradiative emission). default: 0.0
 dephasing: float
Local dephasing coefficient. default: 0.0
 pumping: float
Incoherent pumping coefficient. default: 0.0
 collective_emission: float
Collective (superradiant) emmission coefficient. default: 0.0
 collective_pumping: float
Collective pumping coefficient. default: 0.0
 collective_dephasing: float
Collective dephasing coefficient. default: 0.0
Examples
>>> from piqs import Dicke, jspin >>> N = 2 >>> jx, jy, jz = jspin(N) >>> jp = jspin(N, "+") >>> jm = jspin(N, "") >>> ensemble = Dicke(N, emission=1.) >>> L = ensemble.liouvillian()
 Attributes
 N: int
The number of twolevel systems.
 hamiltonian
qutip.Qobj
A Hamiltonian in the Dicke basis.
The matrix dimensions are (nds, nds), with nds being the number of Dicke states. The Hamiltonian can be built with the operators given by the jspin function in the “dicke” basis.
 emission: float
Incoherent emission coefficient (also nonradiative emission). default: 0.0
 dephasing: float
Local dephasing coefficient. default: 0.0
 pumping: float
Incoherent pumping coefficient. default: 0.0
 collective_emission: float
Collective (superradiant) emmission coefficient. default: 0.0
 collective_dephasing: float
Collective dephasing coefficient. default: 0.0
 collective_pumping: float
Collective pumping coefficient. default: 0.0
 nds: int
The number of Dicke states.
 dshape: tuple
The shape of the Hilbert space in the Dicke or uncoupled basis. default: (nds, nds).

c_ops
()[source]¶ Build collapse operators in the full Hilbert space 2^N.
 Returns
 c_ops_list: list
The list with the collapse operators in the 2^N Hilbert space.

coefficient_matrix
()[source]¶ Build coefficient matrix for ODE for a diagonal problem.
 Returns
 M: ndarray
The matrix M of the coefficients for the ODE dp/dt = Mp. p is the vector of the diagonal matrix elements of the density matrix rho in the Dicke basis.

lindbladian
()[source]¶ Build the Lindbladian superoperator of the dissipative dynamics.
 Returns
 lindbladian
qutip.Qobj
The Lindbladian matrix as a qutip.Qobj.
 lindbladian

liouvillian
()[source]¶ Build the total Liouvillian using the Dicke basis.
 Returns
 liouv
qutip.Qobj
The Liouvillian matrix for the system.
 liouv

pisolve
(initial_state, tlist, options=None)[source]¶ Solve for diagonal Hamiltonians and initial states faster.
 Parameters
 initial_state
qutip.Qobj
An initial state specified as a density matrix of qutip.Qbj type.
 tlist: ndarray
A 1D numpy array of list of timesteps to integrate
 options
qutip.solver.Options
The options for the solver.
 initial_state
 Returns
 result: list
A dictionary of the type qutip.solver.Result which holds the results of the evolution.

class
Pim
(N, emission=0.0, dephasing=0, pumping=0, collective_emission=0, collective_pumping=0, collective_dephasing=0)[source]¶ The Permutation Invariant Matrix class.
Initialize the class with the parameters for generating a Permutation Invariant matrix which evolves a given diagonal initial state p as:
dp/dt = Mp
 Parameters
 N: int
The number of twolevel systems.
 emission: float
Incoherent emission coefficient (also nonradiative emission). default: 0.0
 dephasing: float
Local dephasing coefficient. default: 0.0
 pumping: float
Incoherent pumping coefficient. default: 0.0
 collective_emission: float
Collective (superradiant) emmission coefficient. default: 0.0
 collective_pumping: float
Collective pumping coefficient. default: 0.0
 collective_dephasing: float
Collective dephasing coefficient. default: 0.0
 Attributes
 N: int
The number of twolevel systems.
 emission: float
Incoherent emission coefficient (also nonradiative emission). default: 0.0
 dephasing: float
Local dephasing coefficient. default: 0.0
 pumping: float
Incoherent pumping coefficient. default: 0.0
 collective_emission: float
Collective (superradiant) emmission coefficient. default: 0.0
 collective_dephasing: float
Collective dephasing coefficient. default: 0.0
 collective_pumping: float
Collective pumping coefficient. default: 0.0
 M: dict
A nested dictionary of the structure {row: {col: val}} which holds non zero elements of the matrix M

calculate_j_m
(dicke_row, dicke_col)[source]¶ Get the value of j and m for the particular Dicke space element.
 Parameters
 dicke_row, dicke_col: int
The row and column from the Dicke space matrix
 Returns
 j, m: float
The j and m values.

calculate_k
(dicke_row, dicke_col)[source]¶ Get k value from the current row and column element in the Dicke space.
 Parameters
 dicke_row, dicke_col: int
The row and column from the Dicke space matrix.
 Returns
 ——
 k: int
The row index for the matrix M for given Dicke space element.

coefficient_matrix
()[source]¶ Generate the matrix M governing the dynamics for diagonal cases.
If the initial density matrix and the Hamiltonian is diagonal, the evolution of the system is given by the simple ODE: dp/dt = Mp.

isdicke
(dicke_row, dicke_col)[source]¶ Check if an element in a matrix is a valid element in the Dicke space. Dicke row: j value index. Dicke column: m value index. The function returns True if the element exists in the Dicke space and False otherwise.
 Parameters
 dicke_row, dicke_colint
Index of the element in Dicke space which needs to be checked

solve
(rho0, tlist, options=None)[source]¶ Solve the ODE for the evolution of diagonal states and Hamiltonians.

tau_valid
(dicke_row, dicke_col)[source]¶ Find the Tau functions which are valid for this value of (dicke_row, dicke_col) given the number of TLS. This calculates the valid tau values and reurns a dictionary specifying the tau function name and the value.
 Parameters
 dicke_row, dicke_colint
Index of the element in Dicke space which needs to be checked.
 Returns
 taus: dict
A dictionary of key, val as {tau: value} consisting of the valid taus for this row and column of the Dicke space element.
OneDimensional Lattice¶

class
Lattice1d
(num_cell=10, boundary='periodic', cell_num_site=1, cell_site_dof=[1], Hamiltonian_of_cell=None, inter_hop=None)[source]¶ A class for representing a 1d crystal.
The Lattice1d class can be defined with any specific unit cells and a specified number of unit cells in the crystal. It can return dispersion relationship, position operators, Hamiltonian in the position represention etc.
 Parameters
 num_cellint
The number of cells in the crystal.
 boundarystr
Specification of the type of boundary the crystal is defined with.
 cell_num_siteint
The number of sites in the unit cell.
 cell_site_doflist of int/ int
The tensor structure of the degrees of freedom at each site of a unit cell.
 Hamiltonian_of_cellqutip.Qobj
The Hamiltonian of the unit cell.
 inter_hopqutip.Qobj / list of Qobj
The coupling between the unit cell at i and at (i+unit vector)
 Attributes
 num_cellint
The number of unit cells in the crystal.
 cell_num_siteint
The nuber of sites in a unit cell.
 length_for_siteint
The length of the dimension per site of a unit cell.
 cell_tensor_configlist of int
The tensor structure of the cell in the form [cell_num_site,cell_site_dof[:][0] ]
 lattice_tensor_configlist of int
The tensor structure of the crystal in the form [num_cell,cell_num_site,cell_site_dof[:][0]]
 length_of_unit_cellint
The length of the dimension for a unit cell.
 period_bnd_cond_xint
1 indicates “periodic” and 0 indicates “hardwall” boundary condition
 inter_vec_listlist of list
The list of list of coefficients of inter unitcell vectors’ components along Cartesian uit vectors.
 lattice_vectors_listlist of list
The list of list of coefficients of lattice basis vectors’ components along Cartesian unit vectors.
 H_intraqutip.Qobj
The Qobj storing the Hamiltonian of the unnit cell.
 H_inter_listlist of Qobj/ qutip.Qobj
The list of coupling terms between unit cells of the lattice.
 is_realbool
Indicates if the Hamiltonian is real or not.

Hamiltonian
()[source]¶ Returns the lattice Hamiltonian for the instance of Lattice1d.
 Returns
 Qobj(Hamil)qutip.Qobj
oper type Quantum object representing the lattice Hamiltonian.

basis
(cell, site, dof_ind)[source]¶ Returns a single particle wavefunction ket with the particle localized at a specified dof at a specified site of a specified cell.
 Parameters
cell (int) – The cell at which the particle is to be localized.
site (int) – The site of the cell at which the particle is to be localized.
dof_ind (int/ list of int) – The index of the degrees of freedom with which the sigle particle is to be localized.
 Returns
 vec_iqutip.Qobj
ket type Quantum object representing the localized particle.

bloch_wave_functions
()[source]¶ Returns eigenvectors ($psi_n(k)$) of the Hamiltonian in a numpy.ndarray for translationally symmetric lattices with periodic boundary condition.
\begin{eqnarray} \psi_n(k) \rangle = k \rangle \otimes  u_{n}(k) \rangle \\  u_{n}(k) \rangle = a_n(k)a\rangle + b_n(k)b\rangle \\ \end{eqnarray}Please see section 1.2 of Asbóth, J. K., Oroszlány, L., & Pályi, A. (2016). A short course on topological insulators. Lecture notes in physics, 919 for a review.
 Returns
 eigenstatesordered np.array
eigenstates[j][0] is the jth eigenvalue. eigenstates[j][1] is the corresponding eigenvector.

bulk_Hamiltonians
()[source]¶ Returns the bulk momentum space Hamiltonian ($H(k)$) for the lattice at the good quantum numbers of k in a numpy ndarray of Qobj’s.
Please see section 1.2 of Asbóth, J. K., Oroszlány, L., & Pályi, A. (2016). A short course on topological insulators. Lecture notes in physics, 919 for a review.
 Returns
 knxanp.array
knxA[j][0] is the jth good Quantum number k.
 qH_ksnp.ndarray of Qobj’s
qH_ks[j] is the Oobj of type oper that holds a bulk Hamiltonian for a good quantum number k.

cell_periodic_parts
()[source]¶ Returns eigenvectors of the bulk Hamiltonian, i.e. the cell periodic part($u_n(k)$) of the Bloch wavefunctios in a numpy.ndarray for translationally symmetric lattices with periodic boundary condition.
\begin{eqnarray} \psi_n(k) \rangle = k \rangle \otimes  u_{n}(k) \rangle \\  u_{n}(k) \rangle = a_n(k)a\rangle + b_n(k)b\rangle \\ \end{eqnarray}Please see section 1.2 of Asbóth, J. K., Oroszlány, L., & Pályi, A. (2016). A short course on topological insulators. Lecture notes in physics, 919 for a review.
 Returns
 knxanp.array
knxA[j][0] is the jth good Quantum number k.
 vec_knsnp.ndarray of Qobj’s
vec_kns[j] is the Oobj of type ket that holds an eigenvector of the bulk Hamiltonian of the lattice.

display_lattice
()[source]¶ Produces a graphic portraying the lattice symbolically with a unit cell marked in it.
 Returns
 inter_TQobj
The coefficient of $psi_{i,N}^{dagger}psi_{0,i+1}$, i.e. the coupling between the two boundary sites of the two unit cells i and i+1.

display_unit_cell
(label_on=False)[source]¶ Produces a graphic displaying the unit cell features with labels on if defined by user. Also returns a dict of Qobj’s corresponding to the labeled elements on the display.
 Returns
 Hcelldict
Hcell[i][j] is the Hamiltonian segment for $H_{i,j}$ labeled on the graphic.

distribute_operator
(op)[source]¶ A function that returns an operator matrix that applies op to all the cells in the 1d lattice
 Parameters
op (qutip.Qobj) – Qobj representing the operator to be applied at all cells.
 Returns
 op_Hqutip.Qobj
Quantum object representing the operator with op applied at all cells.

get_dispersion
(knpoints=0)[source]¶ Returns dispersion relationship for the lattice with the specified number of unit cells with a k array and a band energy array.
 Returns
 knxanp.array
knxA[j][0] is the jth good Quantum number k.
 val_knsnp.array
val_kns[j][:] is the array of band energies of the jth band good at all the good Quantum numbers of k.

k
()[source]¶ Returns the crystal momentum operator. All degrees of freedom has the cell number at their correspondig entry in the position operator.
 Returns
 Qobj(ks)qutip.Qobj
The crystal momentum operator in units of 1/a. L is the number of unit cells, a is the length of a unit cell which is always taken to be 1.

operator_at_cells
(op, cells)[source]¶ A function that returns an operator matrix that applies op to specific cells specified in the cells list
 Parameters
 opqutip.Qobj
Qobj representing the operator to be applied at certain cells.
 cells: list of int
The cells at which the operator op is to be applied.
 Returns
 Qobj(op_H)Qobj
Quantum object representing the operator with op applied at the specified cells.

operator_between_cells
(op, row_cell, col_cell)[source]¶ A function that returns an operator matrix that applies op to specific cells specified in the cells list
 Parameters
 opqutip.Qobj
Qobj representing the operator to be put between cells row_cell and col_cell.
 row_cell: int
The row index for cell for the operator op to be applied.
 col_cell: int
The column index for cell for the operator op to be applied.
 Returns
 oper_bet_cellQobj
Quantum object representing the operator with op applied between the specified cells.

plot_dispersion
()[source]¶ Plots the dispersion relationship for the lattice with the specified number of unit cells. The dispersion of the infinte crystal is also plotted if num_cell is smaller than MAXc.

winding_number
()[source]¶ Returns the winding number for a lattice that has chiral symmetry and also plots the trajectory of (dx,dy)(dx,dy are the coefficients of sigmax and sigmay in the Hamiltonian respectively) on a plane.
 Returns
 winding_numberint or str
knxA[j][0] is the jth good Quantum number k.
Distribution functions¶

class
Distribution
(data=None, xvecs=[], xlabels=[])[source]¶ A class for representation spatial distribution functions.
The Distribution class can be used to prepresent spatial distribution functions of arbitray dimension (although only 1D and 2D distributions are used so far).
It is indented as a base class for specific distribution function, and provide implementation of basic functions that are shared among all Distribution functions, such as visualization, calculating marginal distributions, etc.
 Parameters
 dataarray_like
Data for the distribution. The dimensions must match the lengths of the coordinate arrays in xvecs.
 xvecslist
List of arrays that spans the space for each coordinate.
 xlabelslist
List of labels for each coordinate.

marginal
(dim=0)[source]¶ Calculate the marginal distribution function along the dimension dim. Return a new Distribution instance describing this reduced dimensionality distribution.
 Parameters
 dimint
The dimension (coordinate index) along which to obtain the marginal distribution.
 Returns
 dDistributions
A new instances of Distribution that describes the marginal distribution.

project
(dim=0)[source]¶ Calculate the projection (max value) distribution function along the dimension dim. Return a new Distribution instance describing this reduceddimensionality distribution.
 Parameters
 dimint
The dimension (coordinate index) along which to obtain the projected distribution.
 Returns
 dDistributions
A new instances of Distribution that describes the projection.

visualize
(fig=None, ax=None, figsize=(8, 6), colorbar=True, cmap=None, style='colormap', show_xlabel=True, show_ylabel=True)[source]¶ Visualize the data of the distribution in 1D or 2D, depending on the dimensionality of the underlaying distribution.
Parameters:
 figmatplotlib Figure instance
If given, use this figure instance for the visualization,
 axmatplotlib Axes instance
If given, render the visualization using this axis instance.
 figsizetuple
Size of the new Figure instance, if one needs to be created.
 colorbar: Bool
Whether or not the colorbar (in 2D visualization) should be used.
 cmap: matplotlib colormap instance
If given, use this colormap for 2D visualizations.
 stylestring
Type of visualization: ‘colormap’ (default) or ‘surface’.
 Returns
 fig, axtuple
A tuple of matplotlib figure and axes instances.

class
TwoModeQuadratureCorrelation
(state=None, theta1=0.0, theta2=0.0, extent=[[ 5, 5], [ 5, 5]], steps=250)[source]¶ 
update
(state)[source]¶ calculate probability distribution for quadrature measurement outcomes given a twomode wavefunction or density matrix

Quantum information processing¶

class
Gate
(*args, **kwargs)[source]¶ Representation of a quantum gate, with its required parametrs, and target and control qubits.
 Parameters
 namestring
Gate name.
 targetslist or int
Gate targets.
 controlslist or int
Gate controls.
 arg_valuefloat
Argument value(phi).
 arg_labelstring
Label for gate representation.
 classical_controlsint or list of int, optional
indices of classical bits to control gate on.
 control_valueint, optional
value of classical bits to control on, the classical controls are interpreted as an integer with lowest bit being the first one. If not specified, then the value is interpreted to be 2 ** len(classical_controls)  1 (i.e. all classical controls are 1).

class
Measurement
(name, targets=None, index=None, classical_store=None)[source]¶ Representation of a quantum measurement, with its required parameters, and target qubits.
 Parameters
 namestring
Measurement name.
 targetslist or int
Gate targets.
 classical_storeint
Result of the measurment is stored in this classical register of the circuit.

measurement_comp_basis
(state)[source]¶ Measures a particular qubit (determined by the target) whose ket vector/ density matrix is specified in the computational basis and returns collapsed_states and probabilities (retains full dimension).
 Parameters
 stateket or oper
state to be measured on specified by ket vector or density matrix
 Returns
 collapsed_statesList of Qobjs
the collapsed state obtained after measuring the qubits and obtaining the qubit specified by the target in the state specified by the index.
 probabilitiesList of floats
the probability of measuring a state in a the state specified by the index.

class
QubitCircuit
(N, input_states=None, output_states=None, reverse_states=True, user_gates=None, dims=None, num_cbits=0)[source]¶ Representation of a quantum program/algorithm, maintaining a sequence of gates.
 Parameters
 Nint
Number of qubits in the system.
 user_gatesdict
Define a dictionary of the custom gates. See examples for detail.
 input_stateslist
A list of string such as 0,’+’, “A”, “Y”. Only used for latex.
 dimslist
A list of integer for the dimension of each composite system. e.g [2,2,2,2,2] for 5 qubits system. If None, qubits system will be the default option.
Examples
>>> def user_gate(): ... mat = np.array([[1., 0], ... [0., 1.j]]) ... return Qobj(mat, dims=[[2], [2]]) >>> qubit_circuit = QubitCircuit(2, user_gates={"T":user_gate}) >>> qubit_circuit.add_gate("T", targets=[0])

add_1q_gate
(name, start=0, end=None, qubits=None, arg_value=None, arg_label=None, classical_controls=None, control_value=None)[source]¶ Adds a single qubit gate with specified parameters on a variable number of qubits in the circuit. By default, it applies the given gate to all the qubits in the register.
 Parameters
 namestring
Gate name.
 startint
Starting location of qubits.
 endint
Last qubit for the gate.
 qubitslist
Specific qubits for applying gates.
 arg_valuefloat
Argument value(phi).
 arg_labelstring
Label for gate representation.

add_circuit
(qc, start=0)[source]¶ Adds a block of a qubit circuit to the main circuit. Globalphase gates are not added.
 Parameters
 qc
QubitCircuit
The circuit block to be added to the main circuit.
 startint
The qubit on which the first gate is applied.
 qc

add_gate
(gate, targets=None, controls=None, arg_value=None, arg_label=None, index=None, classical_controls=None, control_value=None)[source]¶ Adds a gate with specified parameters to the circuit.
 Parameters
 gate: string or :class:`.Gate`
Gate name. If gate is an instance of
Gate
, parameters are unpacked and added. targets: list
Gate targets.
 controls: list
Gate controls.
 arg_value: float
Argument value(phi).
 arg_label: string
Label for gate representation.
 indexlist
Positions to add the gate.
 classical_controlsint or list of int, optional
indices of classical bits to control gate on.
 control_valueint, optional
value of classical bits to control on, the classical controls are interpreted as an integer with lowest bit being the first one. If not specified, then the value is interpreted to be 2 ** len(classical_controls)  1 (i.e. all classical controls are 1).

add_measurement
(measurement, targets=None, index=None, classical_store=None)[source]¶ Adds a measurement with specified parameters to the circuit.
 Parameters
 name: string
Measurement name. If name is an instance of Measuremnent, parameters are unpacked and added.
 targets: list
Gate targets
 indexlist
Positions to add the gate.
 classical_storeint
Classical register where result of measurement is stored.

add_state
(state, targets=None, state_type='input')[source]¶ Add an input or ouput state to the circuit. By default all the input and output states will be initialized to None. A particular state can be added by specifying the state and the qubit where it has to be added along with the type as input or output.
 Parameters
 state: str
The state that has to be added. It can be any string such as 0, ‘+’, “A”, “Y”
 targets: list
A list of qubit positions where the given state has to be added.
 state_type: str
One of either “input” or “output”. This specifies whether the state to be added is an input or output. default: “input”

adjacent_gates
()[source]¶ Method to resolve two qubit gates with nonadjacent control/s or target/s in terms of gates with adjacent interactions.
 Returns
 qubit_circuit:
QubitCircuit
Return
QubitCircuit
of the gates for the qubit circuit with the resolved nonadjacent gates.
 qubit_circuit:

propagators
(expand=True)[source]¶ Propagator matrix calculator for N qubits returning the individual steps as unitary matrices operating from left to right. :returns: U_list – Return list of unitary matrices for the qubit circuit. :rtype: list

propagators_no_expand
()[source]¶ Propagator matrix calculator for N qubits returning the individual steps as unitary matrices operating from left to right.
 Returns
 U_listlist
Return list of unitary matrices for the qubit circuit.

remove_gate_or_measurement
(index=None, end=None, name=None, remove='first')[source]¶ Remove a gate from a specific index or between two indexes or the first, last or all instances of a particular gate.
 Parameters
 indexint
Location of gate or measurement to be removed.
 namestring
Gate or Measurement name to be removed.
 removestring
If first or all gates/measurements are to be removed.

resolve_gates
(basis=['CNOT', 'RX', 'RY', 'RZ'])[source]¶ Unitary matrix calculator for N qubits returning the individual steps as unitary matrices operating from left to right in the specified basis. Calls ‘_resolve_to_universal’ for each gate, this function maps each ‘GATENAME’ with its corresponding ‘_gate_basis_2q’ Subsequently calls _resolve_2q_basis for each basis, this function maps each ‘2QGATENAME’ with its corresponding ‘_basis_’
 Parameters
 basislist.
Basis of the resolved circuit.
 Returns
 qc
QubitCircuit
Return
QubitCircuit
of resolved gates for the qubit circuit in the desired basis.
 qc

reverse_circuit
()[source]¶ Reverse an entire circuit of unitary gates.
 Returns
 qubit_circuit
QubitCircuit
Return
QubitCircuit
of resolved gates for the qubit circuit in the reverse order.
 qubit_circuit

run
(state, cbits=None, U_list=None, measure_results=None, precompute_unitary=False)[source]¶ Calculate the result of one instance of circuit run.
 Parameters
 stateket or oper
state vector or density matrix input.
 cbitsList of ints, optional
initialization of the classical bits.
 U_list: list of Qobj, optional
list of predefined unitaries corresponding to circuit.
 measure_resultstuple of ints, optional
optional specification of each measurement result to enable postselection. If specified, the measurement results are set to the tuple of bits (sequentially) instead of being chosen at random.
 precompute_unitary: Boolean, optional
Specify if computation is done by precomputing and aggregating gate unitaries. Possibly a faster method in the case of large number of repeat runs with different state inputs.
 Returns
 final_stateQobj
output state of the circuit run.

run_statistics
(state, U_list=None, cbits=None, precompute_unitary=False)[source]¶ Calculate all the possible outputs of a circuit (varied by measurement gates).
 Parameters
 stateket or oper
state vector or density matrix input.
 cbitsList of ints, optional
initialization of the classical bits.
 U_list: list of Qobj, optional
list of predefined unitaries corresponding to circuit.
 measure_resultstuple of ints, optional
optional specification of each measurement result to enable postselection. If specified, the measurement results are set to the tuple of bits (sequentially) instead of being chosen at random.
 precompute_unitary: Boolean, optional
Specify if computation is done by precomputing and aggregating gate unitaries. Possibly a faster method in the case of large number of repeat runs with different state inputs.
 Returns
 result: CircuitResult
Return a CircuitResult object containing output states and and their probabilities.

class
CircuitResult
(final_states, probabilities, cbits=None)[source]¶ 
get_cbits
(index=None)[source]¶ Return list of classical bit outputs corresponding to the results.
 Parameters
 index: int
Indicates ith output, probability pair to be returned.
 Returns
 cbits: list of int or list of list of int
list of classical bit outputs


class
CircuitSimulator
(qc, state=None, cbits=None, U_list=None, measure_results=None, mode='state_vector_simulator', precompute_unitary=False)[source]¶ 
initialize
(state=None, cbits=None, measure_results=None)[source]¶ Reset Simulator state variables to start a new run.
 Parameters
 state: ket or oper
ket or density matrix
 cbits: list of int, optional
initial value of classical bits
 U_list: list of Qobj, optional
list of predefined unitaries corresponding to circuit.
 measure_resultstuple of ints, optional
optional specification of each measurement result to enable postselection. If specified, the measurement results are set to the tuple of bits (sequentially) instead of being chosen at random.

run
(state, cbits=None, measure_results=None)[source]¶ Calculate the result of one instance of circuit run.
 Parameters
 stateket or oper
state vector or density matrix input.
 cbitsList of ints, optional
initialization of the classical bits.
 measure_resultstuple of ints, optional
optional specification of each measurement result to enable postselection. If specified, the measurement results are set to the tuple of bits (sequentially) instead of being chosen at random.
 Returns
 result: CircuitResult
Return a CircuitResult object containing output state and probability.

run_statistics
(state, cbits=None)[source]¶ Calculate all the possible outputs of a circuit (varied by measurement gates).
 Parameters
 stateket
state to be observed on specified by density matrix.
 cbitsList of ints, optional
initialization of the classical bits.
 Returns
 result: CircuitResult
Return a CircuitResult object containing output states and and their probabilities.


class
Processor
(N, t1=None, t2=None, dims=None, spline_kind='step_func')[source]¶ A simulator of a quantum device based on the QuTiP solver
qutip.mesolve
. It is defined by the available driving Hamiltonian and the decoherence time for each component systems. The processor can simulate the evolution under the given control pulses. Noisy evolution is supported byNoise
and can be added to the processor. Parameters
 N: int
The number of component systems.
 t1: list or float, optional
Characterize the decoherence of amplitude damping for each qubit. A list of size N or a float for all qubits.
 t2: list of float, optional
Characterize the decoherence of dephasing for each qubit. A list of size N or a float for all qubits.
 dims: list, optional
The dimension of each component system. Default value is a qubit system of
dim=[2,2,2,...,2]
 spline_kind: str, optional
Type of the coefficient interpolation. Default is “step_func” Note that they have different requirement for the length of
coeff
.“step_func”: The coefficient will be treated as a step function. E.g.
tlist=[0,1,2]
andcoeff=[3,2]
, means that the coefficient is 3 in t=[0,1) and 2 in t=[2,3). It requireslen(coeff)=len(tlist)1
orlen(coeff)=len(tlist)
, but in the second case the last element of coeff has no effect.“cubic”: Use cubic interpolation for the coefficient. It requires
len(coeff)=len(tlist)
 Attributes
 N: int
The number of component systems.
 pulses: list of :class:`.Pulse`
A list of control pulses of this device
 t1: float or list
Characterize the decoherence of amplitude damping of each qubit.
 t2: float or list
Characterize the decoherence of dephasing for each qubit.
 noise: :class:`.Noise`, optional
A list of noise objects. They will be processed when creating the noisy
qutip.QobjEvo
from the processor or run the simulation. drift: :class:`qutip.qip.pulse.Drift`
A Drift object representing the drift Hamiltonians.
 dims: list
The dimension of each component system. Default value is a qubit system of
dim=[2,2,2,...,2]
 spline_kind: str
Type of the coefficient interpolation. See parameters of
Processor
for details.

add_control
(qobj, targets=None, cyclic_permutation=False, label=None)[source]¶ Add a control Hamiltonian to the processor. It creates a new
Pulse
object for the device that is turned off (tlist = None
,coeff = None
). To activate the pulse, one can set its tlist and coeff. Parameters
 qobj: :class:`qutip.Qobj`
The Hamiltonian for the control pulse..
 targets: list, optional
The indices of the target qubits (or subquantum system of other dimensions).
 cyclic_permutation: bool, optional
If true, the Hamiltonian will be expanded for all cyclic permutation of the target qubits.
 label: str, optional
The label (name) of the pulse

add_drift
(qobj, targets, cyclic_permutation=False)[source]¶ Add a drift Hamiltonians. The drift Hamiltonians are intrinsic of the quantum system and cannot be controlled by external field.
 Parameters
 qobj: :class:`qutip.Qobj`
The drift Hamiltonian.
 targets: list
The indices of the target qubits (or subquantum system of other dimensions).

add_noise
(noise)[source]¶ Add a noise object to the processor
 Parameters
 noise: :class:`.Noise`
The noise object defined outside the processor

add_pulse
(pulse)[source]¶ Add a new pulse to the device.
 Parameters
 pulse: :class:`.Pulse`
Pulse object to be added.

property
coeffs
¶ A list of the coefficients for all control pulses.

property
ctrls
¶ A list of Hamiltonians of all pulses.

eliminate_auxillary_modes
(U)[source]¶ Eliminate the auxillary modes like the cavity modes in cqed. (Defined in subclasses)

get_full_coeffs
(full_tlist=None)[source]¶ Return the full coefficients in a 2d matrix form. Each row corresponds to one pulse. If the tlist are different for different pulses, the length of each row will be same as the full_tlist (see method get_full_tlist). Interpolation is used for adding the missing coefficient according to spline_kind.
 Returns
 coeffs: arraylike 2d
The coefficients for all ideal pulses.

get_full_tlist
(tol=1e10)[source]¶ Return the full tlist of the ideal pulses. If different pulses have different time steps, it will collect all the time steps in a sorted array.
 Returns
 full_tlist: arraylike 1d
The full time sequence for the ideal evolution.

get_noisy_pulses
(device_noise=False, drift=False)[source]¶ It takes the pulses defined in the Processor and adds noise according to Processor.noise. It does not modify the pulses saved in Processor.pulses but returns a new list. The length of the new list of noisy pulses might be longer because of drift Hamiltonian and device noise. They will be added to the end of the pulses list.
 Parameters
 device_noise: bool, optional
If true, include pulse independent noise such as single qubit Relaxation. Default is False.
 drift: bool, optional
If true, include drift Hamiltonians. Default is False.
 Returns
 noisy_pulses: list of
Pulse
A list of noisy pulses.
 noisy_pulses: list of

get_operators_labels
()[source]¶ Get the labels for each Hamiltonian. It is used in the method``plot_pulses``. It is a 2d nested list, in the plot, a different color will be used for each sublist.

get_qobjevo
(args=None, noisy=False)[source]¶ Create a
qutip.QobjEvo
representation of the evolution. It calls the method get_noisy_pulses and create the QobjEvo from it. Parameters
 args: dict, optional
Arguments for
qutip.QobjEvo
 noisy: bool, optional
If noise are included. Default is False.
 Returns
 qobjevo:
qutip.QobjEvo
The
qutip.QobjEvo
representation of the unitary evolution. c_ops: list of
qutip.QobjEvo
A list of lindblad operators is also returned. if
noisy==Flase
, it is always an empty list.
 qobjevo:

load_circuit
(qc)[source]¶ Translate an
QubitCircuit
to its corresponding Hamiltonians. (Defined in subclasses)

plot_pulses
(title=None, figsize=(12, 6), dpi=None, show_axis=False, rescale_pulse_coeffs=True, num_steps=1000)[source]¶ Plot the ideal pulse coefficients.
 Parameters
 title: str, optional
Title for the plot.
 figsize: tuple, optional
The size of the figure.
 dpi: int, optional
The dpi of the figure.
 show_axis: bool, optional
If the axis are shown.
 rescale_pulse_coeffs: bool, optional
Rescale the hight of each pulses.
 num_steps: int, optional
Number of time steps in the plot.
 Returns
 fig: matplotlib.figure.Figure
The Figure object for the plot.
 ax: matplotlib.axes._subplots.AxesSubplot
The axes for the plot.
Notes
plot_pulses
only works for array_like coefficients

read_coeff
(file_name, inctime=True)[source]¶ Read the control amplitudes matrix and time list saved in the file by save_amp.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list in included in the first column.
 Returns
 tlist: array_like
The time list read from the file.
 coeffs: array_like
The pulse matrix read from the file.

remove_pulse
(indices=None, label=None)[source]¶ Remove the control pulse with given indices.
 Parameters
 indices: int or list of int
The indices of the control Hamiltonians to be removed.
 label: str
The label of the pulse

run
(qc=None)[source]¶ Calculate the propagator of the evolution by matrix exponentiation. This method won’t include noise or collpase.
 Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by load_circuit.
 Returns
 U_list: list
The propagator matrix obtained from the physical implementation.

run_analytically
(init_state=None, qc=None)[source]¶ Simulate the state evolution under the given qutip.QubitCircuit with matrice exponentiation. It will calculate the propagator with matrix exponentiation and return a list of
qutip.Qobj
. This method won’t include noise or collpase. Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by
load_circuit
. init_state: :class:`qutip.Qobj`, optional
The initial state of the qubits in the register.
 Returns
 evo_result:
qutip.Result
An instance of the class
qutip.Result
will be returned.
 evo_result:

run_state
(init_state=None, analytical=False, states=None, noisy=True, solver='mesolve', **kwargs)[source]¶ If analytical is False, use
qutip.mesolve
to calculate the time of the state evolution and return the result. Other arguments of mesolve can be given as keyword arguments.If analytical is True, calculate the propagator with matrix exponentiation and return a list of matrices. Noise will be neglected in this option.
 Parameters
 init_state: Qobj
Initial density matrix or state vector (ket).
 analytical: bool
If True, calculate the evolution with matrices exponentiation.
 states: :class:`qutip.Qobj`, optional
Old API, same as init_state.
 solver: str
“mesolve” or “mcsolve”
 **kwargs
Keyword arguments for the qutip solver.
 Returns
 evo_result:
qutip.Result
If
analytical
is False, an instance of the classqutip.Result
will be returned.If
analytical
is True, a list of matrices representation is returned.
 evo_result:

class
OptPulseProcessor
(N, drift=None, t1=None, t2=None, dims=None)[source]¶ A processor, which takes the Hamiltonian available as dynamic generators, calls the qutip.control.optimize_pulse_unitary function to find an optimized pulse sequence for the desired quantum circuit. The processor can simulate the evolution under the given control pulses using
qutip.mesolve
. (For attributes documentation, please refer to the parent classProcessor
) Parameters
 N: int
The number of component systems.
 drift: `:class:`qutip.Qobj`
The drift Hamiltonian. The size must match the whole quantum system.
 t1: list or float
Characterize the decoherence of amplitude damping for each qubit. A list of size N or a float for all qubits.
 t2: list of float
Characterize the decoherence of dephasing for each qubit. A list of size N or a float for all qubits.
 dims: list
The dimension of each component system. Default value is a qubit system of
dim=[2,2,2,...,2]

add_control
(qobj, targets=None, cyclic_permutation=False, label=None)¶ Add a control Hamiltonian to the processor. It creates a new
Pulse
object for the device that is turned off (tlist = None
,coeff = None
). To activate the pulse, one can set its tlist and coeff. Parameters
 qobj: :class:`qutip.Qobj`
The Hamiltonian for the control pulse..
 targets: list, optional
The indices of the target qubits (or subquantum system of other dimensions).
 cyclic_permutation: bool, optional
If true, the Hamiltonian will be expanded for all cyclic permutation of the target qubits.
 label: str, optional
The label (name) of the pulse

add_drift
(qobj, targets, cyclic_permutation=False)¶ Add a drift Hamiltonians. The drift Hamiltonians are intrinsic of the quantum system and cannot be controlled by external field.
 Parameters
 qobj: :class:`qutip.Qobj`
The drift Hamiltonian.
 targets: list
The indices of the target qubits (or subquantum system of other dimensions).

add_noise
(noise)¶ Add a noise object to the processor
 Parameters
 noise: :class:`.Noise`
The noise object defined outside the processor

add_pulse
(pulse)¶ Add a new pulse to the device.
 Parameters
 pulse: :class:`.Pulse`
Pulse object to be added.

property
coeffs
¶ A list of the coefficients for all control pulses.

property
ctrls
¶ A list of Hamiltonians of all pulses.

eliminate_auxillary_modes
(U)¶ Eliminate the auxillary modes like the cavity modes in cqed. (Defined in subclasses)

get_full_coeffs
(full_tlist=None)¶ Return the full coefficients in a 2d matrix form. Each row corresponds to one pulse. If the tlist are different for different pulses, the length of each row will be same as the full_tlist (see method get_full_tlist). Interpolation is used for adding the missing coefficient according to spline_kind.
 Returns
 coeffs: arraylike 2d
The coefficients for all ideal pulses.

get_full_tlist
(tol=1e10)¶ Return the full tlist of the ideal pulses. If different pulses have different time steps, it will collect all the time steps in a sorted array.
 Returns
 full_tlist: arraylike 1d
The full time sequence for the ideal evolution.

get_noisy_pulses
(device_noise=False, drift=False)¶ It takes the pulses defined in the Processor and adds noise according to Processor.noise. It does not modify the pulses saved in Processor.pulses but returns a new list. The length of the new list of noisy pulses might be longer because of drift Hamiltonian and device noise. They will be added to the end of the pulses list.
 Parameters
 device_noise: bool, optional
If true, include pulse independent noise such as single qubit Relaxation. Default is False.
 drift: bool, optional
If true, include drift Hamiltonians. Default is False.
 Returns
 noisy_pulses: list of
Pulse
A list of noisy pulses.
 noisy_pulses: list of

get_operators_labels
()¶ Get the labels for each Hamiltonian. It is used in the method``plot_pulses``. It is a 2d nested list, in the plot, a different color will be used for each sublist.

get_qobjevo
(args=None, noisy=False)¶ Create a
qutip.QobjEvo
representation of the evolution. It calls the method get_noisy_pulses and create the QobjEvo from it. Parameters
 args: dict, optional
Arguments for
qutip.QobjEvo
 noisy: bool, optional
If noise are included. Default is False.
 Returns
 qobjevo:
qutip.QobjEvo
The
qutip.QobjEvo
representation of the unitary evolution. c_ops: list of
qutip.QobjEvo
A list of lindblad operators is also returned. if
noisy==Flase
, it is always an empty list.
 qobjevo:

load_circuit
(qc, min_fid_err=inf, merge_gates=True, setting_args=None, verbose=False, **kwargs)[source]¶ Find the pulses realizing a given
QubitCircuit
using qutip.control.optimize_pulse_unitary. Further parameter for for qutip.control.optimize_pulse_unitary needs to be given as keyword arguments. By default, it first merge all the gates into one unitary and then find the control pulses for it. It can be turned off and one can set different parameters for different gates. See examples for details. Parameters
 qc: :class:`.QubitCircuit` or list of Qobj
The quantum circuit to be translated.
 min_fid_err: float, optional
The minimal fidelity tolerance, if the fidelity error of any gate decomposition is higher, a warning will be given. Default is infinite.
 merge_gates: boolean, optimal
If True, merge all gate/Qobj into one Qobj and then find the optimal pulses for this unitary matrix. If False, find the optimal pulses for each gate/Qobj.
 setting_args: dict, optional
Only considered if merge_gates is False. It is a dictionary containing keyword arguments for different gates.
E.g.:
setting_args = {"SNOT": {"num_tslots": 10, "evo_time": 1}, "SWAP": {"num_tslots": 30, "evo_time": 3}, "CNOT": {"num_tslots": 30, "evo_time": 3}}
 verbose: boolean, optional
If true, the information for each decomposed gate will be shown. Default is False.
 **kwargs
keyword arguments for qutip.control.optimize_pulse_unitary
 Returns
 tlist: array_like
A NumPy array specifies the time of each coefficient
 coeffs: array_like
A 2d NumPy array of the shape (len(ctrls), len(tlist)1). Each row corresponds to the control pulse sequence for one Hamiltonian.
Notes
len(tlist)  1 = coeffs.shape[1]
since tlist gives the beginning and the end of the pulses.Examples
Same parameter for all the gates:
qc = QubitCircuit(N=1) qc.add_gate("SNOT", 0) num_tslots = 10 evo_time = 10 processor = OptPulseProcessor(N=1, drift=sigmaz(), ctrls=[sigmax()]) # num_tslots and evo_time are two keyword arguments tlist, coeffs = processor.load_circuit( qc, num_tslots=num_tslots, evo_time=evo_time)
Different parameters for different gates:
qc = QubitCircuit(N=2) qc.add_gate("SNOT", 0) qc.add_gate("SWAP", targets=[0, 1]) qc.add_gate('CNOT', controls=1, targets=[0]) processor = OptPulseProcessor(N=2, drift=tensor([sigmaz()]*2)) processor.add_control(sigmax(), cyclic_permutation=True) processor.add_control(sigmay(), cyclic_permutation=True) processor.add_control(tensor([sigmay(), sigmay()])) setting_args = {"SNOT": {"num_tslots": 10, "evo_time": 1}, "SWAP": {"num_tslots": 30, "evo_time": 3}, "CNOT": {"num_tslots": 30, "evo_time": 3}} tlist, coeffs = processor.load_circuit(qc, setting_args=setting_args, merge_gates=False)

plot_pulses
(title=None, figsize=(12, 6), dpi=None, show_axis=False, rescale_pulse_coeffs=True, num_steps=1000)¶ Plot the ideal pulse coefficients.
 Parameters
 title: str, optional
Title for the plot.
 figsize: tuple, optional
The size of the figure.
 dpi: int, optional
The dpi of the figure.
 show_axis: bool, optional
If the axis are shown.
 rescale_pulse_coeffs: bool, optional
Rescale the hight of each pulses.
 num_steps: int, optional
Number of time steps in the plot.
 Returns
 fig: matplotlib.figure.Figure
The Figure object for the plot.
 ax: matplotlib.axes._subplots.AxesSubplot
The axes for the plot.
Notes
plot_pulses
only works for array_like coefficients

read_coeff
(file_name, inctime=True)¶ Read the control amplitudes matrix and time list saved in the file by save_amp.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list in included in the first column.
 Returns
 tlist: array_like
The time list read from the file.
 coeffs: array_like
The pulse matrix read from the file.

remove_pulse
(indices=None, label=None)¶ Remove the control pulse with given indices.
 Parameters
 indices: int or list of int
The indices of the control Hamiltonians to be removed.
 label: str
The label of the pulse

run
(qc=None)¶ Calculate the propagator of the evolution by matrix exponentiation. This method won’t include noise or collpase.
 Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by load_circuit.
 Returns
 U_list: list
The propagator matrix obtained from the physical implementation.

run_analytically
(init_state=None, qc=None)¶ Simulate the state evolution under the given qutip.QubitCircuit with matrice exponentiation. It will calculate the propagator with matrix exponentiation and return a list of
qutip.Qobj
. This method won’t include noise or collpase. Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by
load_circuit
. init_state: :class:`qutip.Qobj`, optional
The initial state of the qubits in the register.
 Returns
 evo_result:
qutip.Result
An instance of the class
qutip.Result
will be returned.
 evo_result:

run_state
(init_state=None, analytical=False, states=None, noisy=True, solver='mesolve', **kwargs)¶ If analytical is False, use
qutip.mesolve
to calculate the time of the state evolution and return the result. Other arguments of mesolve can be given as keyword arguments.If analytical is True, calculate the propagator with matrix exponentiation and return a list of matrices. Noise will be neglected in this option.
 Parameters
 init_state: Qobj
Initial density matrix or state vector (ket).
 analytical: bool
If True, calculate the evolution with matrices exponentiation.
 states: :class:`qutip.Qobj`, optional
Old API, same as init_state.
 solver: str
“mesolve” or “mcsolve”
 **kwargs
Keyword arguments for the qutip solver.
 Returns
 evo_result:
qutip.Result
If
analytical
is False, an instance of the classqutip.Result
will be returned.If
analytical
is True, a list of matrices representation is returned.
 evo_result:

save_coeff
(file_name, inctime=True)¶ Save a file with the control amplitudes in each timeslot.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list should be included in the first column.

class
ModelProcessor
(N, correct_global_phase=True, t1=None, t2=None)[source]¶ The base class for a circuit processor simulating a physical device, e.g cavityQED, spinchain. The available Hamiltonian of the system is predefined. The processor can simulate the evolution under the given control pulses either numerically or analytically. It cannot be used alone, please refer to the subclasses. (Only additional attributes are documented here, for others please refer to the parent class
Processor
) Parameters
 N: int
The number of component systems.
 correct_global_phase: boolean, optional
If true, the analytical solution will track the global phase. It has no effect on the numerical solution.
 t1: list or float
Characterize the decoherence of amplitude damping for each qubit. A list of size N or a float for all qubits.
 t2: list of float
Characterize the decoherence of dephasing for each qubit. A list of size N or a float for all qubits.
 Attributes
 params: dict
A Python dictionary contains the name and the value of the parameters in the physical realization, such as laser frequency, detuning etc.
 correct_global_phase: float
Save the global phase, the analytical solution will track the global phase. It has no effect on the numerical solution.

add_control
(qobj, targets=None, cyclic_permutation=False, label=None)¶ Add a control Hamiltonian to the processor. It creates a new
Pulse
object for the device that is turned off (tlist = None
,coeff = None
). To activate the pulse, one can set its tlist and coeff. Parameters
 qobj: :class:`qutip.Qobj`
The Hamiltonian for the control pulse..
 targets: list, optional
The indices of the target qubits (or subquantum system of other dimensions).
 cyclic_permutation: bool, optional
If true, the Hamiltonian will be expanded for all cyclic permutation of the target qubits.
 label: str, optional
The label (name) of the pulse

add_drift
(qobj, targets, cyclic_permutation=False)¶ Add a drift Hamiltonians. The drift Hamiltonians are intrinsic of the quantum system and cannot be controlled by external field.
 Parameters
 qobj: :class:`qutip.Qobj`
The drift Hamiltonian.
 targets: list
The indices of the target qubits (or subquantum system of other dimensions).

add_noise
(noise)¶ Add a noise object to the processor
 Parameters
 noise: :class:`.Noise`
The noise object defined outside the processor

add_pulse
(pulse)¶ Add a new pulse to the device.
 Parameters
 pulse: :class:`.Pulse`
Pulse object to be added.

property
coeffs
¶ A list of the coefficients for all control pulses.

property
ctrls
¶ A list of Hamiltonians of all pulses.

eliminate_auxillary_modes
(U)¶ Eliminate the auxillary modes like the cavity modes in cqed. (Defined in subclasses)

get_full_coeffs
(full_tlist=None)¶ Return the full coefficients in a 2d matrix form. Each row corresponds to one pulse. If the tlist are different for different pulses, the length of each row will be same as the full_tlist (see method get_full_tlist). Interpolation is used for adding the missing coefficient according to spline_kind.
 Returns
 coeffs: arraylike 2d
The coefficients for all ideal pulses.

get_full_tlist
(tol=1e10)¶ Return the full tlist of the ideal pulses. If different pulses have different time steps, it will collect all the time steps in a sorted array.
 Returns
 full_tlist: arraylike 1d
The full time sequence for the ideal evolution.

get_noisy_pulses
(device_noise=False, drift=False)¶ It takes the pulses defined in the Processor and adds noise according to Processor.noise. It does not modify the pulses saved in Processor.pulses but returns a new list. The length of the new list of noisy pulses might be longer because of drift Hamiltonian and device noise. They will be added to the end of the pulses list.
 Parameters
 device_noise: bool, optional
If true, include pulse independent noise such as single qubit Relaxation. Default is False.
 drift: bool, optional
If true, include drift Hamiltonians. Default is False.
 Returns
 noisy_pulses: list of
Pulse
A list of noisy pulses.
 noisy_pulses: list of

get_operators_labels
()¶ Get the labels for each Hamiltonian. It is used in the method``plot_pulses``. It is a 2d nested list, in the plot, a different color will be used for each sublist.

get_ops_and_u
()[source]¶ Get the labels for each Hamiltonian.
 Returns
 ctrls: list
The list of Hamiltonians
 coeffs: array_like
The transposed pulse matrix

get_qobjevo
(args=None, noisy=False)¶ Create a
qutip.QobjEvo
representation of the evolution. It calls the method get_noisy_pulses and create the QobjEvo from it. Parameters
 args: dict, optional
Arguments for
qutip.QobjEvo
 noisy: bool, optional
If noise are included. Default is False.
 Returns
 qobjevo:
qutip.QobjEvo
The
qutip.QobjEvo
representation of the unitary evolution. c_ops: list of
qutip.QobjEvo
A list of lindblad operators is also returned. if
noisy==Flase
, it is always an empty list.
 qobjevo:

load_circuit
(qc)¶ Translate an
QubitCircuit
to its corresponding Hamiltonians. (Defined in subclasses)

plot_pulses
(title=None, figsize=(12, 6), dpi=None, show_axis=False, rescale_pulse_coeffs=True, num_steps=1000)¶ Plot the ideal pulse coefficients.
 Parameters
 title: str, optional
Title for the plot.
 figsize: tuple, optional
The size of the figure.
 dpi: int, optional
The dpi of the figure.
 show_axis: bool, optional
If the axis are shown.
 rescale_pulse_coeffs: bool, optional
Rescale the hight of each pulses.
 num_steps: int, optional
Number of time steps in the plot.
 Returns
 fig: matplotlib.figure.Figure
The Figure object for the plot.
 ax: matplotlib.axes._subplots.AxesSubplot
The axes for the plot.
Notes
plot_pulses
only works for array_like coefficients

pulse_matrix
(dt=0.01)[source]¶ Generates the pulse matrix for the desired physical system.
 Returns
 t, u, labels:
Returns the total time and label for every operation.

read_coeff
(file_name, inctime=True)¶ Read the control amplitudes matrix and time list saved in the file by save_amp.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list in included in the first column.
 Returns
 tlist: array_like
The time list read from the file.
 coeffs: array_like
The pulse matrix read from the file.

remove_pulse
(indices=None, label=None)¶ Remove the control pulse with given indices.
 Parameters
 indices: int or list of int
The indices of the control Hamiltonians to be removed.
 label: str
The label of the pulse

run
(qc=None)¶ Calculate the propagator of the evolution by matrix exponentiation. This method won’t include noise or collpase.
 Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by load_circuit.
 Returns
 U_list: list
The propagator matrix obtained from the physical implementation.

run_analytically
(init_state=None, qc=None)¶ Simulate the state evolution under the given qutip.QubitCircuit with matrice exponentiation. It will calculate the propagator with matrix exponentiation and return a list of
qutip.Qobj
. This method won’t include noise or collpase. Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by
load_circuit
. init_state: :class:`qutip.Qobj`, optional
The initial state of the qubits in the register.
 Returns
 evo_result:
qutip.Result
An instance of the class
qutip.Result
will be returned.
 evo_result:

run_state
(init_state=None, analytical=False, qc=None, states=None, **kwargs)[source]¶ If analytical is False, use
qutip.mesolve
to calculate the time of the state evolution and return the result. Other arguments of mesolve can be given as keyword arguments. If analytical is True, calculate the propagator with matrix exponentiation and return a list of matrices. Parameters
 init_state: Qobj
Initial density matrix or state vector (ket).
 analytical: boolean
If True, calculate the evolution with matrices exponentiation.
 qc: :class:`.QubitCircuit`, optional
A quantum circuit. If given, it first calls the
load_circuit
and then calculate the evolution. states: :class:`qutip.Qobj`, optional
Old API, same as init_state.
 **kwargs
Keyword arguments for the qutip solver.
 Returns
 evo_result:
qutip.Result
If
analytical
is False, an instance of the classqutip.Result
will be returned.If
analytical
is True, a list of matrices representation is returned.
 evo_result:

save_coeff
(file_name, inctime=True)¶ Save a file with the control amplitudes in each timeslot.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list should be included in the first column.

set_all_tlist
(tlist)¶ Set the same tlist for all the pulses.
 Parameters
 tlist: arraylike, optional
A list of time at which the timedependent coefficients are applied. See
Pulse
for detailed information`

class
SpinChain
(N, correct_global_phase, sx, sz, sxsy, t1, t2)[source]¶ The processor based on the physical implementation of a spin chain qubits system. The available Hamiltonian of the system is predefined. The processor can simulate the evolution under the given control pulses either numerically or analytically. It is a base class and should not be used directly, please refer the the subclasses
qutip.qip.device.LinearSpinChain
andqutip.qip.device.CircularSpinChain
. (Only additional attributes are documented here, for others please refer to the parent classModelProcessor
) Parameters
 N: int
The number of qubits in the system.
 correct_global_phase: float
Save the global phase, the analytical solution will track the global phase. It has no effect on the numerical solution.
 sx: int or list
The delta for each of the qubits in the system.
 sz: int or list
The epsilon for each of the qubits in the system.
 sxsy: int or list
The interaction strength for each of the qubit pair in the system.
 t1: list or float
Characterize the decoherence of amplitude damping for each qubit. A list of size N or a float for all qubits.
 t2: list of float
Characterize the decoherence of dephasing for each qubit. A list of size N or a float for all qubits.
 Attributes
 sx: list
The delta for each of the qubits in the system.
 sz: list
The epsilon for each of the qubits in the system.
 sxsy: list
The interaction strength for each of the qubit pair in the system.
 sx_ops: list
A list of sigmax Hamiltonians for each qubit.
 sz_ops: list
A list of sigmaz Hamiltonians for each qubit.
 sxsy_ops: list
A list of tensor(sigmax, sigmay) interacting Hamiltonians for each qubit.
 sx_u: array_like
Pulse matrix for sigmax Hamiltonians.
 sz_u: array_like
Pulse matrix for sigmaz Hamiltonians.
 sxsy_u: array_like
Pulse matrix for tensor(sigmax, sigmay) interacting Hamiltonians.

add_control
(qobj, targets=None, cyclic_permutation=False, label=None)¶ Add a control Hamiltonian to the processor. It creates a new
Pulse
object for the device that is turned off (tlist = None
,coeff = None
). To activate the pulse, one can set its tlist and coeff. Parameters
 qobj: :class:`qutip.Qobj`
The Hamiltonian for the control pulse..
 targets: list, optional
The indices of the target qubits (or subquantum system of other dimensions).
 cyclic_permutation: bool, optional
If true, the Hamiltonian will be expanded for all cyclic permutation of the target qubits.
 label: str, optional
The label (name) of the pulse

add_drift
(qobj, targets, cyclic_permutation=False)¶ Add a drift Hamiltonians. The drift Hamiltonians are intrinsic of the quantum system and cannot be controlled by external field.
 Parameters
 qobj: :class:`qutip.Qobj`
The drift Hamiltonian.
 targets: list
The indices of the target qubits (or subquantum system of other dimensions).

add_noise
(noise)¶ Add a noise object to the processor
 Parameters
 noise: :class:`.Noise`
The noise object defined outside the processor

add_pulse
(pulse)¶ Add a new pulse to the device.
 Parameters
 pulse: :class:`.Pulse`
Pulse object to be added.

adjacent_gates
(qc, setup='linear')[source]¶ Method to resolve 2 qubit gates with nonadjacent control/s or target/s in terms of gates with adjacent interactions for linear/circular spin chain system.
 Parameters
 qc: :class:`.QubitCircuit`
The circular spin chain circuit to be resolved
 setup: Boolean
Linear of Circular spin chain setup
 Returns
 qc:
QubitCircuit
Returns QubitCircuit of resolved gates for the qubit circuit in the desired basis.
 qc:

property
coeffs
¶ A list of the coefficients for all control pulses.

property
ctrls
¶ A list of Hamiltonians of all pulses.

eliminate_auxillary_modes
(U)[source]¶ Eliminate the auxillary modes like the cavity modes in cqed. (Defined in subclasses)

get_full_coeffs
(full_tlist=None)¶ Return the full coefficients in a 2d matrix form. Each row corresponds to one pulse. If the tlist are different for different pulses, the length of each row will be same as the full_tlist (see method get_full_tlist). Interpolation is used for adding the missing coefficient according to spline_kind.
 Returns
 coeffs: arraylike 2d
The coefficients for all ideal pulses.

get_full_tlist
(tol=1e10)¶ Return the full tlist of the ideal pulses. If different pulses have different time steps, it will collect all the time steps in a sorted array.
 Returns
 full_tlist: arraylike 1d
The full time sequence for the ideal evolution.

get_noisy_pulses
(device_noise=False, drift=False)¶ It takes the pulses defined in the Processor and adds noise according to Processor.noise. It does not modify the pulses saved in Processor.pulses but returns a new list. The length of the new list of noisy pulses might be longer because of drift Hamiltonian and device noise. They will be added to the end of the pulses list.
 Parameters
 device_noise: bool, optional
If true, include pulse independent noise such as single qubit Relaxation. Default is False.
 drift: bool, optional
If true, include drift Hamiltonians. Default is False.
 Returns
 noisy_pulses: list of
Pulse
A list of noisy pulses.
 noisy_pulses: list of

get_operators_labels
()¶ Get the labels for each Hamiltonian. It is used in the method``plot_pulses``. It is a 2d nested list, in the plot, a different color will be used for each sublist.

get_ops_and_u
()¶ Get the labels for each Hamiltonian.
 Returns
 ctrls: list
The list of Hamiltonians
 coeffs: array_like
The transposed pulse matrix

get_qobjevo
(args=None, noisy=False)¶ Create a
qutip.QobjEvo
representation of the evolution. It calls the method get_noisy_pulses and create the QobjEvo from it. Parameters
 args: dict, optional
Arguments for
qutip.QobjEvo
 noisy: bool, optional
If noise are included. Default is False.
 Returns
 qobjevo:
qutip.QobjEvo
The
qutip.QobjEvo
representation of the unitary evolution. c_ops: list of
qutip.QobjEvo
A list of lindblad operators is also returned. if
noisy==Flase
, it is always an empty list.
 qobjevo:

load_circuit
(qc, setup, schedule_mode='ASAP', compiler=None)[source]¶ Decompose a
QubitCircuit
in to the control amplitude generating the corresponding evolution. Parameters
 qc: :class:`.QubitCircuit`
Takes the quantum circuit to be implemented.
 setup: string
“linear” or “circular” for two subclasses.
 Returns
 tlist: array_like
A NumPy array specifies the time of each coefficient
 coeffs: array_like
A 2d NumPy array of the shape (len(ctrls), len(tlist)). Each row corresponds to the control pulse sequence for one Hamiltonian.

optimize_circuit
(qc)[source]¶ Take a quantum circuit/algorithm and convert it into the optimal form/basis for the desired physical system.
 Parameters
 qc: :class:`.QubitCircuit`
Takes the quantum circuit to be implemented.
 Returns
 qc:
QubitCircuit
The circuit representation with elementary gates that can be implemented in this model.
 qc:

plot_pulses
(title=None, figsize=(12, 6), dpi=None, show_axis=False, rescale_pulse_coeffs=True, num_steps=1000)¶ Plot the ideal pulse coefficients.
 Parameters
 title: str, optional
Title for the plot.
 figsize: tuple, optional
The size of the figure.
 dpi: int, optional
The dpi of the figure.
 show_axis: bool, optional
If the axis are shown.
 rescale_pulse_coeffs: bool, optional
Rescale the hight of each pulses.
 num_steps: int, optional
Number of time steps in the plot.
 Returns
 fig: matplotlib.figure.Figure
The Figure object for the plot.
 ax: matplotlib.axes._subplots.AxesSubplot
The axes for the plot.
Notes
plot_pulses
only works for array_like coefficients

pulse_matrix
(dt=0.01)¶ Generates the pulse matrix for the desired physical system.
 Returns
 t, u, labels:
Returns the total time and label for every operation.

read_coeff
(file_name, inctime=True)¶ Read the control amplitudes matrix and time list saved in the file by save_amp.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list in included in the first column.
 Returns
 tlist: array_like
The time list read from the file.
 coeffs: array_like
The pulse matrix read from the file.

remove_pulse
(indices=None, label=None)¶ Remove the control pulse with given indices.
 Parameters
 indices: int or list of int
The indices of the control Hamiltonians to be removed.
 label: str
The label of the pulse

run
(qc=None)¶ Calculate the propagator of the evolution by matrix exponentiation. This method won’t include noise or collpase.
 Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by load_circuit.
 Returns
 U_list: list
The propagator matrix obtained from the physical implementation.

run_analytically
(init_state=None, qc=None)¶ Simulate the state evolution under the given qutip.QubitCircuit with matrice exponentiation. It will calculate the propagator with matrix exponentiation and return a list of
qutip.Qobj
. This method won’t include noise or collpase. Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by
load_circuit
. init_state: :class:`qutip.Qobj`, optional
The initial state of the qubits in the register.
 Returns
 evo_result:
qutip.Result
An instance of the class
qutip.Result
will be returned.
 evo_result:

run_state
(init_state=None, analytical=False, qc=None, states=None, **kwargs)¶ If analytical is False, use
qutip.mesolve
to calculate the time of the state evolution and return the result. Other arguments of mesolve can be given as keyword arguments. If analytical is True, calculate the propagator with matrix exponentiation and return a list of matrices. Parameters
 init_state: Qobj
Initial density matrix or state vector (ket).
 analytical: boolean
If True, calculate the evolution with matrices exponentiation.
 qc: :class:`.QubitCircuit`, optional
A quantum circuit. If given, it first calls the
load_circuit
and then calculate the evolution. states: :class:`qutip.Qobj`, optional
Old API, same as init_state.
 **kwargs
Keyword arguments for the qutip solver.
 Returns
 evo_result:
qutip.Result
If
analytical
is False, an instance of the classqutip.Result
will be returned.If
analytical
is True, a list of matrices representation is returned.
 evo_result:

save_coeff
(file_name, inctime=True)¶ Save a file with the control amplitudes in each timeslot.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list should be included in the first column.

set_all_tlist
(tlist)¶ Set the same tlist for all the pulses.
 Parameters
 tlist: arraylike, optional
A list of time at which the timedependent coefficients are applied. See
Pulse
for detailed information`

set_up_ops
(N)[source]¶ Generate the Hamiltonians for the spinchain model and save them in the attribute ctrls.
 Parameters
 N: int
The number of qubits in the system.

set_up_params
(sx, sz)[source]¶ Save the parameters in the attribute params and check the validity. The keys of params including “sx”, “sz”, and “sxsy”, each mapped to a list for parameters corresponding to each qubits. For coupling strength “sxsy”, list element i is the interaction between qubits i and i+1.
 Parameters
 sx: float or list
The coefficient of sigmax in the model
 sz: flaot or list
The coefficient of sigmaz in the model
Notes
The coefficient of sxsy is defined in the submethods. All parameters will be multiplied by 2*pi for simplicity

to_array
(params, N)¶ Transfer a parameter to an array.

class
LinearSpinChain
(N, correct_global_phase=True, sx=0.25, sz=1.0, sxsy=0.1, t1=None, t2=None)[source]¶ A processor based on the physical implementation of a linear spin chain qubits system. The available Hamiltonian of the system is predefined. The processor can simulate the evolution under the given control pulses either numerically or analytically.
 Parameters
 N: int
The number of qubits in the system.
 correct_global_phase: float
Save the global phase, the analytical solution will track the global phase. It has no effect on the numerical solution.
 sx: int or list
The delta for each of the qubits in the system.
 sz: int or list
The epsilon for each of the qubits in the system.
 sxsy: int or list
The interaction strength for each of the qubit pair in the system.
 t1: list or float, optional
Characterize the decoherence of amplitude damping for each qubit.
 t2: list of float, optional
Characterize the decoherence of dephasing for each qubit.

add_control
(qobj, targets=None, cyclic_permutation=False, label=None)¶ Add a control Hamiltonian to the processor. It creates a new
Pulse
object for the device that is turned off (tlist = None
,coeff = None
). To activate the pulse, one can set its tlist and coeff. Parameters
 qobj: :class:`qutip.Qobj`
The Hamiltonian for the control pulse..
 targets: list, optional
The indices of the target qubits (or subquantum system of other dimensions).
 cyclic_permutation: bool, optional
If true, the Hamiltonian will be expanded for all cyclic permutation of the target qubits.
 label: str, optional
The label (name) of the pulse

add_drift
(qobj, targets, cyclic_permutation=False)¶ Add a drift Hamiltonians. The drift Hamiltonians are intrinsic of the quantum system and cannot be controlled by external field.
 Parameters
 qobj: :class:`qutip.Qobj`
The drift Hamiltonian.
 targets: list
The indices of the target qubits (or subquantum system of other dimensions).

add_noise
(noise)¶ Add a noise object to the processor
 Parameters
 noise: :class:`.Noise`
The noise object defined outside the processor

add_pulse
(pulse)¶ Add a new pulse to the device.
 Parameters
 pulse: :class:`.Pulse`
Pulse object to be added.

adjacent_gates
(qc)[source]¶ Method to resolve 2 qubit gates with nonadjacent control/s or target/s in terms of gates with adjacent interactions for linear/circular spin chain system.
 Parameters
 qc: :class:`.QubitCircuit`
The circular spin chain circuit to be resolved
 setup: Boolean
Linear of Circular spin chain setup
 Returns
 qc:
QubitCircuit
Returns QubitCircuit of resolved gates for the qubit circuit in the desired basis.
 qc:

property
coeffs
¶ A list of the coefficients for all control pulses.

property
ctrls
¶ A list of Hamiltonians of all pulses.

eliminate_auxillary_modes
(U)¶ Eliminate the auxillary modes like the cavity modes in cqed. (Defined in subclasses)

get_full_coeffs
(full_tlist=None)¶ Return the full coefficients in a 2d matrix form. Each row corresponds to one pulse. If the tlist are different for different pulses, the length of each row will be same as the full_tlist (see method get_full_tlist). Interpolation is used for adding the missing coefficient according to spline_kind.
 Returns
 coeffs: arraylike 2d
The coefficients for all ideal pulses.

get_full_tlist
(tol=1e10)¶ Return the full tlist of the ideal pulses. If different pulses have different time steps, it will collect all the time steps in a sorted array.
 Returns
 full_tlist: arraylike 1d
The full time sequence for the ideal evolution.

get_noisy_pulses
(device_noise=False, drift=False)¶ It takes the pulses defined in the Processor and adds noise according to Processor.noise. It does not modify the pulses saved in Processor.pulses but returns a new list. The length of the new list of noisy pulses might be longer because of drift Hamiltonian and device noise. They will be added to the end of the pulses list.
 Parameters
 device_noise: bool, optional
If true, include pulse independent noise such as single qubit Relaxation. Default is False.
 drift: bool, optional
If true, include drift Hamiltonians. Default is False.
 Returns
 noisy_pulses: list of
Pulse
A list of noisy pulses.
 noisy_pulses: list of

get_operators_labels
()[source]¶ Get the labels for each Hamiltonian. It is used in the method``plot_pulses``. It is a 2d nested list, in the plot, a different color will be used for each sublist.

get_ops_and_u
()¶ Get the labels for each Hamiltonian.
 Returns
 ctrls: list
The list of Hamiltonians
 coeffs: array_like
The transposed pulse matrix

get_qobjevo
(args=None, noisy=False)¶ Create a
qutip.QobjEvo
representation of the evolution. It calls the method get_noisy_pulses and create the QobjEvo from it. Parameters
 args: dict, optional
Arguments for
qutip.QobjEvo
 noisy: bool, optional
If noise are included. Default is False.
 Returns
 qobjevo:
qutip.QobjEvo
The
qutip.QobjEvo
representation of the unitary evolution. c_ops: list of
qutip.QobjEvo
A list of lindblad operators is also returned. if
noisy==Flase
, it is always an empty list.
 qobjevo:

load_circuit
(qc, schedule_mode='ASAP', compiler=None)[source]¶ Decompose a
QubitCircuit
in to the control amplitude generating the corresponding evolution. Parameters
 qc: :class:`.QubitCircuit`
Takes the quantum circuit to be implemented.
 setup: string
“linear” or “circular” for two subclasses.
 Returns
 tlist: array_like
A NumPy array specifies the time of each coefficient
 coeffs: array_like
A 2d NumPy array of the shape (len(ctrls), len(tlist)). Each row corresponds to the control pulse sequence for one Hamiltonian.

optimize_circuit
(qc)¶ Take a quantum circuit/algorithm and convert it into the optimal form/basis for the desired physical system.
 Parameters
 qc: :class:`.QubitCircuit`
Takes the quantum circuit to be implemented.
 Returns
 qc:
QubitCircuit
The circuit representation with elementary gates that can be implemented in this model.
 qc:

plot_pulses
(title=None, figsize=(12, 6), dpi=None, show_axis=False, rescale_pulse_coeffs=True, num_steps=1000)¶ Plot the ideal pulse coefficients.
 Parameters
 title: str, optional
Title for the plot.
 figsize: tuple, optional
The size of the figure.
 dpi: int, optional
The dpi of the figure.
 show_axis: bool, optional
If the axis are shown.
 rescale_pulse_coeffs: bool, optional
Rescale the hight of each pulses.
 num_steps: int, optional
Number of time steps in the plot.
 Returns
 fig: matplotlib.figure.Figure
The Figure object for the plot.
 ax: matplotlib.axes._subplots.AxesSubplot
The axes for the plot.
Notes
plot_pulses
only works for array_like coefficients

pulse_matrix
(dt=0.01)¶ Generates the pulse matrix for the desired physical system.
 Returns
 t, u, labels:
Returns the total time and label for every operation.

read_coeff
(file_name, inctime=True)¶ Read the control amplitudes matrix and time list saved in the file by save_amp.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list in included in the first column.
 Returns
 tlist: array_like
The time list read from the file.
 coeffs: array_like
The pulse matrix read from the file.

remove_pulse
(indices=None, label=None)¶ Remove the control pulse with given indices.
 Parameters
 indices: int or list of int
The indices of the control Hamiltonians to be removed.
 label: str
The label of the pulse

run
(qc=None)¶ Calculate the propagator of the evolution by matrix exponentiation. This method won’t include noise or collpase.
 Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by load_circuit.
 Returns
 U_list: list
The propagator matrix obtained from the physical implementation.

run_analytically
(init_state=None, qc=None)¶ Simulate the state evolution under the given qutip.QubitCircuit with matrice exponentiation. It will calculate the propagator with matrix exponentiation and return a list of
qutip.Qobj
. This method won’t include noise or collpase. Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by
load_circuit
. init_state: :class:`qutip.Qobj`, optional
The initial state of the qubits in the register.
 Returns
 evo_result:
qutip.Result
An instance of the class
qutip.Result
will be returned.
 evo_result:

run_state
(init_state=None, analytical=False, qc=None, states=None, **kwargs)¶ If analytical is False, use
qutip.mesolve
to calculate the time of the state evolution and return the result. Other arguments of mesolve can be given as keyword arguments. If analytical is True, calculate the propagator with matrix exponentiation and return a list of matrices. Parameters
 init_state: Qobj
Initial density matrix or state vector (ket).
 analytical: boolean
If True, calculate the evolution with matrices exponentiation.
 qc: :class:`.QubitCircuit`, optional
A quantum circuit. If given, it first calls the
load_circuit
and then calculate the evolution. states: :class:`qutip.Qobj`, optional
Old API, same as init_state.
 **kwargs
Keyword arguments for the qutip solver.
 Returns
 evo_result:
qutip.Result
If
analytical
is False, an instance of the classqutip.Result
will be returned.If
analytical
is True, a list of matrices representation is returned.
 evo_result:

save_coeff
(file_name, inctime=True)¶ Save a file with the control amplitudes in each timeslot.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list should be included in the first column.

set_all_tlist
(tlist)¶ Set the same tlist for all the pulses.
 Parameters
 tlist: arraylike, optional
A list of time at which the timedependent coefficients are applied. See
Pulse
for detailed information`

set_up_ops
(N)[source]¶ Generate the Hamiltonians for the spinchain model and save them in the attribute ctrls.
 Parameters
 N: int
The number of qubits in the system.

set_up_params
(sx, sz, sxsy)[source]¶ Save the parameters in the attribute params and check the validity. The keys of params including “sx”, “sz”, and “sxsy”, each mapped to a list for parameters corresponding to each qubits. For coupling strength “sxsy”, list element i is the interaction between qubits i and i+1.
 Parameters
 sx: float or list
The coefficient of sigmax in the model
 sz: flaot or list
The coefficient of sigmaz in the model
Notes
The coefficient of sxsy is defined in the submethods. All parameters will be multiplied by 2*pi for simplicity

to_array
(params, N)¶ Transfer a parameter to an array.

class
CircularSpinChain
(N, correct_global_phase=True, sx=0.25, sz=1.0, sxsy=0.1, t1=None, t2=None)[source]¶ A processor based on the physical implementation of a circular spin chain qubits system. The available Hamiltonian of the system is predefined. The processor can simulate the evolution under the given control pulses either numerically or analytically.
 Parameters
 N: int
The number of qubits in the system.
 correct_global_phase: float
Save the global phase, the analytical solution will track the global phase. It has no effect on the numerical solution.
 sx: int or list
The delta for each of the qubits in the system.
 sz: int or list
The epsilon for each of the qubits in the system.
 sxsy: int or list
The interaction strength for each of the qubit pair in the system.
 t1: list or float, optional
Characterize the decoherence of amplitude damping for each qubit.
 t2: list of float, optional
Characterize the decoherence of dephasing for each qubit.

add_control
(qobj, targets=None, cyclic_permutation=False, label=None)¶ Add a control Hamiltonian to the processor. It creates a new
Pulse
object for the device that is turned off (tlist = None
,coeff = None
). To activate the pulse, one can set its tlist and coeff. Parameters
 qobj: :class:`qutip.Qobj`
The Hamiltonian for the control pulse..
 targets: list, optional
The indices of the target qubits (or subquantum system of other dimensions).
 cyclic_permutation: bool, optional
If true, the Hamiltonian will be expanded for all cyclic permutation of the target qubits.
 label: str, optional
The label (name) of the pulse

add_drift
(qobj, targets, cyclic_permutation=False)¶ Add a drift Hamiltonians. The drift Hamiltonians are intrinsic of the quantum system and cannot be controlled by external field.
 Parameters
 qobj: :class:`qutip.Qobj`
The drift Hamiltonian.
 targets: list
The indices of the target qubits (or subquantum system of other dimensions).

add_noise
(noise)¶ Add a noise object to the processor
 Parameters
 noise: :class:`.Noise`
The noise object defined outside the processor

add_pulse
(pulse)¶ Add a new pulse to the device.
 Parameters
 pulse: :class:`.Pulse`
Pulse object to be added.

adjacent_gates
(qc)[source]¶ Method to resolve 2 qubit gates with nonadjacent control/s or target/s in terms of gates with adjacent interactions for linear/circular spin chain system.
 Parameters
 qc: :class:`.QubitCircuit`
The circular spin chain circuit to be resolved
 setup: Boolean
Linear of Circular spin chain setup
 Returns
 qc:
QubitCircuit
Returns QubitCircuit of resolved gates for the qubit circuit in the desired basis.
 qc:

property
coeffs
¶ A list of the coefficients for all control pulses.

property
ctrls
¶ A list of Hamiltonians of all pulses.

eliminate_auxillary_modes
(U)¶ Eliminate the auxillary modes like the cavity modes in cqed. (Defined in subclasses)

get_full_coeffs
(full_tlist=None)¶ Return the full coefficients in a 2d matrix form. Each row corresponds to one pulse. If the tlist are different for different pulses, the length of each row will be same as the full_tlist (see method get_full_tlist). Interpolation is used for adding the missing coefficient according to spline_kind.
 Returns
 coeffs: arraylike 2d
The coefficients for all ideal pulses.

get_full_tlist
(tol=1e10)¶ Return the full tlist of the ideal pulses. If different pulses have different time steps, it will collect all the time steps in a sorted array.
 Returns
 full_tlist: arraylike 1d
The full time sequence for the ideal evolution.

get_noisy_pulses
(device_noise=False, drift=False)¶ It takes the pulses defined in the Processor and adds noise according to Processor.noise. It does not modify the pulses saved in Processor.pulses but returns a new list. The length of the new list of noisy pulses might be longer because of drift Hamiltonian and device noise. They will be added to the end of the pulses list.
 Parameters
 device_noise: bool, optional
If true, include pulse independent noise such as single qubit Relaxation. Default is False.
 drift: bool, optional
If true, include drift Hamiltonians. Default is False.
 Returns
 noisy_pulses: list of
Pulse
A list of noisy pulses.
 noisy_pulses: list of

get_operators_labels
()[source]¶ Get the labels for each Hamiltonian. It is used in the method``plot_pulses``. It is a 2d nested list, in the plot, a different color will be used for each sublist.

get_ops_and_u
()¶ Get the labels for each Hamiltonian.
 Returns
 ctrls: list
The list of Hamiltonians
 coeffs: array_like
The transposed pulse matrix

get_qobjevo
(args=None, noisy=False)¶ Create a
qutip.QobjEvo
representation of the evolution. It calls the method get_noisy_pulses and create the QobjEvo from it. Parameters
 args: dict, optional
Arguments for
qutip.QobjEvo
 noisy: bool, optional
If noise are included. Default is False.
 Returns
 qobjevo:
qutip.QobjEvo
The
qutip.QobjEvo
representation of the unitary evolution. c_ops: list of
qutip.QobjEvo
A list of lindblad operators is also returned. if
noisy==Flase
, it is always an empty list.
 qobjevo:

load_circuit
(qc, schedule_mode='ASAP', compiler=None)[source]¶ Decompose a
QubitCircuit
in to the control amplitude generating the corresponding evolution. Parameters
 qc: :class:`.QubitCircuit`
Takes the quantum circuit to be implemented.
 setup: string
“linear” or “circular” for two subclasses.
 Returns
 tlist: array_like
A NumPy array specifies the time of each coefficient
 coeffs: array_like
A 2d NumPy array of the shape (len(ctrls), len(tlist)). Each row corresponds to the control pulse sequence for one Hamiltonian.

optimize_circuit
(qc)¶ Take a quantum circuit/algorithm and convert it into the optimal form/basis for the desired physical system.
 Parameters
 qc: :class:`.QubitCircuit`
Takes the quantum circuit to be implemented.
 Returns
 qc:
QubitCircuit
The circuit representation with elementary gates that can be implemented in this model.
 qc:

plot_pulses
(title=None, figsize=(12, 6), dpi=None, show_axis=False, rescale_pulse_coeffs=True, num_steps=1000)¶ Plot the ideal pulse coefficients.
 Parameters
 title: str, optional
Title for the plot.
 figsize: tuple, optional
The size of the figure.
 dpi: int, optional
The dpi of the figure.
 show_axis: bool, optional
If the axis are shown.
 rescale_pulse_coeffs: bool, optional
Rescale the hight of each pulses.
 num_steps: int, optional
Number of time steps in the plot.
 Returns
 fig: matplotlib.figure.Figure
The Figure object for the plot.
 ax: matplotlib.axes._subplots.AxesSubplot
The axes for the plot.
Notes
plot_pulses
only works for array_like coefficients

pulse_matrix
(dt=0.01)¶ Generates the pulse matrix for the desired physical system.
 Returns
 t, u, labels:
Returns the total time and label for every operation.

read_coeff
(file_name, inctime=True)¶ Read the control amplitudes matrix and time list saved in the file by save_amp.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list in included in the first column.
 Returns
 tlist: array_like
The time list read from the file.
 coeffs: array_like
The pulse matrix read from the file.

remove_pulse
(indices=None, label=None)¶ Remove the control pulse with given indices.
 Parameters
 indices: int or list of int
The indices of the control Hamiltonians to be removed.
 label: str
The label of the pulse

run
(qc=None)¶ Calculate the propagator of the evolution by matrix exponentiation. This method won’t include noise or collpase.
 Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by load_circuit.
 Returns
 U_list: list
The propagator matrix obtained from the physical implementation.

run_analytically
(init_state=None, qc=None)¶ Simulate the state evolution under the given qutip.QubitCircuit with matrice exponentiation. It will calculate the propagator with matrix exponentiation and return a list of
qutip.Qobj
. This method won’t include noise or collpase. Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by
load_circuit
. init_state: :class:`qutip.Qobj`, optional
The initial state of the qubits in the register.
 Returns
 evo_result:
qutip.Result
An instance of the class
qutip.Result
will be returned.
 evo_result:

run_state
(init_state=None, analytical=False, qc=None, states=None, **kwargs)¶ If analytical is False, use
qutip.mesolve
to calculate the time of the state evolution and return the result. Other arguments of mesolve can be given as keyword arguments. If analytical is True, calculate the propagator with matrix exponentiation and return a list of matrices. Parameters
 init_state: Qobj
Initial density matrix or state vector (ket).
 analytical: boolean
If True, calculate the evolution with matrices exponentiation.
 qc: :class:`.QubitCircuit`, optional
A quantum circuit. If given, it first calls the
load_circuit
and then calculate the evolution. states: :class:`qutip.Qobj`, optional
Old API, same as init_state.
 **kwargs
Keyword arguments for the qutip solver.
 Returns
 evo_result:
qutip.Result
If
analytical
is False, an instance of the classqutip.Result
will be returned.If
analytical
is True, a list of matrices representation is returned.
 evo_result:

save_coeff
(file_name, inctime=True)¶ Save a file with the control amplitudes in each timeslot.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list should be included in the first column.

set_all_tlist
(tlist)¶ Set the same tlist for all the pulses.
 Parameters
 tlist: arraylike, optional
A list of time at which the timedependent coefficients are applied. See
Pulse
for detailed information`

set_up_ops
(N)[source]¶ Generate the Hamiltonians for the spinchain model and save them in the attribute ctrls.
 Parameters
 N: int
The number of qubits in the system.

set_up_params
(sx, sz, sxsy)[source]¶ Save the parameters in the attribute params and check the validity. The keys of params including “sx”, “sz”, and “sxsy”, each mapped to a list for parameters corresponding to each qubits. For coupling strength “sxsy”, list element i is the interaction between qubits i and i+1.
 Parameters
 sx: float or list
The coefficient of sigmax in the model
 sz: flaot or list
The coefficient of sigmaz in the model
Notes
The coefficient of sxsy is defined in the submethods. All parameters will be multiplied by 2*pi for simplicity

to_array
(params, N)¶ Transfer a parameter to an array.

class
DispersiveCavityQED
(N, correct_global_phase=True, num_levels=10, deltamax=1.0, epsmax=9.5, w0=10.0, wq=None, eps=9.5, delta=0.0, g=0.01, t1=None, t2=None)[source]¶ The processor based on the physical implementation of a dispersive cavity QED system. The available Hamiltonian of the system is predefined. For a given pulse amplitude matrix, the processor can calculate the state evolution under the given control pulse, either analytically or numerically. (Only additional attributes are documented here, for others please refer to the parent class
ModelProcessor
) Parameters
 N: int
The number of qubits in the system.
 correct_global_phase: float, optional
Save the global phase, the analytical solution will track the global phase. It has no effect on the numerical solution.
 num_levels: int, optional
The number of energy levels in the resonator.
 deltamax: int or list, optional
The coefficients of sigmax for each of the qubits in the system.
 epsmax: int or list, optional
The coefficients of sigmaz for each of the qubits in the system.
 w0: int, optional
The base frequency of the resonator.
 eps: int or list, optional
The epsilon for each of the qubits in the system.
 delta: int or list, optional
The epsilon for each of the qubits in the system.
 g: int or list, optional
The interaction strength for each of the qubit with the resonator.
 t1: list or float
Characterize the decoherence of amplitude damping for each qubit. A list of size N or a float for all qubits.
 t2: list of float
Characterize the decoherence of dephasing for each qubit. A list of size N or a float for all qubits.
 Attributes
 sx_ops: list
A list of sigmax Hamiltonians for each qubit.
 sz_ops: list
A list of sigmaz Hamiltonians for each qubit.
 cavityqubit_ops: list
A list of interacting Hamiltonians between cavity and each qubit.
 sx_u: array_like
Pulse matrix for sigmax Hamiltonians.
 sz_u: array_like
Pulse matrix for sigmaz Hamiltonians.
 g_u: array_like
Pulse matrix for interacting Hamiltonians between cavity and each qubit.
 wq: list of float
The frequency of the qubits calculated from eps and delta for each qubit.
 Delta: list of float
The detuning with respect to w0 calculated from wq and w0 for each qubit.

add_control
(qobj, targets=None, cyclic_permutation=False, label=None)¶ Add a control Hamiltonian to the processor. It creates a new
Pulse
object for the device that is turned off (tlist = None
,coeff = None
). To activate the pulse, one can set its tlist and coeff. Parameters
 qobj: :class:`qutip.Qobj`
The Hamiltonian for the control pulse..
 targets: list, optional
The indices of the target qubits (or subquantum system of other dimensions).
 cyclic_permutation: bool, optional
If true, the Hamiltonian will be expanded for all cyclic permutation of the target qubits.
 label: str, optional
The label (name) of the pulse

add_drift
(qobj, targets, cyclic_permutation=False)¶ Add a drift Hamiltonians. The drift Hamiltonians are intrinsic of the quantum system and cannot be controlled by external field.
 Parameters
 qobj: :class:`qutip.Qobj`
The drift Hamiltonian.
 targets: list
The indices of the target qubits (or subquantum system of other dimensions).

add_noise
(noise)¶ Add a noise object to the processor
 Parameters
 noise: :class:`.Noise`
The noise object defined outside the processor

add_pulse
(pulse)¶ Add a new pulse to the device.
 Parameters
 pulse: :class:`.Pulse`
Pulse object to be added.

property
coeffs
¶ A list of the coefficients for all control pulses.

property
ctrls
¶ A list of Hamiltonians of all pulses.

get_full_coeffs
(full_tlist=None)¶ Return the full coefficients in a 2d matrix form. Each row corresponds to one pulse. If the tlist are different for different pulses, the length of each row will be same as the full_tlist (see method get_full_tlist). Interpolation is used for adding the missing coefficient according to spline_kind.
 Returns
 coeffs: arraylike 2d
The coefficients for all ideal pulses.

get_full_tlist
(tol=1e10)¶ Return the full tlist of the ideal pulses. If different pulses have different time steps, it will collect all the time steps in a sorted array.
 Returns
 full_tlist: arraylike 1d
The full time sequence for the ideal evolution.

get_noisy_pulses
(device_noise=False, drift=False)¶ It takes the pulses defined in the Processor and adds noise according to Processor.noise. It does not modify the pulses saved in Processor.pulses but returns a new list. The length of the new list of noisy pulses might be longer because of drift Hamiltonian and device noise. They will be added to the end of the pulses list.
 Parameters
 device_noise: bool, optional
If true, include pulse independent noise such as single qubit Relaxation. Default is False.
 drift: bool, optional
If true, include drift Hamiltonians. Default is False.
 Returns
 noisy_pulses: list of
Pulse
A list of noisy pulses.
 noisy_pulses: list of

get_operators_labels
()[source]¶ Get the labels for each Hamiltonian. It is used in the method``plot_pulses``. It is a 2d nested list, in the plot, a different color will be used for each sublist.

get_ops_and_u
()¶ Get the labels for each Hamiltonian.
 Returns
 ctrls: list
The list of Hamiltonians
 coeffs: array_like
The transposed pulse matrix

get_qobjevo
(args=None, noisy=False)¶ Create a
qutip.QobjEvo
representation of the evolution. It calls the method get_noisy_pulses and create the QobjEvo from it. Parameters
 args: dict, optional
Arguments for
qutip.QobjEvo
 noisy: bool, optional
If noise are included. Default is False.
 Returns
 qobjevo:
qutip.QobjEvo
The
qutip.QobjEvo
representation of the unitary evolution. c_ops: list of
qutip.QobjEvo
A list of lindblad operators is also returned. if
noisy==Flase
, it is always an empty list.
 qobjevo:

load_circuit
(qc, schedule_mode='ASAP', compiler=None)[source]¶ Decompose a
QubitCircuit
in to the control amplitude generating the corresponding evolution. Parameters
 qc: :class:`.QubitCircuit`
Takes the quantum circuit to be implemented.
 Returns
 tlist: array_like
A NumPy array specifies the time of each coefficient
 coeffs: array_like
A 2d NumPy array of the shape (len(ctrls), len(tlist)). Each row corresponds to the control pulse sequence for one Hamiltonian.

optimize_circuit
(qc)[source]¶ Take a quantum circuit/algorithm and convert it into the optimal form/basis for the desired physical system.
 Parameters
 qc: :class:`.QubitCircuit`
Takes the quantum circuit to be implemented.
 Returns
 qc:
QubitCircuit
The circuit representation with elementary gates that can be implemented in this model.
 qc:

plot_pulses
(title=None, figsize=(12, 6), dpi=None, show_axis=False, rescale_pulse_coeffs=True, num_steps=1000)¶ Plot the ideal pulse coefficients.
 Parameters
 title: str, optional
Title for the plot.
 figsize: tuple, optional
The size of the figure.
 dpi: int, optional
The dpi of the figure.
 show_axis: bool, optional
If the axis are shown.
 rescale_pulse_coeffs: bool, optional
Rescale the hight of each pulses.
 num_steps: int, optional
Number of time steps in the plot.
 Returns
 fig: matplotlib.figure.Figure
The Figure object for the plot.
 ax: matplotlib.axes._subplots.AxesSubplot
The axes for the plot.
Notes
plot_pulses
only works for array_like coefficients

pulse_matrix
(dt=0.01)¶ Generates the pulse matrix for the desired physical system.
 Returns
 t, u, labels:
Returns the total time and label for every operation.

read_coeff
(file_name, inctime=True)¶ Read the control amplitudes matrix and time list saved in the file by save_amp.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list in included in the first column.
 Returns
 tlist: array_like
The time list read from the file.
 coeffs: array_like
The pulse matrix read from the file.

remove_pulse
(indices=None, label=None)¶ Remove the control pulse with given indices.
 Parameters
 indices: int or list of int
The indices of the control Hamiltonians to be removed.
 label: str
The label of the pulse

run
(qc=None)¶ Calculate the propagator of the evolution by matrix exponentiation. This method won’t include noise or collpase.
 Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by load_circuit.
 Returns
 U_list: list
The propagator matrix obtained from the physical implementation.

run_analytically
(init_state=None, qc=None)¶ Simulate the state evolution under the given qutip.QubitCircuit with matrice exponentiation. It will calculate the propagator with matrix exponentiation and return a list of
qutip.Qobj
. This method won’t include noise or collpase. Parameters
 qc: :class:`.QubitCircuit`, optional
Takes the quantum circuit to be implemented. If not given, use the quantum circuit saved in the processor by
load_circuit
. init_state: :class:`qutip.Qobj`, optional
The initial state of the qubits in the register.
 Returns
 evo_result:
qutip.Result
An instance of the class
qutip.Result
will be returned.
 evo_result:

run_state
(init_state=None, analytical=False, qc=None, states=None, **kwargs)¶ If analytical is False, use
qutip.mesolve
to calculate the time of the state evolution and return the result. Other arguments of mesolve can be given as keyword arguments. If analytical is True, calculate the propagator with matrix exponentiation and return a list of matrices. Parameters
 init_state: Qobj
Initial density matrix or state vector (ket).
 analytical: boolean
If True, calculate the evolution with matrices exponentiation.
 qc: :class:`.QubitCircuit`, optional
A quantum circuit. If given, it first calls the
load_circuit
and then calculate the evolution. states: :class:`qutip.Qobj`, optional
Old API, same as init_state.
 **kwargs
Keyword arguments for the qutip solver.
 Returns
 evo_result:
qutip.Result
If
analytical
is False, an instance of the classqutip.Result
will be returned.If
analytical
is True, a list of matrices representation is returned.
 evo_result:

save_coeff
(file_name, inctime=True)¶ Save a file with the control amplitudes in each timeslot.
 Parameters
 file_name: string
Name of the file.
 inctime: bool, optional
True if the time list should be included in the first column.

set_all_tlist
(tlist)¶ Set the same tlist for all the pulses.
 Parameters
 tlist: arraylike, optional
A list of time at which the timedependent coefficients are applied. See
Pulse
for detailed information`

set_up_ops
(N)[source]¶ Generate the Hamiltonians for the spinchain model and save them in the attribute ctrls.
 Parameters
 N: int
The number of qubits in the system.

set_up_params
(N, num_levels, deltamax, epsmax, w0, wq, eps, delta, g)[source]¶ Save the parameters in the attribute params and check the validity. The keys of params including “sx”, “sz”, “w0”, “eps”, “delta” and “g”, each mapped to a list for parameters corresponding to each qubits. For coupling strength “g”, list element i is the interaction between qubits i and i+1.
 Parameters
 N: int
The number of qubits in the system.
 num_levels: int
The number of energy levels in the resonator.
 deltamax: list
The coefficients of sigmax for each of the qubits in the system.
 epsmax: list
The coefficients of sigmaz for each of the qubits in the system.
 wo: int
The base frequency of the resonator.
 wq: list
The frequency of the qubits.
 eps: list
The epsilon for each of the qubits in the system.
 delta: list
The delta for each of the qubits in the system.
 g: list
The interaction strength for each of the qubit with the resonator.
Notes
All parameters will be multiplied by 2*pi for simplicity

to_array
(params, N)¶ Transfer a parameter to an array.

class
Noise
[source]¶ The base class representing noise in a processor. The noise object can be added to
Processor
and contributes to evolution.
get_noisy_dynamics
(dims, pulses, systematic_noise)[source]¶ Return a pulses list added with noise and the pulse independent noise in a dummy Pulse object.
 Parameters
 dims: list, optional
The dimension of the components system, the default value is [2,2…,2] for qubits system.
 pulses: list of :class:`.Pulse`
The input pulses, on which the noise object is to be applied.
 systematic_noise: :class:`.Pulse`
The dummy pulse with no ideal control element.
 Returns


class
DecoherenceNoise
(c_ops, targets=None, coeff=None, tlist=None, all_qubits=False)[source]¶ The decoherence noise in a processor. It generates lindblad noise according to the given collapse operator c_ops.
 Parameters
 c_ops: :class:`qutip.Qobj` or list
The Hamiltonian representing the dynamics of the noise.
 targets: int or list, optional
The indices of qubits that are acted on. Default is on all qubits
 coeff: list, optional
A list of the coefficients for the control Hamiltonians.
 tlist: array_like, optional
A NumPy array specifies the time of each coefficient.
 all_qubits: bool, optional
If c_ops contains only single qubits collapse operator,
all_qubits=True
will allow it to be applied to all qubits.
 Attributes
 c_ops: :class:`qutip.Qobj` or list
The Hamiltonian representing the dynamics of the noise.
 targets: int or list
The indices of qubits that are acted on.
 coeff: list
A list of the coefficients for the control Hamiltonians.
 tlist: array_like
A NumPy array specifies the time of each coefficient.
 all_qubits: bool
If c_ops contains only single qubits collapse operator,
all_qubits=True
will allow it to be applied to all qubits.

get_noisy_dynamics
(dims=None, pulses=None, systematic_noise=None)[source]¶ Return a pulses list added with noise and the pulse independent noise in a dummy Pulse object.
 Parameters
 dims: list, optional
The dimension of the components system, the default value is [2,2…,2] for qubits system.
 pulses: list of :class:`.Pulse`
The input pulses, on which the noise object is to be applied.
 systematic_noise: :class:`.Pulse`
The dummy pulse with no ideal control element.
 Returns

class
RelaxationNoise
(t1=None, t2=None, targets=None)[source]¶ The decoherence on each qubit characterized by two time scales t1 and t2.
 Parameters
 t1: float or list, optional
Characterize the decoherence of amplitude damping for each qubit.
 t2: float or list, optional
Characterize the decoherence of dephasing for each qubit.
 targets: int or list, optional
The indices of qubits that are acted on. Default is on all qubits
 Attributes
 t1: float or list
Characterize the decoherence of amplitude damping for each qubit.
 t2: float or list
Characterize the decoherence of dephasing for each qubit.
 targets: int or list
The indices of qubits that are acted on.

get_noisy_dynamics
(dims=None, pulses=None, systematic_noise=None)[source]¶ Return a pulses list added with noise and the pulse independent noise in a dummy Pulse object.
 Parameters
 dims: list, optional
The dimension of the components system, the default value is [2,2…,2] for qubits system.
 pulses: list of :class:`.Pulse`
The input pulses, on which the noise object is to be applied.
 systematic_noise: :class:`.Pulse`
The dummy pulse with no ideal control element.
 Returns

class
ControlAmpNoise
(coeff, tlist=None, indices=None)[source]¶ The noise in the amplitude of the control pulse.
 Parameters
 coeff: list
A list of the coefficients for the control Hamiltonians. For available choices, see
qutip.QobjEvo
. tlist: array_like, optional
A NumPy array specifies the time of each coefficient.
 indices: list of int, optional
The indices of target pulse in the list of pulses.
 Attributes
 ———
 coeff: list
A list of the coefficients for the control Hamiltonians. For available choices, see
qutip.QobjEvo
. tlist: array_like
A NumPy array specifies the time of each coefficient.
 indices: list of int
The indices of target pulse in the list of pulses.

get_noisy_dynamics
(dims=None, pulses=None, systematic_noise=None)[source]¶ Return a pulses list added with noise and the pulse independent noise in a dummy Pulse object.
 Parameters
 dims: list, optional
The dimension of the components system, the default value is [2,2…,2] for qubits system.
 pulses: list of :class:`.Pulse`
The input pulses, on which the noise object is to be applied.
 systematic_noise: :class:`.Pulse`
The dummy pulse with no ideal control element.
 Returns

class
RandomNoise
(dt, rand_gen, indices=None, **kwargs)[source]¶ Random noise in the amplitude of the control pulse. The arguments for the random generator need to be given as key word arguments.
 Parameters
 dt: float, optional
The time interval between two random amplitude. The coefficients of the noise are the same within this time range.
 rand_gen: numpy.random, optional
A random generator in numpy.random, it has to take a
size
parameter as the size of random numbers in the output array. indices: list of int, optional
The indices of target pulse in the list of pulses.
 **kwargs:
Key word arguments for the random number generator.
Examples
>>> gaussnoise = RandomNoise( dt=0.1, rand_gen=np.random.normal, loc=mean, scale=std)
 Attributes
 dt: float, optional
The time interval between two random amplitude. The coefficients of the noise are the same within this time range.
 rand_gen: numpy.random, optional
A random generator in numpy.random, it has to take a
size
parameter. indices: list of int
The indices of target pulse in the list of pulses.
 **kwargs:
Key word arguments for the random number generator.

get_noisy_dynamics
(dims=None, pulses=None, systematic_noise=None)[source]¶ Return a pulses list added with noise and the pulse independent noise in a dummy Pulse object.
 Parameters
 dims: list, optional
The dimension of the components system, the default value is [2,2…,2] for qubits system.
 pulses: list of :class:`.Pulse`
The input pulses, on which the noise object is to be applied.
 systematic_noise: :class:`.Pulse`
The dummy pulse with no ideal control element.
 Returns

class
Pulse
(qobj, targets, tlist=None, coeff=None, spline_kind=None, label='')[source]¶ Representation of a control pulse and the pulse dependent noise. The pulse is characterized by the ideal control pulse, the coherent noise and the lindblad noise. The later two are lists of noisy evolution dynamics. Each dynamic element is characterized by four variables: qobj, targets, tlist and coeff.
See examples for different construction behavior.
 Parameters
 qobj: :class:’qutip.Qobj’
The Hamiltonian of the ideal pulse.
 targets: list
target qubits of the ideal pulse (or subquantum system of other dimensions).
 tlist: arraylike, optional
tlist of the ideal pulse. A list of time at which the timedependent coefficients are applied. tlist does not have to be equidistant, but must have the same length or one element shorter compared to coeff. See documentation for the parameter spline_kind.
 coeff: arraylike or bool, optional
Timedependent coefficients of the ideal control pulse. If an array, the length must be the same or one element longer compared to tlist. See documentation for the parameter spline_kind. If a bool, the coefficient is a constant 1 or 0.
 spline_kind: str, optional
Type of the coefficient interpolation: “step_func” or “cubic”.
“step_func”: The coefficient will be treated as a step function. E.g.
tlist=[0,1,2]
andcoeff=[3,2]
, means that the coefficient is 3 in t=[0,1) and 2 in t=[2,3). It requireslen(coeff)=len(tlist)1
orlen(coeff)=len(tlist)
, but in the second case the last element of coeff has no effect.“cubic”: Use cubic interpolation for the coefficient. It requires
len(coeff)=len(tlist)
 label: str
The label (name) of the pulse.
Examples
Create a pulse that is turned off
>>> Pulse(sigmaz(), 0) >>> Pulse(sigmaz(), 0, None, None)
Create a time dependent pulse
>>> tlist = np.array([0., 1., 2., 4.]) >>> coeff = np.array([0.5, 1.2, 0.8]) >>> spline_kind = "step_func" >>> Pulse(sigmaz(), 0, tlist=tlist, coeff=coeff, spline_kind="step_func")
Create a time independent pulse
>>> Pulse(sigmaz(), 0, coeff=True)
Create a constant pulse with time range
>>> Pulse(sigmaz(), 0, tlist=tlist, coeff=True)
Create an dummy Pulse (H=0)
>>> Pulse(None, None)
 Attributes
 ideal_pulse: :class:`._EvoElement`
The ideal dynamic of the control pulse.
 coherent_noise: list of :class:`._EvoElement`
The coherent noise caused by the control pulse. Each dynamic element is still characterized by a timedependent Hamiltonian.
 lindblad_noise: list of :class:`._EvoElement`
The dissipative noise of the control pulse. Each dynamic element will be treated as a (timedependent) lindblad operator in the master equation.
 spline_kind: str
See parameter spline_kind.
 label: str
See parameter label.

add_coherent_noise
(qobj, targets, tlist=None, coeff=None)[source]¶ Add a new (timedependent) Hamiltonian to the coherent noise.
 Parameters
 qobj: :class:’qutip.Qobj’
The Hamiltonian of the pulse.
 targets: list
target qubits of the pulse (or subquantum system of other dimensions).
 tlist: arraylike, optional
A list of time at which the timedependent coefficients are applied. tlist does not have to be equidistant, but must have the same length or one element shorter compared to coeff. See documentation for the parameter spline_kind of
Pulse
. coeff: arraylike or bool, optional
Timedependent coefficients of the pulse noise. If an array, the length must be the same or one element longer compared to tlist. See documentation for the parameter spline_kind of
Pulse
. If a bool, the coefficient is a constant 1 or 0.

add_lindblad_noise
(qobj, targets, tlist=None, coeff=None)[source]¶ Add a new (timedependent) lindblad noise to the coherent noise.
 Parameters
 qobj: :class:’qutip.Qobj’
The collapse operator of the lindblad noise.
 targets: list
target qubits of the collapse operator (or subquantum system of other dimensions).
 tlist: arraylike, optional
A list of time at which the timedependent coefficients are applied. tlist does not have to be equidistant, but must have the same length or one element shorter compared to coeff. See documentation for the parameter spline_kind of
Pulse
. coeff: arraylike or bool, optional
Timedependent coefficients of the pulse noise. If an array, the length must be the same or one element longer compared to tlist. See documentation for the parameter spline_kind of
Pulse
. If a bool, the coefficient is a constant 1 or 0.

property
coeff
¶ See parameter coeff.

get_full_tlist
(tol=1e10)[source]¶ Return the full tlist of the pulses and noise. It means that if different
tlist
are present, they will be merged to one with all time points stored in a sorted array. Returns
 full_tlist: arraylike 1d
The full time sequence for the noisy evolution.

get_ideal_qobj
(dims)[source]¶ Get the Hamiltonian of the ideal pulse.
 Parameters
 dims: int or list
Dimension of the system. If int, we assume it is the number of qubits in the system. If list, it is the dimension of the component systems.
 Returns
 qobj:
qutip.Qobj
The Hamiltonian of the ideal pulse.
 qobj:

get_ideal_qobjevo
(dims)[source]¶ Get a QobjEvo representation of the ideal evolution.
 Parameters
 dims: int or list
Dimension of the system. If int, we assume it is the number of qubits in the system. If list, it is the dimension of the component systems.
 Returns
 ideal_evo:
qutip.QobjEvo
A QobjEvo representing the ideal evolution.
 ideal_evo:

get_noisy_qobjevo
(dims)[source]¶ Get the
QobjEvo
representation of the noisy evolution. The result can be used directly as input for the qutip solvers. Parameters
 dims: int or list
Dimension of the system. If int, we assume it is the number of qubits in the system. If list, it is the dimension of the component systems.
 Returns
 noisy_evo:
qutip.QobjEvo
A
QobjEvo
representing the ideal evolution and coherent noise. c_ops: list of
qutip.QobjEvo
A list of (timedependent) lindbald operators.
 noisy_evo:

print_info
()[source]¶ Print the information of the pulse, including the ideal dynamics, the coherent noise and the lindblad noise.

property
qobj
¶ See parameter qobj.

property
targets
¶ See parameter targets.

property
tlist
¶ See parameter tlist

class
GateCompiler
(N, params=None, pulse_dict=None)[source]¶ Base class. It compiles a
QubitCircuit
into the pulse sequence for the processor. The core member function compile calls compiling method from the subclass and concatenate the compiled pulses. Parameters
 N: int
The number of the component systems.
 params: dict, optional
A Python dictionary contains the name and the value of the parameters, such as laser frequency, detuning etc. It will be saved in the class attributes and can be used to calculate the control pulses.
 pulse_dict: dict, optional
A map between the pulse label and its index in the pulse list. If given, the compiled pulse can be identified with
(pulse_label, coeff)
, instead of(pulse_index, coeff)
. The number of keyvalue pairs should match the number of pulses in the processor. If it is empty, an integerpulse_index
needs to be used in the compiling routine saved under the attributesgate_compiler
.
 Attributes
 gate_compiler: dict
The Python dictionary in the form of {gate_name: compiler_function}. It saves the compiling routine for each gate. See subclasses for implementation. Note that for continuous pulse, the first coeff should always be 0.
 args: dict
Arguments for individual compiling routines. It adds more flexibility in customizing compiler.

compile
(circuit, schedule_mode=None, args=None)[source]¶ Compile the the native gates into control pulse sequence. It calls each compiling method and concatenates the compiled pulses.
 Parameters
 circuit: :class:`.QubitCircuit` or list of
Gate
A list of elementary gates that can be implemented in the corresponding hardware. The gate names have to be in gate_compiler. schedule_mode: str, optional
"ASAP"
for “as soon as possible” or"ALAP"
for “as late as possible” orFalse
orNone
for no schedule. Default is None. args: dict, optional
A dictionary of arguments used in a specific gate compiler function.
 Returns
 tlist: array_like
A NumPy array specifies the time of each coefficient
 coeffs: array_like
A 2d NumPy array of the shape
(len(ctrls), len(tlist))
. Each row corresponds to the control pulse sequence for one Hamiltonian.

class
CavityQEDCompiler
(N, params, pulse_dict, global_phase=0.0)[source]¶ Decompose a
QubitCircuit
into the pulse sequence for the processor. Parameters
 N: int
The number of qubits in the system.
 params: dict
A Python dictionary contains the name and the value of the parameters. See
DispersiveCavityQED.set_up_params
for the definition. global_phase: float, optional
Record of the global phase change and will be returned.
 pulse_dict: dict, optional
A map between the pulse label and its index in the pulse list. If given, the compiled pulse can be identified with
(pulse_label, coeff)
, instead of(pulse_index, coeff)
. The number of keyvalue pairs should match the number of pulses in the processor. If it is empty, an integerpulse_index
needs to be used in the compiling routine saved under the attributesgate_compiler
.
 Attributes
 N: int
The number of the component systems.
 params: dict
A Python dictionary contains the name and the value of the parameters, such as laser frequency, detuning etc.
 pulse_dict: dict
A map between the pulse label and its index in the pulse list.
 gate_compiler: dict
The Python dictionary in the form of {gate_name: decompose_function}. It saves the decomposition scheme for each gate.

compile
(circuit, schedule_mode=None, args=None)¶ Compile the the native gates into control pulse sequence. It calls each compiling method and concatenates the compiled pulses.
 Parameters
 circuit: :class:`.QubitCircuit` or list of
Gate
A list of elementary gates that can be implemented in the corresponding hardware. The gate names have to be in gate_compiler. schedule_mode: str, optional
"ASAP"
for “as soon as possible” or"ALAP"
for “as late as possible” orFalse
orNone
for no schedule. Default is None. args: dict, optional
A dictionary of arguments used in a specific gate compiler function.
 Returns
 tlist: array_like
A NumPy array specifies the time of each coefficient
 coeffs: array_like
A 2d NumPy array of the shape
(len(ctrls), len(tlist))
. Each row corresponds to the control pulse sequence for one Hamiltonian.

class
SpinChainCompiler
(N, params, pulse_dict, setup='linear', global_phase=0.0)[source]¶ Compile a
QubitCircuit
into the pulse sequence for the processor. Parameters
 N: int
The number of qubits in the system.
 params: dict
A Python dictionary contains the name and the value of the parameters. See
SpinChain.set_up_params
for the definition. setup: string
“linear” or “circular” for two subclasses.
 global_phase: bool
Record of the global phase change and will be returned.
 pulse_dict: dict, optional
A map between the pulse label and its index in the pulse list. If given, the compiled pulse can be identified with
(pulse_label, coeff)
, instead of(pulse_index, coeff)
. The number of keyvalue pairs should match the number of pulses in the processor. If it is empty, an integerpulse_index
needs to be used in the compiling routine saved under the attributesgate_compiler
.
 Attributes
 N: int
The number of the component systems.
 params: dict
A Python dictionary contains the name and the value of the parameters, such as laser frequency, detuning etc.
 pulse_dict: dict
A map between the pulse label and its index in the pulse list.
 gate_compiler: dict
The Python dictionary in the form of {gate_name: decompose_function}. It saves the decomposition scheme for each gate.
 setup: string
“linear” or “circular” for two subclasses.
 global_phase: bool
Record of the global phase change and will be returned.

compile
(circuit, schedule_mode=None, args=None)¶ Compile the the native gates into control pulse sequence. It calls each compiling method and concatenates the compiled pulses.
 Parameters
 circuit: :class:`.QubitCircuit` or list of
Gate
A list of elementary gates that can be implemented in the corresponding hardware. The gate names have to be in gate_compiler. schedule_mode: str, optional
"ASAP"
for “as soon as possible” or"ALAP"
for “as late as possible” orFalse
orNone
for no schedule. Default is None. args: dict, optional
A dictionary of arguments used in a specific gate compiler function.
 Returns
 tlist: array_like
A NumPy array specifies the time of each coefficient
 coeffs: array_like
A 2d NumPy array of the shape
(len(ctrls), len(tlist))
. Each row corresponds to the control pulse sequence for one Hamiltonian.

class
Scheduler
(method='ALAP', constraint_functions=None)[source]¶ A gate (pulse) scheduler for quantum circuits (instructions). It schedules a given circuit or instructions to reduce the total execution time by parallelization. It uses heuristic methods mainly from in https://doi.org/10.1117/12.666419.
The scheduler includes two methods, “ASAP”, as soon as possible, and “ALAP”, as late as possible. The later is commonly used in quantum computation because of the finite lifetime of qubits.
The scheduler aims at pulse schedule and therefore does not consider merging gates to reduce the gates number. It assumes that the input circuit is optimized at the gate level and matches the hardware topology.
 Parameters
 method: str
“ASAP” for as soon as possible. “ALAP” for as late as possible.
 constraint_functions: list, optional
A list of hardware constraint functions. Default includes a function qubit_contraint, i.e. one qubit cannot be used by two gates at the same time.

apply_constraint
(ind1, ind2, instructions)[source]¶ Apply hardware constraint to check if two instructions can be executed in parallel.
 Parameters
 ind1, ind2: int
indices of the two instructions
 instructions: list
The instruction list

commutation_rules
(ind1, ind2, instructions)[source]¶ Determine if two gates commute, given that their used qubits overlap. Since usually the input gates are already in a universal gate sets, it uses an oversimplified condition:
If the two gates do not have the same name, they are considered as not commuting. If they are the same gate and have the same controls or targets, they are considered as commuting. E.g. CNOT 0, 1 commute with CNOT 0, 2.

schedule
(circuit, gates_schedule=False, return_cycles_list=False, random_shuffle=False, repeat_num=0)[source]¶ Schedule a QubitCircuit, a list of Gates or a list of Instruction. For pulse schedule, the execution time for each Instruction is given in its duration attributes.
The scheduler first generates a quantum gates dependency graph, containing information about which gates have to be executed before some other gates. The graph preserves the mobility of the gates, i.e. commuting gates are not dependent on each other, even if they use the same qubits. Next, it computes the longest distance of each node to the start and end nodes. The distance for each dependency arrow is defined by the execution time of the instruction (By default, it is 1 for all gates). This is used as a priority measure in the next step. The gate with a longer distance to the end node and a shorter distance to the start node has higher priority. In the last step, it uses a listschedule algorithm with hardware constraint and priority and returns a list of cycles for gates/instructions.
For pulse schedule, an additional step is required to compute the start time of each instruction. It adds the additional dependency caused by hardware constraint to the graph and recomputes the distance of each node to the start and end node. This distance is then converted to the start time of each instruction.
 Parameters
 circuit: QubitCircuit or list
For gate schedule, it should be a QubitCircuit or a list of Gate objects. For pulse schedule, it should be a list of Instruction objects, each with an attribute duration that indicates the execution time of this instruction.
 gates_schedule: bool, optional
True, if only gates schedule is needed. This saves some computation that is only useful to pulse schedule. If the input circuit is a QubitCircuit, it will be assigned to True automatically. Otherwise, the default is False.
 return_cycles_list: bool, optional
If True, the method returns the cycles_list, e.g. [{0, 2}, {1, 3}], which means that the first cycle contains gates0 and gates2 while the second cycle contains gates1 and gates3. It is only usefull for gates schedule.
 random_shuffle: bool, optional
If the commuting gates are randomly scuffled to explore larger search space.
 repeat_num: int, optional
Repeat the scheduling several times and use the best result. Used together with
random_shuffle=Ture
.
 Returns
 gate_cycle_indices or instruction_start_time: list
The cycle indices for each gate or the start time for each instruction.
Examples
>>> from qutip.qip.circuit import QubitCircuit >>> from qutip.qip.scheduler import Scheduler >>> circuit = QubitCircuit(7) >>> circuit.add_gate("SNOT", 3) # gate0 >>> circuit.add_gate("CZ", 5, 3) # gate1 >>> circuit.add_gate("CZ", 4, 3) # gate2 >>> circuit.add_gate("CZ", 2, 3) # gate3 >>> circuit.add_gate("CZ", 6, 5) # gate4 >>> circuit.add_gate("CZ", 2, 6) # gate5 >>> circuit.add_gate("SWAP", [0, 2]) # gate6 >>> >>> scheduler = Scheduler("ASAP") >>> scheduler.schedule(circuit, gates_schedule=True) [0, 1, 3, 2, 2, 3, 4]
The result list is the cycle indices for each gate. It means that the circuit can be executed in 5 gate cycles:
[gate0, gate1, (gate3, gate4), (gate2, gate5), gate6]
Notice that gate3 and gate4 commute with gate2, therefore, the order is changed to reduce the number of cycles.

class
Instruction
(gate, tlist=None, pulse_info=(), duration=1)[source]¶ The instruction that implements a quantum gate. It contains the control pulse required to implement the gate on a particular hardware model.
 Parameters
 gate: :class:`.Gate`
The quantum gate.
 duration: list, optional
The execution time needed for the instruction.
 tlist: array_like, optional
A list of time at which the timedependent coefficients are applied. See
Pulse
for detailed information` pulse_info: list, optional
A list of tuples, each tuple corresponding to a pair of pulse label and pulse coefficient, in the format (str, array_like). This pulses will implement the desired gate.
 Attributes
 targets: list, optional
The target qubits.
 controls: list, optional
The control qubits.
 used_qubits: set
Union of the control and target qubits.
Optimal control¶

class
Optimizer
(config, dyn, params=None)[source]¶ Base class for all control pulse optimisers. This class should not be instantiated, use its subclasses. This class implements the fidelity, gradient and interation callback functions. All subclass objects must be initialised with a
OptimConfig
instance  various configuration optionsDynamics
instance  describes the dynamics of the (quantum) system to be control optimised
 Attributes
 log_levelinteger
level of messaging output from the logger. Options are attributes of qutip.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN.
 params: Dictionary
The key value pairs are the attribute name and value. Note: attributes are created if they do not exist already, and are overwritten if they do.
 algstring
Algorithm to use in pulse optimisation. Options are:
‘GRAPE’ (default)  GRadient Ascent Pulse Engineering
‘CRAB’  Chopped RAndom Basis
 alg_paramsDictionary
Options that are specific to the pulse optim algorithm
alg
. disp_conv_msgbool
Set true to display a convergence message (for scipy.optimize.minimize methods anyway)
 optim_methodstring
a scipy.optimize.minimize method that will be used to optimise the pulse for minimum fidelity error
 method_paramsDictionary
Options for the optim_method. Note that where there is an equivalent attribute of this instance or the termination_conditions (for example maxiter) it will override an value in these options
 approx_gradbool
If set True then the method will approximate the gradient itself (if it has requirement and facility for this) This will mean that the fid_err_grad_wrapper will not get called Note it should be left False when using the Dynamics to calculate approximate gradients Note it is set True automatically when the alg is CRAB
 amp_lboundfloat or list of floats
lower boundaries for the control amplitudes Can be a scalar value applied to all controls or a list of bounds for each control
 amp_uboundfloat or list of floats
upper boundaries for the control amplitudes Can be a scalar value applied to all controls or a list of bounds for each control
 boundsList of floats
Bounds for the parameters. If not set before the run_optimization call then the list is built automatically based on the amp_lbound and amp_ubound attributes. Setting this attribute directly allows specific bounds to be set for individual parameters. Note: Only some methods use bounds
 dynamicsDynamics (subclass instance)
describes the dynamics of the (quantum) system to be control optimised (see Dynamics classes for details)
 configOptimConfig instance
various configuration options (see OptimConfig for details)
 termination_conditionsTerminationCondition instance
attributes determine when the optimisation will end
 pulse_generatorPulseGen (subclass instance)
(can be) used to create initial pulses not used by the class, but set by pulseoptim.create_pulse_optimizer
 statsStats
attributes of which give performance stats for the optimisation set to None to reduce overhead of calculating stats. Note it is (usually) shared with the Dynamics instance
 dump
dump.OptimDump
Container for data dumped during the optimisation. Can be set by specifying the dumping level or set directly. Note this is mainly intended for user and a development debugging but could be used for status information during a long optimisation.
dumping
stringThe level of data dumping that will occur during the optimisation
 dump_to_filebool
If set True then data will be dumped to file during the optimisation dumping will be set to SUMMARY during init_optim if dump_to_file is True and dumping not set. Default is False
 dump_dirstring
Basically a link to dump.dump_dir. Exists so that it can be set through optim_params. If dump is None then will return None or will set dumping to SUMMARY when setting a path
 iter_summary
OptimIterSummary
Summary of the most recent iteration. Note this is only set if dummping is on

apply_method_params
(params=None)[source]¶ Loops through all the method_params (either passed here or the method_params attribute) If the name matches an attribute of this object or the termination conditions object, then the value of this attribute is set. Otherwise it is assumed to a method_option for the scipy.optimize.minimize function

apply_params
(params=None)[source]¶ Set object attributes based on the dictionary (if any) passed in the instantiation, or passed as a parameter This is called during the instantiation automatically. The key value pairs are the attribute name and value Note: attributes are created if they do not exist already, and are overwritten if they do.

property
dumping
¶ The level of data dumping that will occur during the optimisation
NONE : No processing data dumped (Default)
SUMMARY : A summary at each iteration will be recorded
FULL : All logs will be generated and dumped
CUSTOM : Some customised level of dumping
When first set to CUSTOM this is equivalent to SUMMARY. It is then up to the user to specify which logs are dumped

fid_err_func_wrapper
(*args)[source]¶ Get the fidelity error achieved using the ctrl amplitudes passed in as the first argument.
This is called by generic optimisation algorithm as the func to the minimised. The argument is the current variable values, i.e. control amplitudes, passed as a flat array. Hence these are reshaped as [nTimeslots, n_ctrls] and then used to update the stored ctrl values (if they have changed)
The error is checked against the target, and the optimisation is terminated if the target has been achieved.

fid_err_grad_wrapper
(*args)[source]¶ Get the gradient of the fidelity error with respect to all of the variables, i.e. the ctrl amplidutes in each timeslot
This is called by generic optimisation algorithm as the gradients of func to the minimised wrt the variables. The argument is the current variable values, i.e. control amplitudes, passed as a flat array. Hence these are reshaped as [nTimeslots, n_ctrls] and then used to update the stored ctrl values (if they have changed)
Although the optimisation algorithms have a check within them for function convergence, i.e. local minima, the sum of the squares of the normalised gradient is checked explicitly, and the optimisation is terminated if this is below the min_gradient_norm condition

init_optim
(term_conds)[source]¶ Check optimiser attribute status and passed parameters before running the optimisation. This is called by run_optimization, but could called independently to check the configuration.

iter_step_callback_func
(*args)[source]¶ Check the elapsed wall time for the optimisation run so far. Terminate if this has exceeded the maximum allowed time

run_optimization
(term_conds=None)[source]¶ This default function optimisation method is a wrapper to the scipy.optimize.minimize function.
It will attempt to minimise the fidelity error with respect to some parameters, which are determined by _get_optim_var_vals (see below)
The optimisation end when one of the passed termination conditions has been met, e.g. target achieved, wall time, or function call or iteration count exceeded. Note these conditions include gradient minimum met (local minima) for methods that use a gradient.
The function minimisation method is taken from the optim_method attribute. Note that not all of these methods have been tested. Note that some of these use a gradient and some do not. See the scipy documentation for details. Options specific to the method can be passed setting the method_params attribute.
If the parameter term_conds=None, then the termination_conditions attribute must already be set. It will be overwritten if the parameter is not None
The result is returned in an OptimResult object, which includes the final fidelity, time evolution, reason for termination etc

class
OptimizerBFGS
(config, dyn, params=None)[source]¶ Implements the run_optimization method using the BFGS algorithm

run_optimization
(term_conds=None)[source]¶ Optimise the control pulse amplitudes to minimise the fidelity error using the BFGS (Broyden–Fletcher–Goldfarb–Shanno) algorithm The optimisation end when one of the passed termination conditions has been met, e.g. target achieved, gradient minimum met (local minima), wall time / iteration count exceeded.
Essentially this is wrapper to the: scipy.optimize.fmin_bfgs function
If the parameter term_conds=None, then the termination_conditions attribute must already be set. It will be overwritten if the parameter is not None
The result is returned in an OptimResult object, which includes the final fidelity, time evolution, reason for termination etc


class
OptimizerLBFGSB
(config, dyn, params=None)[source]¶ Implements the run_optimization method using the LBFGSB algorithm
 Attributes
 max_metric_corrinteger
The maximum number of variable metric corrections used to define the limited memory matrix. That is the number of previous gradient values that are used to approximate the Hessian see the scipy.optimize.fmin_l_bfgs_b documentation for description of m argument

init_optim
(term_conds)[source]¶ Check optimiser attribute status and passed parameters before running the optimisation. This is called by run_optimization, but could called independently to check the configuration.

run_optimization
(term_conds=None)[source]¶ Optimise the control pulse amplitudes to minimise the fidelity error using the LBFGSB algorithm, which is the constrained (bounded amplitude values), limited memory, version of the Broyden–Fletcher–Goldfarb–Shanno algorithm.
The optimisation end when one of the passed termination conditions has been met, e.g. target achieved, gradient minimum met (local minima), wall time / iteration count exceeded.
Essentially this is wrapper to the: scipy.optimize.fmin_l_bfgs_b function This in turn is a warpper for well established implementation of the LBFGSB algorithm written in Fortran, which is therefore very fast. See SciPy documentation for credit and details on this function.
If the parameter term_conds=None, then the termination_conditions attribute must already be set. It will be overwritten if the parameter is not None
The result is returned in an OptimResult object, which includes the final fidelity, time evolution, reason for termination etc

class
OptimizerCrab
(config, dyn, params=None)[source]¶ Optimises the pulse using the CRAB algorithm [1]. It uses the scipy.optimize.minimize function with the method specified by the optim_method attribute. See Optimizer.run_optimization for details It minimises the fidelity error function with respect to the CRAB basis function coefficients.
AJGP ToDo: Add citation here

class
OptimizerCrabFmin
(config, dyn, params=None)[source]¶ Optimises the pulse using the CRAB algorithm [1], [2]. It uses the
scipy.optimize.fmin
function which is effectively a wrapper for the NelderMead method. It minimises the fidelity error function with respect to the CRAB basis function coefficients. This is the default Optimizer for CRAB.References
 1
P. Doria, T. Calarco & S. Montangero. Phys. Rev. Lett. 106, 190501 (2011).
 2
T. Caneva, T. Calarco, & S. Montangero. Phys. Rev. A 84, 022326 (2011).

run_optimization
(term_conds=None)[source]¶ This function optimisation method is a wrapper to the scipy.optimize.fmin function.
It will attempt to minimise the fidelity error with respect to some parameters, which are determined by _get_optim_var_vals which in the case of CRAB are the basis function coefficients
The optimisation end when one of the passed termination conditions has been met, e.g. target achieved, wall time, or function call or iteration count exceeded. Specifically to the fmin method, the optimisation will stop when change parameter values is less than xtol or the change in function value is below ftol.
If the parameter term_conds=None, then the termination_conditions attribute must already be set. It will be overwritten if the parameter is not None
The result is returned in an OptimResult object, which includes the final fidelity, time evolution, reason for termination etc

class
OptimIterSummary
[source]¶ A summary of the most recent iteration of the pulse optimisation
 Attributes
 iter_numint
Iteration number of the pulse optimisation
 fid_func_call_numint
Fidelity function call number of the pulse optimisation
 grad_func_call_numint
Gradient function call number of the pulse optimisation
 fid_errfloat
Fidelity error
 grad_normfloat
fidelity gradient (wrt the control parameters) vector norm that is the magnitude of the gradient
 wall_timefloat
Time spent computing the pulse optimisation so far (in seconds of elapsed time)

class
TerminationConditions
[source]¶ Base class for all termination conditions Used to determine when to stop the optimisation algorithm Note different subclasses should be used to match the type of optimisation being used
 Attributes
 fid_err_targfloat
Target fidelity error
 fid_goalfloat
goal fidelity, e.g. 1  self.fid_err_targ It its typical to set this for unitary systems
 max_wall_timefloat
# maximum time for optimisation (seconds)
 min_gradient_normfloat
Minimum normalised gradient after which optimisation will terminate
 max_iterationsinteger
Maximum iterations of the optimisation algorithm
 max_fid_func_callsinteger
Maximum number of calls to the fidelity function during the optimisation algorithm
 accuracy_factorfloat
Determines the accuracy of the result. Typical values for accuracy_factor are: 1e12 for low accuracy; 1e7 for moderate accuracy; 10.0 for extremely high accuracy scipy.optimize.fmin_l_bfgs_b factr argument. Only set for specific methods (fmin_l_bfgs_b) that uses this Otherwise the same thing is passed as method_option ftol (although the scale is different) Hence it is not defined here, but may be set by the user

class
OptimResult
[source]¶ Attributes give the result of the pulse optimisation attempt
 Attributes
 termination_reasonstring
Description of the reason for terminating the optimisation
 fidelityfloat
final (normalised) fidelity that was achieved
 initial_fid_errfloat
fidelity error before optimisation starting
 fid_errfloat
final fidelity error that was achieved
 goal_achievedboolean
True is the fidely error achieved was below the target
 grad_norm_finalfloat
Final value of the sum of the squares of the (normalised) fidelity error gradients
 grad_norm_min_reachedfloat
True if the optimisation terminated due to the minimum value of the gradient being reached
 num_iterinteger
Number of iterations of the optimisation algorithm completed
 max_iter_exceededboolean
True if the iteration limit was reached
 max_fid_func_exceededboolean
True if the fidelity function call limit was reached
 wall_timefloat
time elapsed during the optimisation
 wall_time_limit_exceededboolean
True if the wall time limit was reached
 timearray[num_tslots+1] of float
Time are the start of each timeslot with the final value being the total evolution time
 initial_ampsarray[num_tslots, n_ctrls]
The amplitudes at the start of the optimisation
 final_ampsarray[num_tslots, n_ctrls]
The amplitudes at the end of the optimisation
 evo_full_finalQobj
The evolution operator from t=0 to t=T based on the final amps
 evo_full_initialQobj
The evolution operator from t=0 to t=T based on the initial amps
 statsStats
Object contaning the stats for the run (if any collected)
 optimizerOptimizer
Instance of the Optimizer used to generate the result

class
Dynamics
(optimconfig, params=None)[source]¶ This is a base class only. See subclass descriptions and choose an appropriate one for the application.
Note that initialize_controls must be called before most of the methods can be used. init_timeslots can be called sometimes earlier in order to access timeslot related attributes
This acts as a container for the operators that are used to calculate time evolution of the system under study. That is the dynamics generators (Hamiltonians, Lindbladians etc), the propagators from one timeslot to the next, and the evolution operators. Due to the large number of matrix additions and multiplications, for small systems at least, the optimisation performance is much better using ndarrays to represent these operators. However
 Attributes
 log_levelinteger
level of messaging output from the logger. Options are attributes of qutip.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN
 params: Dictionary
The key value pairs are the attribute name and value Note: attributes are created if they do not exist already, and are overwritten if they do.
 statsStats
Attributes of which give performance stats for the optimisation set to None to reduce overhead of calculating stats. Note it is (usually) shared with the Optimizer object
 tslot_computerTimeslotComputer (subclass instance)
Used to manage when the timeslot dynamics generators, propagators, gradients etc are updated
 prop_computerPropagatorComputer (subclass instance)
Used to compute the propagators and their gradients
 fid_computerFidelityComputer (subclass instance)
Used to computer the fidelity error and the fidelity error gradient.
 memory_optimizationint
Level of memory optimisation. Setting to 0 (default) means that execution speed is prioritized over memory. Setting to 1 means that some memory prioritisation steps will be taken, for instance using Qobj (and hence sparse arrays) as the the internal operator data type, and not caching some operators Potentially further memory saving maybe made with memory_optimization > 1. The options are processed in _set_memory_optimizations, see this for more information. Individual memory saving options can be switched by settting them directly (see below)
 oper_dtypetype
Data type for internal dynamics generators, propagators and time evolution operators. This can be ndarray or Qobj, or (in theory) any other representaion that supports typical matrix methods (e.g. dot) ndarray performs best for smaller quantum systems. Qobj may perform better for larger systems, and will also perform better when (custom) fidelity measures use Qobj methods such as partial trace. See _choose_oper_dtype for how this is chosen when not specified
 cache_phased_dyn_genbool
If True then the dynamics generators will be saved with and without the propagation prefactor (if there is one) Defaults to True when memory_optimization=0, otherwise False
 cache_prop_gradbool
If the True then the propagator gradients (for exact gradients) will be computed when the propagator are computed and cache until the are used by the fidelity computer. If False then the fidelity computer will calculate them as needed. Defaults to True when memory_optimization=0, otherwise False
 cache_dyn_gen_eigenvectors_adj: bool
If True then DynamicsUnitary will cached the adjoint of the Hamiltion eignvector matrix Defaults to True when memory_optimization=0, otherwise False
 sparse_eigen_decomp: bool
If True then DynamicsUnitary will use the sparse eigenvalue decomposition. Defaults to True when memory_optimization<=1, otherwise False
 num_tslotsinteger
Number of timeslots (aka timeslices)
num_ctrls
integercalculate the of controls from the length of the control list
 evo_timefloat
Total time for the evolution
 tauarray[num_tslots] of float
Duration of each timeslot Note that if this is set before initialize_controls is called then num_tslots and evo_time are calculated from tau, otherwise tau is generated from num_tslots and evo_time, that is equal size time slices
 timearray[num_tslots+1] of float
Cumulative time for the evolution, that is the time at the start of each time slice
 drift_dyn_genQobj or list of Qobj
Drift or system dynamics generator (Hamiltonian) Matrix defining the underlying dynamics of the system Can also be a list of Qobj (length num_tslots) for time varying drift dynamics
 ctrl_dyn_genList of Qobj
Control dynamics generator (Hamiltonians) List of matrices defining the control dynamics
 initialQobj
Starting state / gate The matrix giving the initial state / gate, i.e. at time 0 Typically the identity for gate evolution
 targetQobj
Target state / gate: The matrix giving the desired state / gate for the evolution
 ctrl_ampsarray[num_tslots, num_ctrls] of float
Control amplitudes The amplitude (scale factor) for each control in each timeslot
 initial_ctrl_scalingfloat
Scale factor applied to be applied the control amplitudes when they are initialised This is used by the PulseGens rather than in any fucntions in this class
 initial_ctrl_offsetfloat
Linear offset applied to be applied the control amplitudes when they are initialised This is used by the PulseGens rather than in any fucntions in this class
dyn_gen
List of QobjList of combined dynamics generators (Qobj) for each timeslot
prop
list of QobjList of propagators (Qobj) for each timeslot
prop_grad
array[num_tslots, num_ctrls] of QobjArray of propagator gradients (Qobj) for each timeslot, control
fwd_evo
List of QobjList of evolution operators (Qobj) from the initial to the given
onwd_evo
List of QobjList of evolution operators (Qobj) from the initial to the given
onto_evo
List of QobjList of evolution operators (Qobj) from the initial to the given
 evo_currentBoolean
Used to flag that the dynamics used to calculate the evolution operators is current. It is set to False when the amplitudes change
 fact_mat_round_precfloat
Rounding precision used when calculating the factor matrix to determine if two eigenvalues are equivalent Only used when the PropagatorComputer uses diagonalisation
 def_amps_fnamestring
Default name for the output used when save_amps is called
 unitarity_check_levelint
If > 0 then unitarity of the system evolution is checked at at evolution recomputation. level 1 checks all propagators level 2 checks eigen basis as well Default is 0
 unitarity_tol :
Tolerance used in checking if operator is unitary Default is 1e10
 dump
dump.DynamicsDump
Store of historical calculation data. Set to None (Default) for no storing of historical data Use dumping property to set level of data dumping
dumping
stringThe level of data dumping that will occur during the time evolution calculation.
 dump_to_filebool
If set True then data will be dumped to file during the calculations dumping will be set to SUMMARY during init_evo if dump_to_file is True and dumping not set. Default is False
 dump_dirstring
Basically a link to dump.dump_dir. Exists so that it can be set through dyn_params. If dump is None then will return None or will set dumping to SUMMARY when setting a path

apply_params
(params=None)[source]¶ Set object attributes based on the dictionary (if any) passed in the instantiation, or passed as a parameter This is called during the instantiation automatically. The key value pairs are the attribute name and value Note: attributes are created if they do not exist already, and are overwritten if they do.

combine_dyn_gen
(k)[source]¶ Computes the dynamics generator for a given timeslot The is the combined Hamiltion for unitary systems

compute_evolution
()[source]¶ Recalculate the time evolution operators Dynamics generators (e.g. Hamiltonian) and prop (propagators) are calculated as necessary Actual work is completed by the recompute_evolution method of the timeslot computer

property
dumping
¶ The level of data dumping that will occur during the time evolution calculation.
NONE : No processing data dumped (Default)
SUMMARY : A summary of each time evolution will be recorded
FULL : All operators used or created in the calculation dumped
CUSTOM : Some customised level of dumping
When first set to CUSTOM this is equivalent to SUMMARY. It is then up to the user to specify which operators are dumped. WARNING: FULL could consume a lot of memory!

property
dyn_gen
¶ List of combined dynamics generators (Qobj) for each timeslot

property
dyn_gen_phase
¶ Some op that is applied to the dyn_gen before expontiating to get the propagator. See phase_application for how this is applied

property
full_evo
¶ Full evolution  time evolution at final time slot

property
fwd_evo
¶ List of evolution operators (Qobj) from the initial to the given timeslot

get_ctrl_dyn_gen
(j)[source]¶ Get the dynamics generator for the control Not implemented in the base class. Choose a subclass

get_drift_dim
()[source]¶ Returns the size of the matrix that defines the drift dynamics that is assuming the drift is NxN, then this returns N

get_dyn_gen
(k)[source]¶ Get the combined dynamics generator for the timeslot Not implemented in the base class. Choose a subclass

get_num_ctrls
()[source]¶ calculate the of controls from the length of the control list sets the num_ctrls property, which can be used alternatively subsequently

init_timeslots
()[source]¶ Generate the timeslot duration array ‘tau’ based on the evo_time and num_tslots attributes, unless the tau attribute is already set in which case this step in ignored Generate the cumulative time array ‘time’ based on the tau values

initialize_controls
(amps, init_tslots=True)[source]¶ Set the initial control amplitudes and time slices Note this must be called after the configuration is complete before any dynamics can be calculated

property
num_ctrls
¶ calculate the of controls from the length of the control list sets the num_ctrls property, which can be used alternatively subsequently

property
onto_evo
¶ List of evolution operators (Qobj) from the initial to the given timeslot

property
onwd_evo
¶ List of evolution operators (Qobj) from the initial to the given timeslot

property
phase_application
¶ scalar(string), default=’preop’ Determines how the phase is applied to the dynamics generators
‘preop’ : P = expm(phase*dyn_gen)
‘postop’ : P = expm(dyn_gen*phase)
‘custom’ : Customised phase application
The ‘custom’ option assumes that the _apply_phase method has been set to a custom function.
 Type
phase_application

property
prop
¶ List of propagators (Qobj) for each timeslot

property
prop_grad
¶ Array of propagator gradients (Qobj) for each timeslot, control

save_amps
(file_name=None, times=None, amps=None, verbose=False)[source]¶ Save a file with the current control amplitudes in each timeslot The first column in the file will be the start time of the slot
 Parameters
 file_namestring
Name of the file If None given the def_amps_fname attribuite will be used
 timesList type (or string)
List / array of the start times for each slot If None given this will be retrieved through get_amp_times() If ‘exclude’ then times will not be saved in the file, just the amplitudes
 ampsArray[num_tslots, num_ctrls]
Amplitudes to be saved If None given the ctrl_amps attribute will be used
 verboseBoolean
If True then an info message will be logged

class
DynamicsGenMat
(optimconfig, params=None)[source]¶ This sub class can be used for any system where no additional operator is applied to the dynamics generator before calculating the propagator, e.g. classical dynamics, Lindbladian

class
DynamicsUnitary
(optimconfig, params=None)[source]¶ This is the subclass to use for systems with dynamics described by unitary matrices. E.g. closed systems with Hermitian Hamiltonians Note a matrix diagonalisation is used to compute the exponent The eigen decomposition is also used to calculate the propagator gradient. The method is taken from DYNAMO (see file header)
 Attributes
 drift_hamQobj
This is the drift Hamiltonian for unitary dynamics It is mapped to drift_dyn_gen during initialize_controls
 ctrl_hamList of Qobj
These are the control Hamiltonians for unitary dynamics It is mapped to ctrl_dyn_gen during initialize_controls
 HList of Qobj
The combined drift and control Hamiltonians for each timeslot These are the dynamics generators for unitary dynamics. It is mapped to dyn_gen during initialize_controls

check_unitarity
()[source]¶ Checks whether all propagators are unitary For propagators found not to be unitary, the potential underlying causes are investigated.

initialize_controls
(amplitudes, init_tslots=True)[source]¶ Set the initial control amplitudes and time slices Note this must be called after the configuration is complete before any dynamics can be calculated

property
num_ctrls
¶ calculate the of controls from the length of the control list sets the num_ctrls property, which can be used alternatively subsequently

class
DynamicsSymplectic
(optimconfig, params=None)[source]¶ Symplectic systems This is the subclass to use for systems where the dynamics is described by symplectic matrices, e.g. coupled oscillators, quantum optics
 Attributes
 omegaarray[drift_dyn_gen.shape]
matrix used in the calculation of propagators (time evolution) with symplectic systems.

property
dyn_gen_phase
¶ The phasing operator for the symplectic group generators usually refered to as Omega By default this is applied as ‘postop’ dyn_gen*Omega If phase_application is ‘preop’ it is applied as Omega*dyn_gen

class
PropagatorComputer
(dynamics, params=None)[source]¶ Base for all Propagator Computer classes that are used to calculate the propagators, and also the propagator gradient when exact gradient methods are used Note: they must be instantiated with a Dynamics object, that is the container for the data that the functions operate on This base class cannot be used directly. See subclass descriptions and choose the appropriate one for the application
 Attributes
 log_levelinteger
level of messaging output from the logger. Options are attributes of qutip_utils.logging, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN
 grad_exactboolean
indicates whether the computer class instance is capable of computing propagator gradients. It is used to determine whether to create the Dynamics prop_grad array

apply_params
(params=None)[source]¶ Set object attributes based on the dictionary (if any) passed in the instantiation, or passed as a parameter This is called during the instantiation automatically. The key value pairs are the attribute name and value Note: attributes are created if they do not exist already, and are overwritten if they do.

class
PropCompApproxGrad
(dynamics, params=None)[source]¶ This subclass can be used when the propagator is calculated simply by expm of the dynamics generator, i.e. when gradients will be calculated using approximate methods.

class
PropCompDiag
(dynamics, params=None)[source]¶ Coumputes the propagator exponentiation using diagonalisation of of the dynamics generator

class
PropCompFrechet
(dynamics, params=None)[source]¶ Frechet method for calculating the propagator: exponentiating the combined dynamics generator and the propagator gradient. It should work for all systems, e.g. unitary, open, symplectic. There are other
PropagatorComputer
subclasses that may be more efficient.

class
FidelityComputer
(dynamics, params=None)[source]¶ Base class for all Fidelity Computers. This cannot be used directly. See subclass descriptions and choose one appropriate for the application Note: this must be instantiated with a Dynamics object, that is the container for the data that the methods operate on
 Attributes
 log_levelinteger
level of messaging output from the logger. Options are attributes of qutip.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN
 dimensional_normfloat
Normalisation constant
 fid_norm_funcfunction
Used to normalise the fidelity See SU and PSU options for the unitary dynamics
 grad_norm_funcfunction
Used to normalise the fidelity gradient See SU and PSU options for the unitary dynamics
 uses_onwd_evoboolean
flag to specify whether the onwd_evo evolution operator (see Dynamics) is used by the FidelityComputer
 uses_onto_evoboolean
 flag to specify whether the onto_evo evolution operator
(see Dynamics) is used by the FidelityComputer
 fid_errfloat
Last computed value of the fidelity error
 fidelityfloat
Last computed value of the normalised fidelity
 fidelity_currentboolean
flag to specify whether the fidelity / fid_err are based on the current amplitude values. Set False when amplitudes change
 fid_err_grad: array[num_tslot, num_ctrls] of float
Last computed values for the fidelity error gradients wrt the control in the timeslot
 grad_normfloat
Last computed value for the norm of the fidelity error gradients (sqrt of the sum of the squares)
 fid_err_grad_currentboolean
flag to specify whether the fidelity / fid_err are based on the current amplitude values. Set False when amplitudes change

apply_params
(params=None)[source]¶ Set object attributes based on the dictionary (if any) passed in the instantiation, or passed as a parameter This is called during the instantiation automatically. The key value pairs are the attribute name and value Note: attributes are created if they do not exist already, and are overwritten if they do.

class
FidCompUnitary
(dynamics, params=None)[source]¶ Computes fidelity error and gradient assuming unitary dynamics, e.g. closed qubit systems Note fidelity and gradient calculations were taken from DYNAMO (see file header)
 Attributes
 phase_optionstring
 determines how global phase is treated in fidelity calculations:
PSU  global phase ignored SU  global phase included
 fidelity_prenormcomplex
Last computed value of the fidelity before it is normalised It is stored to use in the gradient normalisation calculation
 fidelity_prenorm_currentboolean
flag to specify whether fidelity_prenorm are based on the current amplitude values. Set False when amplitudes change

compute_fid_grad
()[source]¶ Calculates exact gradient of function wrt to each timeslot control amplitudes. Note these gradients are not normalised These are returned as a (nTimeslots x n_ctrls) array

get_fid_err_gradient
()[source]¶ Returns the normalised gradient of the fidelity error in a (nTimeslots x n_ctrls) array The gradients are cached in case they are requested mutliple times between control updates (although this is not typically found to happen)

get_fidelity
()[source]¶ Gets the appropriately normalised fidelity value The normalisation is determined by the fid_norm_func pointer which should be set in the config

get_fidelity_prenorm
()[source]¶ Gets the current fidelity value prior to normalisation Note the gradient function uses this value The value is cached, because it is used in the gradient calculation

init_normalization
()[source]¶ Calc norm of <Ufinal  Ufinal> to scale subsequent norms When considering unitary time evolution operators, this basically results in calculating the trace of the identity matrix and is hence equal to the size of the target matrix There may be situations where this is not the case, and hence it is not assumed to be so. The normalisation function called should be set to either the PSU  global phase ignored SU  global phase respected

normalize_gradient_PSU
(grad)[source]¶ Normalise the gradient matrix passed as grad This PSU version is independent of global phase

class
FidCompTraceDiff
(dynamics, params=None)[source]¶ Computes fidelity error and gradient for general system dynamics by calculating the the fidelity error as the trace of the overlap of the difference between the target and evolution resulting from the pulses with the transpose of the same. This should provide a distance measure for dynamics described by matrices Note the gradient calculation is taken from: ‘Robust quantum gates for open systems via optimal control: Markovian versus nonMarkovian dynamics’ Frederik F Floether, Pierre de Fouquieres, and Sophie G Schirmer
 Attributes
 scale_factorfloat
The fidelity error calculated is of some arbitary scale. This factor can be used to scale the fidelity error such that it may represent some physical measure If None is given then it is caculated as 1/2N, where N is the dimension of the drift, when the Dynamics are initialised.

compute_fid_err_grad
()[source]¶ Calculate exact gradient of the fidelity error function wrt to each timeslot control amplitudes. Uses the trace difference norm fidelity These are returned as a (nTimeslots x n_ctrls) array

get_fid_err_gradient
()[source]¶ Returns the normalised gradient of the fidelity error in a (nTimeslots x n_ctrls) array The gradients are cached in case they are requested mutliple times between control updates (although this is not typically found to happen)

class
FidCompTraceDiffApprox
(dynamics, params=None)[source]¶ As FidCompTraceDiff, except uses the finite difference method to compute approximate gradients
 Attributes
 epsilonfloat
control amplitude offset to use when approximating the gradient wrt a timeslot control amplitude

class
TimeslotComputer
(dynamics, params=None)[source]¶ Base class for all Timeslot Computers Note: this must be instantiated with a Dynamics object, that is the container for the data that the methods operate on
 Attributes
 log_levelinteger
level of messaging output from the logger. Options are attributes of qutip.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN
 evo_comp_summaryEvoCompSummary
A summary of the most recent evolution computation Used in the stats and dump Will be set to None if neither stats or dump are set

apply_params
(params=None)[source]¶ Set object attributes based on the dictionary (if any) passed in the instantiation, or passed as a parameter This is called during the instantiation automatically. The key value pairs are the attribute name and value Note: attributes are created if they do not exist already, and are overwritten if they do.

class
TSlotCompUpdateAll
(dynamics, params=None)[source]¶ Timeslot Computer  Update All Updates all dynamics generators, propagators and evolutions when ctrl amplitudes are updated

compare_amps
(new_amps)[source]¶ Determine if any amplitudes have changed. If so, then mark the timeslots as needing recalculation Returns: True if amplitudes are the same, False if they have changed


class
PulseGen
(dyn=None, params=None)[source]¶ Pulse generator Base class for all Pulse generators The object can optionally be instantiated with a Dynamics object, in which case the timeslots and amplitude scaling and offset are copied from that. Otherwise the class can be used independently by setting: tau (array of timeslot durations) or num_tslots and pulse_time for equally spaced timeslots
 Attributes
 num_tslotsinteger
Number of timeslots, aka timeslices (copied from Dynamics if given)
 pulse_timefloat
total duration of the pulse (copied from Dynamics.evo_time if given)
 scalingfloat
linear scaling applied to the pulse (copied from Dynamics.initial_ctrl_scaling if given)
 offsetfloat
linear offset applied to the pulse (copied from Dynamics.initial_ctrl_offset if given)
 tauarray[num_tslots] of float
Duration of each timeslot (copied from Dynamics if given)
 lboundfloat
Lower boundary for the pulse amplitudes Note that the scaling and offset attributes can be used to fully bound the pulse for all generators except some of the random ones This bound (if set) may result in additional shifting / scaling Default is Inf
 uboundfloat
Upper boundary for the pulse amplitudes Note that the scaling and offset attributes can be used to fully bound the pulse for all generators except some of the random ones This bound (if set) may result in additional shifting / scaling Default is Inf
 periodicboolean
True if the pulse generator produces periodic pulses
 randomboolean
True if the pulse generator produces random pulses
 log_levelinteger
level of messaging output from the logger. Options are attributes of qutip.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN

apply_params
(params=None)[source]¶ Set object attributes based on the dictionary (if any) passed in the instantiation, or passed as a parameter This is called during the instantiation automatically. The key value pairs are the attribute name and value

class
PulseGenRandom
(dyn=None, params=None)[source]¶ Generates random pulses as simply random values for each timeslot

class
PulseGenLinear
(dyn=None, params=None)[source]¶ Generates linear pulses
 Attributes
 gradientfloat
Gradient of the line. Note this is calculated from the start_val and end_val if these are given
 start_valfloat
Start point of the line. That is the starting amplitude
 end_valfloat
End point of the line. That is the amplitude at the start of the last timeslot

gen_pulse
(gradient=None, start_val=None, end_val=None)[source]¶ Generate a linear pulse using either the gradient and start value or using the end point to calulate the gradient Note that the scaling and offset parameters are still applied, so unless these values are the default 1.0 and 0.0, then the actual gradient etc will be different Returns the pulse as an array of vales for each timeslot

class
PulseGenPeriodic
(dyn=None, params=None)[source]¶ Intermediate class for all periodic pulse generators All of the periodic pulses range from 1 to 1 All have a start phase that can be set between 0 and 2pi
 Attributes
 num_wavesfloat
Number of complete waves (cycles) that occur in the pulse. wavelen and freq calculated from this if it is given
 wavelenfloat
Wavelength of the pulse (assuming the speed is 1) freq is calculated from this if it is given
 freqfloat
Frequency of the pulse
 start_phasefloat
Phase of the pulse signal when t=0

init_pulse
(num_waves=None, wavelen=None, freq=None, start_phase=None)[source]¶ Calculate the wavelength, frequency, number of waves etc from the each other and the other parameters If num_waves is given then the other parameters are worked from this Otherwise if the wavelength is given then it is the driver Otherwise the frequency is used to calculate wavelength and num_waves

class
PulseGenSine
(dyn=None, params=None)[source]¶ Generates sine wave pulses

gen_pulse
(num_waves=None, wavelen=None, freq=None, start_phase=None)[source]¶ Generate a sine wave pulse If no params are provided then the class object attributes are used. If they are provided, then these will reinitialise the object attribs. returns the pulse as an array of vales for each timeslot


class
PulseGenGaussian
(dyn=None, params=None)[source]¶ Generates pulses with a Gaussian profile

gen_pulse
(mean=None, variance=None)[source]¶ Generate a pulse with Gaussian shape. The peak is centre around the mean and the variance determines the breadth The scaling and offset attributes are applied as an amplitude and fixed linear offset. Note that the maximum amplitude will be scaling + offset.


class
PulseGenGaussianEdge
(dyn=None, params=None)[source]¶ Generate pulses with inverted Gaussian ramping in and out It’s intended use for a ramping modulation, which is often required in experimental setups.
 Attributes
 decay_timefloat
Determines the ramping rate. It is approximately the time required to bring the pulse to full amplitude It is set to 1/10 of the pulse time by default

class
PulseGenCrab
(dyn=None, num_coeffs=None, params=None)[source]¶ Base class for all CRAB pulse generators Note these are more involved in the optimisation process as they are used to produce piecewise control amplitudes each time new optimisation parameters are tried
 Attributes
 num_coeffsinteger
Number of coefficients used for each basis function
 num_basis_funcsinteger
Number of basis functions In this case set at 2 and should not be changed
 coeffsfloat array[num_coeffs, num_basis_funcs]
The basis coefficient values
 randomize_coeffsbool
If True (default) then the coefficients are set to some random values when initialised, otherwise they will all be equal to self.scaling

estimate_num_coeffs
(dim)[source]¶ Estimate the number coefficients based on the dimensionality of the system. :returns: num_coeffs – estimated number of coefficients :rtype: int

get_optim_var_vals
()[source]¶ Get the parameter values to be optimised :returns: :rtype: list (or 1d array) of floats

class
PulseGenCrabFourier
(dyn=None, num_coeffs=None, params=None)[source]¶ Generates a pulse using the Fourier basis functions, i.e. sin and cos
 Attributes
 freqsfloat array[num_coeffs]
Frequencies for the basis functions
 randomize_freqsbool
If True (default) the some random offset is applied to the frequencies

gen_pulse
(coeffs=None)[source]¶ Generate a pulse using the Fourier basis with the freqs and coeffs attributes.
 Parameters
 coeffsfloat array[num_coeffs, num_basis_funcs]
The basis coefficient values If given this overides the default and sets the attribute of the same name.

class
Stats
[source]¶ Base class for all optimisation statistics Used for configurations where all timeslots are updated each iteration e.g. exact gradients Note that all times are generated using timeit.default_timer() and are in seconds
 Attributes
 dyn_gen_namestring
Text used in some report functions. Makes sense to set it to ‘Hamiltonian’ when using unitary dynamics Default is simply ‘dynamics generator’
 num_iterinteger
Number of iterations of the optimisation algorithm
 wall_time_optim_startfloat
Start time for the optimisation
 wall_time_optim_endfloat
End time for the optimisation
 wall_time_optimfloat
Time elasped during the optimisation
 wall_time_dyn_gen_computefloat
Total wall (elasped) time computing combined dynamics generator (for example combining drift and control Hamiltonians)
 wall_time_prop_computefloat
Total wall (elasped) time computing propagators, that is the time evolution from one timeslot to the next Includes calculating the propagator gradient for exact gradients
 wall_time_fwd_prop_computefloat
Total wall (elasped) time computing combined forward propagation, that is the time evolution from the start to a specific timeslot. Excludes calculating the propagators themselves
 wall_time_onwd_prop_computefloat
Total wall (elasped) time computing combined onward propagation, that is the time evolution from a specific timeslot to the end time. Excludes calculating the propagators themselves
 wall_time_gradient_computefloat
Total wall (elasped) time computing the fidelity error gradient. Excludes calculating the propagator gradients (in exact gradient methods)
 num_fidelity_func_callsinteger
Number of calls to fidelity function by the optimisation algorithm
 num_grad_func_callsinteger
Number of calls to gradient function by the optimisation algorithm
 num_tslot_recomputeinteger
Number of time the timeslot evolution is recomputed (It is only computed if any amplitudes changed since the last call)
 num_fidelity_computesinteger
Number of time the fidelity is computed (It is only computed if any amplitudes changed since the last call)
 num_grad_computesinteger
Number of time the gradient is computed (It is only computed if any amplitudes changed since the last call)
 num_ctrl_amp_updatesinteger
Number of times the control amplitudes are updated
 mean_num_ctrl_amp_updates_per_iterfloat
Mean number of control amplitude updates per iteration
 num_timeslot_changesinteger
Number of times the amplitudes of a any control in a timeslot changes
 mean_num_timeslot_changes_per_updatefloat
Mean average number of timeslot amplitudes that are changed per update
 num_ctrl_amp_changesinteger
Number of times individual control amplitudes that are changed
 mean_num_ctrl_amp_changes_per_updatefloat
Mean average number of control amplitudes that are changed per update

class
Dump
[source]¶ A container for dump items. The lists for dump items is depends on the type Note: abstract class
 Attributes
 parentsome control object (Dynamics or Optimizer)
aka the host. Object that generates the data that is dumped and is host to this dump object.
 dump_dirstr
directory where files (if any) will be written out the path and be relative or absolute use ~/ to specify user home directory Note: files are only written when write_to_file is True of writeout is called explicitly Defaults to ~/.qtrl_dump
level
stringThe level of data dumping that will occur.
 write_to_filebool
When set True data and summaries (as configured) will be written interactively to file during the processing Set during instantiation by the host based on its dump_to_file attrib
 dump_file_extstr
Default file extension for any file names that are auto generated
 fname_basestr
First part of any auto generated file names. This is usually overridden in the subclass
 dump_summarybool
If True a summary is recorded each time a new item is added to the the dump. Default is True
 summary_sepstr
delimiter for the summary file. default is a space
 data_sepstr
delimiter for the data files (arrays saved to file). default is a space
 summary_filestr
File path for summary file. Automatically generated. Can be set specifically

property
level
¶ The level of data dumping that will occur.
 SUMMARY
A summary will be recorded
 FULL
All possible dumping
 CUSTOM
Some customised level of dumping
When first set to CUSTOM this is equivalent to SUMMARY. It is then up to the user to specify what specifically is dumped

class
OptimDump
(optim, level='SUMMARY')[source]¶ A container for dumps of optimisation data generated during the pulse optimisation.
 Attributes
 dump_summarybool
When True summary items are appended to the iter_summary
 iter_summarylist of
optimizer.OptimIterSummary
Summary at each iteration
 dump_fid_errbool
When True values are appended to the fid_err_log
 fid_err_loglist of float
Fidelity error at each call of the fid_err_func
 dump_grad_normbool
When True values are appended to the fid_err_log
 grad_norm_loglist of float
Gradient norm at each call of the grad_norm_log
 dump_gradbool
When True values are appended to the grad_log
 grad_loglist of ndarray
Gradients at each call of the fid_grad_func

property
dump_all
¶ True if everything (ignoring the summary) is to be dumped

property
dump_any
¶ True if anything other than the summary is to be dumped

writeout
(f=None)[source]¶ write all the logs and the summary out to file(s)
 Parameters
 ffilename or filehandle
If specified then all summary and object data will go in one file. If None is specified then type specific files will be generated in the dump_dir If a filehandle is specified then it must be a byte mode file as numpy.savetxt is used, and requires this.

class
DynamicsDump
(dynamics, level='SUMMARY')[source]¶ A container for dumps of dynamics data. Mainly time evolution calculations.
 Attributes
 dump_summarybool
If True a summary is recorded
 evo_summarylist of
tslotcomp.EvoCompSummary
Summary items are appended if dump_summary is True at each recomputation of the evolution.
 dump_ampsbool
If True control amplitudes are dumped
 dump_dyn_genbool
If True the dynamics generators (Hamiltonians) are dumped
 dump_propbool
If True propagators are dumped
 dump_prop_gradbool
If True propagator gradients are dumped
 dump_fwd_evobool
If True forward evolution operators are dumped
 dump_onwd_evobool
If True onward evolution operators are dumped
 dump_onto_evobool
If True onto (or backward) evolution operators are dumped
 evo_dumpslist of
EvoCompDumpItem
A new dump item is appended at each recomputation of the evolution. That is if any of the calculation objects are to be dumped.

property
dump_all
¶ True if all of the calculation objects are to be dumped

property
dump_any
¶ True if any of the calculation objects are to be dumped

writeout
(f=None)[source]¶ Write all the dump items and the summary out to file(s).
 Parameters
 ffilename or filehandle
If specified then all summary and object data will go in one file. If None is specified then type specific files will be generated in the dump_dir. If a filehandle is specified then it must be a byte mode file as numpy.savetxt is used, and requires this.

class
EvoCompDumpItem
(dump)[source]¶ A copy of all objects generated to calculate one time evolution. Note the attributes are only set if the corresponding
DynamicsDump
dump_*
attribute is set.
writeout
(f=None)[source]¶ write all the objects out to files
 Parameters
 ffilename or filehandle
If specified then all object data will go in one file. If None is specified then type specific files will be generated in the dump_dir If a filehandle is specified then it must be a byte mode file as numpy.savetxt is used, and requires this.
