Classes

Qobj

class Qobj(arg=None, dims=None, type=None, copy=True, superrep=None, isherm=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 C-number), as well as a collection of common operator/state operations. The Qobj constructor optionally takes a dimension list and/or shape list as arguments.

Parameters:

inpt: array_like: Data for vector/matrix representation of the quantum object.
dims: list: Dimensions of object used for tensor products.
type: {‘bra’, ‘ket’, ‘oper’, ‘operator-ket’, ‘operator-bra’, ‘super’}: The type of quantum object to be represented.
shape: list: Shape of underlying data structure (matrix shape).
copy: bool: Flag specifying whether Qobj should get a copy of the input data, or use the original.

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’, ‘operator-ket’, ‘operator-bra’, 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=1e-12)	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.

conj()[source]: Get the element-wise conjugation of the quantum object.

contract(inplace=False)[source]

Contract subspaces of the tensor structure which are 1D. Not defined on superoperators. If all dimensions are scalar, a Qobj of dimension [[1], [1]] is returned, i.e. _multiple_ scalar dimensions are contracted, but one is left.

Parameters:

inplace: bool, optional: If True, modify the dimensions in place. If False, return a copied object.

Returns:

out: Qobj: Quantum object with dimensions contracted. Will be self if inplace is True.

copy()[source]: Create identical copy

cosm()[source]

Cosine of a quantum operator.

Operator must be square.

Returns:

operqutip.Qobj: Matrix cosine of operator.

Raises:

TypeError: Quantum object is not square.

Notes

Uses the Q.expm() method.

dag()[source]: Get the Hermitian adjoint of the quantum object.

data_as(format=None, copy=True)[source]

Matrix from quantum object.

Parameters:

formatstr, default: None: Type of the output, “ndarray” for Dense, “csr_matrix” for CSR. A ValueError will be raised if the format is not supported.
copybool {False, True}: Whether to return a copy

Returns:

datanumpy.ndarray, scipy.sparse.matrix_csr, etc.: Matrix in the type of the underlying libraries.

diag()[source]

Diagonal elements of quantum object.

Returns:

diagsarray: Returns array of real values if operators is Hermitian, otherwise complex values are returned.

dnorm(B=None)[source]

Calculates the diamond norm, or the diamond distance to another operator.

Parameters:

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

Returns:

dfloat: Either the diamond norm of this operator, or the diamond distance from this operator to B.

dual_chan()[source]: Dual channel of quantum object representing a completely positive map.

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.

expm(dtype=<class 'qutip.core.data.dense.Dense'>)[source]

Matrix exponential of quantum operator.

Input operator must be square.

Parameters:

dtypetype: The data-layer type that should be output. As the matrix exponential is almost dense, this defaults to outputting dense matrices.

Returns:

operqutip.Qobj: Exponentiated quantum operator.

Raises:

TypeError: Quantum operator is not square.

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.
eigvecqutip.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:

operqutip.Qobj: Matrix inverse of operator.

Raises:

TypeError: Quantum object is not square.

logm()[source]

Matrix logarithm of quantum operator.

Input operator must be square.

Returns:

operqutip.Qobj: Logarithm of the quantum operator.

Raises:

TypeError: Quantum operator 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:

braqutip.Qobj: Quantum object of type ‘bra’ or ‘ket’
ketqutip.Qobj: Quantum object of type ‘ket’.

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, kwargs=None)[source]

Norm of a quantum object.

Default norm is L2-norm for kets and trace-norm for operators. Other ket and operator norms may be specified using the norm parameter.

Parameters:

normstr: Which type of norm to use. Allowed values for vectors are ‘l2’ and ‘max’. Allowed values for matrices are ‘tr’ for the trace norm, ‘fro’ for the Frobenius norm, ‘one’ and ‘max’.
kwargsdict: Additional keyword arguments to pass on to the relevant norm solver. See details for each norm function in data.norm.

Returns:

normfloat: The requested norm of the operator or state quantum object.

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 Hilbert-Schmidt overlap when one of the Qobj is an operator/density matrix.

Parameters:

otherqutip.Qobj: Quantum object for a state vector of type ‘ket’, ‘bra’ or density matrix.

Returns:

overlapcomplex: Complex valued overlap.

Raises:

TypeError: Can only calculate overlap between a bra, ket and density matrix quantum objects.

permute(order)[source]

Permute the tensor structure of a quantum object. For example, qutip.tensor(x, y).permute([1, 0]) will give the same result as qutip.tensor(y, x) and qutip.tensor(a, b, c).permute([1, 2, 0]) will be the same as qutip.tensor(b, c, a)

For regular objects (bras, kets and operators) we expect order to be a flat list of integers, which specifies the new order of the tensor product.

For superoperators, we expect order to be something like [[0, 2], [1, 3]] which tells us to permute according to [0, 2, 1, 3], and then group indices according to the length of each sublist. As another example, permuting a superoperator with dimensions of [[[1, 2, 3], [1, 2, 3]], [[1, 2, 3], [1, 2, 3]]] by an order [[0, 3], [1, 4], [2, 5]] should give a new object with dimensions [[[1, 1], [2, 2], [3, 3]], [[1, 1], [2, 2], [3, 3]]].

Parameters:

orderlist: List of indices specifying the new tensor order.

Returns:

Pqutip.Qobj: Permuted quantum object.

proj()[source]

Form the projector from a given ket or bra vector.

Parameters:

Qqutip.Qobj: Input bra or ket vector

Returns:

Pqutip.Qobj: Projection operator.

ptrace(sel, dtype=None)[source]

Take the partial trace of the quantum object leaving the selected subspaces. In other words, trace out all subspaces which are _not_ passed.

This is typically a function which acts on operators; bras and kets will be promoted to density matrices before the operation takes place since the partial trace is inherently undefined on pure states.

For operators which are currently being represented as states in the superoperator formalism (i.e. the object has type operator-ket or operator-bra), the partial trace is applied as if the operator were in the conventional form. This means that for any operator x, operator_to_vector(x).ptrace(0) == operator_to_vector(x.ptrace(0)) and similar for operator-bra.

The story is different for full superoperators. In the formalism that QuTiP uses, if an operator has dimensions (dims) of [[2, 3], [2, 3]] then it can be represented as a state on a Hilbert space of dimensions [2, 3, 2, 3], and a superoperator would be an operator which acts on this joint space. This function performs the partial trace on superoperators by letting the selected components refer to elements of the _joint_ _space_, and then returns a regular operator (of type oper).

Parameters:

selint or iterable of int: An int or list of components to keep after partial trace. The selected subspaces will _not_ be reordered, no matter order they are supplied to ptrace.

Returns:

operqutip.Qobj: Quantum object representing partial trace with selected components remaining.

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:

operqutip.Qobj: Matrix sine of operator.

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:

operqutip.Qobj: Matrix square root of operator.

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=None)[source]

Removes small elements from the quantum object.

Parameters:

atolfloat: Absolute tolerance used by tidyup. Default is set via qutip global settings parameters.

Returns:

operqutip.Qobj: Quantum object with small elements removed.

to(data_type)[source]

Convert the underlying data store of this Qobj into a different storage representation.

The different storage representations available are the “data-layer types” which are known to qutip.data.to. By default, these are qutip.data.Dense and qutip.data.CSR, which respectively construct a dense matrix store and a compressed sparse row one. Certain algorithms and operations may be faster or more accurate when using a more appropriate data store.

If the data store is already in the format requested, the function returns self. Otherwise, it returns a copy of itself with the data store in the new type.

Parameters:

data_typetype: The data-layer type that the data of this Qobj should be converted to.

Returns:

Qobj: A new Qobj if a type conversion took place with the data stored in the requested format, or self if not.

tr()[source]

Trace of a quantum object.

Returns:

tracefloat: Returns the trace of the quantum object.

trans()[source]

Get the matrix transpose of the quantum operator.

Returns:

operQobj: Transpose of input operator.

transform(inpt, inverse=False)[source]

Basis transform defined by input array.

Input array can be a matrix defining the transformation, or a list of kets that defines the new basis.

Parameters:

inptarray_like: A matrix or list of kets defining the transformation.
inversebool: Whether to return inverse transformation.

Returns:

operqutip.Qobj: Operator in new basis.

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 2-norm.

Returns:

operqutip.Qobj: A valid density operator.

unit(inplace=False, norm=None, kwargs=None)[source]

Operator or state normalized to unity. Uses norm from Qobj.norm().

Parameters:

inplacebool: Do an in-place normalization
normstr: Requested norm for states / operators.
kwargsdict: Additional key-word arguments to be passed on to the relevant norm function (see norm for more details).

Returns:

objqutip.Qobj: Normalized quantum object. Will be the self object if in place.

QobjEvo

class QobjEvo

A class for representing time-dependent quantum objects, such as quantum operators and states.

Importantly, QobjEvo instances are used to represent such time-dependent quantum objects when working with QuTiP solvers.

A QobjEvo instance may be constructed from one of the following:

a callable f(t: double, args: dict) -> Qobj that returns the value of the quantum object at time t.

a [Qobj, Coefficient] pair, where Coefficient may also be any item that can be used to construct a coefficient (e.g. a function, a numpy array of coefficient values, a string expression).

a Qobj (which creates a constant QobjEvo term).

a list of such callables, pairs or Qobjs.

a QobjEvo (in which case a copy is created, all other arguments are ignored except args which, if passed, replaces the existing arguments).

Parameters:

Q_objectcallable, list or Qobj

A specification of the time-depedent quantum object. See the paragraph above for a full description and the examples section below for examples.

argsdict, optional

A dictionary that contains the arguments for the coefficients. Arguments may be omitted if no function or string coefficients that require arguments are present.

tlistarray-like, optional

A list of times corresponding to the values of the coefficients supplied as numpy arrays. If no coefficients are supplied as numpy arrays, tlist may be omitted, otherwise it is required.

The times in tlist do not need to be equidistant, but must be sorted.

By default, a cubic spline interpolation will be used to interpolate the value of the (numpy array) coefficients at time t. If the coefficients are to be treated as step functions, pass the argument order=0 (see below).

orderint, default=3

Order of the spline interpolation that is to be used to interpolate the value of the (numpy array) coefficients at time t. 0 use previous or left value.

copybool, default=True

Whether to make a copy of the Qobj instances supplied in the Q_object parameter.

compressbool, default=True

Whether to compress the QobjEvo instance terms after the instance has been created.

This sums the constant terms in a single term and combines [Qobj, coefficient] pairs with the same Qobj into a single pair containing the sum of the coefficients.

See compress.

function_style{None, “pythonic”, “dict”, “auto”}

The style of function signature used by callables in Q_object. If style is None, the value of qutip.settings.core["function_coefficient_style"] is used. Otherwise the supplied value overrides the global setting.

boundary_conditions2-Tuple, str or None, optional

Boundary conditions for spline evaluation. Default value is None. Correspond to bc_type of scipy.interpolate.make_interp_spline. Refer to Scipy’s documentation for further details: https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.make_interp_spline.html

Examples

A QobjEvo constructed from a function:

def f(t, args):
    return qutip.qeye(N) * np.exp(args['w'] * t)

QobjEvo(f, args={'w': 1j})

For list based QobjEvo, the list must consist of :obj`~Qobj` or [Qobj, Coefficient] pairs:

QobjEvo([H0, [H1, coeff1], [H2, coeff2]], args=args)

The coefficients may be specified either using a Coefficient object or by a function, string, numpy array or any object that can be passed to the coefficient function. See the documentation of coefficient for a full description.

An example of a coefficient specified by a function:

def f1_t(t, args):
    return np.exp(-1j * t * args["w1"])

QobjEvo([[H1, f1_t]], args={"w1": 1.})

And of coefficients specified by string expressions:

H = QobjEvo(
    [H0, [H1, 'exp(-1j*w1*t)'], [H2, 'cos(w2*t)']],
    args={"w1": 1., "w2": 2.}
)

Coefficients maybe also be expressed as numpy arrays giving a list of the coefficient values:

tlist = np.logspace(-5, 0, 100)
H = QobjEvo(
    [H0, [H1, np.exp(-1j * tlist)], [H2, np.cos(2. * tlist)]],
    tlist=tlist
)

The coeffients array must have the same len as the tlist.

A QobjEvo may also be built using simple arithmetic operations combining Qobj with Coefficient, for example:

coeff = qutip.coefficient("exp(-1j*w1*t)", args={"w1": 1})
qevo = H0 + H1 * coeff

Attributes:

dimslist: List of dimensions keeping track of the tensor structure.
shape(int, int): List of dimensions keeping track of the tensor structure.
typestr: Type of quantum object: ‘bra’, ‘ket’, ‘oper’, ‘operator-ket’, ‘operator-bra’, or ‘super’.
superrepstr: Representation used if type is ‘super’. One of ‘super’ (Liouville form) or ‘choi’ (Choi matrix with tr = dimension).

arguments()

Update the arguments.

Parameters:

_argsdict [optional]: New arguments as a dict. Update args with arguments(new_args).
**kwargs: New arguments as a keywors. Update args with arguments(**new_args).
.. note::: If both the positional _args and keywords are passed new values from both will be used. If a key is present with both, the _args dict value will take priority.

compress()

Look for redundance in the QobjEvo components:

Constant parts, (Qobj without Coefficient) will be summed. Pairs [Qobj, Coefficient] with the same Qobj are merged.

Example: [[sigmax(), f1], [sigmax(), f2]] -> [[sigmax(), f1+f2]]

The QobjEvo is transformed inplace.

Returns:

None

conj(): Get the element-wise conjugation of the quantum object.

copy(): Return a copy of this QobjEvo

dag(): Get the Hermitian adjoint of the quantum object.

expect()

Expectation value of this operator at time t with the state.

Parameters:

tfloat: Time of the operator to apply.
stateQobj: right matrix of the product
check_realbool (True): Whether to convert the result to a real when the imaginary part is smaller than the real part by a dactor of settings.core['rtol'].

Returns:

expectfloat or complex: state.adjoint() @ self @ state if state is a ket. trace(self @ matrix) is state is an operator or operator-ket.

expect_data(): Expectation is defined as state.adjoint() @ self @ state if state is a vector, or state is an operator and self is a superoperator. If state is an operator and self is an operator, then expectation is trace(self @ matrix).

isconstant: Does the system change depending on t

isoper: Indicates if the system represents an operator.

issuper: Indicates if the system represents a superoperator.

linear_map()

Apply mapping to each Qobj contribution.

Example: QobjEvo([sigmax(), coeff]).linear_map(spre) gives the same result has QobjEvo([spre(sigmax()), coeff])

Returns:

QobjEvo: Modified object

Notes

Does not modify the coefficients, thus linear_map(conj) would not give the the conjugate of the QobjEvo. It’s only valid for linear transformations.

matmul()

Product of this operator at time t to the state. self(t) @ state

Parameters:

tfloat: Time of the operator to apply.
stateQobj: right matrix of the product

Returns:

productQobj: The result product as a Qobj

matmul_data(): Compute out += self(t) @ state

num_elements: Number of parts composing the system

tidyup(): Removes small elements from quantum object.

to()

Convert the underlying data store of all component into the desired storage representation.

The different storage representations available are the “data-layer types”. By default, these are qutip.data.Dense and qutip.data.CSR, which respectively construct a dense matrix store and a compressed sparse row one.

The QobjEvo is transformed inplace.

Parameters:

data_typetype: The data-layer type that the data of this Qobj should be converted to.

Returns:

None

to_list()

Restore the QobjEvo to a list form.

Returns:

list_qevo: list: The QobjEvo as a list, element are either Qobj for constant parts, [Qobj, Coefficient] for coefficient based term. The original format of the Coefficient is not restored. Lastly if the original QobjEvo is constructed with a function returning a Qobj, the term is returned as a pair of the original function and args (dict).

trans(): Transpose of the quantum object

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 [‘$\left|0\right>$’, ‘$\left|1\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_arc(start, end, fmt='b', steps=None, **kwargs)[source]

Adds an arc between two points on a sphere. The arc is set to be blue solid curve by default.

The start and end points must be on the same sphere (i.e. have the same radius) but need not be on the unit sphere.

Parameters:

startQobj or array-like: Array with cartesian coordinates of the first point, or a state vector or density matrix that can be mapped to a point on or within the Bloch sphere.
endQobj or array-like: Array with cartesian coordinates of the second point, or a state vector or density matrix that can be mapped to a point on or within the Bloch sphere.
fmtstr, default: “b”: A matplotlib format string for rendering the arc.
stepsint, default: None: The number of segments to use when rendering the arc. The default uses 100 steps times the distance between the start and end points, with a minimum of 2 steps.
**kwargsdict: Additional parameters to pass to the matplotlib .plot function when rendering this arc.

add_line(start, end, fmt='k', **kwargs)[source]

Adds a line segment connecting two points on the bloch sphere.

The line segment is set to be a black solid line by default.

Parameters:

startQobj or array-like: Array with cartesian coordinates of the first point, or a state vector or density matrix that can be mapped to a point on or within the Bloch sphere.
endQobj or array-like: Array with cartesian coordinates of the second point, or a state vector or density matrix that can be mapped to a point on or within the Bloch sphere.
fmtstr, default: “k”: A matplotlib format string for rendering the line.
**kwargsdict: Additional parameters to pass to the matplotlib .plot function when rendering this line.

add_points(points, meth='s', colors=None, alpha=1.0)[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.
colorsarray_like: Optional array with colors for the points. A single color for meth ‘s’, and list of colors for meth ‘m’
alphafloat, default=1.: Transparency value for the vectors. Values between 0 and 1.
.. note::: When using meth=l in QuTiP 4.6, the line transparency defaulted to 0.75 and there was no way to alter it. When the alpha parameter was added in QuTiP 4.7, the default became alpha=1.0 for values of meth.

add_states(state, kind='vector', colors=None, alpha=1.0)[source]

Add a state vector Qobj to Bloch sphere.

Parameters:

stateQobj: Input state vector.
kind{‘vector’, ‘point’}: Type of object to plot.
colorsarray_like: Optional array with colors for the states.
alphafloat, default=1.: Transparency value for the vectors. Values between 0 and 1.

add_vectors(vectors, colors=None, alpha=1.0)[source]

Add a list of vectors to Bloch sphere.

Parameters:

vectorsarray_like: Array with vectors of unit length or smaller.
colorsarray_like: Optional array with colors for the vectors.
alphafloat, default=1.: Transparency value for the vectors. Values between 0 and 1.

clear()[source]: Resets Bloch sphere data sets to empty.

make_sphere()[source]: Plots Bloch sphere and data sets.

render()[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 directory dirc.

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

show()[source]

Display Bloch sphere and corresponding data sets.

Notes

When using inline plotting in Jupyter notebooks, any figure created in a notebook cell is displayed after the cell executes. Thus if you create a figure yourself and use it create a Bloch sphere with b = Bloch(..., fig=fig) and then call b.show() in the same cell, then the figure will be displayed twice. If you do create your own figure, the simplest solution to this is to not call .show() in the cell you create the figure in.

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

class Bloch3d(fig=None)[source]

Class for plotting data on a 3D Bloch sphere using mayavi. Valid data can be either points, vectors, or qobj objects corresponding to state vectors or density matrices. for a two-state system (or subsystem).

Notes

The use of mayavi for 3D rendering of the Bloch sphere comes with a few limitations: I) You can not embed a Bloch3d figure into a matplotlib window. II) The use of LaTex is not supported by the mayavi rendering engine. Therefore all labels must be defined using standard text. Of course you can post-process the generated figures later to add LaTeX using other software if needed.

Attributes:

figinstance {None}: User supplied Matplotlib Figure instance for plotting Bloch sphere.
font_colorstr {‘black’}: Color of font used for Bloch sphere labels.
font_scalefloat {0.08}: Scale for font used for Bloch sphere labels.
framebool {True}: Draw frame for Bloch sphere
frame_alphafloat {0.05}: Sets transparency of Bloch sphere frame.
frame_colorstr {‘gray’}: Color of sphere wireframe.
frame_numint {8}: Number of frame elements to draw.
frame_radiusfloats {0.005}: Width of wireframe.
point_colorlist {[‘r’, ‘g’, ‘b’, ‘y’]}: List of colors for Bloch sphere point markers to cycle through. i.e. By default, points 0 and 4 will both be blue (‘r’).
point_modestring {‘sphere’,’cone’,’cube’,’cylinder’,’point’}: Point marker shapes.
point_sizefloat {0.075}: Size of points on Bloch sphere.
sphere_alphafloat {0.1}: Transparency of Bloch sphere itself.
sphere_colorstr {‘#808080’}: Color of Bloch sphere.
sizelist {[500,500]}: Size of Bloch sphere plot in pixels. Best to have both numbers the same otherwise you will have a Bloch sphere that looks like a football.
vector_colorlist {[‘r’, ‘g’, ‘b’, ‘y’]}: List of vector colors to cycle through.
vector_widthint {3}: Width of displayed vectors.
viewlist {[45,65]}: Azimuthal and Elevation viewing angles.
xlabellist {['|x>', '']}: List of strings corresponding to +x and -x axes labels, respectively.
xlposlist {[1.07,-1.07]}: Positions of +x and -x labels respectively.
ylabellist {['|y>', '']}: List of strings corresponding to +y and -y axes labels, respectively.
ylposlist {[1.07,-1.07]}: Positions of +y and -y labels respectively.
zlabellist {['|0>', '|1>']}: List of strings corresponding to +z and -z axes labels, respectively.
zlposlist {[1.07,-1.07]}: Positions of +z and -z labels respectively.

add_points(points, meth='s', alpha=1.0)[source]

Add a list of data points to bloch sphere.

Parameters:

pointsarray/list: Collection of data points.
methstr {‘s’,’m’}: Type of points to plot, use ‘m’ for multicolored.
alphafloat, default=1.: Transparency value for the vectors. Values between 0 and 1.

add_states(state, kind='vector', alpha=1.0)[source]

Add a state vector Qobj to Bloch sphere.

Parameters:

stateqobj: Input state vector.
kindstr {‘vector’,’point’}: Type of object to plot.
alphafloat, default=1.: Transparency value for the vectors. Values between 0 and 1.

add_vectors(vectors, alpha=1.0)[source]

Add a list of vectors to Bloch sphere.

Parameters:

vectorsarray/list: Array with vectors of unit length or smaller.
alphafloat, default=1.: Transparency value for the vectors. Values between 0 and 1.

clear()[source]: Resets the Bloch sphere data sets to empty.

make_sphere()[source]: Plots Bloch sphere and data sets.

plot_points()[source]: Plots points on the Bloch sphere.

plot_vectors()[source]: Plots vectors on the Bloch sphere.

save(name=None, format='png', dirc=None)[source]

Saves Bloch sphere to file of type format in directory dirc.

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. Default is ‘png’.
dircstr: Directory for output images. Defaults to current working directory.

Returns:

File containing plot of Bloch sphere.

show()[source]: Display the Bloch sphere and corresponding data sets.

Distributions

class QFunc(xvec, yvec, g: float = 1.4142135623730951, memory: float = 1024)[source]

Class-based method of calculating the Husimi-Q function of many different quantum states at fixed phase-space points 0.5*g* (xvec + i*yvec). This class has slightly higher first-usage costs than qfunc, but subsequent operations will be several times faster. However, it can require quite a lot of memory. Call the created object as a function to retrieve the Husimi-Q function.

Parameters:

xvec, yvecarray_like: x- and y-coordinates at which to calculate the Husimi-Q function.
gfloat, default sqrt(2): Scaling factor for a = 0.5 * g * (x + iy). The value of g is related to the value of hbar in the commutation relation $[x,\,y] = i\hbar$ via $\hbar=2/g^2$, so the default corresponds to $\hbar=1$.
memoryreal, default 1024: Size in MB that may be used internally as workspace. This class will raise MemoryError if subsequently passed a state of sufficiently large dimension that this bound would be exceeded. In those cases, use qfunc with precompute_memory=None instead to force using the slower, more memory-efficient algorithm.

Solvers

class SESolver(H, *, options=None)[source]

Bases: Solver

Schrodinger equation evolution of a state vector or unitary matrix for a given Hamiltonian.

Parameters:

HQobj, QobjEvo: System Hamiltonian as a Qobj or QobjEvo for time-dependent Hamiltonians. List of [Qobj, Coefficient] or callable that can be made into QobjEvo are also accepted.
optionsdict, optional: Options for the solver, see SESolver.options and Integrator for a list of all options.

Attributes:

stats: dict: Diverse diagnostic statistics of the evolution.

classmethod add_integrator(integrator, key)

Register an integrator.

Parameters:

integratorIntegrator: The ODE solver to register.
keyslist of str: Values of the method options that refer to this integrator.

property options

Solver’s options:

store_final_state: bool, default=False: Whether or not to store the final state of the evolution in the result class.
store_states: bool, default=None: Whether or not to store the state vectors or density matrices. On None the states will be saved if no expectation operators are given.
normalize_output: bool, default=True: Normalize output state to hide ODE numerical errors.
progress_bar: str {‘text’, ‘enhanced’, ‘tqdm’, ‘’}, {}: How to present the solver progress. ‘tqdm’ uses the python module of the same name and raise an error if not installed. Empty string or False will disable the bar.
progress_kwargs: dict, default={“chunk_size”: 10}: Arguments to pass to the progress_bar. Qutip’s bars use chunk_size.
method: str, default=”adams”: Which ordinary differential equation integration method to use.

resultclass: alias of Result

run(state0, tlist, *, args=None, e_ops=None)

Do the evolution of the Quantum system.

For a state0 at time tlist[0] do the evolution as directed by rhs and for each time in tlist store the state and/or expectation values in a Result. The evolution method and stored results are determined by options.

Parameters:

state0Qobj: Initial state of the evolution.
tlistlist of double: Time for which to save the results (state and/or expect) of the evolution. The first element of the list is the initial time of the evolution. Each times of the list must be increasing, but does not need to be uniformy distributed.
argsdict, optional {None}: Change the args of the rhs for the evolution.
e_opslist {None}: List of Qobj, QobjEvo or callable to compute the expectation values. Function[s] must have the signature f(t : float, state : Qobj) -> expect.

start(state0, t0)

Set the initial state and time for a step evolution. options for the evolutions are read at this step.

Parameters:

state0Qobj: Initial state of the evolution.
t0double: Initial time of the evolution.

step(t, *, args=None, copy=True)

Evolve the state to t and return the state as a Qobj.

Parameters:

tdouble: Time to evolve to, must be higher than the last call.
argsdict, optional {None}: Update the args of the system. The change is effective from the beginning of the interval. Changing args can slow the evolution.
copybool, optional {True}: Whether to return a copy of the data or the data in the ODE solver.
.. note::: The state must be initialized first by calling start or run. If run is called, step will continue from the last time and state obtained.

property sys_dims

Dimensions of the space that the system use:

qutip.basis(sovler.dims) will create a state with proper dimensions for this solver.

class MESolver(H, c_ops=None, *, options=None)[source]

Bases: SESolver

Master equation evolution of a density matrix for a given Hamiltonian and set of collapse operators, or a Liouvillian.

Evolve the density matrix (rho0) using a given Hamiltonian or Liouvillian (H) and an optional set of collapse operators (c_ops), by integrating the set of ordinary differential equations that define the system.

If either H or the Qobj elements in c_ops are superoperators, they will be treated as direct contributions to the total system Liouvillian. This allows the solution of master equations that are not in standard Lindblad form.

Parameters:

HQobj, QobjEvo: Possibly time-dependent system Liouvillian or Hamiltonian as a Qobj or QobjEvo. List of [Qobj, Coefficient] or callable that can be made into QobjEvo are also accepted.
c_opslist of Qobj, QobjEvo: Single collapse operator, or list of collapse operators, or a list of Liouvillian superoperators. None is equivalent to an empty list.
optionsdict, optional: Options for the solver, see MESolver.options and Integrator for a list of all options.

Attributes:

stats: dict: Diverse diagnostic statistics of the evolution.

classmethod add_integrator(integrator, key)

Register an integrator.

Parameters:

integratorIntegrator: The ODE solver to register.
keyslist of str: Values of the method options that refer to this integrator.

property options

Solver’s options:

store_final_state: bool, default=False: Whether or not to store the final state of the evolution in the result class.
store_states: bool, default=None: Whether or not to store the state vectors or density matrices. On None the states will be saved if no expectation operators are given.
normalize_output: bool, default=True: Normalize output state to hide ODE numerical errors.
progress_bar: str {‘text’, ‘enhanced’, ‘tqdm’, ‘’}, {}: How to present the solver progress. ‘tqdm’ uses the python module of the same name and raise an error if not installed. Empty string or False will disable the bar.
progress_kwargs: dict, default={“chunk_size”: 10}: Arguments to pass to the progress_bar. Qutip’s bars use chunk_size.
method: str, default=”adams”: Which ordinary differential equation integration method to use.

resultclass: alias of Result

run(state0, tlist, *, args=None, e_ops=None)

Do the evolution of the Quantum system.

For a state0 at time tlist[0] do the evolution as directed by rhs and for each time in tlist store the state and/or expectation values in a Result. The evolution method and stored results are determined by options.

Parameters:

state0Qobj: Initial state of the evolution.
tlistlist of double: Time for which to save the results (state and/or expect) of the evolution. The first element of the list is the initial time of the evolution. Each times of the list must be increasing, but does not need to be uniformy distributed.
argsdict, optional {None}: Change the args of the rhs for the evolution.
e_opslist {None}: List of Qobj, QobjEvo or callable to compute the expectation values. Function[s] must have the signature f(t : float, state : Qobj) -> expect.

start(state0, t0)

Set the initial state and time for a step evolution. options for the evolutions are read at this step.

Parameters:

state0Qobj: Initial state of the evolution.
t0double: Initial time of the evolution.

step(t, *, args=None, copy=True)

Evolve the state to t and return the state as a Qobj.

Parameters:

tdouble: Time to evolve to, must be higher than the last call.
argsdict, optional {None}: Update the args of the system. The change is effective from the beginning of the interval. Changing args can slow the evolution.
copybool, optional {True}: Whether to return a copy of the data or the data in the ODE solver.
.. note::: The state must be initialized first by calling start or run. If run is called, step will continue from the last time and state obtained.

property sys_dims

Dimensions of the space that the system use:

qutip.basis(sovler.dims) will create a state with proper dimensions for this solver.

class BRSolver(H, a_ops, c_ops=None, sec_cutoff=0.1, *, options=None)[source]

Bases: Solver

Bloch Redfield equation evolution of a density matrix for a given Hamiltonian and set of bath coupling operators.

Parameters:

HQobj, QobjEvo

Possibly time-dependent system Liouvillian or Hamiltonian as a Qobj or QobjEvo. list of [Qobj, Coefficient] or callable that can be made into QobjEvo are also accepted.

a_opslist of (a_op, spectra)

Nested list of system operators that couple to the environment, and the corresponding bath spectra.

a_opqutip.Qobj, qutip.QobjEvo: The operator coupling to the environment. Must be hermitian.
spectraCoefficient: The corresponding bath spectra. As a Coefficient using an ‘w’ args. Can depend on t only if a_op is a qutip.QobjEvo. SpectraCoefficient can be used to conver a coefficient depending on t to one depending on w.

Example:

a_ops = [
    (a+a.dag(), coefficient('w>0', args={'w':0})),
    (QobjEvo([b+b.dag(), lambda t: ...]),
     coefficient(lambda t, w: ...), args={"w": 0}),
    (c+c.dag(), SpectraCoefficient(coefficient(array, tlist=ws))),
]

c_opslist of Qobj, QobjEvo

Single collapse operator, or list of collapse operators, or a list of Lindblad dissipator. None is equivalent to an empty list.

optionsdict, optional

Options for the solver, see BRSolver.options and Integrator for a list of all options.

sec_cutofffloat {0.1}

Cutoff for secular approximation. Use -1 if secular approximation is not used when evaluating bath-coupling terms.

Attributes:

stats: dict: Diverse diagnostic statistics of the evolution.

classmethod add_integrator(integrator, key)

Register an integrator.

Parameters:

integratorIntegrator: The ODE solver to register.
keyslist of str: Values of the method options that refer to this integrator.

property options

Options for bloch redfield solver:

store_final_state: bool, default=False: Whether or not to store the final state of the evolution in the result class.
store_states: bool, default=None: Whether or not to store the state vectors or density matrices. On None the states will be saved if no expectation operators are given.
normalize_output: bool, default=False: Normalize output state to hide ODE numerical errors.
progress_bar: str {‘text’, ‘enhanced’, ‘tqdm’, ‘’}, default=”text”: How to present the solver progress. ‘tqdm’ uses the python module of the same name and raise an error if not installed. Empty string or False will disable the bar.
progress_kwargs: dict, default={“chunk_size”:10}: Arguments to pass to the progress_bar. Qutip’s bars use chunk_size.
tensor_type: str [‘sparse’, ‘dense’, ‘data’], default=”sparse”: Which data type to use when computing the brtensor. With a cutoff ‘sparse’ is usually the most efficient.
sparse_eigensolver: bool, default=False: Whether to use the sparse eigensolver
method: str, default=”adams”: Which ODE integrator methods are supported.

resultclass: alias of Result

run(state0, tlist, *, args=None, e_ops=None)

Do the evolution of the Quantum system.

For a state0 at time tlist[0] do the evolution as directed by rhs and for each time in tlist store the state and/or expectation values in a Result. The evolution method and stored results are determined by options.

Parameters:

state0Qobj: Initial state of the evolution.
tlistlist of double: Time for which to save the results (state and/or expect) of the evolution. The first element of the list is the initial time of the evolution. Each times of the list must be increasing, but does not need to be uniformy distributed.
argsdict, optional {None}: Change the args of the rhs for the evolution.
e_opslist {None}: List of Qobj, QobjEvo or callable to compute the expectation values. Function[s] must have the signature f(t : float, state : Qobj) -> expect.

start(state0, t0)

Set the initial state and time for a step evolution. options for the evolutions are read at this step.

Parameters:

state0Qobj: Initial state of the evolution.
t0double: Initial time of the evolution.

step(t, *, args=None, copy=True)

Evolve the state to t and return the state as a Qobj.

Parameters:

tdouble: Time to evolve to, must be higher than the last call.
argsdict, optional {None}: Update the args of the system. The change is effective from the beginning of the interval. Changing args can slow the evolution.
copybool, optional {True}: Whether to return a copy of the data or the data in the ODE solver.
.. note::: The state must be initialized first by calling start or run. If run is called, step will continue from the last time and state obtained.

property sys_dims

Dimensions of the space that the system use:

qutip.basis(sovler.dims) will create a state with proper dimensions for this solver.

class SMESolver(H, sc_ops, heterodyne, *, c_ops=(), options=None)[source]

Bases: StochasticSolver

Stochastic Master Equation Solver.

Parameters:

HQobj, QobjEvo, QobjEvo compatible format.: System Hamiltonian as a Qobj or QobjEvo for time-dependent Hamiltonians. List of [Qobj, Coefficient] or callable that can be made into QobjEvo are also accepted.
sc_opslist of (QobjEvo, QobjEvo compatible format): List of stochastic collapse operators.
heterodynebool, [False]: Whether to use heterodyne or homodyne detection.
optionsdict, [optional]: Options for the solver, see SMESolver.options and SIntegrator for a list of all options.

classmethod add_integrator(integrator, key)

Register an integrator.

Parameters:

integratorIntegrator: The ODE solver to register.
keyslist of str: Values of the method options that refer to this integrator.

property options

Options for stochastic solver:

store_final_state: bool, default=False: Whether or not to store the final state of the evolution in the result class.
store_states: bool, default=None: Whether or not to store the state vectors or density matrices. On None the states will be saved if no expectation operators are given.
store_measurement: bool, [False]: Whether to store the measurement for each trajectories. Storing measurements will also store the wiener process, or brownian noise for each trajectories.
progress_bar: str {‘text’, ‘enhanced’, ‘tqdm’, ‘’}, default=”text”: How to present the solver progress. ‘tqdm’ uses the python module of the same name and raise an error if not installed. Empty string or False will disable the bar.
progress_kwargs: dict, default={“chunk_size”:10}: Arguments to pass to the progress_bar. Qutip’s bars use chunk_size.
keep_runs_results: bool: Whether to store results from all trajectories or just store the averages.
method: str, default=”rouchon”: Which ODE integrator methods are supported.
map: str {“serial”, “parallel”, “loky”}, default=”serial”: How to run the trajectories. “parallel” uses concurent module to run in parallel while “loky” use the module of the same name to do so.
job_timeout: None, int, default=None: Maximum time to compute one trajectory.
num_cpus: None, int, default=None: Number of cpus to use when running in parallel. None detect the number of available cpus.
bitgenerator: {None, “MT19937”, “PCG64DXSM”, …}, default=None: Which of numpy.random’s bitgenerator to use. With None, your numpy version’s default is used.

resultclass: alias of StochasticResult

run(state, tlist, ntraj=1, *, args=None, e_ops=(), timeout=None, target_tol=None, seed=None)

Do the evolution of the Quantum system.

For a state at time tlist[0] do the evolution as directed by rhs and for each time in tlist store the state and/or expectation values in a Result. The evolution method and stored results are determined by options.

Parameters:

stateQobj: Initial state of the evolution.
tlistlist of double: Time for which to save the results (state and/or expect) of the evolution. The first element of the list is the initial time of the evolution. Time in the list must be in increasing order, but does not need to be uniformly distributed.
ntrajint: Number of trajectories to add.
argsdict, optional {None}: Change the args of the rhs for the evolution.
e_opslist: list of Qobj or QobjEvo to compute the expectation values. Alternatively, function[s] with the signature f(t, state) -> expect can be used.
timeoutfloat, optional [1e8]: Maximum time in seconds for the trajectories to run. Once this time is reached, the simulation will end even if the number of trajectories is less than ntraj. The map function, set in options, can interupt the running trajectory or wait for it to finish. Set to an arbitrary high number to disable.
target_tol{float, tuple, list}, optional [None]: Target tolerance of the evolution. The evolution will compute trajectories until the error on the expectation values is lower than this tolerance. The maximum number of trajectories employed is given by ntraj. The error is computed using jackknife resampling. target_tol can be an absolute tolerance or a pair of absolute and relative tolerance, in that order. Lastly, it can be a list of pairs of (atol, rtol) for each e_ops.
seed{int, SeedSequence, list} optional: Seed or list of seeds for each trajectories.

Returns:

resultsqutip.solver.MultiTrajResult: Results of the evolution. States and/or expect will be saved. You can control the saved data in the options.

start(state, t0, seed=None)

Set the initial state and time for a step evolution.

Parameters:

stateQobj: Initial state of the evolution.
t0double: Initial time of the evolution.
seedint, SeedSequence, list, {None}: Seed for the random number generator. It can be a single seed used to spawn seeds for each trajectory or a list of seed, one for each trajectory.
..note ::: When using step evolution, only one trajectory can be computed at once.

step(t, *, args=None, copy=True)

Evolve the state to t and return the state as a Qobj.

Parameters:

tdouble: Time to evolve to, must be higher than the last call.
argsdict, optional {None}: Update the args of the system. The change is effective from the beginning of the interval. Changing args can slow the evolution.
copybool, optional {True}: Whether to return a copy of the data or the data in the ODE solver.

property sys_dims

Dimensions of the space that the system use:

qutip.basis(sovler.dims) will create a state with proper dimensions for this solver.

trajectory_resultclass: alias of Result

class SSESolver(H, sc_ops, heterodyne, *, c_ops=(), options=None)[source]

Bases: StochasticSolver

Stochastic Schrodinger Equation Solver.

Parameters:

HQobj, QobjEvo, QobjEvo compatible format.: System Hamiltonian as a Qobj or QobjEvo for time-dependent Hamiltonians. List of [Qobj, Coefficient] or callable that can be made into QobjEvo are also accepted.
c_opslist of (QobjEvo, QobjEvo compatible format): Deterministic collapse operator which will contribute with a standard Lindblad type of dissipation.
sc_opslist of (QobjEvo, QobjEvo compatible format): List of stochastic collapse operators.
heterodynebool, [False]: Whether to use heterodyne or homodyne detection.
optionsdict, [optional]: Options for the solver, see SSESolver.options and SIntegrator for a list of all options.

classmethod add_integrator(integrator, key)

Register an integrator.

Parameters:

integratorIntegrator: The ODE solver to register.
keyslist of str: Values of the method options that refer to this integrator.

property options

Options for stochastic solver:

store_final_state: bool, default=False: Whether or not to store the final state of the evolution in the result class.
store_states: bool, default=None: Whether or not to store the state vectors or density matrices. On None the states will be saved if no expectation operators are given.
store_measurement: bool, [False]: Whether to store the measurement for each trajectories. Storing measurements will also store the wiener process, or brownian noise for each trajectories.
progress_bar: str {‘text’, ‘enhanced’, ‘tqdm’, ‘’}, default=”text”: How to present the solver progress. ‘tqdm’ uses the python module of the same name and raise an error if not installed. Empty string or False will disable the bar.
progress_kwargs: dict, default={“chunk_size”:10}: Arguments to pass to the progress_bar. Qutip’s bars use chunk_size.
keep_runs_results: bool: Whether to store results from all trajectories or just store the averages.
method: str, default=”rouchon”: Which ODE integrator methods are supported.
map: str {“serial”, “parallel”, “loky”}, default=”serial”: How to run the trajectories. “parallel” uses concurent module to run in parallel while “loky” use the module of the same name to do so.
job_timeout: None, int, default=None: Maximum time to compute one trajectory.
num_cpus: None, int, default=None: Number of cpus to use when running in parallel. None detect the number of available cpus.
bitgenerator: {None, “MT19937”, “PCG64DXSM”, …}, default=None: Which of numpy.random’s bitgenerator to use. With None, your numpy version’s default is used.

resultclass: alias of StochasticResult

run(state, tlist, ntraj=1, *, args=None, e_ops=(), timeout=None, target_tol=None, seed=None)

Do the evolution of the Quantum system.

For a state at time tlist[0] do the evolution as directed by rhs and for each time in tlist store the state and/or expectation values in a Result. The evolution method and stored results are determined by options.

Parameters:

stateQobj: Initial state of the evolution.
tlistlist of double: Time for which to save the results (state and/or expect) of the evolution. The first element of the list is the initial time of the evolution. Time in the list must be in increasing order, but does not need to be uniformly distributed.
ntrajint: Number of trajectories to add.
argsdict, optional {None}: Change the args of the rhs for the evolution.
e_opslist: list of Qobj or QobjEvo to compute the expectation values. Alternatively, function[s] with the signature f(t, state) -> expect can be used.
timeoutfloat, optional [1e8]: Maximum time in seconds for the trajectories to run. Once this time is reached, the simulation will end even if the number of trajectories is less than ntraj. The map function, set in options, can interupt the running trajectory or wait for it to finish. Set to an arbitrary high number to disable.
target_tol{float, tuple, list}, optional [None]: Target tolerance of the evolution. The evolution will compute trajectories until the error on the expectation values is lower than this tolerance. The maximum number of trajectories employed is given by ntraj. The error is computed using jackknife resampling. target_tol can be an absolute tolerance or a pair of absolute and relative tolerance, in that order. Lastly, it can be a list of pairs of (atol, rtol) for each e_ops.
seed{int, SeedSequence, list} optional: Seed or list of seeds for each trajectories.

Returns:

resultsqutip.solver.MultiTrajResult: Results of the evolution. States and/or expect will be saved. You can control the saved data in the options.

start(state, t0, seed=None)

Set the initial state and time for a step evolution.

Parameters:

stateQobj: Initial state of the evolution.
t0double: Initial time of the evolution.
seedint, SeedSequence, list, {None}: Seed for the random number generator. It can be a single seed used to spawn seeds for each trajectory or a list of seed, one for each trajectory.
..note ::: When using step evolution, only one trajectory can be computed at once.

step(t, *, args=None, copy=True)

Evolve the state to t and return the state as a Qobj.

Parameters:

tdouble: Time to evolve to, must be higher than the last call.
argsdict, optional {None}: Update the args of the system. The change is effective from the beginning of the interval. Changing args can slow the evolution.
copybool, optional {True}: Whether to return a copy of the data or the data in the ODE solver.

property sys_dims

Dimensions of the space that the system use:

qutip.basis(sovler.dims) will create a state with proper dimensions for this solver.

trajectory_resultclass: alias of Result

Monte Carlo Solvers

class MCSolver(H, c_ops, *, options=None)[source]

Bases: MultiTrajSolver

Monte Carlo Solver of a state vector $|\psi \rangle$ for a given Hamiltonian and sets of collapse operators. Options for the underlying ODE solver are given by the Options class.

Parameters:

Hqutip.Qobj, qutip.QobjEvo, list, callable.: System Hamiltonian as a Qobj, QobjEvo. It can also be any input type that QobjEvo accepts (see qutip.QobjEvo’s documentation). H can also be a superoperator (liouvillian) if some collapse operators are to be treated deterministically.
c_opslist: A list of collapse operators in any input type that QobjEvo accepts (see qutip.QobjEvo’s documentation). They must be operators even if H is a superoperator.
optionsdict, [optional]: Options for the evolution.

classmethod add_integrator(integrator, key)

Register an integrator.

Parameters:

integratorIntegrator: The ODE solver to register.
keyslist of str: Values of the method options that refer to this integrator.

mc_integrator_class: alias of MCIntegrator

property options

Options for monte carlo solver:

store_final_state: bool, default=False: Whether or not to store the final state of the evolution in the result class.
store_states: bool, default=None: Whether or not to store the state vectors or density matrices. On None the states will be saved if no expectation operators are given.
progress_bar: str {‘text’, ‘enhanced’, ‘tqdm’, ‘’}, default=”text”: How to present the solver progress. ‘tqdm’ uses the python module of the same name and raise an error if not installed. Empty string or False will disable the bar.
progress_kwargs: dict, default={“chunk_size”:10}: Arguments to pass to the progress_bar. Qutip’s bars use chunk_size.
keep_runs_results: bool: Whether to store results from all trajectories or just store the averages.
method: str, default=”adams”: Which ODE integrator methods are supported.
map: str {“serial”, “parallel”, “loky”}: How to run the trajectories. “parallel” uses concurent module to run in parallel while “loky” use the module of the same name to do so.
job_timeout: None, int: Maximum time to compute one trajectory.
num_cpus: None, int: Number of cpus to use when running in parallel. None detect the number of available cpus.
bitgenerator: {None, “MT19937”, “PCG64”, “PCG64DXSM”, …}: Which of numpy.random’s bitgenerator to use. With None, your numpy version’s default is used.
mc_corr_eps: float: Small number used to detect non-physical collapse caused by numerical imprecision.
norm_t_tol: float: Tolerance in time used when finding the collapse.
norm_tol: float: Tolerance in norm used when finding the collapse.
norm_steps: int: Maximum number of tries to find the collapse.
improved_sampling: Bool: Whether to use the improved sampling algorithm of Abdelhafez et al. PRA (2019)

property resultclass

Base class for storing results for solver using multiple trajectories.

Parameters:

e_opsQobj, QobjEvo, function or list or dict of these

The e_ops parameter defines the set of values to record at each time step t. If an element is a Qobj or QobjEvo the value recorded is the expectation value of that operator given the state at t. If the element is a function, f, the value recorded is f(t, state).

The values are recorded in the .expect attribute of this result object. .expect is a list, where each item contains the values of the corresponding e_op.

Function e_ops must return a number so the average can be computed.

optionsdict

The options for this result class.

solverstr or None

The name of the solver generating these results.

statsdict or None

The stats generated by the solver while producing these results. Note that the solver may update the stats directly while producing results.

kwdict

Additional parameters specific to a result sub-class.

run(state, tlist, ntraj=1, *, args=None, e_ops=(), timeout=None, target_tol=None, seed=None)[source]: Do the evolution of the Quantum system. See the overridden method for further details. The modification here is to sample the no-jump trajectory first. Then, the no-jump probability is used as a lower-bound for random numbers in future monte carlo runs

start(state, t0, seed=None)

Set the initial state and time for a step evolution.

Parameters:

stateQobj: Initial state of the evolution.
t0double: Initial time of the evolution.
seedint, SeedSequence, list, {None}: Seed for the random number generator. It can be a single seed used to spawn seeds for each trajectory or a list of seed, one for each trajectory.
..note ::: When using step evolution, only one trajectory can be computed at once.

step(t, *, args=None, copy=True)

Evolve the state to t and return the state as a Qobj.

Parameters:

tdouble: Time to evolve to, must be higher than the last call.
argsdict, optional {None}: Update the args of the system. The change is effective from the beginning of the interval. Changing args can slow the evolution.
copybool, optional {True}: Whether to return a copy of the data or the data in the ODE solver.

property sys_dims

Dimensions of the space that the system use:

qutip.basis(sovler.dims) will create a state with proper dimensions for this solver.

trajectory_resultclass: alias of McTrajectoryResult

class NonMarkovianMCSolver(H, ops_and_rates, *_args, args=None, options=None, **kwargs)[source]

Bases: MCSolver

Monte Carlo Solver for Lindblad equations with “rates” that may be negative. The c_ops parameter of qutip.MCSolver is replaced by an ops_and_rates parameter to allow for negative rates. Options for the underlying ODE solver are given by the Options class.

Parameters:

Hqutip.Qobj, qutip.QobjEvo, list, callable.

System Hamiltonian as a Qobj, QobjEvo. It can also be any input type that QobjEvo accepts (see qutip.QobjEvo documentation). H can also be a superoperator (liouvillian) if some collapse operators are to be treated deterministically.

ops_and_rateslist

A list of tuples (L, Gamma), where the Lindblad operator L is a qutip.Qobj and Gamma represents the corresponding rate, which is allowed to be negative. The Lindblad operators must be operators even if H is a superoperator. Each rate Gamma may be just a number (in the case of a constant rate) or, otherwise, specified using any format accepted by qutip.coefficient.

argsNone / dict

Arguments for time-dependent Hamiltonian and collapse operator terms.

optionsSolverOptions, [optional]

Options for the evolution.

seedint, SeedSequence, list, [optional]

Seed for the random number generator. It can be a single seed used to spawn seeds for each trajectory or a list of seed, one for each trajectory. Seeds are saved in the result and can be reused with:

seeds=prev_result.seeds

classmethod add_integrator(integrator, key)

Register an integrator.

Parameters:

integratorIntegrator: The ODE solver to register.
keyslist of str: Values of the method options that refer to this integrator.

current_martingale()[source]: Returns the value of the influence martingale along the current trajectory. The value of the martingale is the product of the continuous and the discrete contribution. The current time and the collapses that have happened are read out from the internal integrator.

mc_integrator_class: alias of NmMCIntegrator

property options

Options for monte carlo solver:

store_final_state: bool, default=False: Whether or not to store the final state of the evolution in the result class.
store_states: bool, default=None: Whether or not to store the state vectors or density matrices. On None the states will be saved if no expectation operators are given.
progress_bar: str {‘text’, ‘enhanced’, ‘tqdm’, ‘’}, default=”text”: How to present the solver progress. ‘tqdm’ uses the python module of the same name and raise an error if not installed. Empty string or False will disable the bar.
progress_kwargs: dict, default={“chunk_size”:10}: Arguments to pass to the progress_bar. Qutip’s bars use chunk_size.
keep_runs_results: bool: Whether to store results from all trajectories or just store the averages.
method: str, default=”adams”: Which ODE integrator methods are supported.
map: str {“serial”, “parallel”, “loky”}: How to run the trajectories. “parallel” uses concurent module to run in parallel while “loky” use the module of the same name to do so.
job_timeout: None, int: Maximum time to compute one trajectory.
num_cpus: None, int: Number of cpus to use when running in parallel. None detect the number of available cpus.
bitgenerator: {None, “MT19937”, “PCG64”, “PCG64DXSM”, …}: Which of numpy.random’s bitgenerator to use. With None, your numpy version’s default is used.
mc_corr_eps: float: Small number used to detect non-physical collapse caused by numerical imprecision.
norm_t_tol: float: Tolerance in time used when finding the collapse.
norm_tol: float: Tolerance in norm used when finding the collapse.
norm_steps: int: Maximum number of tries to find the collapse.
improved_sampling: Bool: Whether to use the improved sampling algorithm of Abdelhafez et al. PRA (2019)

rate(t, i)[source]

Return the i’th unshifted rate at time t.

Parameters:

tfloat: The time at which to calculate the rate.
iint: Which rate to calculate.

Returns:

ratefloat: The value of rate i at time t.

rate_shift(t)[source]

Return the rate shift at time t.

The rate shift is 2 * abs(min([0, rate_1(t), rate_2(t), ...])).

Parameters:

tfloat: The time at which to calculate the rate shift.

Returns:

rate_shiftfloat: The rate shift amount.

resultclass: alias of NmmcResult

run(state, tlist, *args, **kwargs)[source]

Do the evolution of the Quantum system.

For a state at time tlist[0] do the evolution as directed by rhs and for each time in tlist store the state and/or expectation values in a Result. The evolution method and stored results are determined by options.

Parameters:

stateQobj: Initial state of the evolution.
tlistlist of double: Time for which to save the results (state and/or expect) of the evolution. The first element of the list is the initial time of the evolution. Time in the list must be in increasing order, but does not need to be uniformly distributed.
ntrajint: Number of trajectories to add.
argsdict, optional {None}: Change the args of the rhs for the evolution.
e_opslist: list of Qobj or QobjEvo to compute the expectation values. Alternatively, function[s] with the signature f(t, state) -> expect can be used.
timeoutfloat, optional [1e8]: Maximum time in seconds for the trajectories to run. Once this time is reached, the simulation will end even if the number of trajectories is less than ntraj. The map function, set in options, can interupt the running trajectory or wait for it to finish. Set to an arbitrary high number to disable.
target_tol{float, tuple, list}, optional [None]: Target tolerance of the evolution. The evolution will compute trajectories until the error on the expectation values is lower than this tolerance. The maximum number of trajectories employed is given by ntraj. The error is computed using jackknife resampling. target_tol can be an absolute tolerance or a pair of absolute and relative tolerance, in that order. Lastly, it can be a list of pairs of (atol, rtol) for each e_ops.
seed{int, SeedSequence, list} optional: Seed or list of seeds for each trajectories.

Returns:

resultsqutip.solver.MultiTrajResult: Results of the evolution. States and/or expect will be saved. You can control the saved data in the options.

sqrt_shifted_rate(t, i)[source]

Return the square root of the i’th shifted rate at time t.

Parameters:

tfloat: The time at wich to calculate the shifted rate.
iint: Which shifted rate to calculate.

Returns:

ratefloat: The square root of the shifted value of rate i at time t.

start(state, t0, seed=None)[source]

Set the initial state and time for a step evolution.

Parameters:

stateQobj: Initial state of the evolution.
t0double: Initial time of the evolution.
seedint, SeedSequence, list, {None}: Seed for the random number generator. It can be a single seed used to spawn seeds for each trajectory or a list of seed, one for each trajectory.
..note ::: When using step evolution, only one trajectory can be computed at once.

step(t, *, args=None, copy=True)[source]

Evolve the state to t and return the state as a Qobj.

Parameters:

tdouble: Time to evolve to, must be higher than the last call.
argsdict, optional {None}: Update the args of the system. The change is effective from the beginning of the interval. Changing args can slow the evolution.
copybool, optional {True}: Whether to return a copy of the data or the data in the ODE solver.

property sys_dims

Dimensions of the space that the system use:

qutip.basis(sovler.dims) will create a state with proper dimensions for this solver.

trajectory_resultclass: alias of NmmcTrajectoryResult

Non-Markovian HEOM Solver

class HEOMSolver(H, bath, max_depth, *, options=None)[source]

HEOM solver that supports multiple baths.

The baths must be all either bosonic or fermionic baths.

Parameters:

HQobj, QobjEvo

Possibly time-dependent system Liouvillian or Hamiltonian as a Qobj or QobjEvo. list of [Qobj, Coefficient] or callable that can be made into QobjEvo are also accepted.

bathBath or list of Bath

A Bath containing the exponents of the expansion of the bath correlation funcion and their associated coefficients and coupling operators, or a list of baths.

If multiple baths are given, they must all be either fermionic or bosonic baths.

max_depthint

The maximum depth of the heirarchy (i.e. the maximum number of bath exponent “excitations” to retain).

optionsdict, optional

Generic solver options. If set to None the default options will be used. Keyword only. Default: None.

Attributes:

adosHierarchyADOs: The description of the hierarchy constructed from the given bath and maximum depth.
rhsQobjEvo: The right-hand side (RHS) of the hierarchy evolution ODE. Internally the system and bath coupling operators are converted to qutip.data.CSR instances during construction of the RHS, so the operators in the rhs will all be sparse.

property options

Options for HEOMSolver:

store_final_state: bool, default=False: Whether or not to store the final state of the evolution in the result class.
store_states: bool, default=None: Whether or not to store the state vectors or density matrices. On None the states will be saved if no expectation operators are given.
normalize_output: bool, default=False: Normalize output state to hide ODE numerical errors.
progress_bar: str {‘text’, ‘enhanced’, ‘tqdm’, ‘’}, default=”text”: How to present the solver progress. ‘tqdm’ uses the python module of the same name and raise an error if not installed. Empty string or False will disable the bar.
progress_kwargs: dict, default={“chunk_size”: 10}: Arguments to pass to the progress_bar. Qutip’s bars use chunk_size.
method: str, default=”adams”: Which ordinary differential equation integration method to use.
state_data_type: str, default=”dense”: Name of the data type of the state used during the ODE evolution. Use an empty string to keep the input state type. Many integrators support only work with Dense.
store_adosbool, default=False: Whether or not to store the HEOM ADOs. Only relevant when using the HEOM solver.

resultclass: alias of HEOMResult

run(state0, tlist, *, args=None, e_ops=None)[source]

Solve for the time evolution of the system.

Parameters:

state0Qobj or HierarchyADOsState or array-like

If rho0 is a Qobj the it is the initial state of the system (i.e. a Qobj density matrix).

If it is a HierarchyADOsState or array-like, then rho0 gives the initial state of all ADOs.

Usually the state of the ADOs would be determine from a previous call to .run(...) with the solver results option store_ados set to True. For example, result = solver.run(...) could be followed by solver.run(result.ado_states[-1], tlist).

If a numpy array-like is passed its shape must be (number_of_ados, n, n) where (n, n) is the system shape (i.e. shape of the system density matrix) and the ADOs must be in the same order as in .ados.labels.

tlistlist

An ordered list of times at which to return the value of the state.

argsdict, optional {None}

Change the args of the RHS for the evolution.

e_opsQobj / QobjEvo / callable / list / dict / None, optional

A list or dictionary of operators as Qobj, QobjEvo and/or callable functions (they can be mixed) or a single operator or callable function. For an operator op, the result will be computed using (state * op).tr() and the state at each time t. For callable functions, f, the result is computed using f(t, ado_state). The values are stored in the expect and e_data attributes of the result (see the return section below).

Returns:

HEOMResult

The results of the simulation run, with the following important attributes:

times: the times t (i.e. the tlist).
states: the system state at each time t (only available if e_ops was None or if the solver option store_states was set to True).
ado_states: the full ADO state at each time (only available if the results option ado_return was set to True). Each element is an instance of HierarchyADOsState. The state of a particular ADO may be extracted from result.ado_states[i] by calling extract.
expect: a list containing the values of each e_ops at time t.
e_data: a dictionary containing the values of each e_ops at tme t. The keys are those given by e_ops if it was a dict, otherwise they are the indexes of the supplied e_ops.

See HEOMResult and Result for the complete list of attributes.

start(state0, t0)[source]

Set the initial state and time for a step evolution.

Parameters:

state0Qobj: Initial state of the evolution. This may provide either just the initial density matrix of the system, or the full set of ADOs for the hierarchy. See the documentation for rho0 in the .run(...) method for details.
t0double: Initial time of the evolution.

steady_state(use_mkl=True, mkl_max_iter_refine=100, mkl_weighted_matching=False)[source]

Compute the steady state of the system.

Parameters:

use_mklbool, default=False

Whether to use mkl or not. If mkl is not installed or if this is false, use the scipy splu solver instead.

mkl_max_iter_refineint

Specifies the the maximum number of iterative refinement steps that the MKL PARDISO solver performs.

For a complete description, see iparm(8) in http://cali2.unilim.fr/intel-xe/mkl/mklman/GUID-264E311E-ACED-4D56-AC31-E9D3B11D1CBF.htm.

mkl_weighted_matchingbool

MKL PARDISO can use a maximum weighted matching algorithm to permute large elements close the diagonal. This strategy adds an additional level of reliability to the factorization methods.

For a complete description, see iparm(13) in http://cali2.unilim.fr/intel-xe/mkl/mklman/GUID-264E311E-ACED-4D56-AC31-E9D3B11D1CBF.htm.

Returns:

steady_stateQobj: The steady state density matrix of the system.
steady_adosHierarchyADOsState: The steady state of the full ADO hierarchy. A particular ADO may be extracted from the full state by calling HEOMSolver.extract.

property sys_dims

Dimensions of the space that the system use, excluding any environment:

qutip.basis(sovler.dims) will create a state with proper dimensions for this solver.

class HSolverDL(H_sys, coup_op, coup_strength, temperature, N_cut, N_exp, cut_freq, *, bnd_cut_approx=False, options=None, combine=True)[source]

A helper class for creating an HEOMSolver that is backwards compatible with the HSolverDL provided in qutip.nonmarkov.heom in QuTiP 4.6 and below.

See HEOMSolver and DrudeLorentzBath for more descriptions of the underlying solver and bath construction.

An exact copy of the QuTiP 4.6 HSolverDL is provided in qutip.nonmarkov.dlheom_solver for cases where the functionality of the older solver is required. The older solver will be completely removed in QuTiP 5.

Note

Unlike the version of HSolverDL in QuTiP 4.6, this solver supports supplying a time-dependent or Liouvillian H_sys.

Note

For compatibility with HSolverDL in QuTiP 4.6 and below, the parameter N_exp specifying the number of exponents to keep in the expansion of the bath correlation function is one more than the equivalent Nk used in the DrudeLorentzBath. I.e., Nk = N_exp - 1. The Nk parameter in the DrudeLorentzBath does not count the zeroeth exponent in order to better match common usage in the literature.

Note

The stats and renorm arguments accepted in QuTiP 4.6 and below are no longer supported.

Parameters:

H_sysQobj or QobjEvo or list: The system Hamiltonian or Liouvillian. See HEOMSolver for a complete description.
coup_opQobj: Operator describing the coupling between system and bath. See parameter Q in BosonicBath for a complete description.
coup_strengthfloat: Coupling strength. Referred to as lam in DrudeLorentzBath.
temperaturefloat: Bath temperature. Referred to as T in DrudeLorentzBath.
N_cutint: The maximum depth of the hierarchy. See max_depth in HEOMSolver for a full description.
N_expint: Number of exponential terms used to approximate the bath correlation functions. The equivalent Nk in DrudeLorentzBath is one less than N_exp (see note above).
cut_freqfloat: Bath spectral density cutoff frequency. Referred to as gamma in DrudeLorentzBath.
bnd_cut_approxbool: Use boundary cut off approximation. If true, the Matsubara terminator is added to the system Liouvillian (and H_sys is promoted to a Liouvillian if it was a Hamiltonian). Keyword only. Default: False.
optionsdict, optional: Generic solver options. If set to None the default options will be used. Keyword only. Default: None.
combinebool, default True: Whether to combine exponents with the same frequency (and coupling operator). See BosonicBath.combine for details. Keyword only. Default: True.

class BathExponent(type, dim, Q, ck, vk, ck2=None, sigma_bar_k_offset=None, tag=None)[source]

Represents a single exponent (naively, an excitation mode) within the decomposition of the correlation functions of a bath.

Parameters:

type{“R”, “I”, “RI”, “+”, “-”} or BathExponent.ExponentType

The type of bath exponent.

“R” and “I” are bosonic bath exponents that appear in the real and imaginary parts of the correlation expansion.

“RI” is combined bosonic bath exponent that appears in both the real and imaginary parts of the correlation expansion. The combined exponent has a single vk. The ck is the coefficient in the real expansion and ck2 is the coefficient in the imaginary expansion.

“+” and “-” are fermionic bath exponents. These fermionic bath exponents must specify sigma_bar_k_offset which specifies the amount to add to k (the exponent index within the bath of this exponent) to determine the k of the corresponding exponent with the opposite sign (i.e. “-” or “+”).

dimint or None

The dimension (i.e. maximum number of excitations for this exponent). Usually 2 for fermionic exponents or None (i.e. unlimited) for bosonic exponents.

QQobj

The coupling operator for this excitation mode.

vkcomplex

The frequency of the exponent of the excitation term.

ckcomplex

The coefficient of the excitation term.

ck2optional, complex

For exponents of type “RI” this is the coefficient of the term in the imaginary expansion (and ck is the coefficient in the real expansion).

sigma_bar_k_offsetoptional, int

For exponents of type “+” this gives the offset (within the list of exponents within the bath) of the corresponding “-” bath exponent. For exponents of type “-” it gives the offset of the corresponding “+” exponent.

tagoptional, str, tuple or any other object

A label for the exponent (often the name of the bath). It defaults to None.

Attributes:

fermionicbool: True if the type of the exponent is a Fermionic type (i.e. either “+” or “-”) and False otherwise.
All of the parameters are also available as attributes.

types: alias of ExponentType

class Bath(exponents)[source]

Represents a list of bath expansion exponents.

Parameters:

exponentslist of BathExponent: The exponents of the correlation function describing the bath.

Attributes:

All of the parameters are available as attributes.

class BosonicBath(Q, ck_real, vk_real, ck_imag, vk_imag, combine=True, tag=None)[source]

A helper class for constructing a bosonic bath from the expansion coefficients and frequencies for the real and imaginary parts of the bath correlation function.

If the correlation functions C(t) is split into real and imaginary parts:

C(t) = C_real(t) + i * C_imag(t)

then:

C_real(t) = sum(ck_real * exp(- vk_real * t))
C_imag(t) = sum(ck_imag * exp(- vk_imag * t))

Defines the coefficients ck and the frequencies vk.

Note that the ck and vk may be complex, even through C_real(t) and C_imag(t) (i.e. the sum) is real.

Parameters:

QQobj: The coupling operator for the bath.
ck_reallist of complex: The coefficients of the expansion terms for the real part of the correlation function. The corresponding frequencies are passed as vk_real.
vk_reallist of complex: The frequencies (exponents) of the expansion terms for the real part of the correlation function. The corresponding ceofficients are passed as ck_real.
ck_imaglist of complex: The coefficients of the expansion terms in the imaginary part of the correlation function. The corresponding frequencies are passed as vk_imag.
vk_imaglist of complex: The frequencies (exponents) of the expansion terms for the imaginary part of the correlation function. The corresponding ceofficients are passed as ck_imag.
combinebool, default True: Whether to combine exponents with the same frequency (and coupling operator). See combine for details.
tagoptional, str, tuple or any other object: A label for the bath exponents (for example, the name of the bath). It defaults to None but can be set to help identify which bath an exponent is from.

classmethod combine(exponents, rtol=1e-05, atol=1e-07)[source]

Group bosonic exponents with the same frequency and return a single exponent for each frequency present.

Exponents with the same frequency are only combined if they share the same coupling operator .Q.

Note that combined exponents take their tag from the first exponent in the group being combined (i.e. the one that occurs first in the given exponents list).

Parameters:

exponentslist of BathExponent: The list of exponents to combine.
rtolfloat, default 1e-5: The relative tolerance to use to when comparing frequencies and coupling operators.
atolfloat, default 1e-7: The absolute tolerance to use to when comparing frequencies and coupling operators.

Returns:

list of BathExponent: The new reduced list of exponents.

class DrudeLorentzBath(Q, lam, gamma, T, Nk, combine=True, tag=None)[source]

A helper class for constructing a Drude-Lorentz bosonic bath from the bath parameters (see parameters below).

Parameters:

QQobj: Operator describing the coupling between system and bath.
lamfloat: Coupling strength.
gammafloat: Bath spectral density cutoff frequency.
Tfloat: Bath temperature.
Nkint: Number of exponential terms used to approximate the bath correlation functions.
combinebool, default True: Whether to combine exponents with the same frequency (and coupling operator). See BosonicBath.combine for details.
tagoptional, str, tuple or any other object: A label for the bath exponents (for example, the name of the bath). It defaults to None but can be set to help identify which bath an exponent is from.

terminator()[source]

Return the Matsubara terminator for the bath and the calculated approximation discrepancy.

Returns:

delta: float: The approximation discrepancy. That is, the difference between the true correlation function of the Drude-Lorentz bath and the sum of the Nk exponential terms is approximately 2 * delta * dirac(t), where dirac(t) denotes the Dirac delta function.
terminatorQobj: The Matsubara terminator – i.e. a liouvillian term representing the contribution to the system-bath dynamics of all exponential expansion terms beyond Nk. It should be used by adding it to the system liouvillian (i.e. liouvillian(H_sys)).

class DrudeLorentzPadeBath(Q, lam, gamma, T, Nk, combine=True, tag=None)[source]

A helper class for constructing a Padé expansion for a Drude-Lorentz bosonic bath from the bath parameters (see parameters below).

A Padé approximant is a sum-over-poles expansion ( see https://en.wikipedia.org/wiki/Pad%C3%A9_approximant).

The application of the Padé method to spectrum decompoisitions is described in “Padé spectrum decompositions of quantum distribution functions and optimal hierarchical equations of motion construction for quantum open systems” [1].

The implementation here follows the approach in the paper.

[1] J. Chem. Phys. 134, 244106 (2011); https://doi.org/10.1063/1.3602466

This is an alternative to the DrudeLorentzBath which constructs a simpler exponential expansion.

Parameters:

QQobj: Operator describing the coupling between system and bath.
lamfloat: Coupling strength.
gammafloat: Bath spectral density cutoff frequency.
Tfloat: Bath temperature.
Nkint: Number of Padé exponentials terms used to approximate the bath correlation functions.
combinebool, default True: Whether to combine exponents with the same frequency (and coupling operator). See BosonicBath.combine for details.
tagoptional, str, tuple or any other object: A label for the bath exponents (for example, the name of the bath). It defaults to None but can be set to help identify which bath an exponent is from.

terminator()[source]

Return the Padé terminator for the bath and the calculated approximation discrepancy.

Returns:

delta: float: The approximation discrepancy. That is, the difference between the true correlation function of the Drude-Lorentz bath and the sum of the Nk exponential terms is approximately 2 * delta * dirac(t), where dirac(t) denotes the Dirac delta function.
terminatorQobj: The Padé terminator – i.e. a liouvillian term representing the contribution to the system-bath dynamics of all exponential expansion terms beyond Nk. It should be used by adding it to the system liouvillian (i.e. liouvillian(H_sys)).

class UnderDampedBath(Q, lam, gamma, w0, T, Nk, combine=True, tag=None)[source]

A helper class for constructing an under-damped bosonic bath from the bath parameters (see parameters below).

Parameters:

QQobj: Operator describing the coupling between system and bath.
lamfloat: Coupling strength.
gammafloat: Bath spectral density cutoff frequency.
w0float: Bath spectral density resonance frequency.
Tfloat: Bath temperature.
Nkint: Number of exponential terms used to approximate the bath correlation functions.
combinebool, default True: Whether to combine exponents with the same frequency (and coupling operator). See BosonicBath.combine for details.
tagoptional, str, tuple or any other object: A label for the bath exponents (for example, the name of the bath). It defaults to None but can be set to help identify which bath an exponent is from.

class FermionicBath(Q, ck_plus, vk_plus, ck_minus, vk_minus, tag=None)[source]

A helper class for constructing a fermionic bath from the expansion coefficients and frequencies for the + and - modes of the bath correlation function.

There must be the same number of + and - modes and their coefficients must be specified in the same order so that ck_plus[i], vk_plus[i] are the plus coefficient and frequency corresponding to the minus mode ck_minus[i], vk_minus[i].

In the fermionic case the order in which excitations are created or destroyed is important, resulting in two different correlation functions labelled C_plus(t) and C_plus(t):

C_plus(t) = sum(ck_plus * exp(- vk_plus * t))
C_minus(t) = sum(ck_minus * exp(- vk_minus * t))

where the expansions above define the coeffiients ck and the frequencies vk.

Parameters:

QQobj: The coupling operator for the bath.
ck_pluslist of complex: The coefficients of the expansion terms for the + part of the correlation function. The corresponding frequencies are passed as vk_plus.
vk_pluslist of complex: The frequencies (exponents) of the expansion terms for the + part of the correlation function. The corresponding ceofficients are passed as ck_plus.
ck_minuslist of complex: The coefficients of the expansion terms for the - part of the correlation function. The corresponding frequencies are passed as vk_minus.
vk_minuslist of complex: The frequencies (exponents) of the expansion terms for the - part of the correlation function. The corresponding ceofficients are passed as ck_minus.
tagoptional, str, tuple or any other object: A label for the bath exponents (for example, the name of the bath). It defaults to None but can be set to help identify which bath an exponent is from.

class LorentzianBath(Q, gamma, w, mu, T, Nk, tag=None)[source]

A helper class for constructing a Lorentzian fermionic bath from the bath parameters (see parameters below).

Note

This Matsubara expansion used in this bath converges very slowly and Nk > 20 may be required to get good convergence. The Padé expansion used by LorentzianPadeBath converges much more quickly.

Parameters:

QQobj: Operator describing the coupling between system and bath.
gammafloat: The coupling strength between the system and the bath.
wfloat: The width of the environment.
mufloat: The chemical potential of the bath.
Tfloat: Bath temperature.
Nkint: Number of exponential terms used to approximate the bath correlation functions.
tagoptional, str, tuple or any other object: A label for the bath exponents (for example, the name of the bath). It defaults to None but can be set to help identify which bath an exponent is from.

class LorentzianPadeBath(Q, gamma, w, mu, T, Nk, tag=None)[source]

A helper class for constructing a Padé expansion for Lorentzian fermionic bath from the bath parameters (see parameters below).

A Padé approximant is a sum-over-poles expansion ( see https://en.wikipedia.org/wiki/Pad%C3%A9_approximant).

The application of the Padé method to spectrum decompoisitions is described in “Padé spectrum decompositions of quantum distribution functions and optimal hierarchical equations of motion construction for quantum open systems” [1].

The implementation here follows the approach in the paper.

[1] J. Chem. Phys. 134, 244106 (2011); https://doi.org/10.1063/1.3602466

This is an alternative to the LorentzianBath which constructs a simpler exponential expansion that converges much more slowly in this particular case.

Parameters:

QQobj: Operator describing the coupling between system and bath.
gammafloat: The coupling strength between the system and the bath.
wfloat: The width of the environment.
mufloat: The chemical potential of the bath.
Tfloat: Bath temperature.
Nkint: Number of exponential terms used to approximate the bath correlation functions.
tagoptional, str, tuple or any other object: A label for the bath exponents (for example, the name of the bath). It defaults to None but can be set to help identify which bath an exponent is from.

class HierarchyADOs(exponents, max_depth)[source]

A description of ADOs (auxilliary density operators) with the hierarchical equations of motion.

The list of ADOs is constructed from a list of bath exponents (corresponding to one or more baths). Each ADO is referred to by a label that lists the number of “excitations” of each bath exponent. The level of a label within the hierarchy is the sum of the “excitations” within the label.

For example the label (0, 0, ..., 0) represents the density matrix of the system being solved and is the only 0th level label.

The labels with a single 1, i.e. (1, 0, ..., 0), (0, 1, 0, ... 0), etc. are the 1st level labels.

The second level labels all have either two 1s or a single 2, and so on for the third and higher levels of the hierarchy.

Parameters:

exponentslist of BathExponent: The exponents of the correlation function describing the bath or baths.
max_depthint: The maximum depth of the hierarchy (i.e. the maximum sum of “excitations” in the hierarchy ADO labels or maximum ADO level).

Attributes:

exponentslist of BathExponent: The exponents of the correlation function describing the bath or baths.
max_depthint: The maximum depth of the hierarchy (i.e. the maximum sum of “excitations” in the hierarchy ADO labels).
dimslist of int: The dimensions of each exponent within the bath(s).
vklist of complex: The frequency of each exponent within the bath(s).
cklist of complex: The coefficient of each exponent within the bath(s).
ck2: list of complex: For exponents of type “RI”, the coefficient of the exponent within the imaginary expansion. For other exponent types, the entry is None.
sigma_bar_k_offset: list of int: For exponents of type “+” or “-” the offset within the list of modes of the corresponding “-” or “+” exponent. For other exponent types, the entry is None.
labels: list of tuples: A list of the ADO labels within the hierarchy.

exps(label)[source]

Converts an ADO label into a tuple of exponents, with one exponent for each “excitation” within the label.

The number of exponents returned is always equal to the level of the label within the hierarchy (i.e. the sum of the indices within the label).

Parameters:

labeltuple: The ADO label to convert to a list of exponents.

Returns:

tuple of BathExponent: A tuple of BathExponents.

Examples

ados.exps((1, 0, 0)) would return [ados.exponents[0]]

ados.exps((2, 0, 0)) would return [ados.exponents[0], ados.exponents[0]].

ados.exps((1, 2, 1)) would return [ados.exponents[0], ados.exponents[1], ados.exponents[1], ados.exponents[2]].

filter(level=None, tags=None, dims=None, types=None)[source]

Return a list of ADO labels for ADOs whose “excitations” match the given patterns.

Each of the filter parameters (tags, dims, types) may be either unspecified (None) or a list. Unspecified parameters are excluded from the filtering.

All specified filter parameters must be lists of the same length. Each position in the lists describes a particular excitation and any exponent that matches the filters may supply that excitation. The level of all labels returned is thus equal to the length of the filter parameter lists.

Within a filter parameter list, items that are None represent wildcards and match any value of that exponent attribute

Parameters:

levelint: The hierarchy depth to return ADOs from.
tagslist of object or None: Filter parameter that matches the .tag attribute of exponents.
dimslist of int: Filter parameter that matches the .dim attribute of exponents.
typeslist of BathExponent types or list of str: Filter parameter that matches the .type attribute of exponents. Types may be supplied by name (e.g. “R”, “I”, “+”) instead of by the actual type (e.g. BathExponent.types.R).

Returns:

list of tuple: The ADO label for each ADO whose exponent excitations (i.e. label) match the given filters or level.

idx(label)[source]

Return the index of the ADO label within the list of labels, i.e. within self.labels.

Parameters:

labeltuple: The label to look up.

Returns:

int: The index of the label within the list of ADO labels.

next(label, k)[source]

Return the ADO label with one more excitation in the k’th exponent dimension or None if adding the excitation would exceed the dimension or maximum depth of the hierarchy.

Parameters:

labeltuple: The ADO label to add an excitation to.
kint: The exponent to add the excitation to.

Returns:

tuple or None: The next label.

prev(label, k)[source]

Return the ADO label with one fewer excitation in the k’th exponent dimension or None if the label has no exciations in the k’th exponent.

Parameters:

labeltuple: The ADO label to remove the excitation from.
kint: The exponent to remove the excitation from.

Returns:

tuple or None: The previous label.

class HierarchyADOsState(rho, ados, ado_state)[source]

Provides convenient access to the full hierarchy ADO state at a particular point in time, t.

Parameters:

rhoQobj: The current state of the system (i.e. the 0th component of the hierarchy).
adosHierarchyADOs: The description of the hierarchy.
ado_statenumpy.array: The full state of the hierarchy.

Attributes:

rhoQobj: The system state.
In addition, all of the attributes of the hierarchy description,
i.e. ``HierarchyADOs``, are provided directly on this class for
convenience. E.g. one can access ``.labels``, or ``.exponents`` or
call ``.idx(label)`` directly.
See :class:`HierarchyADOs` for a full list of the available attributes
and methods.

extract(idx_or_label)[source]

Extract a Qobj representing the specified ADO from a full representation of the ADO states.

Parameters:

idxint or label: The index of the ADO to extract. If an ADO label, e.g. (0, 1, 0, ...) is supplied instead, then the ADO is extracted by label instead.

Returns:

Qobj: A Qobj representing the state of the specified ADO.

class HEOMResult(e_ops, options, *, solver=None, stats=None, **kw)[source]

Integrator

class IntegratorScipyAdams(system, options)[source]

Integrator using Scipy ode with zvode integrator using adams method. Ordinary Differential Equation solver by netlib (http://www.netlib.org/odepack).

Usable with method="adams"

property options

Supported options by zvode integrator:

atolfloat, default=1e-8: Absolute tolerance.
rtolfloat, default=1e-6: Relative tolerance.
orderint, default=12, ‘adams’ or 5, ‘bdf’: Order of integrator <=12 ‘adams’, <=5 ‘bdf’
nstepsint, default=2500: Max. number of internal steps/call.
first_stepfloat, default=0: Size of initial step (0 = automatic).
min_stepfloat, default=0: Minimum step size (0 = automatic).
max_stepfloat, default=0: Maximum step size (0 = automatic) When using pulses, change to half the thinest pulse otherwise it may be skipped.

class IntegratorScipyBDF(system, options)[source]

Integrator using Scipy ode with zvode integrator using bdf method. Ordinary Differential Equation solver by netlib (http://www.netlib.org/odepack).

Usable with method="bdf"

property options

Supported options by zvode integrator:

atolfloat, default=1e-8: Absolute tolerance.
rtolfloat, default=1e-6: Relative tolerance.
orderint, default=12, ‘adams’ or 5, ‘bdf’: Order of integrator <=12 ‘adams’, <=5 ‘bdf’
nstepsint, default=2500: Max. number of internal steps/call.
first_stepfloat, default=0: Size of initial step (0 = automatic).
min_stepfloat, default=0: Minimum step size (0 = automatic).
max_stepfloat, default=0: Maximum step size (0 = automatic) When using pulses, change to half the thinest pulse otherwise it may be skipped.

class IntegratorScipylsoda(system, options)[source]

Integrator using Scipy ode with lsoda integrator. ODE solver by netlib (http://www.netlib.org/odepack) Automatically choose between ‘Adams’ and ‘BDF’ methods to solve both stiff and non-stiff systems.

Usable with method="lsoda"

property options

Supported options by lsoda integrator:

atolfloat, default=1e-8: Absolute tolerance.
rtolfloat, default=1e-6: Relative tolerance.
nstepsint, default=2500: Max. number of internal steps/call.
max_order_nsint, default=12: Maximum order used in the nonstiff case (<= 12).
max_order_sint, default=5: Maximum order used in the stiff case (<= 5).
first_stepfloat, default=0: Size of initial step (0 = automatic).
max_stepfloat, default=0: Maximum step size (0 = automatic) When using pulses, change to half the thinest pulse otherwise it may be skipped.
min_stepfloat, default=0: Minimum step size (0 = automatic)

class IntegratorScipyDop853(system, options)[source]

Integrator using Scipy ode with dop853 integrator. Eight order runge-kutta method by Dormand & Prince. Use fortran implementation from [E. Hairer, S.P. Norsett and G. Wanner, Solving Ordinary Differential Equations i. Nonstiff Problems. 2nd edition. Springer Series in Computational Mathematics, Springer-Verlag (1993)].

Usable with method="dop853"

property options

Supported options by dop853 integrator:

atolfloat, default=1e-8: Absolute tolerance.
rtolfloat, default=1e-6: Relative tolerance.
nstepsint, default=2500: Max. number of internal steps/call.
first_stepfloat, default=0: Size of initial step (0 = automatic).
max_stepfloat, default=0: Maximum step size (0 = automatic)
ifactor, dfactorfloat, default=6., 0.3: Maximum factor to increase/decrease step size by in one step
betafloat, default=0: Beta parameter for stabilised step size control.

See scipy.integrate.ode ode for more detail

class IntegratorVern7(system, options)[source]

QuTiP’s implementation of Verner’s “most efficient” Runge-Kutta method of order 7. These are Runge-Kutta methods with variable steps and dense output.

The implementation uses QuTiP’s Data objects for the state, allowing sparse, GPU or other data layer objects to be used efficiently by the solver in their native formats.

See http://people.math.sfu.ca/~jverner/ for a detailed description of the methods.

Usable with method="vern7"

property options

Supported options by verner method:

atolfloat, default=1e-8: Absolute tolerance.
rtolfloat, default=1e-6: Relative tolerance.
nstepsint, default=1000: Max. number of internal steps/call.
first_stepfloat, default=0: Size of initial step (0 = automatic).
min_stepfloat, default=0: Minimum step size (0 = automatic).
max_stepfloat, default=0: Maximum step size (0 = automatic) When using pulses, change to half the thinest pulse otherwise it may be skipped.
interpolatebool, default=True: Whether to use interpolation step, faster most of the time.

class IntegratorVern9(system, options)[source]

QuTiP’s implementation of Verner’s “most efficient” Runge-Kutta method of order 9. These are Runge-Kutta methods with variable steps and dense output.

The implementation uses QuTiP’s Data objects for the state, allowing sparse, GPU or other data layer objects to be used efficiently by the solver in their native formats.

See http://people.math.sfu.ca/~jverner/ for a detailed description of the methods.

Usable with method="vern9"

property options

Supported options by verner method:

atolfloat, default=1e-8: Absolute tolerance.
rtolfloat, default=1e-6: Relative tolerance.
nstepsint, default=1000: Max. number of internal steps/call.
first_stepfloat, default=0: Size of initial step (0 = automatic).
min_stepfloat, default=0: Minimum step size (0 = automatic).
max_stepfloat, default=0: Maximum step size (0 = automatic) When using pulses, change to half the thinest pulse otherwise it may be skipped.
interpolatebool, default=True: Whether to use interpolation step, faster most of the time.

class IntegratorDiag(system, options)[source]

Integrator solving the ODE by diagonalizing the system and solving analytically. It can only solve constant system and has a long preparation time, but the integration is fast.

Usable with method="diag"

property options

Supported options by “diag” method:

eigensolver_dtypestr, default=”dense”: Qutip data type {“dense”, “csr”, etc.} to use when computing the eigenstates. The dense eigen solver is usually faster and more stable.

class IntegratorKrylov(system, options)[source]

Evolve the state vector (“psi0”) finding an approximation for the time evolution operator of Hamiltonian (“H”) by obtaining the projection of the time evolution operator on a set of small dimensional Krylov subspaces (m << dim(H)).

property options

Supported options by krylov method:

atolfloat, default=1e-7: Absolute tolerance.
nstepsint, default=100: Max. number of internal steps/call.
min_step, max_stepfloat, default=(1e-5, 1e5): Minimum and maximum step size.
krylov_dim: int, default=0: Dimension of Krylov approximation subspaces used for the time evolution approximation. If the defaut 0 is given, the dimension is calculated from the system size N, using min(int((N + 100)**0.5), N-1).
sub_system_tol: float, default=1e-7: Tolerance to detect a happy breakdown. A happy breakdown occurs when the initial ket is in a subspace of the Hamiltonian smaller than krylov_dim.
always_compute_step: bool, default=False: If True, the step length is computed each time a new Krylov subspace is computed. Otherwise it is computed only once when creating the integrator.

Stochastic Integrator

class RouchonSODE(rhs, options)[source]

Stochastic integration method keeping the positivity of the density matrix. See eq. (4) Pierre Rouchon and Jason F. Ralpha, Efficient Quantum Filtering for Quantum Feedback Control, arXiv:1410.5345 [quant-ph], Phys. Rev. A 91, 012118, (2015).

Order: strong 1

Note

This method should be used with very small dt. Unlike other methods that will return unphysical state (negative eigenvalues, Nans) when the time step is too large, this method will return state that seems normal.

property options

Supported options by Rouchon Stochastic Integrators:

dtfloat, default=0.001: Internal time step.
tolfloat, default=1e-7: Relative tolerance.

class EulerSODE(rhs, options)[source]

A simple generalization of the Euler method for ordinary differential equations to stochastic differential equations. Only solver which could take non-commuting sc_ops.

Order: 0.5

property options

Supported options by Explicit Stochastic Integrators:

dtfloat, default=0.001: Internal time step.
tolfloat, default=1e-10: Tolerance for the time steps.

class Milstein_SODE(rhs, options)[source]

An order 1.0 strong Taylor scheme. Better approximate numerical solution to stochastic differential equations. See eq. (3.12) of chapter 10.3 of Peter E. Kloeden and Exkhard Platen, Numerical Solution of Stochastic Differential Equations..

Order strong 1.0

property options

Supported options by Explicit Stochastic Integrators:

dtfloat, default=0.001: Internal time step.
tolfloat, default=1e-10: Tolerance for the time steps.

class Taylor1_5_SODE(rhs, options)[source]

Order 1.5 strong Taylor scheme. Solver with more terms of the Ito-Taylor expansion. See eq. (4.6) of chapter 10.4 of Peter E. Kloeden and Exkhard Platen, Numerical Solution of Stochastic Differential Equations.

Order strong 1.5

property options

Supported options by Order 1.5 strong Taylor Stochastic Integrators:

dtfloat, default=0.001: Internal time step.
tolfloat, default=1e-10: Relative tolerance.
derr_dtfloat, default=1e-6: Finite time difference used to compute the derrivative of the hamiltonian and sc_ops.

class Implicit_Milstein_SODE(rhs, options)[source]

An order 1.0 implicit strong Taylor scheme. Implicit Milstein scheme for the numerical simulation of stiff stochastic differential equations. Eq. (2.11) with alpha=0.5 of chapter 12.2 of Peter E. Kloeden and Exkhard Platen, Numerical Solution of Stochastic Differential Equations.

Order strong 1.0

property options

Supported options by Implicit Stochastic Integrators:

dtfloat, default=0.001: Internal time step.
tolfloat, default=1e-10: Tolerance for the time steps.
solve_methodstr, default=None: Method used for solver the Ax=b of the implicit step. Accept methods supported by qutip.core.data.solve. When the system is constant, the inverse of the matrix A can be used by entering inv.
solve_optionsdict, default={}: Options to pass to the call to qutip.core.data.solve.

class Implicit_Taylor1_5_SODE(rhs, options)[source]

Order 1.5 implicit strong Taylor scheme. Solver with more terms of the Ito-Taylor expansion. Eq. (2.18) with alpha=0.5 of chapter 12.2 of Peter E. Kloeden and Exkhard Platen, Numerical Solution of Stochastic Differential Equations.

Order strong 1.5

property options

Supported options by Implicit Order 1.5 strong Taylor Stochastic Integrators:

dtfloat, default=0.001: Internal time step.
tolfloat, default=1e-10: Tolerance for the time steps.
solve_methodstr, default=None: Method used for solver the Ax=b of the implicit step. Accept methods supported by qutip.core.data.solve. When the system is constant, the inverse of the matrix A can be used by entering inv.
solve_optionsdict, default={}: Options to pass to the call to qutip.core.data.solve.
derr_dtfloat, default=1e-6: Finite time difference used to compute the derrivative of the hamiltonian and sc_ops.

class PlatenSODE(rhs, options)[source]

Explicit scheme, creates the Milstein using finite differences instead of analytic derivatives. Also contains some higher order terms, thus converges better than Milstein while staying strong order 1.0. Does not require derivatives. See eq. (7.47) of chapter 7 of H.-P. Breuer and F. Petruccione, The Theory of Open Quantum Systems.

Order: strong 1, weak 2

property options

Supported options by Explicit Stochastic Integrators:

dtfloat, default=0.001: Internal time step.
tolfloat, default=1e-10: Tolerance for the time steps.

class Explicit1_5_SODE(rhs, options)[source]

Explicit order 1.5 strong schemes. Reproduce the order 1.5 strong Taylor scheme using finite difference instead of derivatives. Slower than taylor15 but usable when derrivatives cannot be analytically obtained. See eq. (2.13) of chapter 11.2 of Peter E. Kloeden and Exkhard Platen, Numerical Solution of Stochastic Differential Equations.

Order: strong 1.5

property options

Supported options by Explicit Stochastic Integrators:

dtfloat, default=0.001: Internal time step.
tolfloat, default=1e-10: Tolerance for the time steps.

class PredCorr_SODE(rhs, options)[source]

Generalization of the trapezoidal method to stochastic differential equations. More stable than explicit methods. See eq. (5.4) of chapter 15.5 of Peter E. Kloeden and Exkhard Platen, Numerical Solution of Stochastic Differential Equations.

Order strong 0.5, weak 1.0
Codes to only correct the stochastic part ($\alpha=0$, $\eta=1/2$): 'pred-corr', 'predictor-corrector' or 'pc-euler'
Codes to correct both the stochastic and deterministic parts ($\alpha=1/2$, $\eta=1/2$): 'pc-euler-imp', 'pc-euler-2' or 'pred-corr-2'

property options

Supported options by Explicit Stochastic Integrators:

dtfloat, default=0.001: Internal time step.
tolfloat, default=1e-10: Tolerance for the time steps.
alphafloat, default=0.: Implicit factor to the drift. eff_drift ~= drift(t) * (1-alpha) + drift(t+dt) * alpha
etafloat, default=0.5: Implicit factor to the diffusion. eff_diffusion ~= diffusion(t) * (1-eta) + diffusion(t+dt) * eta

Solver Options and Results

class Result(e_ops, options, *, solver=None, stats=None, **kw)[source]

Base class for storing solver results.

Parameters:

e_opsQobj, QobjEvo, function or list or dict of these

The e_ops parameter defines the set of values to record at each time step t. If an element is a Qobj or QobjEvo the value recorded is the expectation value of that operator given the state at t. If the element is a function, f, the value recorded is f(t, state).

The values are recorded in the e_data and expect attributes of this result object. e_data is a dictionary and expect is a list, where each item contains the values of the corresponding e_op.

optionsdict

The options for this result class.

solverstr or None

The name of the solver generating these results.

statsdict or None

The stats generated by the solver while producing these results. Note that the solver may update the stats directly while producing results.

kwdict

Additional parameters specific to a result sub-class.

Attributes:

timeslist

A list of the times at which the expectation values and states were recorded.

stateslist of Qobj

The state at each time t (if the recording of the state was requested).

final_stateQobj:

The final state (if the recording of the final state was requested).

expectlist of arrays of expectation values

A list containing the values of each e_op. The list is in the same order in which the e_ops were supplied and empty if no e_ops were given.

Each element is itself a list and contains the values of the corresponding e_op, with one value for each time in .times.

The same lists of values may be accessed via the .e_data dictionary and the original e_ops are available via the .e_ops attribute.

e_datadict

A dictionary containing the values of each e_op. If the e_ops were supplied as a dictionary, the keys are the same as in that dictionary. Otherwise the keys are the index of the e_op in the .expect list.

The lists of expectation values returned are the same lists as those returned by .expect.

e_opsdict

A dictionary containing the supplied e_ops as ExpectOp instances. The keys of the dictionary are the same as for .e_data. Each value is object where .e_ops[k](t, state) calculates the value of e_op k at time t and the given state, and .e_ops[k].op is the original object supplied to create the e_op.

solverstr or None

The name of the solver generating these results.

statsdict or None

The stats generated by the solver while producing these results.

optionsdict

The options for this result class.

add(t, state)[source]

Add a state to the results for the time t of the evolution.

Adding a state calculates the expectation value of the state for each of the supplied e_ops and stores the result in .expect.

The state is recorded in .states and .final_state if specified by the supplied result options.

Parameters:

tfloat

The time of the added state.

statetypically a Qobj

The state a time t. Usually this is a Qobj with suitable dimensions, but it sub-classes of result might support other forms of the state.

.. note::

The expectation values, i.e. e_ops, and states are recorded by the state processors (see .add_processor).

Additional processors may be added by sub-classes.

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 two-level systems.

hamiltonianqutip.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 qutip.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 two-level systems.

hamiltonianqutip.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:

lindbladianqutip.Qobj: The Lindbladian matrix as a qutip.Qobj.

liouvillian()[source]

Build the total Liouvillian using the Dicke basis.

Returns:

liouvqutip.Qobj: The Liouvillian matrix for the system.

pisolve(initial_state, tlist)[source]

Solve for diagonal Hamiltonians and initial states faster.

Parameters:

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

Returns:

result: list: A dictionary of the type qutip.piqs.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 two-level 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 two-level 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)[source]: Solve the ODE for the evolution of diagonal states and Hamiltonians.

tau1(j, m)[source]: Calculate coefficient matrix element relative to (j, m, m).

tau2(j, m)[source]: Calculate coefficient matrix element relative to (j, m+1, m+1).

tau3(j, m)[source]: Calculate coefficient matrix element relative to (j+1, m+1, m+1).

tau4(j, m)[source]: Calculate coefficient matrix element relative to (j-1, m+1, m+1).

tau5(j, m)[source]: Calculate coefficient matrix element relative to (j+1, m, m).

tau6(j, m)[source]: Calculate coefficient matrix element relative to (j-1, m, m).

tau7(j, m)[source]: Calculate coefficient matrix element relative to (j+1, m-1, m-1).

tau8(j, m)[source]: Calculate coefficient matrix element relative to (j, m-1, m-1).

tau9(j, m)[source]: Calculate coefficient matrix element relative to (j-1, m-1, m-1).

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.

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 reduced-dimensionality 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 WignerDistribution(rho=None, extent=[[-5, 5], [-5, 5]], steps=250)[source]

class QDistribution(rho=None, extent=[[-5, 5], [-5, 5]], steps=250)[source]

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 two-mode wavefunction or density matrix

update_psi(psi)[source]: calculate probability distribution for quadrature measurement outcomes given a two-mode wavefunction

update_rho(rho)[source]: calculate probability distribution for quadrature measurement outcomes given a two-mode density matrix

class HarmonicOscillatorWaveFunction(psi=None, omega=1.0, extent=[-5, 5], steps=250)[source]

update(psi)[source]: Calculate the wavefunction for the given state of an harmonic oscillator

class HarmonicOscillatorProbabilityFunction(rho=None, omega=1.0, extent=[-5, 5], steps=250)[source]

update(rho)[source]: Calculate the probability function for the given state of an harmonic oscillator (as density matrix)