# Functions

## Manipulation and Creation of States and Operators

### Quantum States

basis(dimensions, n=None, offset=None)

  Generates the vector representation of a Fock state.

  Parameters:
    dimensions int or list of ints

      Number of Fock states in Hilbert space. If a list, then the resultant object will be a tensor product over spaces with those dimensions.

    n int or list of ints, optional (default 0 for all dimensions)

      Integer corresponding to desired number state, defaults to 0 for all dimensions if omitted. The shape must match `dimensions`, e.g. if `dimensions` is a list, then `n` must either be omitted or a list of equal length.

    offset int or list of ints, optional (default 0 for all dimensions)

      The lowest number state that is included in the finite number state representation of the state in the relevant dimension.

  Returns:
    state `qutip.Qobj`

      Qobj representing the requested number state `|n>`.

  Notes

  A subtle incompatibility with the quantum optics toolbox: In QuTiP:

      basis(N, 0) = ground state

  but in the qotoolbox:

      basis(N, 1) = ground state

  Examples

      >>> basis(5,2)
      Quantum object: dims = [[5], [1]], shape = (5, 1), type = ket
      Qobj data =
      [[ 0.+0.j]
       [ 0.+0.j]
       [ 1.+0.j]
       [ 0.+0.j]
       [ 0.+0.j]]
      >>> basis([2,2,2], [0,1,0])
      Quantum object: dims = [[2, 2, 2], [1, 1, 1]], shape = (8, 1), type = ket
      Qobj data =
      [[0.]
       [0.]
       [1.]
       [0.]
       [0.]
       [0.]
       [0.]
       [0.]]

bell_state(state='00')

  Returns the selected Bell state:

  \[\begin{split}\begin{aligned} \lvert B_{00}\rangle &= \frac1{\sqrt2}(\lvert00\rangle+\lvert11\rangle)\\ \lvert B_{01}\rangle &= \frac1{\sqrt2}(\lvert00\rangle-\lvert11\rangle)\\ \lvert B_{10}\rangle &= \frac1{\sqrt2}(\lvert01\rangle+\lvert10\rangle)\\ \lvert B_{11}\rangle &= \frac1{\sqrt2}(\lvert01\rangle-\lvert10\rangle)\\ \end{aligned}\end{split}\]
  Returns:
    Bell_state qobj

      Bell state

bra(seq, dim=2)

  Produces a multiparticle bra state for a list or string, where each element stands for state of the respective particle.

  Parameters:
    seq str / list of ints or characters

      Each element defines state of the respective particle. (e.g. [1,1,0,1] or a string “1101”). For qubits it is also possible to use the following conventions:

      - ‘g’/’e’ (ground and excited state)

      - ‘u’/’d’ (spin up and down)

      - ‘H’/’V’ (horizontal and vertical polarization)

      Note: for dimension > 9 you need to use a list.

    dim int (default: 2) / list of ints

      Space dimension for each particle: int if there are the same, list if they are different.

  Returns:
    bra qobj

  Examples

      >>> bra("10")
      Quantum object: dims = [[1, 1], [2, 2]], shape = [1, 4], type = bra
      Qobj data =
      [[ 0.  0.  1.  0.]]

      >>> bra("Hue")
      Quantum object: dims = [[1, 1, 1], [2, 2, 2]], shape = [1, 8], type = bra
      Qobj data =
      [[ 0.  1.  0.  0.  0.  0.  0.  0.]]

      >>> bra("12", 3)
      Quantum object: dims = [[1, 1], [3, 3]], shape = [1, 9], type = bra
      Qobj data =
      [[ 0.  0.  0.  0.  0.  1.  0.  0.  0.]]

      >>> bra("31", [5, 2])
      Quantum object: dims = [[1, 1], [5, 2]], shape = [1, 10], type = bra
      Qobj data =
      [[ 0.  0.  0.  0.  0.  0.  0.  1.  0.  0.]]

coherent(N, alpha, offset=0, method=None)

  Generates a coherent state with eigenvalue alpha.

  Constructed using displacement operator on vacuum state.

  Parameters:
    N int

      Number of Fock states in Hilbert space.

    alpha float/complex

      Eigenvalue of coherent state.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the state. Using a non-zero offset will make the default method ‘analytic’.

    method string {‘operator’, ‘analytic’}

      Method for generating coherent state.

  Returns:
    state qobj

      Qobj quantum object for coherent state

  Notes

  Select method ‘operator’ (default) or ‘analytic’. With the ‘operator’ method, the coherent state is generated by displacing the vacuum state using the displacement operator defined in the truncated Hilbert space of size ‘N’. This method guarantees that the resulting state is normalized. With ‘analytic’ method the coherent state is generated using the analytical formula for the coherent state coefficients in the Fock basis. This method does not guarantee that the state is normalized if truncated to a small number of Fock states, but would in that case give more accurate coefficients.

  Examples

      >>> coherent(5,0.25j)
      Quantum object: dims = [[5], [1]], shape = [5, 1], type = ket
      Qobj data =
      [[  9.69233235e-01+0.j        ]
       [  0.00000000e+00+0.24230831j]
       [ -4.28344935e-02+0.j        ]
       [  0.00000000e+00-0.00618204j]
       [  7.80904967e-04+0.j        ]]

coherent_dm(N, alpha, offset=0, method=None)

  Density matrix representation of a coherent state.

  Constructed via outer product of `qutip.states.coherent`

  Parameters:
    N int

      Number of Fock states in Hilbert space.

    alpha float/complex

      Eigenvalue for coherent state.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the state.

    method string {‘operator’, ‘analytic’}

      Method for generating coherent density matrix.

  Returns:
    dm qobj

      Density matrix representation of coherent state.

  Notes

  Select method ‘operator’ (default) or ‘analytic’. With the ‘operator’ method, the coherent density matrix is generated by displacing the vacuum state using the displacement operator defined in the truncated Hilbert space of size ‘N’. This method guarantees that the resulting density matrix is normalized. With ‘analytic’ method the coherent density matrix is generated using the analytical formula for the coherent state coefficients in the Fock basis. This method does not guarantee that the state is normalized if truncated to a small number of Fock states, but would in that case give more accurate coefficients.

  Examples

      >>> coherent_dm(3,0.25j)
      Quantum object: dims = [[3], [3]], shape = [3, 3], type = oper, isHerm = True
      Qobj data =
      [[ 0.93941695+0.j          0.00000000-0.23480733j -0.04216943+0.j        ]
       [ 0.00000000+0.23480733j  0.05869011+0.j          0.00000000-0.01054025j]
       [-0.04216943+0.j          0.00000000+0.01054025j  0.00189294+0.j        ]]

enr_fock(dims, excitations, state)

  Generate the Fock state representation in a excitation-number restricted state space. The dims argument is a list of integers that define the number of quantums states of each component of a composite quantum system, and the excitations specifies the maximum number of excitations for the basis states that are to be included in the state space. The state argument is a tuple of integers that specifies the state (in the number basis representation) for which to generate the Fock state representation.

  Parameters:
    dims list

      A list of the dimensions of each subsystem of a composite quantum system.

    excitations integer

      The maximum number of excitations that are to be included in the state space.

    state list of integers

      The state in the number basis representation.

  Returns:
    ket Qobj

      A Qobj instance that represent a Fock state in the exication-number- restricted state space defined by dims and exciations.

enr_state_dictionaries(dims, excitations)

  Return the number of states, and lookup-dictionaries for translating a state tuple to a state index, and vice versa, for a system with a given number of components and maximum number of excitations.

  Parameters:
    dims: list

      A list with the number of states in each sub-system.

    excitations integer

      The maximum numbers of dimension

  Returns:
    nstates, state2idx, idx2state: integer, dict, list

      The number of states nstates, a dictionary for looking up state indices from a state tuple, and a list containing the state tuples ordered by state indices. state2idx and idx2state are reverses of each other, i.e., state2idx[idx2state[idx]] = idx and idx2state[state2idx[state]] = state.

enr_thermal_dm(dims, excitations, n)

  Generate the density operator for a thermal state in the excitation-number- restricted state space defined by the dims and exciations arguments. See the documentation for enr_fock for a more detailed description of these arguments. The temperature of each mode in dims is specified by the average number of excitatons n.

  Parameters:
    dims list

      A list of the dimensions of each subsystem of a composite quantum system.

    excitations integer

      The maximum number of excitations that are to be included in the state space.

    n integer

      The average number of exciations in the thermal state. n can be a float (which then applies to each mode), or a list/array of the same length as dims, in which each element corresponds specifies the temperature of the corresponding mode.

  Returns:
    dm Qobj

      Thermal state density matrix.

fock(dimensions, n=None, offset=None)

  Bosonic Fock (number) state.

  Same as `qutip.states.basis`.

  Parameters:
    dimensions int or list of ints

      Number of Fock states in Hilbert space. If a list, then the resultant object will be a tensor product over spaces with those dimensions.

    n int or list of ints, optional (default 0 for all dimensions)

      Integer corresponding to desired number state, defaults to 0 for all dimensions if omitted. The shape must match `dimensions`, e.g. if `dimensions` is a list, then `n` must either be omitted or a list of equal length.

    offset int or list of ints, optional (default 0 for all dimensions)

      The lowest number state that is included in the finite number state representation of the state in the relevant dimension.

  Returns:
    Requested number state \(\left|n\right>\).

  Examples

      >>> fock(4,3)
      Quantum object: dims = [[4], [1]], shape = [4, 1], type = ket
      Qobj data =
      [[ 0.+0.j]
       [ 0.+0.j]
       [ 0.+0.j]
       [ 1.+0.j]]

fock_dm(dimensions, n=None, offset=None)

  Density matrix representation of a Fock state

  Constructed via outer product of `qutip.states.fock`.

  Parameters:
    dimensions int or list of ints

      Number of Fock states in Hilbert space. If a list, then the resultant object will be a tensor product over spaces with those dimensions.

    n int or list of ints, optional (default 0 for all dimensions)

      Integer corresponding to desired number state, defaults to 0 for all dimensions if omitted. The shape must match `dimensions`, e.g. if `dimensions` is a list, then `n` must either be omitted or a list of equal length.

    offset int or list of ints, optional (default 0 for all dimensions)

      The lowest number state that is included in the finite number state representation of the state in the relevant dimension.

  Returns:
    dm qobj

      Density matrix representation of Fock state.

  Examples

      >>> fock_dm(3,1)
      Quantum object: dims = [[3], [3]], shape = [3, 3], type = oper, isHerm = True
      Qobj data =
      [[ 0.+0.j  0.+0.j  0.+0.j]
       [ 0.+0.j  1.+0.j  0.+0.j]
       [ 0.+0.j  0.+0.j  0.+0.j]]

ghz_state(N=3)

  Returns the N-qubit GHZ-state.

  Parameters:
    N int (default=3)

      Number of qubits in state

  Returns:
    G qobj

      N-qubit GHZ-state

ket(seq, dim=2)

  Produces a multiparticle ket state for a list or string, where each element stands for state of the respective particle.

  Parameters:
    seq str / list of ints or characters

      Each element defines state of the respective particle. (e.g. [1,1,0,1] or a string “1101”). For qubits it is also possible to use the following conventions: - ‘g’/’e’ (ground and excited state) - ‘u’/’d’ (spin up and down) - ‘H’/’V’ (horizontal and vertical polarization) Note: for dimension > 9 you need to use a list.

    dim int (default: 2) / list of ints

      Space dimension for each particle: int if there are the same, list if they are different.

  Returns:
    ket qobj

  Examples

      >>> ket("10")
      Quantum object: dims = [[2, 2], [1, 1]], shape = [4, 1], type = ket
      Qobj data =
      [[ 0.]
       [ 0.]
       [ 1.]
       [ 0.]]

      >>> ket("Hue")
      Quantum object: dims = [[2, 2, 2], [1, 1, 1]], shape = [8, 1], type = ket
      Qobj data =
      [[ 0.]
       [ 1.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 0.]]

      >>> ket("12", 3)
      Quantum object: dims = [[3, 3], [1, 1]], shape = [9, 1], type = ket
      Qobj data =
      [[ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 1.]
       [ 0.]
       [ 0.]
       [ 0.]]

      >>> ket("31", [5, 2])
      Quantum object: dims = [[5, 2], [1, 1]], shape = [10, 1], type = ket
      Qobj data =
      [[ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 1.]
       [ 0.]
       [ 0.]]

ket2dm(Q)

  Takes input ket or bra vector and returns density matrix formed by outer product.

  Parameters:
    Q qobj

      Ket or bra type quantum object.

  Returns:
    dm qobj

      Density matrix formed by outer product of Q.

  Examples

      >>> x=basis(3,2)
      >>> ket2dm(x)
      Quantum object: dims = [[3], [3]], shape = [3, 3], type = oper, isHerm = True
      Qobj data =
      [[ 0.+0.j  0.+0.j  0.+0.j]
       [ 0.+0.j  0.+0.j  0.+0.j]
       [ 0.+0.j  0.+0.j  1.+0.j]]

maximally_mixed_dm(N)

  Returns the maximally mixed density matrix for a Hilbert space of dimension N.

  Parameters:
    N int

      Number of basis states in Hilbert space.

  Returns:
    dm qobj

      Thermal state density matrix.

phase_basis(N, m, phi0=0)

  Basis vector for the mth phase of the Pegg-Barnett phase operator.

  Parameters:
    N int

      Number of basis vectors in Hilbert space.

    m int

      Integer corresponding to the mth discrete phase phi_m=phi0+2*pi*m/N

    phi0 float (default=0)

      Reference phase angle.

  Returns:
    state qobj

      Ket vector for mth Pegg-Barnett phase operator basis state.

  Notes

  The Pegg-Barnett basis states form a complete set over the truncated Hilbert space.

projection(N, n, m, offset=None)

  The projection operator that projects state \(\lvert m\rangle\) on state \(\lvert n\rangle\).

  Parameters:
    N int

      Number of basis states in Hilbert space.

    n, m float

      The number states in the projection.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the projector.

  Returns:
    oper qobj

      Requested projection operator.

qutrit_basis()

  Basis states for a three level system (qutrit)

  Returns:
    qstates array

      Array of qutrit basis vectors

singlet_state()

  Returns the two particle singlet-state:

  \[\lvert S\rangle = \frac1{\sqrt2}(\lvert01\rangle-\lvert10\rangle)\]

  that is identical to the fourth bell state.

  Returns:
    Bell_state qobj

      \(\lvert B_{11}\rangle\) Bell state

spin_coherent(j, theta, phi, type='ket')

  Generate the coherent spin state \(\lvert \theta, \phi\rangle\).

  Parameters:
    j float

      The spin of the state.

    theta float

      Angle from z axis.

    phi float

      Angle from x axis.

    type string {‘ket’, ‘bra’, ‘dm’}

      Type of state to generate.

  Returns:
    state qobj

      Qobj quantum object for spin coherent state

spin_state(j, m, type='ket')

  Generates the spin state \(\lvert j, m\rangle\), i.e. the eigenstate of the spin-j Sz operator with eigenvalue m.

  Parameters:
    j float

      The spin of the state ().

    m int

      Eigenvalue of the spin-j Sz operator.

    type string {‘ket’, ‘bra’, ‘dm’}

      Type of state to generate.

  Returns:
    state qobj

      Qobj quantum object for spin state

state_index_number(dims, index)

  Return a quantum number representation given a state index, for a system of composite structure defined by dims.

  Example

      >>> state_index_number([2, 2, 2], 6)
      [1, 1, 0]

  Parameters:
    dims list or array

      The quantum state dimensions array, as it would appear in a Qobj.

    index integer

      The index of the state in standard enumeration ordering.

  Returns:
    state tuple

      The state number tuple corresponding to index index in standard enumeration ordering.

state_number_enumerate(dims, excitations=None)

  An iterator that enumerates all the state number tuples (quantum numbers of the form (n1, n2, n3, …)) for a system with dimensions given by dims.

  Example

      >>> for state in state_number_enumerate([2,2]):
      >>>     print(state)
      ( 0  0 )
      ( 0  1 )
      ( 1  0 )
      ( 1  1 )

  Parameters:
    dims list or array

      The quantum state dimensions array, as it would appear in a Qobj.

    excitations integer (None)

      Restrict state space to states with excitation numbers below or equal to this value.

  Returns:
    state_number tuple

      Successive state number tuples that can be used in loops and other iterations, using standard state enumeration by definition.

state_number_index(dims, state)

  Return the index of a quantum state corresponding to state, given a system with dimensions given by dims.

  Example

      >>> state_number_index([2, 2, 2], [1, 1, 0])
      6

  Parameters:
    dims list or array

      The quantum state dimensions array, as it would appear in a Qobj.

    state list

      State number array.

  Returns:
    idx int

      The index of the state given by state in standard enumeration ordering.

state_number_qobj(dims, state)

  Return a Qobj representation of a quantum state specified by the state array state.

  Example

      >>> state_number_qobj([2, 2, 2], [1, 0, 1])
      Quantum object: dims = [[2, 2, 2], [1, 1, 1]], shape = [8, 1], type = ket
      Qobj data =
      [[ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 0.]
       [ 1.]
       [ 0.]
       [ 0.]]

  Parameters:
    dims list or array

      The quantum state dimensions array, as it would appear in a Qobj.

    state list

      State number array.

  Returns:
    state `qutip.Qobj`

      The state as a `qutip.Qobj` instance.

thermal_dm(N, n, method='operator')

  Density matrix for a thermal state of n particles

  Parameters:
    N int

      Number of basis states in Hilbert space.

    n float

      Expectation value for number of particles in thermal state.

    method string {‘operator’, ‘analytic’}

      `string` that sets the method used to generate the thermal state probabilities

  Returns:
    dm qobj

      Thermal state density matrix.

  Notes

  The ‘operator’ method (default) generates the thermal state using the truncated number operator `num(N)`. This is the method that should be used in computations. The ‘analytic’ method uses the analytic coefficients derived in an infinite Hilbert space. The analytic form is not necessarily normalized, if truncated too aggressively.

  Examples

      >>> thermal_dm(5, 1)
      Quantum object: dims = [[5], [5]], shape = [5, 5], type = oper, isHerm = True
      Qobj data =
      [[ 0.51612903  0.          0.          0.          0.        ]
       [ 0.          0.25806452  0.          0.          0.        ]
       [ 0.          0.          0.12903226  0.          0.        ]
       [ 0.          0.          0.          0.06451613  0.        ]
       [ 0.          0.          0.          0.          0.03225806]]

      >>> thermal_dm(5, 1, 'analytic')
      Quantum object: dims = [[5], [5]], shape = [5, 5], type = oper, isHerm = True
      Qobj data =
      [[ 0.5      0.       0.       0.       0.     ]
       [ 0.       0.25     0.       0.       0.     ]
       [ 0.       0.       0.125    0.       0.     ]
       [ 0.       0.       0.       0.0625   0.     ]
       [ 0.       0.       0.       0.       0.03125]]

triplet_states()

  Returns a list of the two particle triplet-states:

  \[\lvert T_1\rangle = \lvert11\rangle \lvert T_2\rangle = \frac1{\sqrt2}(\lvert01\rangle + \lvert10\rangle) \lvert T_3\rangle = \lvert00\rangle\]
  Returns:
    trip_states list

      2 particle triplet states

w_state(N=3)

  Returns the N-qubit W-state.

  Parameters:
    N int (default=3)

      Number of qubits in state

  Returns:
    W qobj

      N-qubit W-state

zero_ket(N, dims=None)

  Creates the zero ket vector with shape Nx1 and dimensions dims.

  Parameters:
    N int

      Hilbert space dimensionality

    dims list

      Optional dimensions if ket corresponds to a composite Hilbert space.

  Returns:
    zero_ket qobj

      Zero ket on given Hilbert space.

### Quantum Operators

This module contains functions for generating Qobj representation of a variety of commonly occuring quantum operators.

charge(Nmax, Nmin=None, frac=1)

  Generate the diagonal charge operator over charge states from Nmin to Nmax.

  Parameters:
    Nmax int

      Maximum charge state to consider.

    Nmin int (default = -Nmax)

      Lowest charge state to consider.

    frac float (default = 1)

      Specify fractional charge if needed.

  Returns:
    C Qobj

      Charge operator over [Nmin,Nmax].

  Notes

  New in version 3.2.

commutator(A, B, kind='normal')

  Return the commutator of kind kind (normal, anti) of the two operators A and B.

create(N, offset=0)

  Creation (raising) operator.

  Parameters:
    N int

      Dimension of Hilbert space.

  Returns:
    oper qobj

      Qobj for raising operator.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the operator.

  Examples

      >>> create(4)
      Quantum object: dims = [[4], [4]], shape = [4, 4], type = oper, isHerm = False
      Qobj data =
      [[ 0.00000000+0.j  0.00000000+0.j  0.00000000+0.j  0.00000000+0.j]
       [ 1.00000000+0.j  0.00000000+0.j  0.00000000+0.j  0.00000000+0.j]
       [ 0.00000000+0.j  1.41421356+0.j  0.00000000+0.j  0.00000000+0.j]
       [ 0.00000000+0.j  0.00000000+0.j  1.73205081+0.j  0.00000000+0.j]]

destroy(N, offset=0)

  Destruction (lowering) operator.

  Parameters:
    N int

      Dimension of Hilbert space.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the operator.

  Returns:
    oper qobj

      Qobj for lowering operator.

  Examples

      >>> destroy(4)
      Quantum object: dims = [[4], [4]], shape = [4, 4], type = oper, isHerm = False
      Qobj data =
      [[ 0.00000000+0.j  1.00000000+0.j  0.00000000+0.j  0.00000000+0.j]
       [ 0.00000000+0.j  0.00000000+0.j  1.41421356+0.j  0.00000000+0.j]
       [ 0.00000000+0.j  0.00000000+0.j  0.00000000+0.j  1.73205081+0.j]
       [ 0.00000000+0.j  0.00000000+0.j  0.00000000+0.j  0.00000000+0.j]]

displace(N, alpha, offset=0)

  Single-mode displacement operator.

  Parameters:
    N int

      Dimension of Hilbert space.

    alpha float/complex

      Displacement amplitude.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the operator.

  Returns:
    oper qobj

      Displacement operator.

  Examples

      >>> displace(4,0.25)
      Quantum object: dims = [[4], [4]], shape = [4, 4], type = oper, isHerm = False
      Qobj data =
      [[ 0.96923323+0.j -0.24230859+0.j  0.04282883+0.j -0.00626025+0.j]
       [ 0.24230859+0.j  0.90866411+0.j -0.33183303+0.j  0.07418172+0.j]
       [ 0.04282883+0.j  0.33183303+0.j  0.84809499+0.j -0.41083747+0.j]
       [ 0.00626025+0.j  0.07418172+0.j  0.41083747+0.j  0.90866411+0.j]]

enr_destroy(dims, excitations)

  Generate annilation operators for modes in a excitation-number-restricted state space. For example, consider a system consisting of 4 modes, each with 5 states. The total hilbert space size is 5**4 = 625. If we are only interested in states that contain up to 2 excitations, we only need to include states such as

  > (0, 0, 0, 0) (0, 0, 0, 1) (0, 0, 0, 2) (0, 0, 1, 0) (0, 0, 1, 1) (0, 0, 2, 0) …

  This function creates annihilation operators for the 4 modes that act within this state space:

  > a1, a2, a3, a4 = enr_destroy([5, 5, 5, 5], excitations=2)

  From this point onwards, the annihiltion operators a1, …, a4 can be used to setup a Hamiltonian, collapse operators and expectation-value operators, etc., following the usual pattern.

  Parameters:
    dims list

      A list of the dimensions of each subsystem of a composite quantum system.

    excitations integer

      The maximum number of excitations that are to be included in the state space.

  Returns:
    a_ops list of qobj

      A list of annihilation operators for each mode in the composite quantum system described by dims.

enr_identity(dims, excitations)

  Generate the identity operator for the excitation-number restricted state space defined by the dims and exciations arguments. See the docstring for enr_fock for a more detailed description of these arguments.

  Parameters:
    dims list

      A list of the dimensions of each subsystem of a composite quantum system.

    excitations integer

      The maximum number of excitations that are to be included in the state space.

    state list of integers

      The state in the number basis representation.

  Returns:
    op Qobj

      A Qobj instance that represent the identity operator in the exication-number-restricted state space defined by dims and exciations.

identity(dims)

  Identity operator. Alternative name to `qeye`.

  Parameters:
    dimensions(int) or (list of int) or (list of list of int)

      Dimension of Hilbert space. If provided as a list of ints, then the dimension is the product over this list, but the `dims` property of the new Qobj are set to this list. This can produce either oper or super depending on the passed dimensions.

  Returns:
    oper qobj

      Identity operator Qobj.

jmat(j, *args)

  Higher-order spin operators:

  Parameters:
    j float

      Spin of operator

    args str

      Which operator to return ‘x’,’y’,’z’,’+’,’-‘. If no args given, then output is [‘x’,’y’,’z’]

  Returns:
    jmat qobj / ndarray

      `qobj` for requested spin operator(s).

  Notes

  If no ‘args’ input, then returns array of [‘x’,’y’,’z’] operators.

  Examples

      >>> jmat(1)
      [ Quantum object: dims = [[3], [3]], shape = [3, 3], type = oper, isHerm = True
      Qobj data =
      [[ 0.          0.70710678  0.        ]
       [ 0.70710678  0.          0.70710678]
       [ 0.          0.70710678  0.        ]]
       Quantum object: dims = [[3], [3]], shape = [3, 3], type = oper, isHerm = True
      Qobj data =
      [[ 0.+0.j          0.-0.70710678j  0.+0.j        ]
       [ 0.+0.70710678j  0.+0.j          0.-0.70710678j]
       [ 0.+0.j          0.+0.70710678j  0.+0.j        ]]
       Quantum object: dims = [[3], [3]], shape = [3, 3], type = oper, isHerm = True
      Qobj data =
      [[ 1.  0.  0.]
       [ 0.  0.  0.]
       [ 0.  0. -1.]]]

momentum(N, offset=0)

  Momentum operator p=-1j/sqrt(2)*(a-a.dag())

  Parameters:
    N int

      Number of Fock states in Hilbert space.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the operator.

  Returns:
    oper qobj

      Momentum operator as Qobj.

num(N, offset=0)

  Quantum object for number operator.

  Parameters:
    N int

      The dimension of the Hilbert space.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the operator.

  Returns:
    oper: qobj

      Qobj for number operator.

  Examples

      >>> num(4)
      Quantum object: dims = [[4], [4]], shape = [4, 4], type = oper, isHerm = True
      Qobj data =
      [[0 0 0 0]
       [0 1 0 0]
       [0 0 2 0]
       [0 0 0 3]]

phase(N, phi0=0)

  Single-mode Pegg-Barnett phase operator.

  Parameters:
    N int

      Number of basis states in Hilbert space.

    phi0 float

      Reference phase.

  Returns:
    oper qobj

      Phase operator with respect to reference phase.

  Notes

  The Pegg-Barnett phase operator is Hermitian on a truncated Hilbert space.

position(N, offset=0)

  Position operator x=1/sqrt(2)*(a+a.dag())

  Parameters:
    N int

      Number of Fock states in Hilbert space.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the operator.

  Returns:
    oper qobj

      Position operator as Qobj.

qdiags(diagonals, offsets, dims=None, shape=None)

  Constructs an operator from an array of diagonals.

  Parameters:
    diagonals sequence of array_like

      Array of elements to place along the selected diagonals.

    offsets sequence of ints
      Sequence for diagonals to be set:

        - k=0 main diagonal

        - k>0 kth upper diagonal

        - k<0 kth lower diagonal

    dims list, optional

      Dimensions for operator

    shape list, tuple, optional

      Shape of operator. If omitted, a square operator large enough to contain the diagonals is generated.

  See also

  `scipy.sparse.diags`

    for usage information.

  Notes

  This function requires SciPy 0.11+.

  Examples

      >>> qdiags(sqrt(range(1, 4)), 1)
      Quantum object: dims = [[4], [4]], shape = [4, 4], type = oper, isherm = False
      Qobj data =
      [[ 0.          1.          0.          0.        ]
       [ 0.          0.          1.41421356  0.        ]
       [ 0.          0.          0.          1.73205081]
       [ 0.          0.          0.          0.        ]]

qeye(dimensions)

  Identity operator.

  Parameters:
    dimensions(int) or (list of int) or (list of list of int)

      Dimension of Hilbert space. If provided as a list of ints, then the dimension is the product over this list, but the `dims` property of the new Qobj are set to this list. This can produce either oper or super depending on the passed dimensions.

  Returns:
    oper qobj

      Identity operator Qobj.

  Examples

      >>> qeye(3)
      Quantum object: dims = [[3], [3]], shape = (3, 3), type = oper, isherm = True
      Qobj data =
      [[ 1.  0.  0.]
       [ 0.  1.  0.]
       [ 0.  0.  1.]]
      >>> qeye([2,2])
      Quantum object: dims = [[2, 2], [2, 2]], shape = (4, 4), type = oper, isherm = True
      Qobj data =
      [[1. 0. 0. 0.]
       [0. 1. 0. 0.]
       [0. 0. 1. 0.]
       [0. 0. 0. 1.]]

qutrit_ops()

  Operators for a three level system (qutrit).

  Returns:
    opers: array

      array of qutrit operators.

qzero(dimensions)

  Zero operator.

  Parameters:
    dimensions(int) or (list of int) or (list of list of int)

      Dimension of Hilbert space. If provided as a list of ints, then the dimension is the product over this list, but the `dims` property of the new Qobj are set to this list. This can produce either oper or super depending on the passed dimensions.

  Returns:
    qzero qobj

      Zero operator Qobj.

sigmam()

  Annihilation operator for Pauli spins.

  Examples

      >>> sigmam()
      Quantum object: dims = [[2], [2]], shape = [2, 2], type = oper, isHerm = False
      Qobj data =
      [[ 0.  0.]
       [ 1.  0.]]

sigmap()

  Creation operator for Pauli spins.

  Examples

      >>> sigmap()
      Quantum object: dims = [[2], [2]], shape = [2, 2], type = oper, isHerm = False
      Qobj data =
      [[ 0.  1.]
       [ 0.  0.]]

sigmax()

  Pauli spin 1/2 sigma-x operator

  Examples

      >>> sigmax()
      Quantum object: dims = [[2], [2]], shape = [2, 2], type = oper, isHerm = False
      Qobj data =
      [[ 0.  1.]
       [ 1.  0.]]

sigmay()

  Pauli spin 1/2 sigma-y operator.

  Examples

      >>> sigmay()
      Quantum object: dims = [[2], [2]], shape = [2, 2], type = oper, isHerm = True
      Qobj data =
      [[ 0.+0.j  0.-1.j]
       [ 0.+1.j  0.+0.j]]

sigmaz()

  Pauli spin 1/2 sigma-z operator.

  Examples

      >>> sigmaz()
      Quantum object: dims = [[2], [2]], shape = [2, 2], type = oper, isHerm = True
      Qobj data =
      [[ 1.  0.]
       [ 0. -1.]]

spin_Jm(j)

  Spin-j annihilation operator

  Parameters:
    j float

      Spin of operator

  Returns:
    op Qobj

      `qobj` representation of the operator.

spin_Jp(j)

  Spin-j creation operator

  Parameters:
    j float

      Spin of operator

  Returns:
    op Qobj

      `qobj` representation of the operator.

spin_Jx(j)

  Spin-j x operator

  Parameters:
    j float

      Spin of operator

  Returns:
    op Qobj

      `qobj` representation of the operator.

spin_Jy(j)

  Spin-j y operator

  Parameters:
    j float

      Spin of operator

  Returns:
    op Qobj

      `qobj` representation of the operator.

spin_Jz(j)

  Spin-j z operator

  Parameters:
    j float

      Spin of operator

  Returns:
    op Qobj

      `qobj` representation of the operator.

squeeze(N, z, offset=0)

  Single-mode Squeezing operator.

  Parameters:
    N int

      Dimension of hilbert space.

    z float/complex

      Squeezing parameter.

    offset int (default 0)

      The lowest number state that is included in the finite number state representation of the operator.

  Returns:
    oper `qutip.Qobj`

      Squeezing operator.

  Examples

      >>> squeeze(4, 0.25)
      Quantum object: dims = [[4], [4]], shape = [4, 4], type = oper, isHerm = False
      Qobj data =
      [[ 0.98441565+0.j  0.00000000+0.j  0.17585742+0.j  0.00000000+0.j]
       [ 0.00000000+0.j  0.95349007+0.j  0.00000000+0.j  0.30142443+0.j]
       [-0.17585742+0.j  0.00000000+0.j  0.98441565+0.j  0.00000000+0.j]
       [ 0.00000000+0.j -0.30142443+0.j  0.00000000+0.j  0.95349007+0.j]]

squeezing(a1, a2, z)

  Generalized squeezing operator.

  \[S(z) = \exp\left(\frac{1}{2}\left(z^*a_1a_2 - za_1^\dagger a_2^\dagger\right)\right)\]
  Parameters:
    a1 `qutip.Qobj`

      Operator 1.

    a2 `qutip.Qobj`

      Operator 2.

    z float/complex

      Squeezing parameter.

  Returns:
    oper `qutip.Qobj`

      Squeezing operator.

tunneling(N, m=1)

  Tunneling operator with elements of the form \(\sum |N><N+m| + |N+m><N|\).

  Parameters:
    N int

      Number of basis states in Hilbert space.

    m int (default = 1)

      Number of excitations in tunneling event.

  Returns:
    T Qobj

      Tunneling operator.

  Notes

  New in version 3.2.

### Quantum Objects

The Quantum Object (Qobj) class, for representing quantum states and operators, and related functions.

dag(A)

  Adjont operator (dagger) of a quantum object.

  Parameters:
    A `qutip.Qobj`

      Input quantum object.

  Returns:
    oper `qutip.Qobj`

      Adjoint of input operator

  Notes

  This function is for legacy compatibility only. It is recommended to use the `dag()` Qobj method.

dims(inpt)

  Returns the dims attribute of a quantum object.

  Parameters:
    inpt `qutip.Qobj`

      Input quantum object.

  Returns:
    dims list

      A `list` of the quantum objects dimensions.

  Notes

  This function is for legacy compatibility only. Using the Qobj.dims attribute is recommended.

isbra(Q)

  Determines if given quantum object is a bra-vector.

  Parameters:
    Q `qutip.Qobj`

      Quantum object

  Returns:
    isbra bool

      True if Qobj is bra-vector, False otherwise.

  Notes

  This function is for legacy compatibility only. Using the Qobj.isbra attribute is recommended.

  Examples

      >>> psi = basis(5,2)
      >>> isket(psi)
      False

isequal(A, B, tol=None)

  Determines if two qobj objects are equal to within given tolerance.

  Parameters:
    A `qutip.Qobj`

      Qobj one

    B `qutip.Qobj`

      Qobj two

    tol float

      Tolerence for equality to be valid

  Returns:
    isequal bool

      True if qobjs are equal, False otherwise.

  Notes

  This function is for legacy compatibility only. Instead, it is recommended to use the equality operator of Qobj instances instead: A == B.

isherm(Q)

  Determines if given operator is Hermitian.

  Parameters:
    Q `qutip.Qobj`

      Quantum object

  Returns:
    isherm bool

      True if operator is Hermitian, False otherwise.

  Notes

  This function is for legacy compatibility only. Using the Qobj.isherm attribute is recommended.

  Examples

      >>> a = destroy(4)
      >>> isherm(a)
      False

isket(Q)

  Determines if given quantum object is a ket-vector.

  Parameters:
    Q `qutip.Qobj`

      Quantum object

  Returns:
    isket bool

      True if qobj is ket-vector, False otherwise.

  Notes

  This function is for legacy compatibility only. Using the Qobj.isket attribute is recommended.

  Examples

      >>> psi = basis(5,2)
      >>> isket(psi)
      True

isoper(Q)

  Determines if given quantum object is a operator.

  Parameters:
    Q `qutip.Qobj`

      Quantum object

  Returns:
    isoper bool

      True if Qobj is operator, False otherwise.

  Notes

  This function is for legacy compatibility only. Using the Qobj.isoper attribute is recommended.

  Examples

      >>> a = destroy(5)
      >>> isoper(a)
      True

isoperbra(Q)

  Determines if given quantum object is an operator in row vector form (operator-bra).

  Parameters:
    Q `qutip.Qobj`

      Quantum object

  Returns:
    isoperbra bool

      True if Qobj is operator-bra, False otherwise.

  Notes

  This function is for legacy compatibility only. Using the Qobj.isoperbra attribute is recommended.

isoperket(Q)

  Determines if given quantum object is an operator in column vector form (operator-ket).

  Parameters:
    Q `qutip.Qobj`

      Quantum object

  Returns:
    isoperket bool

      True if Qobj is operator-ket, False otherwise.

  Notes

  This function is for legacy compatibility only. Using the Qobj.isoperket attribute is recommended.

issuper(Q)

  Determines if given quantum object is a super-operator.

  Parameters:
    Q `qutip.Qobj`

      Quantum object

  Returns:
    issuper bool

      True if Qobj is superoperator, False otherwise.

  Notes

  This function is for legacy compatibility only. Using the Qobj.issuper attribute is recommended.

ptrace(Q, sel)

  Partial trace of the Qobj with selected components remaining.

  Parameters:
    Q `qutip.Qobj`

      Composite quantum object.

    sel int/list

      An `int` or `list` of components to keep after partial trace.

  Returns:
    oper `qutip.Qobj`

      Quantum object representing partial trace with selected components remaining.

  Notes

  This function is for legacy compatibility only. It is recommended to use the `ptrace()` Qobj method.

qobj_list_evaluate(qobj_list, t, args)

  Deprecated: See Qobj.evaluate

shape(inpt)

  Returns the shape attribute of a quantum object.

  Parameters:
    inpt `qutip.Qobj`

      Input quantum object.

  Returns:
    shape list

      A `list` of the quantum objects shape.

  Notes

  This function is for legacy compatibility only. Using the Qobj.shape attribute is recommended.

### Random Operators and States

This module is a collection of random state and operator generators. The sparsity of the ouput Qobj’s is controlled by varing the density parameter.

rand_dm(N, density=0.75, pure=False, dims=None, seed=None)

  Creates a random NxN density matrix.

  Parameters:
    N int, ndarray, list

      If int, then shape of output operator. If list/ndarray then eigenvalues of generated density matrix.

    density float

      Density between [0,1] of output density matrix.

    dims list

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]].

    seed int

      Seed for the random number generator.

  Returns:
    oper qobj

      NxN density matrix quantum operator.

  Notes

  For small density matrices., choosing a low density will result in an error as no diagonal elements will be generated such that \(Tr(\rho)=1\).

rand_dm_ginibre(N=2, rank=None, dims=None, seed=None)

  Returns a Ginibre random density operator of dimension `dim` and rank `rank` by using the algorithm of [BCSZ08]. If `rank` is None, a full-rank (Hilbert-Schmidt ensemble) random density operator will be returned.

  Parameters:
    N int

      Dimension of the density operator to be returned.

    dims list

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]].

    rank int or None

      Rank of the sampled density operator. If None, a full-rank density operator is generated.

  Returns:
    rho Qobj

      An N × N density operator sampled from the Ginibre or Hilbert-Schmidt distribution.

rand_dm_hs(N=2, dims=None, seed=None)

  Returns a Hilbert-Schmidt random density operator of dimension `dim` and rank `rank` by using the algorithm of [BCSZ08].

  Parameters:
    N int

      Dimension of the density operator to be returned.

    dims list

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]].

  Returns:
    rho Qobj

      A dim × dim density operator sampled from the Ginibre or Hilbert-Schmidt distribution.

rand_herm(N, density=0.75, dims=None, pos_def=False, seed=None)

  Creates a random NxN sparse Hermitian quantum object.

  If ‘N’ is an integer, uses \(H=0.5*(X+X^{+})\) where \(X\) is a randomly generated quantum operator with a given density. Else uses complex Jacobi rotations when ‘N’ is given by an array.

  Parameters:
    N int, list/ndarray

      If int, then shape of output operator. If list/ndarray then eigenvalues of generated operator.

    density float

      Density between [0,1] of output Hermitian operator.

    dims list

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]].

    pos_def bool (default=False)

      Return a positive semi-definite matrix (by diagonal dominance).

    seed int

      seed for the random number generator

  Returns:
    oper qobj

      NxN Hermitian quantum operator.

  Notes

  If given a list/ndarray as input ‘N’, this function returns a random Hermitian object with eigenvalues given in the list/ndarray. This is accomplished via complex Jacobi rotations. While this method is ~50% faster than the corresponding (real only) Matlab code, it should not be repeatedly used for generating matrices larger than ~1000x1000.

rand_ket(N=None, density=1, dims=None, seed=None)

  Creates a random Nx1 sparse ket vector.

  Parameters:
    N int

      Number of rows for output quantum vector. If None, N is deduced from dims.

    density float

      Density between [0,1] of output ket state.

    dims list

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[1]].

    seed int

      Seed for the random number generator.

  Returns:
    oper qobj

      Nx1 ket quantum state vector.

  Raises:
    ValueError

      If neither N or dims are specified.

rand_ket_haar(N=None, dims=None, seed=None)

  Returns a Haar random pure state of dimension `dim` by applying a Haar random unitary to a fixed pure state.

  Parameters:
    N int

      Dimension of the state vector to be returned. If None, N is deduced from dims.

    dims list of ints, or None

      Dimensions of the resultant quantum object. If None, [[N],[1]] is used.

  Returns:
    psi Qobj

      A random state vector drawn from the Haar measure.

  Raises:
    ValueError

      If neither N or dims are specified.

rand_stochastic(N, density=0.75, kind='left', dims=None, seed=None)

  Generates a random stochastic matrix.

  Parameters:
    N int

      Dimension of matrix.

    density float

      Density between [0,1] of output density matrix.

    kind str (Default = ‘left’)

      Generate ‘left’ or ‘right’ stochastic matrix.

    dims list

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]].

  Returns:
    oper qobj

      Quantum operator form of stochastic matrix.

rand_super(N=5, dims=None, seed=None)

  Returns a randomly drawn superoperator acting on operators acting on N dimensions.

  Parameters:
    N int

      Square root of the dimension of the superoperator to be returned.

    dims list

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[[N],[N]], [[N],[N]]].

rand_super_bcsz(N=2, enforce_tp=True, rank=None, dims=None, seed=None)

  Returns a random superoperator drawn from the Bruzda et al ensemble for CPTP maps [BCSZ08]. Note that due to finite numerical precision, for ranks less than full-rank, zero eigenvalues may become slightly negative, such that the returned operator is not actually completely positive.

  Parameters:
    N int

      Square root of the dimension of the superoperator to be returned.

    enforce_tp bool

      If True, the trace-preserving condition of [BCSZ08] is enforced; otherwise only complete positivity is enforced.

    rank int or None

      Rank of the sampled superoperator. If None, a full-rank superoperator is generated.

    dims list

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[[N],[N]], [[N],[N]]].

  Returns:
    rho Qobj

      A superoperator acting on vectorized dim × dim density operators, sampled from the BCSZ distribution.

rand_unitary(N, density=0.75, dims=None, seed=None)

  Creates a random NxN sparse unitary quantum object.

  Uses \(\exp(-iH)\) where H is a randomly generated Hermitian operator.

  Parameters:
    N int

      Shape of output quantum operator.

    density float

      Density between [0,1] of output Unitary operator.

    dims list

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]].

  Returns:
    oper qobj

      NxN Unitary quantum operator.

rand_unitary_haar(N=2, dims=None, seed=None)

  Returns a Haar random unitary matrix of dimension `dim`, using the algorithm of [Mez07].

  Parameters:
    N int

      Dimension of the unitary to be returned.

    dims list of lists of int, or None

      Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]].

  Returns:
    U Qobj

      Unitary of dims `[[dim], [dim]]` drawn from the Haar measure.

### Three-Level Atoms

This module provides functions that are useful for simulating the three level atom with QuTiP. A three level atom (qutrit) has three states, which are linked by dipole transitions so that 1 <-> 2 <-> 3. Depending on there relative energies they are in the ladder, lambda or vee configuration. The structure of the relevant operators is the same for any of the three configurations:

    Ladder:          Lambda:                 Vee:
                                |two>                       |three>
      -------|three>           -------                      -------
         |                       / \             |one>         /
         |                      /   \           -------       /
         |                     /     \             \         /
      -------|two>            /       \             \       /
         |                   /         \             \     /
         |                  /           \             \   /
         |                 /        --------           \ /
      -------|one>      -------      |three>         -------
                         |one>                       |two>

References

The naming of qutip operators follows the convention in [1] .

[1]

Shore, B. W., “The Theory of Coherent Atomic Excitation”, Wiley, 1990.

Notes

Contributed by Markus Baden, Oct. 07, 2011

three_level_basis()

  Basis states for a three level atom.

  Returns:
    states array

      array of three level atom basis vectors.

three_level_ops()

  Operators for a three level system (qutrit)

  Returns:
    ops array

      array of three level operators.

### Superoperators and Liouvillians

lindblad_dissipator(a, b=None, data_only=False, chi=None)

  Lindblad dissipator (generalized) for a single pair of collapse operators (a, b), or for a single collapse operator (a) when b is not specified:

  \[\mathcal{D}[a,b]\rho = a \rho b^\dagger - \frac{1}{2}a^\dagger b\rho - \frac{1}{2}\rho a^\dagger b\]
  Parameters:
    a Qobj or QobjEvo

      Left part of collapse operator.

    b Qobj or QobjEvo (optional)

      Right part of collapse operator. If not specified, b defaults to a.

  Returns:
    D qobj, QobjEvo

      Lindblad dissipator superoperator.

liouvillian(H, c_ops=[], data_only=False, chi=None)

  Assembles the Liouvillian superoperator from a Hamiltonian and a `list` of collapse operators. Like liouvillian, but with an experimental implementation which avoids creating extra Qobj instances, which can be advantageous for large systems.

  Parameters:
    H Qobj or QobjEvo

      System Hamiltonian.

    c_ops array_like of Qobj or QobjEvo

      A `list` or `array` of collapse operators.

  Returns:
    L Qobj or QobjEvo

      Liouvillian superoperator.

operator_to_vector(op)

  Create a vector representation given a quantum operator in matrix form. The passed object should have a `Qobj.type` of ‘oper’ or ‘super’; this function is not designed for general-purpose matrix reshaping.

  Parameters:
    op Qobj or QobjEvo

      Quantum operator in matrix form. This must have a type of ‘oper’ or ‘super’.

  Returns:
    Qobj or QobjEvo

      The same object, but re-cast into a column-stacked-vector form of type ‘operator-ket’. The output is the same type as the passed object.

spost(A)

  Superoperator formed from post-multiplication by operator A

  Parameters:
    A Qobj or QobjEvo

      Quantum operator for post multiplication.

  Returns:
    super Qobj or QobjEvo

      Superoperator formed from input qauntum object.

spre(A)

  Superoperator formed from pre-multiplication by operator A.

  Parameters:
    A Qobj or QobjEvo

      Quantum operator for pre-multiplication.

  Returns:
    super :Qobj or QobjEvo

      Superoperator formed from input quantum object.

sprepost(A, B)

  Superoperator formed from pre-multiplication by operator A and post- multiplication of operator B.

  Parameters:
    A Qobj or QobjEvo

      Quantum operator for pre-multiplication.

    B Qobj or QobjEvo

      Quantum operator for post-multiplication.

  Returns:
    super Qobj or QobjEvo

      Superoperator formed from input quantum objects.

vector_to_operator(op)

  Create a matrix representation given a quantum operator in vector form. The passed object should have a `Qobj.type` of ‘operator-ket’; this function is not designed for general-purpose matrix reshaping.

  Parameters:
    op Qobj or QobjEvo

      Quantum operator in column-stacked-vector form. This must have a type of ‘operator-ket’.

  Returns:
    Qobj or QobjEvo

      The same object, but re-cast into “standard” operator form. The output is the same type as the passed object.

### Superoperator Representations

This module implements transformations between superoperator representations, including supermatrix, Kraus, Choi and Chi (process) matrix formalisms.

chi_to_choi(q_oper)

  Converts a Chi matrix to a Choi matrix.

  NOTE: this is only supported for qubits right now. Need to extend to Heisenberg-Weyl for other subsystem dimensions.

choi_to_chi(q_oper)

  Converts a Choi matrix to a Chi matrix in the Pauli basis.

  NOTE: this is only supported for qubits right now. Need to extend to Heisenberg-Weyl for other subsystem dimensions.

choi_to_kraus(q_oper, tol=1e-09)

  Takes a Choi matrix and returns a list of Kraus operators. TODO: Create a new class structure for quantum channels, perhaps as a strict sub-class of Qobj.

choi_to_super(q_oper)

  Takes a Choi matrix to a superoperator TODO: Sanitize input, Abstract-ify application of channels to states

kraus_to_choi(kraus_ops)

  Convert a list of Kraus operators into Choi representation of the channel.

  Essentially, kraus operators are a decomposition of a Choi matrix, so in this function we build Choi matrix from vector representation of Kraus operators.

  Parameters:
    kraus_ops list[Qobj]

      The list of Kraus operators to be converted to Choi representation.

  Returns:
    choi Qobj

      A quantum object representing the same map as `kraus_ops`, such that `choi.superrep == "choi"`.

kraus_to_super(kraus_list)

  Converts a list of Kraus operators and returns a super operator.

super_to_choi(q_oper)

  Takes a superoperator to a Choi matrix TODO: Sanitize input, incorporate as method on Qobj if type==’super’

to_chi(q_oper)

  Converts a Qobj representing a quantum map to a representation as a chi (process) matrix in the Pauli basis, such that the trace of the returned operator is equal to the dimension of the system.

  Parameters:
    q_oper Qobj

      Superoperator to be converted to Chi representation. If `q_oper` is `type="oper"`, then it is taken to act by conjugation, such that `to_chi(A) == to_chi(sprepost(A, A.dag()))`.

  Returns:
    chi Qobj

      A quantum object representing the same map as `q_oper`, such that `chi.superrep == "chi"`.

  Raises:
    TypeError: if the given quantum object is not a map, or cannot be converted

      to Chi representation.

to_choi(q_oper)

  Converts a Qobj representing a quantum map to the Choi representation, such that the trace of the returned operator is equal to the dimension of the system.

  Parameters:
    q_oper Qobj

      Superoperator to be converted to Choi representation. If `q_oper` is `type="oper"`, then it is taken to act by conjugation, such that `to_choi(A) == to_choi(sprepost(A, A.dag()))`.

  Returns:
    choi Qobj

      A quantum object representing the same map as `q_oper`, such that `choi.superrep == "choi"`.

  Raises:
    TypeError: if the given quantum object is not a map, or cannot be converted

      to Choi representation.

to_kraus(q_oper, tol=1e-09)

  Converts a Qobj representing a quantum map to a list of quantum objects, each representing an operator in the Kraus decomposition of the given map.

  Parameters:
    q_oper Qobj

      Superoperator to be converted to Kraus representation. If `q_oper` is `type="oper"`, then it is taken to act by conjugation, such that `to_kraus(A) == to_kraus(sprepost(A, A.dag())) == [A]`.

    tol Float

      Optional threshold parameter for eigenvalues/Kraus ops to be discarded. The default is to=1e-9.

  Returns:
    kraus_ops list of Qobj

      A list of quantum objects, each representing a Kraus operator in the decomposition of `q_oper`.

  Raises:
    TypeError: if the given quantum object is not a map, or cannot be

      decomposed into Kraus operators.

to_stinespring(q_oper)

  Converts a Qobj representing a quantum map $Lambda$ to a pair of partial isometries $A$ and $B$ such that $Lambda(X) = Tr_2(A X B^dagger)$ for all inputs $X$, where the partial trace is taken over a a new index on the output dimensions of $A$ and $B$.

  For completely positive inputs, $A$ will always equal $B$ up to precision errors.

  Parameters:
    q_oper Qobj

      Superoperator to be converted to a Stinespring pair.

  Returns:
    A, B Qobj

      Quantum objects representing each of the Stinespring matrices for the input Qobj.

to_super(q_oper)

  Converts a Qobj representing a quantum map to the supermatrix (Liouville) representation.

  Parameters:
    q_oper Qobj

      Superoperator to be converted to supermatrix representation. If `q_oper` is `type="oper"`, then it is taken to act by conjugation, such that `to_super(A) == sprepost(A, A.dag())`.

  Returns:
    superop Qobj

      A quantum object representing the same map as `q_oper`, such that `superop.superrep == "super"`.

  Raises:
    TypeError

      If the given quantum object is not a map, or cannot be converted to supermatrix representation.

### Operators and Superoperator Dimensions

Internal use module for manipulating dims specifications.

collapse_dims_oper(dims)

  Given the dimensions specifications for a ket-, bra- or oper-type Qobj, returns a dimensions specification describing the same shape by collapsing all composite systems. For instance, the bra-type dimensions specification `[[2, 3], [1]]` collapses to `[[6], [1]]`.

  Parameters:
    dims list of lists of ints

      Dimensions specifications to be collapsed.

  Returns:
    collapsed_dims list of lists of ints

      Collapsed dimensions specification describing the same shape such that `len(collapsed_dims[0]) == len(collapsed_dims[1]) == 1`.

collapse_dims_super(dims)

  Given the dimensions specifications for an operator-ket-, operator-bra- or super-type Qobj, returns a dimensions specification describing the same shape by collapsing all composite systems. For instance, the super-type dimensions specification `[[[2, 3], [2, 3]], [[2, 3], [2, 3]]]` collapses to `[[[6], [6]], [[6], [6]]]`.

  Parameters:
    dims list of lists of ints

      Dimensions specifications to be collapsed.

  Returns:
    collapsed_dims list of lists of ints

      Collapsed dimensions specification describing the same shape such that `len(collapsed_dims[i][j]) == 1` for `i` and `j` in `range(2)`.

deep_remove(l, *what)

  Removes scalars from all levels of a nested list.

  Given a list containing a mix of scalars and lists, returns a list of the same structure, but where one or more scalars have been removed.

  Examples

      >>> deep_remove([[[[0, 1, 2]], [3, 4], [5], [6, 7]]], 0, 5)
      [[[[1, 2]], [3, 4], [], [6, 7]]]

dims_idxs_to_tensor_idxs(dims, indices)

  Given the dims of a Qobj instance, and some indices into dims, returns the corresponding tensor indices. This helps resolve, for instance, that column-stacking for superoperators, oper-ket and oper-bra implies that the input and output tensor indices are reversed from their order in dims.

  Parameters:
    dims list

      Dimensions specification for a Qobj.

    indices int, list or tuple

      Indices to convert to tensor indices. Can be specified as a single index, or as a collection of indices. In the latter case, this can be nested arbitrarily deep. For instance, [0, [0, (2, 3)]].

  Returns:
    tens_indices int, list or tuple

      Container of the same structure as indices containing the tensor indices for each element of indices.

dims_to_tensor_perm(dims)

  Given the dims of a Qobj instance, returns a list representing a permutation from the flattening of that dims specification to the corresponding tensor indices.

  Parameters:
    dims list

      Dimensions specification for a Qobj.

  Returns:
    perm list

      A list such that `data[flatten(dims)[idx]]` gives the index of the tensor `data` corresponding to the `idx``th dimension of ``dims`.

dims_to_tensor_shape(dims)

  Given the dims of a Qobj instance, returns the shape of the corresponding tensor. This helps, for instance, resolve the column-stacking convention for superoperators.

  Parameters:
    dims list

      Dimensions specification for a Qobj.

  Returns:
    tensor_shape tuple

      NumPy shape of the corresponding tensor.

enumerate_flat(l)

  Labels the indices at which scalars occur in a flattened list.

  Given a list containing a mix of scalars and lists, returns a list of the same structure, where each scalar has been replaced by an index into the flattened list.

  Examples

      >>> print(enumerate_flat([[[10], [20, 30]], 40]))
      [[[0], [1, 2]], 3]

flatten(l)

  Flattens a list of lists to the first level.

  Given a list containing a mix of scalars and lists, flattens down to a list of the scalars within the original list.

  Examples

      >>> flatten([[[0], 1], 2])
      [0, 1, 2]

is_scalar(dims)

  Returns True if a dims specification is effectively a scalar (has dimension 1).

unflatten(l, idxs)

  Unflattens a list by a given structure.

  Given a list of scalars and a deep list of indices as produced by flatten, returns an “unflattened” form of the list. This perfectly inverts flatten.

  Examples

      >>> l = [[[10, 20, 30], [40, 50, 60]], [[70, 80, 90], [100, 110, 120]]]
      >>> idxs = enumerate_flat(l)
      >>> unflatten(flatten(l), idxs) == l
      True

## Functions acting on states and operators

### Expectation Values

expect(oper, state)

  Calculates the expectation value for operator(s) and state(s).

  Parameters:
    oper qobj/array-like

      A single or a list or operators for expectation value.

    state qobj/array-like

      A single or a list of quantum states or density matrices.

  Returns:
    expt float/complex/array-like

      Expectation value. `real` if oper is Hermitian, `complex` otherwise. A (nested) array of expectaction values of state or operator are arrays.

  Examples

      >>> expect(num(4), basis(4, 3)) == 3
          True

variance(oper, state)

  Variance of an operator for the given state vector or density matrix.

  Parameters:
    oper qobj

      Operator for expectation value.

    state qobj/list

      A single or list of quantum states or density matrices..

  Returns:
    var float

      Variance of operator ‘oper’ for given state.

### Tensor

Module for the creation of composite quantum objects via the tensor product.

composite(*args)

  Given two or more operators, kets or bras, returns the Qobj corresponding to a composite system over each argument. For ordinary operators and vectors, this is the tensor product, while for superoperators and vectorized operators, this is the column-reshuffled tensor product.

  If a mix of Qobjs supported on Hilbert and Liouville spaces are passed in, the former are promoted. Ordinary operators are assumed to be unitaries, and are promoted using `to_super`, while kets and bras are promoted by taking their projectors and using `operator_to_vector(ket2dm(arg))`.

super_tensor(*args)

  Calculates the tensor product of input superoperators, by tensoring together the underlying Hilbert spaces on which each vectorized operator acts.

  Parameters:
    args array_like

      `list` or `array` of quantum objects with `type="super"`.

  Returns:
    obj qobj

      A composite quantum object.

tensor(*args)

  Calculates the tensor product of input operators.

  Parameters:
    args array_like

      `list` or `array` of quantum objects for tensor product.

  Returns:
    obj qobj

      A composite quantum object.

  Examples

      >>> tensor([sigmax(), sigmax()])
      Quantum object: dims = [[2, 2], [2, 2]], shape = [4, 4], type = oper, isHerm = True
      Qobj data =
      [[ 0.+0.j  0.+0.j  0.+0.j  1.+0.j]
       [ 0.+0.j  0.+0.j  1.+0.j  0.+0.j]
       [ 0.+0.j  1.+0.j  0.+0.j  0.+0.j]
       [ 1.+0.j  0.+0.j  0.+0.j  0.+0.j]]

tensor_contract(qobj, *pairs)

  Contracts a qobj along one or more index pairs. Note that this uses dense representations and thus should not be used for very large Qobjs.

  Parameters:
    pairs tuple

      One or more tuples `(i, j)` indicating that the `i` and `j` dimensions of the original qobj should be contracted.

  Returns:
    cqobj Qobj

      The original Qobj with all named index pairs contracted away.

### Partial Transpose

partial_transpose(rho, mask, method='dense')

  Return the partial transpose of a Qobj instance rho, where mask is an array/list with length that equals the number of components of rho (that is, the length of rho.dims[0]), and the values in mask indicates whether or not the corresponding subsystem is to be transposed. The elements in mask can be boolean or integers 0 or 1, where True/1 indicates that the corresponding subsystem should be tranposed.

  Parameters:
    rho `qutip.qobj`

      A density matrix.

    mask list / array

      A mask that selects which subsystems should be transposed.

    method str

      choice of method, dense or sparse. The default method is dense. The sparse implementation can be faster for large and sparse systems (hundreds of quantum states).

  Returns:
    rho_pr: `qutip.qobj`

      A density matrix with the selected subsystems transposed.

### Entropy Functions

concurrence(rho)

  Calculate the concurrence entanglement measure for a two-qubit state.

  Parameters:
    state qobj

      Ket, bra, or density matrix for a two-qubit state.

  Returns:
    concur float

      Concurrence

  References

  [1]

  https://en.wikipedia.org/wiki/Concurrence_(quantum_computing)

entropy_conditional(rho, selB, base=2.718281828459045, sparse=False)

  Calculates the conditional entropy \(S(A|B)=S(A,B)-S(B)\) of a selected density matrix component.

  Parameters:
    rho qobj

      Density matrix of composite object

    selB int/list

      Selected components for density matrix B

    base{e,2}

      Base of logarithm.

    sparse{False,True}

      Use sparse eigensolver.

  Returns:
    ent_cond float

      Value of conditional entropy

entropy_linear(rho)

  Linear entropy of a density matrix.

  Parameters:
    rho qobj

      sensity matrix or ket/bra vector.

  Returns:
    entropy float

      Linear entropy of rho.

  Examples

      >>> rho=0.5*fock_dm(2,0)+0.5*fock_dm(2,1)
      >>> entropy_linear(rho)
      0.5

entropy_mutual(rho, selA, selB, base=2.718281828459045, sparse=False)

  Calculates the mutual information S(A:B) between selection components of a system density matrix.

  Parameters:
    rho qobj

      Density matrix for composite quantum systems

    selA int/list

      int or list of first selected density matrix components.

    selB int/list

      int or list of second selected density matrix components.

    base{e,2}

      Base of logarithm.

    sparse{False,True}

      Use sparse eigensolver.

  Returns:
    ent_mut float

      Mutual information between selected components.

entropy_relative(rho, sigma, base=2.718281828459045, sparse=False, tol=1e-12)

  Calculates the relative entropy S(rho||sigma) between two density matrices.

  Parameters:
    rho `qutip.Qobj`

      First density matrix (or ket which will be converted to a density matrix).

    sigma `qutip.Qobj`

      Second density matrix (or ket which will be converted to a density matrix).

    base{e,2}

      Base of logarithm. Defaults to e.

    sparse bool

      Flag to use sparse solver when determining the eigenvectors of the density matrices. Defaults to False.

    tol float

      Tolerance to use to detect 0 eigenvalues or dot producted between eigenvectors. Defaults to 1e-12.

  Returns:
    rel_ent float

      Value of relative entropy. Guaranteed to be greater than zero and should equal zero only when rho and sigma are identical.

  References

  See Nielsen & Chuang, “Quantum Computation and Quantum Information”, Section 11.3.1, pg. 511 for a detailed explanation of quantum relative entropy.

  Examples

  First we define two density matrices:

      >>> rho = qutip.ket2dm(qutip.ket("00"))
      >>> sigma = rho + qutip.ket2dm(qutip.ket("01"))
      >>> sigma = sigma.unit()

  Then we calculate their relative entropy using base 2 (i.e. `log2`) and base e (i.e. `log`).

      >>> qutip.entropy_relative(rho, sigma, base=2)
      1.0
      >>> qutip.entropy_relative(rho, sigma)
      0.6931471805599453

entropy_vn(rho, base=2.718281828459045, sparse=False)

  Von-Neumann entropy of density matrix

  Parameters:
    rho qobj

      Density matrix.

    base{e,2}

      Base of logarithm.

    sparse{False,True}

      Use sparse eigensolver.

  Returns:
    entropy float

      Von-Neumann entropy of rho.

  Examples

      >>> rho=0.5*fock_dm(2,0)+0.5*fock_dm(2,1)
      >>> entropy_vn(rho,2)
      1.0

### Density Matrix Metrics

This module contains a collection of functions for calculating metrics (distance measures) between states and operators.

average_gate_fidelity(oper, target=None)

  Given a Qobj representing the supermatrix form of a map, returns the average gate fidelity (pseudo-metric) of that map.

  Parameters:
    A Qobj

      Quantum object representing a superoperator.

    target Qobj

      Quantum object representing the target unitary; the inverse is applied before evaluating the fidelity.

  Returns:
    fid float

      Fidelity pseudo-metric between A and the identity superoperator, or between A and the target superunitary.

bures_angle(A, B)

  Returns the Bures Angle between two density matrices A & B.

  The Bures angle ranges from 0, for states with unit fidelity, to pi/2.

  Parameters:
    A qobj

      Density matrix or state vector.

    B qobj

      Density matrix or state vector with same dimensions as A.

  Returns:
    angle float

      Bures angle between density matrices.

bures_dist(A, B)

  Returns the Bures distance between two density matrices A & B.

  The Bures distance ranges from 0, for states with unit fidelity, to sqrt(2).

  Parameters:
    A qobj

      Density matrix or state vector.

    B qobj

      Density matrix or state vector with same dimensions as A.

  Returns:
    dist float

      Bures distance between density matrices.

dnorm(A, B=None, solver='CVXOPT', verbose=False, force_solve=False, sparse=True)

  Calculates the diamond norm of the quantum map q_oper, using the simplified semidefinite program of [Wat13].

  The diamond norm SDP is solved by using CVXPY.

  Parameters:
    A Qobj

      Quantum map to take the diamond norm of.

    B Qobj or None

      If provided, the diamond norm of \(A - B\) is taken instead.

    solver str

      Solver to use with CVXPY. One of “CVXOPT” (default) or “SCS”. The latter tends to be significantly faster, but somewhat less accurate.

    verbose bool

      If True, prints additional information about the solution.

    force_solve bool

      If True, forces dnorm to solve the associated SDP, even if a special case is known for the argument.

    sparse bool

      Whether to use sparse matrices in the convex optimisation problem. Default True.

  Returns:
    dn float

      Diamond norm of q_oper.

  Raises:
    ImportError

      If CVXPY cannot be imported.

fidelity(A, B)

  Calculates the fidelity (pseudo-metric) between two density matrices. See: Nielsen & Chuang, “Quantum Computation and Quantum Information”

  Parameters:
    A qobj

      Density matrix or state vector.

    B qobj

      Density matrix or state vector with same dimensions as A.

  Returns:
    fid float

      Fidelity pseudo-metric between A and B.

  Examples

      >>> x = fock_dm(5,3)
      >>> y = coherent_dm(5,1)
      >>> np.testing.assert_almost_equal(fidelity(x,y), 0.24104350624628332)

hellinger_dist(A, B, sparse=False, tol=0)

  Calculates the quantum Hellinger distance between two density matrices.

  Formula: hellinger_dist(A, B) = sqrt(2-2*Tr(sqrt(A)*sqrt(B)))

  See: D. Spehner, F. Illuminati, M. Orszag, and W. Roga, “Geometric measures of quantum correlations with Bures and Hellinger distances” arXiv:1611.03449

  Parameters:
    A `qutip.Qobj`

      Density matrix or state vector.

    B `qutip.Qobj`

      Density matrix or state vector with same dimensions as A.

    tol float

      Tolerance used by sparse eigensolver, if used. (0=Machine precision)

    sparse{False, True}

      Use sparse eigensolver.

  Returns:
    hellinger_dist float

      Quantum Hellinger distance between A and B. Ranges from 0 to sqrt(2).

  Examples

      >>> x=fock_dm(5,3)
      >>> y=coherent_dm(5,1)
      >>> np.testing.assert_almost_equal(hellinger_dist(x,y), 1.3725145002591095)

hilbert_dist(A, B)

  Returns the Hilbert-Schmidt distance between two density matrices A & B.

  Parameters:
    A qobj

      Density matrix or state vector.

    B qobj

      Density matrix or state vector with same dimensions as A.

  Returns:
    dist float

      Hilbert-Schmidt distance between density matrices.

  Notes

  See V. Vedral and M. B. Plenio, Phys. Rev. A 57, 1619 (1998).

process_fidelity(U1, U2, normalize=True)

  Calculate the process fidelity given two process operators.

tracedist(A, B, sparse=False, tol=0)

  Calculates the trace distance between two density matrices.. See: Nielsen & Chuang, “Quantum Computation and Quantum Information”

  Parameters:
    A qobj

      Density matrix or state vector.

    B qobj

      Density matrix or state vector with same dimensions as A.

    tol float

      Tolerance used by sparse eigensolver, if used. (0=Machine precision)

    sparse{False, True}

      Use sparse eigensolver.

  Returns:
    tracedist float

      Trace distance between A and B.

  Examples

      >>> x=fock_dm(5,3)
      >>> y=coherent_dm(5,1)
      >>> np.testing.assert_almost_equal(tracedist(x,y), 0.9705143161472971)

unitarity(oper)

  Returns the unitarity of a quantum map, defined as the Frobenius norm of the unital block of that map’s superoperator representation.

  Parameters:
    oper Qobj

      Quantum map under consideration.

  Returns:
    u float

      Unitarity of `oper`.

### Continuous Variables

This module contains a collection functions for calculating continuous variable quantities from fock-basis representation of the state of multi-mode fields.

correlation_matrix(basis, rho=None)

  Given a basis set of operators \(\{a\}_n\), calculate the correlation matrix:

  \[C_{mn} = \langle a_m a_n \rangle\]
  Parameters:
    basis list

      List of operators that defines the basis for the correlation matrix.

    rho Qobj

      Density matrix for which to calculate the correlation matrix. If rho is None, then a matrix of correlation matrix operators is returned instead of expectation values of those operators.

  Returns:
    corr_mat ndarray

      A 2-dimensional array of correlation values or operators.

correlation_matrix_field(a1, a2, rho=None)

  Calculates the correlation matrix for given field operators \(a_1\) and \(a_2\). If a density matrix is given the expectation values are calculated, otherwise a matrix with operators is returned.

  Parameters:
    a1 Qobj

      Field operator for mode 1.

    a2 Qobj

      Field operator for mode 2.

    rho Qobj

      Density matrix for which to calculate the covariance matrix.

  Returns:
    cov_mat ndarray

      Array of complex numbers or Qobj’s A 2-dimensional array of covariance values, or, if rho=0, a matrix of operators.

correlation_matrix_quadrature(a1, a2, rho=None, g=1.4142135623730951)

  Calculate the quadrature correlation matrix with given field operators \(a_1\) and \(a_2\). If a density matrix is given the expectation values are calculated, otherwise a matrix with operators is returned.

  Parameters:
    a1 Qobj

      Field operator for mode 1.

    a2 Qobj

      Field operator for mode 2.

    rho Qobj

      Density matrix for which to calculate the covariance matrix.

    g float

      Scaling factor for a = 0.5 * g * (x + iy), default g = sqrt(2). The value of g is related to the value of hbar in the commutation relation [x, y] = i * hbar via hbar=2/g ** 2 giving the default value hbar=1.

  Returns:
    corr_mat ndarray

      Array of complex numbers or Qobj’s A 2-dimensional array of covariance values for the field quadratures, or, if rho=0, a matrix of operators.

covariance_matrix(basis, rho, symmetrized=True)

  Given a basis set of operators \(\{a\}_n\), calculate the covariance matrix:

  \[V_{mn} = \frac{1}{2}\langle a_m a_n + a_n a_m \rangle - \langle a_m \rangle \langle a_n\rangle\]

  or, if of the optional argument symmetrized=False,

  \[V_{mn} = \langle a_m a_n\rangle - \langle a_m \rangle \langle a_n\rangle\]
  Parameters:
    basis list

      List of operators that defines the basis for the covariance matrix.

    rho Qobj

      Density matrix for which to calculate the covariance matrix.

    symmetrized bool {True, False}

      Flag indicating whether the symmetrized (default) or non-symmetrized correlation matrix is to be calculated.

  Returns:
    corr_mat ndarray

      A 2-dimensional array of covariance values.

logarithmic_negativity(V, g=1.4142135623730951)

  Calculates the logarithmic negativity given a symmetrized covariance matrix, see `qutip.continuous_variables.covariance_matrix`. Note that the two-mode field state that is described by V must be Gaussian for this function to applicable.

  Parameters:
    V 2d array

      The covariance matrix.

    g float

      Scaling factor for a = 0.5 * g * (x + iy), default g = sqrt(2). The value of g is related to the value of hbar in the commutation relation [x, y] = i * hbar via hbar=2/g ** 2 giving the default value hbar=1.

  Returns:
    N float

      The logarithmic negativity for the two-mode Gaussian state that is described by the the Wigner covariance matrix V.

wigner_covariance_matrix(a1=None, a2=None, R=None, rho=None, g=1.4142135623730951)

  Calculates the Wigner covariance matrix \(V_{ij} = \frac{1}{2}(R_{ij} + R_{ji})\), given the quadrature correlation matrix \(R_{ij} = \langle R_{i} R_{j}\rangle - \langle R_{i}\rangle \langle R_{j}\rangle\), where \(R = (q_1, p_1, q_2, p_2)^T\) is the vector with quadrature operators for the two modes.

  Alternatively, if R = None, and if annihilation operators a1 and a2 for the two modes are supplied instead, the quadrature correlation matrix is constructed from the annihilation operators before then the covariance matrix is calculated.

  Parameters:
    a1 Qobj

      Field operator for mode 1.

    a2 Qobj

      Field operator for mode 2.

    R ndarray

      The quadrature correlation matrix.

    rho Qobj

      Density matrix for which to calculate the covariance matrix.

    g float

      Scaling factor for a = 0.5 * g * (x + iy), default g = sqrt(2). The value of g is related to the value of hbar in the commutation relation [x, y] = i * hbar via hbar=2/g ** 2 giving the default value hbar=1.

  Returns:
    cov_mat ndarray

      A 2-dimensional array of covariance values.

## Measurement

### Measurement of quantum states

Module for measuring quantum objects.

measure(state, ops, targets=None)

  A dispatch method that provides measurement results handling both observable style measurements and projector style measurements (POVMs and PVMs).

  For return signatures, please check:

  - `measure_observable` for observable measurements.

  - `measure_povm` for POVM measurements.

  Parameters:
    state `Qobj`

      The ket or density matrix specifying the state to measure.

    ops `Qobj` or list of `Qobj`

      - measurement observable (`Qobj`); or

      - list of measurement operators \(M_i\) or kets (list of `Qobj`) Either:

        1. specifying a POVM s.t. \(E_i = M_i^\dagger M_i\)

        2. projection operators if ops correspond to projectors (s.t. \(E_i = M_i^\dagger = M_i\))

        3. kets (transformed to projectors)

    targets list of ints, optional

      Specifies a list of target “qubit” indices on which to apply the measurement using `qutip.qip.operations.gates.expand_operator` to expand ops into full dimension.

measure_observable(state, op, targets=None)

  Perform a measurement specified by an operator on the given state.

  This function simulates the classic quantum measurement described in many introductory texts on quantum mechanics. The measurement collapses the state to one of the eigenstates of the given operator and the result of the measurement is the corresponding eigenvalue.

  Parameters:
    state `Qobj`

      The ket or density matrix specifying the state to measure.

    op `Qobj`

      The measurement operator.

    targets list of ints, optional

      Specifies a list of target “qubit” indices on which to apply the measurement using `qutip.qip.operations.gates.expand_operator` to expand op into full dimension.

  Returns:
    measured_value float

      The result of the measurement (one of the eigenvalues of op).

    state `Qobj`

      The new state (a ket if a ket was given, otherwise a density matrix).

  Examples

  Measure the z-component of the spin of the spin-up basis state:

      >>> measure_observable(basis(2, 0), sigmaz())
      (1.0, Quantum object: dims = [[2], [1]], shape = (2, 1), type = ket
      Qobj data =
      [[-1.]
       [ 0.]])

  Since the spin-up basis is an eigenstate of sigmaz, this measurement always returns 1 as the measurement result (the eigenvalue of the spin-up basis) and the original state (up to a global phase).

  Measure the x-component of the spin of the spin-down basis state:

      >>> measure_observable(basis(2, 1), sigmax())
      (-1.0, Quantum object: dims = [[2], [1]], shape = (2, 1), type = ket
      Qobj data =
      [[-0.70710678]
       [ 0.70710678]])

  This measurement returns 1 fifty percent of the time and -1 the other fifty percent of the time. The new state returned is the corresponding eigenstate of sigmax.

  One may also perform a measurement on a density matrix. Below we perform the same measurement as above, but on the density matrix representing the pure spin-down state:

      >>> measure_observable(ket2dm(basis(2, 1)), sigmax())
      (-1.0, Quantum object: dims = [[2], [2]], shape = (2, 2), type = oper
      Qobj data =
      [[ 0.5 -0.5]
       [-0.5  0.5]])

  The measurement result is the same, but the new state is returned as a density matrix.

measure_povm(state, ops, targets=None)

  Perform a measurement specified by list of POVMs.

  This function simulates a POVM measurement. The measurement collapses the state to one of the resultant states of the measurement and returns the index of the operator corresponding to the collapsed state as well as the collapsed state.

  Parameters:
    state `Qobj`

      The ket or density matrix specifying the state to measure.

    ops list of `Qobj`

      List of measurement operators \(M_i\) or kets. Either:

      1. specifying a POVM s.t. \(E_i = M_i^\dagger M_i\)

      2. projection operators if ops correspond to projectors (s.t. \(E_i = M_i^\dagger = M_i\))

      3. kets (transformed to projectors)

    targets list of ints, optional

      Specifies a list of target “qubit” indices on which to apply the measurement using `qutip.qip.operations.gates.expand_operator` to expand `ops` into full dimension.

  Returns:
    index float

      The resultant index of the measurement.

    state `Qobj`

      The new state (a ket if a ket was given, otherwise a density matrix).

measurement_statistics(state, ops, targets=None)

  A dispatch method that provides measurement statistics handling both observable style measurements and projector style measurements(POVMs and PVMs).

  For return signatures, please check:

  - `measurement_statistics_observable` for observable measurements.

  - `measurement_statistics_povm` for POVM measurements.

  Parameters:
    state `Qobj`

      The ket or density matrix specifying the state to measure.

    ops `Qobj` or list of `Qobj`

      - measurement observable (:class:.Qobj); or

      - list of measurement operators \(M_i\) or kets (list of `Qobj`) Either:

        1. specifying a POVM s.t. \(E_i = M_i^\dagger * M_i\)

        2. projection operators if ops correspond to projectors (s.t. \(E_i = M_i^\dagger = M_i\))

        3. kets (transformed to projectors)

    targets list of ints, optional

      Specifies a list of target “qubit” indices on which to apply the measurement using `qutip.qip.operations.gates.expand_operator` to expand ops into full dimension.

measurement_statistics_observable(state, op, targets=None)

  Return the measurement eigenvalues, eigenstates (or projectors) and measurement probabilities for the given state and measurement operator.

  Parameters:
    state `Qobj`

      The ket or density matrix specifying the state to measure.

    op `Qobj`

      The measurement operator.

    targets list of ints, optional

      Specifies a list of targets “qubit” indices on which to apply the measurement using `qutip.qip.operations.gates.expand_operator` to expand op into full dimension.

  Returns:
    eigenvalues: list of float

      The list of eigenvalues of the measurement operator.

    eigenstates_or_projectors: list of `Qobj`

      If the state was a ket, return the eigenstates of the measurement operator. Otherwise return the projectors onto the eigenstates.

    probabilities: list of float

      The probability of measuring the state as being in the corresponding eigenstate (and the measurement result being the corresponding eigenvalue).

measurement_statistics_povm(state, ops, targets=None)

  Returns measurement statistics (resultant states and probabilities) for a measurement specified by a set of positive operator valued measurements on a specified ket or density matrix.

  Parameters:
    state `Qobj`

      The ket or density matrix specifying the state to measure.

    ops list of `Qobj`

      List of measurement operators \(M_i\) or kets. Either:

      1. specifying a POVM s.t. \(E_i = M_i^\dagger M_i\)

      2. projection operators if ops correspond to projectors (s.t. \(E_i = M_i^\dagger = M_i\))

      3. kets (transformed to projectors)

    targets list of ints, optional

      Specifies a list of target “qubit” indices on which to apply the measurement using qutip.qip.operations.gates.expand_operator to expand ops into full dimension.

  Returns:
    collapsed_states list of `Qobj`

      The collapsed states obtained after measuring the qubits and obtaining the qubit specified by the target in the state specified by the index.

    probabilities list of floats

      The probability of measuring a state in a the state specified by the index.

## Dynamics and Time-Evolution

### Schrödinger Equation

This module provides solvers for the unitary Schrodinger equation.

sesolve(H, psi0, tlist, e_ops=None, args=None, options=None, progress_bar=None, _safe_mode=True)

  Schrödinger equation evolution of a state vector or unitary matrix for a given Hamiltonian.

  Evolve the state vector (`psi0`) using a given Hamiltonian (`H`), by integrating the set of ordinary differential equations that define the system. Alternatively evolve a unitary matrix in solving the Schrodinger operator equation.

  The output is either the state vector or unitary matrix at arbitrary points in time (`tlist`), or the expectation values of the supplied operators (`e_ops`). If `e_ops` is a callback function, it is invoked for each time in `tlist` with time and the state as arguments, and the function does not use any return values. `e_ops` cannot be used in conjunction with solving the Schrodinger operator equation

  Parameters:
    H `Qobj`, `QobjEvo`, list, or callable

      System Hamiltonian as a `Qobj` , list of `Qobj` and coefficient, `QobjEvo`, or a callback function for time-dependent Hamiltonians. List format and options can be found in QobjEvo’s description.

    psi0 `Qobj`

      Initial state vector (ket) or initial unitary operator `psi0 = U`.

    tlist array_like of float

      List of times for \(t\).

    e_ops None / list / callback function, optional

      A list of operators as Qobj and/or callable functions (can be mixed) or a single callable function. For callable functions, they are called as `f(t, state)` and return the expectation value. A single callback’s expectation value can be any type, but a callback part of a list must return a number as the expectation value. For operators, the result’s expect will be computed by `qutip.expect` when the state is a `ket`. For operator evolution, the overlap is computed by:

          (e_ops[i].dag() * op(t)).tr()

    args dict, optional

      Dictionary of scope parameters for time-dependent Hamiltonians.

    options `Options`, optional

      Options for the ODE solver.

    progress_bar `BaseProgressBar`, optional

      Optional instance of `BaseProgressBar`, or a subclass thereof, for showing the progress of the simulation.

  Returns:
    output: `Result`

      An instance of the class `Options`, which contains either an array of expectation values for the times specified by `tlist`, or an array or state vectors corresponding to the times in `tlist` (if `e_ops` is an empty list), or nothing if a callback function was given inplace of operators for which to calculate the expectation values.

### Master Equation

This module provides solvers for the Lindblad master equation and von Neumann equation.

mesolve(H, rho0, tlist, c_ops=None, e_ops=None, args=None, options=None, progress_bar=None, _safe_mode=True)

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

  Evolve the state vector or 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. In the absence of collapse operators the system is evolved according to the unitary evolution of the Hamiltonian.

  The output is either the state vector at arbitrary points in time (tlist), or the expectation values of the supplied operators (e_ops). If e_ops is a callback function, it is invoked for each time in tlist with time and the state as arguments, and the function does not use any return values.

  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.

  Time-dependent operators

  For time-dependent problems, H and c_ops can be a specified in a nested-list format where each element in the list is a list of length 2, containing an operator (`qutip.qobj`) at the first element and where the second element is either a string (list string format), a callback function (list callback format) that evaluates to the time-dependent coefficient for the corresponding operator, or a NumPy array (list array format) which specifies the value of the coefficient to the corresponding operator for each value of t in tlist.

  Alternatively, H (but not c_ops) can be a callback function with the signature f(t, args) -> Qobj (callback format), which can return the Hamiltonian or Liouvillian superoperator at any point in time. If the equation cannot be put in standard Lindblad form, then this time-dependence format must be used.

  Examples

  > H = [[H0, ‘sin(w*t)’], [H1, ‘sin(2*w*t)’]]

  > H = [[H0, f0_t], [H1, f1_t]]

  > where f0_t and f1_t are python functions with signature f_t(t, args).

  > H = [[H0, np.sin(w*tlist)], [H1, np.sin(2*w*tlist)]]

  In the list string format and list callback format, the string expression and the callback function must evaluate to a real or complex number (coefficient for the corresponding operator).

  In all cases of time-dependent operators, args is a dictionary of parameters that is used when evaluating operators. It is passed to the callback functions as their second argument.

  Additional options

  Additional options to mesolve can be set via the options argument, which should be an instance of `qutip.solver.Options`. Many ODE integration options can be set this way, and the store_states and store_final_state options can be used to store states even though expectation values are requested via the e_ops argument.

  Note

  If an element in the list-specification of the Hamiltonian or the list of collapse operators are in superoperator form it will be added to the total Liouvillian of the problem without further transformation. This allows for using mesolve for solving master equations that are not in standard Lindblad form.

  Note

  On using callback functions: mesolve transforms all `qutip.Qobj` objects to sparse matrices before handing the problem to the integrator function. In order for your callback function to work correctly, pass all `qutip.Qobj` objects that are used in constructing the Hamiltonian via args. mesolve will check for `qutip.Qobj` in args and handle the conversion to sparse matrices. All other `qutip.Qobj` objects that are not passed via args will be passed on to the integrator in scipy which will raise a NotImplemented exception.

  Parameters:
    H `qutip.Qobj`

      System Hamiltonian, or a callback function for time-dependent Hamiltonians, or alternatively a system Liouvillian.

    rho0 `qutip.Qobj`

      initial density matrix or state vector (ket).

    tlist list / array

      list of times for \(t\).

    c_ops None / list of `qutip.Qobj`

      single collapse operator, or list of collapse operators, or a list of Liouvillian superoperators.

    e_ops None / list / callback function, optional

      A list of operators as Qobj and/or callable functions (can be mixed) or a single callable function. For operators, the result’s expect will be computed by `qutip.expect`. For callable functions, they are called as `f(t, state)` and return the expectation value. A single callback’s expectation value can be any type, but a callback part of a list must return a number as the expectation value.

    args None / dictionary

      dictionary of parameters for time-dependent Hamiltonians and collapse operators.

    options None / `qutip.solver.Options`

      with options for the solver.

    progress_bar None / BaseProgressBar

      Optional instance of BaseProgressBar, or a subclass thereof, for showing the progress of the simulation.

  Returns:
    result: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`, which contains either an array result.expect of expectation values for the times specified by tlist, or an array result.states of state vectors or density matrices corresponding to the times in tlist [if e_ops is an empty list], or nothing if a callback function was given in place of operators for which to calculate the expectation values.

### Monte Carlo Evolution

mcsolve(H, psi0, tlist, c_ops=[], e_ops=[], ntraj=0, args={}, options=None, progress_bar=True, map_func=<function parallel_map>, map_kwargs={}, _safe_mode=True)

  Monte Carlo evolution of a state vector \(|\psi \rangle\) for a given Hamiltonian and sets of collapse operators, and possibly, operators for calculating expectation values. Options for the underlying ODE solver are given by the Options class.

  mcsolve supports time-dependent Hamiltonians and collapse operators using either Python functions of strings to represent time-dependent coefficients. Note that, the system Hamiltonian MUST have at least one constant term.

  As an example of a time-dependent problem, consider a Hamiltonian with two terms `H0` and `H1`, where `H1` is time-dependent with coefficient `sin(w*t)`, and collapse operators `C0` and `C1`, where `C1` is time-dependent with coeffcient `exp(-a*t)`. Here, w and a are constant arguments with values `W` and `A`.

  Using the Python function time-dependent format requires two Python functions, one for each collapse coefficient. Therefore, this problem could be expressed as:

      def H1_coeff(t,args):
          return sin(args['w']*t)

      def C1_coeff(t,args):
          return exp(-args['a']*t)

      H = [H0, [H1, H1_coeff]]

      c_ops = [C0, [C1, C1_coeff]]

      args={'a': A, 'w': W}

  or in String (Cython) format we could write:

      H = [H0, [H1, 'sin(w*t)']]

      c_ops = [C0, [C1, 'exp(-a*t)']]

      args={'a': A, 'w': W}

  Constant terms are preferably placed first in the Hamiltonian and collapse operator lists.

  Parameters:
    H `qutip.Qobj`, `list`

      System Hamiltonian.

    psi0 `qutip.Qobj`

      Initial state vector

    tlist array_like

      Times at which results are recorded.

    ntraj int

      Number of trajectories to run.

    c_ops `qutip.Qobj`, `list`

      single collapse operator or a `list` of collapse operators.

    e_ops `qutip.Qobj`, `list`

      single operator as Qobj or `list` or equivalent of Qobj operators for calculating expectation values.

    args dict

      Arguments for time-dependent Hamiltonian and collapse operator terms.

    options Options

      Instance of ODE solver options.

    progress_bar: BaseProgressBar

      Optional instance of BaseProgressBar, or a subclass thereof, for showing the progress of the simulation. Set to None to disable the progress bar.

    map_func: function

      A map function for managing the calls to the single-trajactory solver.

    map_kwargs: dictionary

      Optional keyword arguments to the map_func function.

  Returns:
    results `qutip.solver.Result`

      Object storing all results from the simulation.

    Note

    It is possible to reuse the random number seeds from a previous run of the mcsolver by passing the output Result object seeds via the Options class, i.e. Options(seeds=prev_result.seeds).

### Exponential Series

essolve(H, rho0, tlist, c_op_list, e_ops)

  Evolution of a state vector or density matrix (rho0) for a given Hamiltonian (H) and set of collapse operators (c_op_list), by expressing the ODE as an exponential series. The output is either the state vector at arbitrary points in time (tlist), or the expectation values of the supplied operators (e_ops).

  Deprecated since version 4.6.0: `essolve` will be removed in QuTiP 5. Please use `sesolve` or `mesolve` for general-purpose integration of the Schroedinger/Lindblad master equation. This will likely be faster than `essolve` for you.

  Parameters:
    H qobj/function_type

      System Hamiltonian.

    rho0 `qutip.qobj`

      Initial state density matrix.

    tlist list/array

      `list` of times for \(t\).

    c_op_list list of `qutip.qobj`

      `list` of `qutip.qobj` collapse operators.

    e_ops list of `qutip.qobj`

      `list` of `qutip.qobj` operators for which to evaluate expectation values.

  Returns:
    expt_array array

      Expectation values of wavefunctions/density matrices for the times specified in `tlist`.

    Note

    This solver does not support time-dependent Hamiltonians. ..

ode2es(L, rho0)

  Creates an exponential series that describes the time evolution for the initial density matrix (or state vector) rho0, given the Liouvillian (or Hamiltonian) L.

  Deprecated since version 4.6.0: `ode2es` will be removed in QuTiP 5. Please use `qutip.Qobj.eigenstates` to get the eigenstates and -values, and use `QobjEvo` for general time-dependence.

  Parameters:
    L qobj

      Liouvillian of the system.

    rho0 qobj

      Initial state vector or density matrix.

  Returns:
    eseries `qutip.eseries`

      `eseries` represention of the system dynamics.

### Krylov Subspace Solver

krylovsolve(H: Qobj, psi0: Qobj, tlist: array, krylov_dim: int, e_ops=None, options=None, progress_bar: bool = None, sparse: bool = False)

  Time evolution of state vectors for time independent Hamiltonians. 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)).

  The output is either the state vector or the expectation values of supplied operators (“e_ops”) at arbitrary points at (“tlist”).

  Additional options

  Additional options to krylovsolve can be set with the following:

  - “store_states”: stores states even though expectation values are requested via the “e_ops” argument.

  - “store_final_state”: store final state even though expectation values are requested via the “e_ops” argument.

  Parameters:
    H `qutip.Qobj`

      System Hamiltonian.

    psi0:class: qutip.Qobj

      Initial state vector (ket).

    tlist None / list / array

      List of times on which to evolve the initial state. If None, nothing happens but the code won’t break.

    krylov_dim: int

      Dimension of Krylov approximation subspaces used for the time evolution approximation.

    e_ops None / list of `qutip.Qobj`

      Single operator or list of operators for which to evaluate expectation values.

    options Options
      Instance of ODE solver options, as well as krylov parameters.
        atol: controls (approximately) the error desired for the final

          solution. (Defaults to 1e-8)

        nsteps: maximum number of krylov’s internal number of Lanczos

          iterations. (Defaults to 10000)

    progress_bar None / BaseProgressBar

      Optional instance of BaseProgressBar, or a subclass thereof, for showing the progress of the simulation.

    sparse bool (default False)

      Use np.array to represent system Hamiltonians. If True, scipy sparse arrays are used instead.

  Returns:
    result: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`, which contains either an array result.expect of expectation values for the times tlist, or an array result.states of state vectors corresponding to the times tlist [if e_ops is an empty list].

### Bloch-Redfield Master Equation

bloch_redfield_solve(R, ekets, rho0, tlist, e_ops=[], options=None, progress_bar=None)

  Evolve the ODEs defined by Bloch-Redfield master equation. The Bloch-Redfield tensor can be calculated by the function `bloch_redfield_tensor`.

  Parameters:
    R `qutip.qobj`

      Bloch-Redfield tensor.

    ekets array of `qutip.qobj`

      Array of kets that make up a basis tranformation for the eigenbasis.

    rho0 `qutip.qobj`

      Initial density matrix.

    tlist list / array

      List of times for \(t\).

    e_ops list of `qutip.qobj` / callback function

      List of operators for which to evaluate expectation values.

    options `qutip.solver.Options`

      Options for the ODE solver.

  Returns:
    output: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`, which contains either an array of expectation values for the times specified by tlist.

bloch_redfield_tensor()

  > Calculates the time-independent Bloch-Redfield tensor for a system given a set of operators and corresponding spectral functions that describes the system’s couplingto its environment.

  Parameters:
    H `qutip.qobj`

      > System Hamiltonian.

      a_opslist

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

      spectra_cblist

        Depreciated.

      c_opslist

        List of system collapse operators.

      use_secularbool {True, False}

        Flag that indicates if the secular approximation should be used.

      sec_cutofffloat {0.1}

        Threshold for secular approximation.

    atol float {qutip.settings.atol}

      Threshold for removing small parameters.

  Returns:
    R, kets: `qutip.Qobj`, list of `qutip.Qobj`

      R is the Bloch-Redfield tensor and kets is a list eigenstates of the Hamiltonian.

brmesolve(H, psi0, tlist, a_ops=[], e_ops=[], c_ops=[], args={}, use_secular=True, sec_cutoff=0.1, tol=1e-12, spectra_cb=None, options=None, progress_bar=None, _safe_mode=True, verbose=False)

  Solves for the dynamics of a system using the Bloch-Redfield master equation, given an input Hamiltonian, Hermitian bath-coupling terms and their associated spectrum functions, as well as possible Lindblad collapse operators.

  For time-independent systems, the Hamiltonian must be given as a Qobj, whereas the bath-coupling terms (a_ops), must be written as a nested list of operator - spectrum function pairs, where the frequency is specified by the w variable.

  Example

  > a_ops = [[a+a.dag(),lambda w: 0.2*(w>=0)]]

  For time-dependent systems, the Hamiltonian, a_ops, and Lindblad collapse operators (c_ops), can be specified in the QuTiP string-based time-dependent format. For the a_op spectra, the frequency variable must be w, and the string cannot contain any other variables other than the possibility of having a time-dependence through the time variable t:

  Example

  > a_ops = [[a+a.dag(), ‘0.2*exp(-t)*(w>=0)’]]

  It is also possible to use Cubic_Spline objects for time-dependence. In the case of a_ops, Cubic_Splines must be passed as a tuple:

  Example

  > a_ops = [ [a+a.dag(), ( f(w), g(t)] ]

  where f(w) and g(t) are strings or Cubic_spline objects for the bath spectrum and time-dependence, respectively.

  Finally, if one has bath-couplimg terms of the form H = f(t)*a + conj[f(t)]*a.dag(), then the correct input format is

  Example

  > a_ops = [ [(a,a.dag()), (f(w), g1(t), g2(t))],… ]

  where f(w) is the spectrum of the operators while g1(t) and g2(t) are the time-dependence of the operators a and a.dag(), respectively

  Parameters:
    H Qobj / list

      System Hamiltonian given as a Qobj or nested list in string-based format.

    psi0: Qobj

      Initial density matrix or state vector (ket).

    tlist array_like

      List of times for evaluating evolution

    a_ops list

      Nested list of Hermitian system operators that couple to the bath degrees of freedom, along with their associated spectra.

    e_ops list

      List of operators for which to evaluate expectation values.

    c_ops list

      List of system collapse operators, or nested list in string-based format.

    args dict

      Placeholder for future implementation, kept for API consistency.

    use_secular bool {True}

      Use secular approximation when evaluating bath-coupling terms.

    sec_cutoff float {0.1}

      Cutoff for secular approximation.

    tol float {qutip.setttings.atol}

      Tolerance used for removing small values after basis transformation.

    spectra_cb list

      DEPRECIATED. Do not use.

    options `qutip.solver.Options`

      Options for the solver.

    progress_bar BaseProgressBar

      Optional instance of BaseProgressBar, or a subclass thereof, for showing the progress of the simulation.

  Returns:
    result: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`, which contains either an array of expectation values, for operators given in e_ops, or a list of states for the times specified by tlist.

### Floquet States and Floquet-Markov Master Equation

floquet_basis_transform(f_modes, f_energies, rho0)

  Make a basis transform that takes rho0 from the floquet basis to the computational basis.

floquet_markov_mesolve(R, rho0, tlist, e_ops, options=None, floquet_basis=True, f_modes_0=None, f_modes_table_t=None, f_energies=None, T=None)

  Solve the dynamics for the system using the Floquet-Markov master equation.

  Note

  It is important to understand in which frame and basis the results are returned here.

  Parameters:
    R array

      The Floquet-Markov master equation tensor R.

    rho0 `qutip.qobj`

      Initial density matrix. If `f_modes_0` is not passed, this density matrix is assumed to be in the Floquet picture.

    tlist list / array

      list of times for \(t\).

    e_ops list of `qutip.qobj` / callback function

      list of operators for which to evaluate expectation values.

    options `qutip.solver.Options`

      options for the ODE solver.

    floquet_basis: bool, True

      If `True`, states and expectation values will be returned in the Floquet basis. If `False`, a transformation will be made to the computational basis; this will be in the lab frame if `f_modes_table`, `T` and ``f_energies` are all supplied, or the interaction picture (defined purely be f_modes_0) if they are not.

    f_modes_0 list of `qutip.qobj` (kets), optional

      A list of initial Floquet modes, used to transform the given starting density matrix into the Floquet basis. If this is not passed, it is assumed that `rho` is already in the Floquet basis.

    f_modes_table_t nested list of `qutip.qobj` (kets), optional

      A lookup-table of Floquet modes at times precalculated by `qutip.floquet.floquet_modes_table`. Necessary if `floquet_basis` is `False` and the transformation should be made back to the lab frame.

    f_energies array_like of float, optional

      The precalculated Floquet quasienergies. Necessary if `floquet_basis` is `False` and the transformation should be made back to the lab frame.

    T float, optional

      The time period of driving. Necessary if `floquet_basis` is `False` and the transformation should be made back to the lab frame.

  Returns:
    output `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`, which contains either an array of expectation values or an array of state vectors, for the times specified by tlist.

floquet_master_equation_rates(f_modes_0, f_energies, c_op, H, T, args, J_cb, w_th, kmax=5, f_modes_table_t=None)

  Calculate the rates and matrix elements for the Floquet-Markov master equation.

  Parameters:
    f_modes_0 list of `qutip.qobj` (kets)

      A list of initial Floquet modes.

    f_energies array

      The Floquet energies.

    c_op `qutip.qobj`

      The collapse operators describing the dissipation.

    H `qutip.qobj`

      System Hamiltonian, time-dependent with period T.

    T float

      The period of the time-dependence of the hamiltonian.

    args dictionary

      Dictionary with variables required to evaluate H.

    J_cb callback functions

      A callback function that computes the noise power spectrum, as a function of frequency, associated with the collapse operator c_op.

    w_th float

      The temperature in units of frequency.

    kmax int

      The truncation of the number of sidebands (default 5).

    f_modes_table_t nested list of `qutip.qobj` (kets)

      A lookup-table of Floquet modes at times precalculated by `qutip.floquet.floquet_modes_table` (optional).

    options `qutip.solver.Options`

      options for the ODE solver.

  Returns:
    output list

      A list (Delta, X, Gamma, A) containing the matrices Delta, X, Gamma and A used in the construction of the Floquet-Markov master equation.

floquet_master_equation_steadystate(H, A)

  Returns the steadystate density matrix (in the floquet basis!) for the Floquet-Markov master equation.

floquet_modes(H, T, args=None, sort=False, U=None, options=None)

  Calculate the initial Floquet modes Phi_alpha(0) for a driven system with period T.

  Returns a list of `qutip.qobj` instances representing the Floquet modes and a list of corresponding quasienergies, sorted by increasing quasienergy in the interval [-pi/T, pi/T]. The optional parameter sort decides if the output is to be sorted in increasing quasienergies or not.

  Parameters:
    H `qutip.qobj`

      system Hamiltonian, time-dependent with period T

    args dictionary

      dictionary with variables required to evaluate H

    T float

      The period of the time-dependence of the hamiltonian. The default value ‘None’ indicates that the ‘tlist’ spans a single period of the driving.

    U `qutip.qobj`

      The propagator for the time-dependent Hamiltonian with period T. If U is None (default), it will be calculated from the Hamiltonian H using `qutip.propagator.propagator`.

    options `qutip.solver.Options`

      options for the ODE solver. For the propagator U.

  Returns:
    output list of kets, list of quasi energies

      Two lists: the Floquet modes as kets and the quasi energies.

floquet_modes_t(f_modes_0, f_energies, t, H, T, args=None, options=None)

  Calculate the Floquet modes at times tlist Phi_alpha(tlist) propagting the initial Floquet modes Phi_alpha(0)

  Parameters:
    f_modes_0 list of `qutip.qobj` (kets)

      Floquet modes at \(t\)

    f_energies list

      Floquet energies.

    t float

      The time at which to evaluate the floquet modes.

    H `qutip.qobj`

      system Hamiltonian, time-dependent with period T

    args dictionary

      dictionary with variables required to evaluate H

    T float

      The period of the time-dependence of the hamiltonian.

    options `qutip.solver.Options`

      options for the ODE solver. For the propagator.

  Returns:
    output list of kets

      The Floquet modes as kets at time \(t\)

floquet_modes_t_lookup(f_modes_table_t, t, T)

  Lookup the floquet mode at time t in the pre-calculated table of floquet modes in the first period of the time-dependence.

  Parameters:
    f_modes_table_t nested list of `qutip.qobj` (kets)

      A lookup-table of Floquet modes at times precalculated by `qutip.floquet.floquet_modes_table`.

    t float

      The time for which to evaluate the Floquet modes.

    T float

      The period of the time-dependence of the hamiltonian.

  Returns:
    output nested list

      A list of Floquet modes as kets for the time that most closely matching the time t in the supplied table of Floquet modes.

floquet_modes_table(f_modes_0, f_energies, tlist, H, T, args=None, options=None)

  Pre-calculate the Floquet modes for a range of times spanning the floquet period. Can later be used as a table to look up the floquet modes for any time.

  Parameters:
    f_modes_0 list of `qutip.qobj` (kets)

      Floquet modes at \(t\)

    f_energies list

      Floquet energies.

    tlist array

      The list of times at which to evaluate the floquet modes.

    H `qutip.qobj`

      system Hamiltonian, time-dependent with period T

    T float

      The period of the time-dependence of the hamiltonian.

    args dictionary

      dictionary with variables required to evaluate H

    options `qutip.solver.Options`

      options for the ODE solver.

  Returns:
    output nested list

      A nested list of Floquet modes as kets for each time in tlist

floquet_state_decomposition(f_states, f_energies, psi)

  Decompose the wavefunction psi (typically an initial state) in terms of the Floquet states, \(\psi = \sum_\alpha c_\alpha \psi_\alpha(0)\).

  Parameters:
    f_states list of `qutip.qobj` (kets)

      A list of Floquet modes.

    f_energies array

      The Floquet energies.

    psi `qutip.qobj`

      The wavefunction to decompose in the Floquet state basis.

  Returns:
    output array

      The coefficients \(c_\alpha\) in the Floquet state decomposition.

floquet_states(f_modes_t, f_energies, t)

  Evaluate the floquet states at time t given the Floquet modes at that time.

  Parameters:
    f_modes_t list of `qutip.qobj` (kets)

      A list of Floquet modes for time \(t\).

    f_energies array

      The Floquet energies.

    t float

      The time for which to evaluate the Floquet states.

  Returns:
    output list

      A list of Floquet states for the time \(t\).

floquet_states_t(f_modes_0, f_energies, t, H, T, args=None, options=None)

  Evaluate the floquet states at time t given the initial Floquet modes.

  Parameters:
    f_modes_t list of `qutip.qobj` (kets)

      A list of initial Floquet modes (for time \(t=0\)).

    f_energies array

      The Floquet energies.

    t float

      The time for which to evaluate the Floquet states.

    H `qutip.qobj`

      System Hamiltonian, time-dependent with period T.

    T float

      The period of the time-dependence of the hamiltonian.

    args dictionary

      Dictionary with variables required to evaluate H.

    options `qutip.solver.Options`

      options for the ODE solver.

  Returns:
    output list

      A list of Floquet states for the time \(t\).

floquet_wavefunction(f_modes_t, f_energies, f_coeff, t)

  Evaluate the wavefunction for a time t using the Floquet state decompositon, given the Floquet modes at time t.

  Parameters:
    f_modes_t list of `qutip.qobj` (kets)

      A list of initial Floquet modes (for time \(t=0\)).

    f_energies array

      The Floquet energies.

    f_coeff array

      The coefficients for Floquet decomposition of the initial wavefunction.

    t float

      The time for which to evaluate the Floquet states.

  Returns:
    output `qutip.qobj`

      The wavefunction for the time \(t\).

floquet_wavefunction_t(f_modes_0, f_energies, f_coeff, t, H, T, args=None, options=None)

  Evaluate the wavefunction for a time t using the Floquet state decompositon, given the initial Floquet modes.

  Parameters:
    f_modes_t list of `qutip.qobj` (kets)

      A list of initial Floquet modes (for time \(t=0\)).

    f_energies array

      The Floquet energies.

    f_coeff array

      The coefficients for Floquet decomposition of the initial wavefunction.

    t float

      The time for which to evaluate the Floquet states.

    H `qutip.qobj`

      System Hamiltonian, time-dependent with period T.

    T float

      The period of the time-dependence of the hamiltonian.

    args dictionary

      Dictionary with variables required to evaluate H.

  Returns:
    output `qutip.qobj`

      The wavefunction for the time \(t\).

fmmesolve(H, rho0, tlist, c_ops=[], e_ops=[], spectra_cb=[], T=None, args={}, options=<qutip.solver.Options object>, floquet_basis=True, kmax=5, _safe_mode=True, options_modes=None)

  Solve the dynamics for the system using the Floquet-Markov master equation.

  Note

  This solver currently does not support multiple collapse operators.

  Parameters:
    H `qutip.qobj`

      system Hamiltonian.

    rho0 / psi0 `qutip.qobj`

      initial density matrix or state vector (ket).

    tlist list / array

      list of times for \(t\).

    c_ops list of `qutip.qobj`

      list of collapse operators.

    e_ops list of `qutip.qobj` / callback function

      list of operators for which to evaluate expectation values.

    spectra_cb list callback functions

      List of callback functions that compute the noise power spectrum as a function of frequency for the collapse operators in c_ops.

    T float

      The period of the time-dependence of the hamiltonian. The default value ‘None’ indicates that the ‘tlist’ spans a single period of the driving.

    args dictionary

      dictionary of parameters for time-dependent Hamiltonians and collapse operators.

      This dictionary should also contain an entry ‘w_th’, which is the temperature of the environment (if finite) in the energy/frequency units of the Hamiltonian. For example, if the Hamiltonian written in units of 2pi GHz, and the temperature is given in K, use the following conversion

          >>> temperature = 25e-3 # unit K
          >>> h = 6.626e-34
          >>> kB = 1.38e-23
          >>> args['w_th'] = temperature * (kB / h) * 2 * pi * 1e-9

    options `qutip.solver.Options`

      options for the ODE solver. For solving the master equation.

    floquet_basis bool

      Will return results in Floquet basis or computational basis (optional).

    k_max int

      The truncation of the number of sidebands (default 5).

    options_modes `qutip.solver.Options`

      options for the ODE solver. For computing Floquet modes.

  Returns:
    output `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`, which contains either an array of expectation values for the times specified by tlist.

fsesolve(H, psi0, tlist, e_ops=[], T=None, args={}, Tsteps=100, options_modes=None)

  Solve the Schrodinger equation using the Floquet formalism.

  Parameters:
    H `qutip.Qobj`

      System Hamiltonian, time-dependent with period T.

    psi0 `qutip.qobj`

      Initial state vector (ket).

    tlist list / array

      list of times for \(t\).

    e_ops list of `qutip.qobj` / callback function

      list of operators for which to evaluate expectation values. If this list is empty, the state vectors for each time in tlist will be returned instead of expectation values.

    T float

      The period of the time-dependence of the hamiltonian.

    args dictionary

      Dictionary with variables required to evaluate H.

    Tsteps integer

      The number of time steps in one driving period for which to precalculate the Floquet modes. Tsteps should be an even number.

    options_modes `qutip.solver.Options`

      options for the ODE solver.

  Returns:
    output `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`, which contains either an array of expectation values or an array of state vectors, for the times specified by tlist.

### Stochastic Schrödinger Equation and Master Equation

general_stochastic(state0, times, d1, d2, e_ops=[], m_ops=[], _safe_mode=True, len_d2=1, args={}, **kwargs)

  Solve stochastic general equation. Dispatch to specific solvers depending on the value of the solver keyword argument.

  Parameters:
    state0 `qutip.Qobj`

      Initial state vector (ket) or density matrix as a vector.

    times list / array

      List of times for \(t\). Must be uniformly spaced.

    d1 function, callable class

      Function representing the deterministic evolution of the system.

      def d1(time (double), state (as a np.array vector)):

        return 1d np.array

    d2 function, callable class

      Function representing the stochastic evolution of the system.

      def d2(time (double), state (as a np.array vector)):

        return 2d np.array (N_sc_ops, len(state0))

    len_d2 int

      Number of output vector produced by d2

    e_ops list of `qutip.Qobj`

      single operator or list of operators for which to evaluate expectation values. Must be a superoperator if the state vector is a density matrix.

    kwargs dictionary

      Optional keyword arguments. See `qutip.stochastic.StochasticSolverOptions`.

  Returns:
    output: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`.

photocurrent_mesolve(H, rho0, times, c_ops=[], sc_ops=[], e_ops=[], _safe_mode=True, args={}, **kwargs)

  Solve stochastic master equation using the photocurrent method.

  Parameters:
    H `qutip.Qobj`, or time dependent system.

      System Hamiltonian. Can depend on time, see StochasticSolverOptions help for format.

    rho0 `qutip.Qobj`

      Initial density matrix or state vector (ket).

    times list / array

      List of times for \(t\). Must be uniformly spaced.

    c_ops list of `qutip.Qobj`, or time dependent Qobjs.

      Deterministic collapse operator which will contribute with a standard Lindblad type of dissipation. Can depend on time, see StochasticSolverOptions help for format.

    sc_ops list of `qutip.Qobj`, or time dependent Qobjs.

      List of stochastic collapse operators. Each stochastic collapse operator will give a deterministic and stochastic contribution to the eqaution of motion according to how the d1 and d2 functions are defined. Can depend on time, see StochasticSolverOptions help for format.

    e_ops list of `qutip.Qobj` / callback function single

      single operator or list of operators for which to evaluate expectation values.

    kwargs dictionary

      Optional keyword arguments. See `qutip.stochastic.StochasticSolverOptions`.

  Returns:
    output: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`.

photocurrent_sesolve(H, psi0, times, sc_ops=[], e_ops=[], _safe_mode=True, args={}, **kwargs)

  Solve stochastic schrodinger equation using the photocurrent method.

  Parameters:
    H `qutip.Qobj`, or time dependent system.

      System Hamiltonian. Can depend on time, see StochasticSolverOptions help for format.

    psi0 `qutip.Qobj`

      Initial state vector (ket).

    times list / array

      List of times for \(t\). Must be uniformly spaced.

    sc_ops list of `qutip.Qobj`, or time dependent Qobjs.

      List of stochastic collapse operators. Each stochastic collapse operator will give a deterministic and stochastic contribution to the eqaution of motion according to how the d1 and d2 functions are defined. Can depend on time, see StochasticSolverOptions help for format.

    e_ops list of `qutip.Qobj` / callback function single

      single operator or list of operators for which to evaluate expectation values.

    kwargs dictionary

      Optional keyword arguments. See `qutip.stochastic.StochasticSolverOptions`.

  Returns:
    output: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`.

smepdpsolve(H, rho0, times, c_ops, e_ops, **kwargs)

  A stochastic (piecewse deterministic process) PDP solver for density matrix evolution.

  Parameters:
    H `qutip.Qobj`

      System Hamiltonian.

    rho0 `qutip.Qobj`

      Initial density matrix.

    times list / array

      List of times for \(t\). Must be uniformly spaced.

    c_ops list of `qutip.Qobj`

      Deterministic collapse operator which will contribute with a standard Lindblad type of dissipation.

    sc_ops list of `qutip.Qobj`

      List of stochastic collapse operators. Each stochastic collapse operator will give a deterministic and stochastic contribution to the eqaution of motion according to how the d1 and d2 functions are defined.

    e_ops list of `qutip.Qobj` / callback function single

      single operator or list of operators for which to evaluate expectation values.

    kwargs dictionary

      Optional keyword arguments. See `qutip.stochastic.StochasticSolverOptions`.

  Returns:
    output: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`.

smesolve(H, rho0, times, c_ops=[], sc_ops=[], e_ops=[], _safe_mode=True, args={}, **kwargs)

  Solve stochastic master equation. Dispatch to specific solvers depending on the value of the solver keyword argument.

  Parameters:
    H `qutip.Qobj`, or time dependent system.

      System Hamiltonian. Can depend on time, see StochasticSolverOptions help for format.

    rho0 `qutip.Qobj`

      Initial density matrix or state vector (ket).

    times list / array

      List of times for \(t\). Must be uniformly spaced.

    c_ops list of `qutip.Qobj`, or time dependent Qobjs.

      Deterministic collapse operator which will contribute with a standard Lindblad type of dissipation. Can depend on time, see StochasticSolverOptions help for format.

    sc_ops list of `qutip.Qobj`, or time dependent Qobjs.

      List of stochastic collapse operators. Each stochastic collapse operator will give a deterministic and stochastic contribution to the eqaution of motion according to how the d1 and d2 functions are defined. Can depend on time, see StochasticSolverOptions help for format.

    e_ops list of `qutip.Qobj`

      single operator or list of operators for which to evaluate expectation values.

    kwargs dictionary

      Optional keyword arguments. See `qutip.stochastic.StochasticSolverOptions`.

  Returns:
    output: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`.

ssepdpsolve(H, psi0, times, c_ops, e_ops, **kwargs)

  A stochastic (piecewse deterministic process) PDP solver for wavefunction evolution. For most purposes, use `qutip.mcsolve` instead for quantum trajectory simulations.

  Parameters:
    H `qutip.Qobj`

      System Hamiltonian.

    psi0 `qutip.Qobj`

      Initial state vector (ket).

    times list / array

      List of times for \(t\). Must be uniformly spaced.

    c_ops list of `qutip.Qobj`

      Deterministic collapse operator which will contribute with a standard Lindblad type of dissipation.

    e_ops list of `qutip.Qobj` / callback function single

      single operator or list of operators for which to evaluate expectation values.

    kwargs dictionary

      Optional keyword arguments. See `qutip.stochastic.StochasticSolverOptions`.

  Returns:
    output: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`.

ssesolve(H, psi0, times, sc_ops=[], e_ops=[], _safe_mode=True, args={}, **kwargs)

  Solve stochastic schrodinger equation. Dispatch to specific solvers depending on the value of the solver keyword argument.

  Parameters:
    H `qutip.Qobj`, or time dependent system.

      System Hamiltonian. Can depend on time, see StochasticSolverOptions help for format.

    psi0 `qutip.Qobj`

      State vector (ket).

    times list / array

      List of times for \(t\). Must be uniformly spaced.

    sc_ops list of `qutip.Qobj`, or time dependent Qobjs.

      List of stochastic collapse operators. Each stochastic collapse operator will give a deterministic and stochastic contribution to the eqaution of motion according to how the d1 and d2 functions are defined. Can depend on time, see StochasticSolverOptions help for format.

    e_ops list of `qutip.Qobj`

      single operator or list of operators for which to evaluate expectation values.

    kwargs dictionary

      Optional keyword arguments. See `qutip.stochastic.StochasticSolverOptions`.

  Returns:
    output: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`.

stochastic_solvers()

  This function is purely a reference point for documenting the available stochastic solver methods, and takes no actions.

  Notes

  Available solvers for `ssesolve` and `smesolve`
    euler-maruyama

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

      - Order 0.5

      - Code: `'euler-maruyama'`, `'euler'` or `0.5`

    milstein

      An order 1.0 strong Taylor scheme. Better approximate numerical solution to stochastic differential equations. See eq. (2.9) of chapter 12.2 of [1].

      - Order strong 1.0

      - Code: `'milstein'` or `1.0`

    milstein-imp

      An order 1.0 implicit strong Taylor scheme. Implicit Milstein scheme for the numerical simulation of stiff stochastic differential equations.

      - Order strong 1.0

      - Code: `'milstein-imp'`

    predictor-corrector

      Generalization of the trapezoidal method to stochastic differential equations. More stable than explicit methods. See eq. (5.4) of chapter 15.5 of [1].

      - 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'`

    platen

      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, therefore usable by `general_stochastic`. See eq. (7.47) of chapter 7 of [2].

      - Order strong 1.0, weak 2.0

      - Code: `'platen'`, `'platen1'` or `'explicit1'`

    rouchon

      Scheme keeping the positivity of the density matrix (`smesolve` only). See eq. (4) with \(\eta=1\) of [3].

      - Order strong 1.0?

      - Code: `'rouchon'` or `'Rouchon'`

    taylor1.5

      Order 1.5 strong Taylor scheme. Solver with more terms of the Ito-Taylor expansion. Default solver for `smesolve` and `ssesolve`. See eq. (4.6) of chapter 10.4 of [1].

      - Order strong 1.5

      - Code: `'taylor1.5'`, `'taylor15'`, `1.5`, or `None`

    taylor1.5-imp

      Order 1.5 implicit strong Taylor scheme. Implicit Taylor 1.5 (\(\alpha = 1/2\), \(\beta\) doesn’t matter). See eq. (2.18) of chapter 12.2 of [1].

      - Order strong 1.5

      - Code: `'taylor1.5-imp'` or `'taylor15-imp'`

    explicit1.5

      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 by `general_stochastic`. See eq. (2.13) of chapter 11.2 of [1].

      - Order strong 1.5

      - Code: `'explicit1.5'`, `'explicit15'` or `'platen15'`

    taylor2.0

      Order 2 strong Taylor scheme. Solver with more terms of the Stratonovich expansion. See eq. (5.2) of chapter 10.5 of [1].

      - Order strong 2.0

      - Code: `'taylor2.0'`, `'taylor20'` or `2.0`

    All solvers, except taylor2.0, are usable in both smesolve and ssesolve and for both heterodyne and homodyne. taylor2.0 only works for 1 stochastic operator independent of time with the homodyne method. `general_stochastic` only accepts the derivative-free solvers: `'euler'`, `'platen'` and `'explicit1.5'`.

  Available solvers for `photocurrent_sesolve` and `photocurrent_mesolve`

    Photocurrent use ordinary differential equations between stochastic “jump/collapse”.

    euler

      Euler method for ordinary differential equations between jumps. Only one jump per time interval. Default solver. See eqs. (4.19) and (4.4) of chapter 4 of [4].

      - Order 1.0

      - Code: `'euler'`

    predictor–corrector

      predictor–corrector method (PECE) for ordinary differential equations. Uses the Poisson distribution to obtain the number of jumps at each timestep.

      - Order 2.0

      - Code: `'pred-corr'`

  References

  [1] (1,2,3,4,5,6)

  Peter E. Kloeden and Exkhard Platen, Numerical Solution of Stochastic Differential Equations.

  [2]

  H.-P. Breuer and F. Petruccione, The Theory of Open Quantum Systems.

  [3]

  Pierre Rouchon and Jason F. Ralpha, Efficient Quantum Filtering for Quantum Feedback Control, arXiv:1410.5345 [quant-ph], Phys. Rev. A 91, 012118, (2015).

  [4]

  Howard M. Wiseman, Gerard J. Milburn, Quantum measurement and control.

### Correlation Functions

coherence_function_g1(H, state0, taulist, c_ops, a_op, solver='me', args={}, options=<qutip.solver.Options object>)

  Calculate the normalized first-order quantum coherence function:

  \[g^{(1)}(\tau) = \frac{\langle A^\dagger(\tau)A(0)\rangle} {\sqrt{\langle A^\dagger(\tau)A(\tau)\rangle \langle A^\dagger(0)A(0)\rangle}}\]

  using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Parameters:
    H Qobj

      system Hamiltonian, may be time-dependent for solver choice of me or mc.

    state0 Qobj

      Initial state density matrix \(\rho(t_0)\) or state vector \(\psi(t_0)\). If ‘state0’ is ‘None’, then the steady state will be used as the initial state. The ‘steady-state’ is only implemented for the me and es solvers.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators, may be time-dependent for solver choice of me or mc.

    a_op Qobj

      operator A.

    solver str

      choice of solver (me for master-equation and es for exponential series).

    options Options

      solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    g1, G1 tuple

      The normalized and unnormalized second-order coherence function.

coherence_function_g2(H, state0, taulist, c_ops, a_op, solver='me', args={}, options=<qutip.solver.Options object>)

  Calculate the normalized second-order quantum coherence function:

  \[ g^{(2)}(\tau) = \frac{\langle A^\dagger(0)A^\dagger(\tau)A(\tau)A(0)\rangle} {\langle A^\dagger(\tau)A(\tau)\rangle \langle A^\dagger(0)A(0)\rangle}\]

  using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Parameters:
    H Qobj

      system Hamiltonian, may be time-dependent for solver choice of me or mc.

    state0 Qobj

      Initial state density matrix \(\rho(t_0)\) or state vector \(\psi(t_0)\). If ‘state0’ is ‘None’, then the steady state will be used as the initial state. The ‘steady-state’ is only implemented for the me and es solvers.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators, may be time-dependent for solver choice of me or mc.

    a_op Qobj

      operator A.

    args dict

      Dictionary of arguments to be passed to solver.

    solver str

      choice of solver (me for master-equation and es for exponential series).

    options Options

      solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    g2, G2 tuple

      The normalized and unnormalized second-order coherence function.

correlation(H, state0, tlist, taulist, c_ops, a_op, b_op, solver='me', reverse=False, args={}, options=<qutip.solver.Options object>)

  Calculate the two-operator two-time correlation function: \(\left<A(t+\tau)B(t)\right>\) along two time axes using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Parameters:
    H Qobj

      system Hamiltonian, may be time-dependent for solver choice of me or mc.

    state0 Qobj

      Initial state density matrix \(\rho(t_0)\) or state vector \(\psi(t_0)\). If ‘state0’ is ‘None’, then the steady state will be used as the initial state. The ‘steady-state’ is only implemented for the me and es solvers.

    tlist array_like

      list of times for \(t\). tlist must be positive and contain the element 0. When taking steady-steady correlations only one tlist value is necessary, i.e. when \(t \rightarrow \infty\); here tlist is automatically set, ignoring user input.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators, may be time-dependent for solver choice of me or mc.

    a_op Qobj

      operator A.

    b_op Qobj

      operator B.

    reverse bool

      If True, calculate \(\left<A(t)B(t+\tau)\right>\) instead of \(\left<A(t+\tau)B(t)\right>\).

    solver str

      choice of solver (me for master-equation, mc for Monte Carlo, and es for exponential series).

    options Options

      solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    corr_mat array

      An 2-dimensional array (matrix) of correlation values for the times specified by tlist (first index) and taulist (second index). If tlist is None, then a 1-dimensional array of correlation values is returned instead.

  References

  See, Gardiner, Quantum Noise, Section 5.2.

correlation_2op_1t(H, state0, taulist, c_ops, a_op, b_op, solver='me', reverse=False, args={}, options=<qutip.solver.Options object>)

  Calculate the two-operator two-time correlation function: \(\left<A(t+\tau)B(t)\right>\) along one time axis using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Parameters:
    H Qobj

      system Hamiltonian, may be time-dependent for solver choice of me or mc.

    state0 Qobj

      Initial state density matrix \(\rho(t_0)\) or state vector \(\psi(t_0)\). If ‘state0’ is ‘None’, then the steady state will be used as the initial state. The ‘steady-state’ is only implemented for the me and es solvers.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators, may be time-dependent for solver choice of me or mc.

    a_op Qobj

      operator A.

    b_op Qobj

      operator B.

    reverse bool {False, True}

      If True, calculate \(\left<A(t)B(t+\tau)\right>\) instead of \(\left<A(t+\tau)B(t)\right>\).

    solver str {‘me’, ‘mc’, ‘es’}

      choice of solver (me for master-equation, mc for Monte Carlo, and es for exponential series).

    options Options

      Solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    corr_vec ndarray

      An array of correlation values for the times specified by taulist.

  References

  See, Gardiner, Quantum Noise, Section 5.2.

correlation_2op_2t(H, state0, tlist, taulist, c_ops, a_op, b_op, solver='me', reverse=False, args={}, options=<qutip.solver.Options object>)

  Calculate the two-operator two-time correlation function: \(\left<A(t+\tau)B(t)\right>\) along two time axes using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Parameters:
    H Qobj

      system Hamiltonian, may be time-dependent for solver choice of me or mc.

    state0 Qobj

      Initial state density matrix \(\rho_0\) or state vector \(\psi_0\). If ‘state0’ is ‘None’, then the steady state will be used as the initial state. The ‘steady-state’ is only implemented for the me and es solvers.

    tlist array_like

      list of times for \(t\). tlist must be positive and contain the element 0. When taking steady-steady correlations only one tlist value is necessary, i.e. when \(t \rightarrow \infty\); here tlist is automatically set, ignoring user input.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators, may be time-dependent for solver choice of me or mc.

    a_op Qobj

      operator A.

    b_op Qobj

      operator B.

    reverse bool {False, True}

      If True, calculate \(\left<A(t)B(t+\tau)\right>\) instead of \(\left<A(t+\tau)B(t)\right>\).

    solver str

      choice of solver (me for master-equation, mc for Monte Carlo, and es for exponential series).

    options Options

      solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    corr_mat ndarray

      An 2-dimensional array (matrix) of correlation values for the times specified by tlist (first index) and taulist (second index). If tlist is None, then a 1-dimensional array of correlation values is returned instead.

  References

  See, Gardiner, Quantum Noise, Section 5.2.

correlation_3op_1t(H, state0, taulist, c_ops, a_op, b_op, c_op, solver='me', args={}, options=<qutip.solver.Options object>)

  Calculate the three-operator two-time correlation function: \(\left<A(t)B(t+\tau)C(t)\right>\) along one time axis using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Note: it is not possibly to calculate a physically meaningful correlation of this form where \(\tau<0\).

  Parameters:
    H Qobj

      system Hamiltonian, may be time-dependent for solver choice of me or mc.

    rho0 Qobj

      Initial state density matrix \(\rho(t_0)\) or state vector \(\psi(t_0)\). If ‘state0’ is ‘None’, then the steady state will be used as the initial state. The ‘steady-state’ is only implemented for the me and es solvers.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators, may be time-dependent for solver choice of me or mc.

    a_op Qobj

      operator A.

    b_op Qobj

      operator B.

    c_op Qobj

      operator C.

    solver str

      choice of solver (me for master-equation, mc for Monte Carlo, and es for exponential series).

    options Options

      solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    corr_vec array

      An array of correlation values for the times specified by taulist

  References

  See, Gardiner, Quantum Noise, Section 5.2.

correlation_3op_2t(H, state0, tlist, taulist, c_ops, a_op, b_op, c_op, solver='me', args={}, options=<qutip.solver.Options object>)

  Calculate the three-operator two-time correlation function: \(\left<A(t)B(t+\tau)C(t)\right>\) along two time axes using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Note: it is not possibly to calculate a physically meaningful correlation of this form where \(\tau<0\).

  Parameters:
    H Qobj

      system Hamiltonian, may be time-dependent for solver choice of me or mc.

    rho0 Qobj

      Initial state density matrix \(\rho_0\) or state vector \(\psi_0\). If ‘state0’ is ‘None’, then the steady state will be used as the initial state. The ‘steady-state’ is only implemented for the me and es solvers.

    tlist array_like

      list of times for \(t\). tlist must be positive and contain the element 0. When taking steady-steady correlations only one tlist value is necessary, i.e. when \(t \rightarrow \infty\); here tlist is automatically set, ignoring user input.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators, may be time-dependent for solver choice of me or mc.

    a_op Qobj

      operator A.

    b_op Qobj

      operator B.

    c_op Qobj

      operator C.

    solver str

      choice of solver (me for master-equation, mc for Monte Carlo, and es for exponential series).

    options Options

      solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    corr_mat array

      An 2-dimensional array (matrix) of correlation values for the times specified by tlist (first index) and taulist (second index). If tlist is None, then a 1-dimensional array of correlation values is returned instead.

  References

  See, Gardiner, Quantum Noise, Section 5.2.

correlation_4op_1t(H, state0, taulist, c_ops, a_op, b_op, c_op, d_op, solver='me', args={}, options=<qutip.solver.Options object>)

  Calculate the four-operator two-time correlation function: \(\left<A(t)B(t+\tau)C(t+\tau)D(t)\right>\) along one time axis using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Note: it is not possibly to calculate a physically meaningful correlation of this form where \(\tau<0\).

  Parameters:
    H Qobj

      system Hamiltonian, may be time-dependent for solver choice of me or mc.

    rho0 Qobj

      Initial state density matrix \(\rho(t_0)\) or state vector \(\psi(t_0)\). If ‘state0’ is ‘None’, then the steady state will be used as the initial state. The ‘steady-state’ is only implemented for the me and es solvers.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators, may be time-dependent for solver choice of me or mc.

    a_op Qobj

      operator A.

    b_op Qobj

      operator B.

    c_op Qobj

      operator C.

    d_op Qobj

      operator D.

    solver str

      choice of solver (me for master-equation, mc for Monte Carlo, and es for exponential series).

    options Options

      solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    corr_vec array

      An array of correlation values for the times specified by taulist.

  References

  See, Gardiner, Quantum Noise, Section 5.2.

  Note

  Deprecated in QuTiP 3.1 Use correlation_3op_1t() instead.

correlation_4op_2t(H, state0, tlist, taulist, c_ops, a_op, b_op, c_op, d_op, solver='me', args={}, options=<qutip.solver.Options object>)

  Calculate the four-operator two-time correlation function: \(\left<A(t)B(t+\tau)C(t+\tau)D(t)\right>\) along two time axes using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Note: it is not possibly to calculate a physically meaningful correlation of this form where \(\tau<0\).

  Parameters:
    H Qobj

      system Hamiltonian, may be time-dependent for solver choice of me or mc.

    rho0 Qobj

      Initial state density matrix \(\rho_0\) or state vector \(\psi_0\). If ‘state0’ is ‘None’, then the steady state will be used as the initial state. The ‘steady-state’ is only implemented for the me and es solvers.

    tlist array_like

      list of times for \(t\). tlist must be positive and contain the element 0. When taking steady-steady correlations only one tlist value is necessary, i.e. when \(t \rightarrow \infty\); here tlist is automatically set, ignoring user input.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators, may be time-dependent for solver choice of me or mc.

    a_op Qobj

      operator A.

    b_op Qobj

      operator B.

    c_op Qobj

      operator C.

    d_op Qobj

      operator D.

    solver str

      choice of solver (me for master-equation, mc for Monte Carlo, and es for exponential series).

    options Options

      solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    corr_mat array

      An 2-dimensional array (matrix) of correlation values for the times specified by tlist (first index) and taulist (second index). If tlist is None, then a 1-dimensional array of correlation values is returned instead.

  References

  See, Gardiner, Quantum Noise, Section 5.2.

correlation_ss(H, taulist, c_ops, a_op, b_op, solver='me', reverse=False, args={}, options=<qutip.solver.Options object>)

  Calculate the two-operator two-time correlation function:

  \[\lim_{t \to \infty} \left<A(t+\tau)B(t)\right>\]

  along one time axis (given steady-state initial conditions) using the quantum regression theorem and the evolution solver indicated by the solver parameter.

  Parameters:
    H Qobj

      system Hamiltonian.

    taulist array_like

      list of times for \(\tau\). taulist must be positive and contain the element 0.

    c_ops list

      list of collapse operators.

    a_op Qobj

      operator A.

    b_op Qobj

      operator B.

    reverse bool

      If True, calculate \(\lim_{t \to \infty} \left<A(t)B(t+\tau)\right>\) instead of \(\lim_{t \to \infty} \left<A(t+\tau)B(t)\right>\).

    solver str

      choice of solver (me for master-equation and es for exponential series).

    options Options

      solver options class. ntraj is taken as a two-element list because the mc correlator calls mcsolve() recursively; by default, ntraj=[20, 100]. mc_corr_eps prevents divide-by-zero errors in the mc correlator; by default, mc_corr_eps=1e-10.

  Returns:
    corr_vec array

      An array of correlation values for the times specified by tlist.

  References

  See, Gardiner, Quantum Noise, Section 5.2.

spectrum(H, wlist, c_ops, a_op, b_op, solver='es', use_pinv=False)

  Calculate the spectrum of the correlation function \(\lim_{t \to \infty} \left<A(t+\tau)B(t)\right>\), i.e., the Fourier transform of the correlation function:

  \[S(\omega) = \int_{-\infty}^{\infty} \lim_{t \to \infty} \left<A(t+\tau)B(t)\right> e^{-i\omega\tau} d\tau.\]

  using the solver indicated by the solver parameter. Note: this spectrum is only defined for stationary statistics (uses steady state rho0)

  Parameters:
    H `qutip.qobj`

      system Hamiltonian.

    wlist array_like

      list of frequencies for \(\omega\).

    c_ops list

      list of collapse operators.

    a_op Qobj

      operator A.

    b_op Qobj

      operator B.

    solver str

      choice of solver (es for exponential series and pi for psuedo-inverse).

    use_pinv bool

      For use with the pi solver: if True use numpy’s pinv method, otherwise use a generic solver.

  Returns:
    spectrum array

      An array with spectrum \(S(\omega)\) for the frequencies specified in wlist.

spectrum_correlation_fft(tlist, y, inverse=False)

  Calculate the power spectrum corresponding to a two-time correlation function using FFT.

  Parameters:
    tlist array_like

      list/array of times \(t\) which the correlation function is given.

    y array_like

      list/array of correlations corresponding to time delays \(t\).

    inverse: boolean

      boolean parameter for using a positive exponent in the Fourier Transform instead. Default is False.

  Returns:
    w, S tuple

      Returns an array of angular frequencies ‘w’ and the corresponding two-sided power spectrum ‘S(w)’.

spectrum_pi(H, wlist, c_ops, a_op, b_op, use_pinv=False)

  Calculate the spectrum of the correlation function \(\lim_{t \to \infty} \left<A(t+\tau)B(t)\right>\), i.e., the Fourier transform of the correlation function:

  \[S(\omega) = \int_{-\infty}^{\infty} \lim_{t \to \infty} \left<A(t+\tau)B(t)\right> e^{-i\omega\tau} d\tau.\]

  using a psuedo-inverse method. Note: this spectrum is only defined for stationary statistics (uses steady state rho0)

  Parameters:
    H `qutip.qobj`

      system Hamiltonian.

    wlist array_like

      list of frequencies for \(\omega\).

    c_ops list of `qutip.qobj`

      list of collapse operators.

    a_op `qutip.qobj`

      operator A.

    b_op `qutip.qobj`

      operator B.

    use_pinv bool

      If True use numpy’s pinv method, otherwise use a generic solver.

  Returns:
    spectrum array

      An array with spectrum \(S(\omega)\) for the frequencies specified in wlist.

spectrum_ss(H, wlist, c_ops, a_op, b_op)

  Calculate the spectrum of the correlation function \(\lim_{t \to \infty} \left<A(t+\tau)B(t)\right>\), i.e., the Fourier transform of the correlation function:

  \[S(\omega) = \int_{-\infty}^{\infty} \lim_{t \to \infty} \left<A(t+\tau)B(t)\right> e^{-i\omega\tau} d\tau.\]

  using an eseries based solver Note: this spectrum is only defined for stationary statistics (uses steady state rho0).

  Parameters:
    H `qutip.qobj`

      system Hamiltonian.

    wlist array_like

      list of frequencies for \(\omega\).

    c_ops list of `qutip.qobj`

      list of collapse operators.

    a_op `qutip.qobj`

      operator A.

    b_op `qutip.qobj`

      operator B.

    use_pinv bool

      If True use numpy’s pinv method, otherwise use a generic solver.

  Returns:
    spectrum array

      An array with spectrum \(S(\omega)\) for the frequencies specified in wlist.

### Steady-state Solvers

Module contains functions for solving for the steady state density matrix of open quantum systems defined by a Liouvillian or Hamiltonian and a list of collapse operators.

build_preconditioner(A, c_op_list=[], **kwargs)

  Constructs a iLU preconditioner necessary for solving for the steady state density matrix using the iterative linear solvers in the ‘steadystate’ function.

  Parameters:
    A qobj

      A Hamiltonian or Liouvillian operator.

    c_op_list list

      A list of collapse operators.

    return_info bool, optional, default = False

      Return a dictionary of solver-specific infomation about the solution and how it was obtained.

    use_rcm bool, optional, default = False

      Use reverse Cuthill-Mckee reordering to minimize fill-in in the LU factorization of the Liouvillian.

    use_wbm bool, optional, default = False

      Use Weighted Bipartite Matching reordering to make the Liouvillian diagonally dominant. This is useful for iterative preconditioners only, and is set to `True` by default when finding a preconditioner.

    weight float, optional

      Sets the size of the elements used for adding the unity trace condition to the linear solvers. This is set to the average abs value of the Liouvillian elements if not specified by the user.

    method str, default = ‘iterative’

      Tells the preconditioner what type of Liouvillian to build for iLU factorization. For direct iterative methods use ‘iterative’. For power iterative methods use ‘power’.

    permc_spec str, optional, default=’COLAMD’

      Column ordering used internally by superLU for the ‘direct’ LU decomposition method. Options include ‘COLAMD’ and ‘NATURAL’. If using RCM then this is set to ‘NATURAL’ automatically unless explicitly specified.

    fill_factor float, optional, default = 100

      Specifies the fill ratio upper bound (>=1) of the iLU preconditioner. Lower values save memory at the cost of longer execution times and a possible singular factorization.

    drop_tol float, optional, default = 1e-4

      Sets the threshold for the magnitude of preconditioner elements that should be dropped. Can be reduced for a courser factorization at the cost of an increased number of iterations, and a possible singular factorization.

    diag_pivot_thresh float, optional, default = None

      Sets the threshold between [0,1] for which diagonal elements are considered acceptable pivot points when using a preconditioner. A value of zero forces the pivot to be the diagonal element.

    ILU_MILU str, optional, default = ‘smilu_2’

      Selects the incomplete LU decomposition method algoithm used in creating the preconditoner. Should only be used by advanced users.

  Returns:
    lu object

      Returns a SuperLU object representing iLU preconditioner.

    info dict, optional

      Dictionary containing solver-specific information.

steadystate(A, c_op_list=[], method='direct', solver=None, **kwargs)

  Calculates the steady state for quantum evolution subject to the supplied Hamiltonian or Liouvillian operator and (if given a Hamiltonian) a list of collapse operators.

  If the user passes a Hamiltonian then it, along with the list of collapse operators, will be converted into a Liouvillian operator in Lindblad form.

  Parameters:
    A `Qobj`

      A Hamiltonian or Liouvillian operator.

    c_op_list list

      A list of collapse operators.

    solver{‘scipy’, ‘mkl’}, optional

      Selects the sparse solver to use. Default is to auto-select based on the availability of the MKL library.

    method str, default ‘direct’

      The allowed methods are

      - ‘direct’

      - ‘eigen’

      - ‘iterative-gmres’

      - ‘iterative-lgmres’

      - ‘iterative-bicgstab’

      - ‘svd’

      - ‘power’

      - ‘power-gmres’

      - ‘power-lgmres’

      - ‘power-bicgstab’

      Method for solving the underlying linear equation. Direct LU solver ‘direct’ (default), sparse eigenvalue problem ‘eigen’, iterative GMRES method ‘iterative-gmres’, iterative LGMRES method ‘iterative-lgmres’, iterative BICGSTAB method ‘iterative-bicgstab’, SVD ‘svd’ (dense), or inverse-power method ‘power’. The iterative power methods ‘power-gmres’, ‘power-lgmres’, ‘power-bicgstab’ use the same solvers as their direct counterparts.

    return_info bool, default False

      Return a dictionary of solver-specific infomation about the solution and how it was obtained.

    sparse bool, default True

      Solve for the steady state using sparse algorithms. If set to False, the underlying Liouvillian operator will be converted into a dense matrix. Use only for ‘smaller’ systems.

    use_rcm bool, default False

      Use reverse Cuthill-Mckee reordering to minimize fill-in in the LU factorization of the Liouvillian.

    use_wbm bool, default False

      Use Weighted Bipartite Matching reordering to make the Liouvillian diagonally dominant. This is useful for iterative preconditioners only, and is set to `True` by default when finding a preconditioner.

    weight float, optional

      Sets the size of the elements used for adding the unity trace condition to the linear solvers. This is set to the average abs value of the Liouvillian elements if not specified by the user.

    max_iter_refine int, default 10

      MKL ONLY. Max. number of iterative refinements to perform.

    scaling_vectors bool

      MKL ONLY. Scale matrix to unit norm columns and rows.

    weighted_matching bool

      MKL ONLY. Use weighted matching to better condition diagonal.

    x0 ndarray, optional

      ITERATIVE ONLY. Initial guess for solution vector.

    maxiter int, default 1000

      ITERATIVE ONLY. Maximum number of iterations to perform.

    tol float, default 1e-12

      ITERATIVE ONLY. Tolerance used for terminating solver.

    mtol float, optional

      ITERATIVE ‘power’ methods ONLY. Tolerance for lu solve method. If None given then `max(0.1*tol, 1e-15)` is used.

    matol float, default 1e-15

      ITERATIVE ONLY. Absolute tolerance for lu solve method.

    permc_spec str, optional

      ITERATIVE ONLY. Column ordering used internally by superLU for the ‘direct’ LU decomposition method. Options include ‘COLAMD’ (default) and ‘NATURAL’. If using RCM then this is set to ‘NATURAL’ automatically unless explicitly specified.

    use_precond bool, default False

      ITERATIVE ONLY. Use an incomplete sparse LU decomposition as a preconditioner for the ‘iterative’ GMRES and BICG solvers. Speeds up convergence time by orders of magnitude in many cases.

    M{sparse matrix, dense matrix, LinearOperator}, optional

      ITERATIVE ONLY. Preconditioner for A. The preconditioner should approximate the inverse of A. Effective preconditioning can dramatically improve the rate of convergence for iterative methods. If no preconditioner is given and `use_precond = True`, then one is generated automatically.

    fill_factor float, default 100

      ITERATIVE ONLY. Specifies the fill ratio upper bound (>=1) of the iLU preconditioner. Lower values save memory at the cost of longer execution times and a possible singular factorization.

    drop_tol float, default 1e-4

      ITERATIVE ONLY. Sets the threshold for the magnitude of preconditioner elements that should be dropped. Can be reduced for a courser factorization at the cost of an increased number of iterations, and a possible singular factorization.

    diag_pivot_thresh float, optional

      ITERATIVE ONLY. Sets the threshold between [0,1] for which diagonal elements are considered acceptable pivot points when using a preconditioner. A value of zero forces the pivot to be the diagonal element.

    ILU_MILU str, default ‘smilu_2’

      ITERATIVE ONLY. Selects the incomplete LU decomposition method algoithm used in creating the preconditoner. Should only be used by advanced users.

  Returns:
    dm qobj

      Steady state density matrix.

    info dict, optional

      Dictionary containing solver-specific information about the solution.

  Notes

  The SVD method works only for dense operators (i.e. small systems).

### Propagators

propagator(H, t, c_op_list=[], args={}, options=None, unitary_mode='batch', parallel=False, progress_bar=None, _safe_mode=True, **kwargs)

  Calculate the propagator U(t) for the density matrix or wave function such that \(\psi(t) = U(t)\psi(0)\) or \(\rho_{\mathrm vec}(t) = U(t) \rho_{\mathrm vec}(0)\) where \(\rho_{\mathrm vec}\) is the vector representation of the density matrix.

  Parameters:
    H qobj or list

      Hamiltonian as a Qobj instance of a nested list of Qobjs and coefficients in the list-string or list-function format for time-dependent Hamiltonians (see description in `qutip.mesolve`).

    t float or array-like

      Time or list of times for which to evaluate the propagator.

    c_op_list list

      List of qobj collapse operators.

    args list/array/dictionary

      Parameters to callback functions for time-dependent Hamiltonians and collapse operators.

    options `qutip.solver.Options`

      with options for the ODE solver.

    unitary_mode = str (‘batch’, ‘single’)

      Solve all basis vectors simulaneously (‘batch’) or individually (‘single’).

    parallel bool {False, True}

      Run the propagator in parallel mode. This will override the unitary_mode settings if set to True.

    progress_bar: BaseProgressBar

      Optional instance of BaseProgressBar, or a subclass thereof, for showing the progress of the simulation. By default no progress bar is used, and if set to True a TextProgressBar will be used.

  Returns:
    a qobj

      Instance representing the propagator \(U(t)\).

propagator_steadystate(U)

  Find the steady state for successive applications of the propagator \(U\).

  Parameters:
    U qobj

      Operator representing the propagator.

  Returns:
    a qobj

      Instance representing the steady-state density matrix.

### Time-dependent problems

rhs_clear()

  Resets the string-format time-dependent Hamiltonian parameters.

  Parameters:

  Returns:
    Nothing, just clears data from internal config module.

### Scattering in Quantum Optical Systems

Photon scattering in quantum optical systems

This module includes a collection of functions for numerically computing photon scattering in driven arbitrary systems coupled to some configuration of output waveguides. The implementation of these functions closely follows the mathematical treatment given in K.A. Fischer, et. al., Scattering of Coherent Pulses from Quantum Optical Systems (2017, arXiv:1710.02875).

scattering_probability(H, psi0, n_emissions, c_ops, tlist, system_zero_state=None, construct_effective_hamiltonian=True)

  Compute the integrated probability of scattering n photons in an arbitrary system. This function accepts a nonlinearly spaced array of times.

  Parameters:
    H:class: qutip.Qobj or list

      System-waveguide(s) Hamiltonian or effective Hamiltonian in Qobj or list-callback format. If construct_effective_hamiltonian is not specified, an effective Hamiltonian is constructed from H and c_ops.

    psi0:class: qutip.Qobj

      Initial state density matrix \(\rho(t_0)\) or state vector \(\psi(t_0)\).

    n_emissions int

      Number of photons emitted by the system (into any combination of waveguides).

    c_ops list

      List of collapse operators for each waveguide; these are assumed to include spontaneous decay rates, e.g. \(\sigma = \sqrt \gamma \cdot a\).

    tlist array_like

      List of times for \(\tau_i\). tlist should contain 0 and exceed the pulse duration / temporal region of interest; tlist need not be linearly spaced.

    system_zero_state:class: qutip.Qobj

      State representing zero excitations in the system. Defaults to basis(systemDims, 0).

    construct_effective_hamiltonian bool

      Whether an effective Hamiltonian should be constructed from H and c_ops: \(H_{eff} = H - \frac{i}{2} \sum_n \sigma_n^\dagger \sigma_n\) Default: True.

  Returns:
    scattering_prob float

      The probability of scattering n photons from the system over the time range specified.

temporal_basis_vector(waveguide_emission_indices, n_time_bins)

  Generate a temporal basis vector for emissions at specified time bins into specified waveguides.

  Parameters:
    waveguide_emission_indices list or tuple

      List of indices where photon emission occurs for each waveguide, e.g. [[t1_wg1], [t1_wg2, t2_wg2], [], [t1_wg4, t2_wg4, t3_wg4]].

    n_time_bins int

      Number of time bins; the range over which each index can vary.

  Returns:
    temporal_basis_vector:class: qutip.Qobj

      A basis vector representing photon scattering at the specified indices. If there are W waveguides, T times, and N photon emissions, then the basis vector has dimensionality (W*T)^N.

temporal_scattered_state(H, psi0, n_emissions, c_ops, tlist, system_zero_state=None, construct_effective_hamiltonian=True)

  Compute the scattered n-photon state projected onto the temporal basis.

  Parameters:
    H:class: qutip.Qobj or list

      System-waveguide(s) Hamiltonian or effective Hamiltonian in Qobj or list-callback format. If construct_effective_hamiltonian is not specified, an effective Hamiltonian is constructed from H and c_ops.

    psi0:class: qutip.Qobj

      Initial state density matrix \(\rho(t_0)\) or state vector \(\psi(t_0)\).

    n_emissions int

      Number of photon emissions to calculate.

    c_ops list

      List of collapse operators for each waveguide; these are assumed to include spontaneous decay rates, e.g. \(\sigma = \sqrt \gamma \cdot a\)

    tlist array_like

      List of times for \(\tau_i\). tlist should contain 0 and exceed the pulse duration / temporal region of interest.

    system_zero_state:class: qutip.Qobj

      State representing zero excitations in the system. Defaults to \(\psi(t_0)\)

    construct_effective_hamiltonian bool

      Whether an effective Hamiltonian should be constructed from H and c_ops: \(H_{eff} = H - \frac{i}{2} \sum_n \sigma_n^\dagger \sigma_n\) Default: True.

  Returns:
    phi_n:class: qutip.Qobj

      The scattered bath state projected onto the temporal basis given by tlist. If there are W waveguides, T times, and N photon emissions, then the state is a tensor product state with dimensionality T^(W*N).

### Permutational Invariance

Permutational Invariant Quantum Solver (PIQS)

This module calculates the Liouvillian for the dynamics of ensembles of identical two-level systems (TLS) in the presence of local and collective processes by exploiting permutational symmetry and using the Dicke basis. It also allows to characterize nonlinear functions of the density matrix.

am(j, m)

  Calculate the operator `am` used later.

  The action of `ap` is given by: \(J_{-}\lvert j,m\rangle = A_{-}(jm)\lvert j,m-1\rangle\)

  Parameters:
    j: float

      The value for j.

    m: float

      The value for m.

  Returns:
    a_minus: float

      The value of \(a_{-}\).

ap(j, m)

  Calculate the coefficient `ap` by applying \(J_+\lvert j,m\rangle\).

  The action of ap is given by: \(J_{+}\lvert j, m\rangle = A_{+}(j, m) \lvert j, m+1\rangle\)

  Parameters:
    j, m: float

      The value for j and m in the dicke basis \(\lvert j, m\rangle\).

  Returns:
    a_plus: float

      The value of \(a_{+}\).

block_matrix(N, elements='ones')

  Construct the block-diagonal matrix for the Dicke basis.

  Parameters:
    N int

      Number of two-level systems.

    elements str {‘ones’ (default),’degeneracy’}
  Returns:
    block_matr ndarray

      A 2D block-diagonal matrix with dimension (nds,nds), where nds is the number of Dicke states for N two-level systems. Filled with ones or the value of degeneracy at each matrix element.

collapse_uncoupled(N, emission=0.0, dephasing=0.0, pumping=0.0, collective_emission=0.0, collective_dephasing=0.0, collective_pumping=0.0)

  Create the collapse operators (c_ops) of the Lindbladian in the uncoupled basis

  These operators are in the uncoupled basis of the two-level system (TLS) SU(2) Pauli matrices.

  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

  Returns:
    c_ops: list

      The list of collapse operators as qutip.Qobj for the system.

  Notes

  The collapse operator list can be given to qutip.mesolve. Notice that the operators are placed in a Hilbert space of dimension \(2^N\). Thus the method is suitable only for small N (of the order of 10).

css(N, x=0.7071067811865475, y=0.7071067811865475, basis='dicke', coordinates='cartesian')

  Generate the density matrix of the Coherent Spin State (CSS).

  It can be defined as, \(\lvert CSS\rangle = \prod_i^N(a\lvert1\rangle_i+b\lvert0\rangle_i)\) with \(a = sin(\frac{\theta}{2})\), \(b = e^{i \phi}\cos(\frac{\theta}{2})\). The default basis is that of Dicke space \(\lvert j, m\rangle \langle j, m'\rvert\). The default state is the symmetric CSS, \(\lvert CSS\rangle = \lvert+\rangle\).

  Parameters:
    N: int

      The number of two-level systems.

    x, y: float

      The coefficients of the CSS state.

    basis: str

      The basis to use. Either “dicke” or “uncoupled”.

    coordinates: str

      Either “cartesian” or “polar”. If polar then the coefficients are constructed as sin(x/2), cos(x/2)e^(iy).

  Returns:
    rho: :class: qutip.Qobj

      The CSS state density matrix.

dicke(N, j, m)

  Generate a Dicke state as a pure density matrix in the Dicke basis.

  For instance, the superradiant state given by \(\lvert j, m\rangle = \lvert 1, 0\rangle\) for N = 2, and the state is represented as a density matrix of size (nds, nds) or (4, 4), with the (1, 1) element set to 1.

  Parameters:
    N: int

      The number of two-level systems.

    j: float

      The eigenvalue j of the Dicke state (j, m).

    m: float

      The eigenvalue m of the Dicke state (j, m).

  Returns:
    rho: :class: qutip.Qobj

      The density matrix.

dicke_basis(N, jmm1=None)

  Initialize the density matrix of a Dicke state for several (j, m, m1).

  This function can be used to build arbitrary states in the Dicke basis \(\lvert j, m\rangle\langle j, m'\rvert\). We create coefficients for each (j, m, m1) value in the dictionary jmm1. The mapping for the (i, k) index of the density matrix to the \(\lvert j, m\rangle\) values is given by the cythonized function jmm1_dictionary. A density matrix is created from the given dictionary of coefficients for each (j, m, m1).

  Parameters:
    N: int

      The number of two-level systems.

    jmm1: dict

      A dictionary of {(j, m, m1): p} that gives a density p for the (j, m, m1) matrix element.

  Returns:
    rho: :class: qutip.Qobj

      The density matrix in the Dicke basis.

dicke_blocks(rho)

  Create the list of blocks for block-diagonal density matrix in the Dicke basis.

  Parameters:
    rho `qutip.Qobj`

      A 2D block-diagonal matrix of ones with dimension (nds,nds), where nds is the number of Dicke states for N two-level systems.

  Returns:
    square_blocks: list of np.array

      Give back the blocks list.

dicke_blocks_full(rho)

  Give the full (2^N-dimensional) list of blocks for a Dicke-basis matrix.

  Parameters:
    rho `qutip.Qobj`

      A 2D block-diagonal matrix of ones with dimension (nds,nds), where nds is the number of Dicke states for N two-level systems.

  Returns:
    full_blocks list

      The list of blocks expanded in the 2^N space for N qubits.

dicke_function_trace(f, rho)

  Calculate the trace of a function on a Dicke density matrix. :param f: A Taylor-expandable function of rho. :type f: function :param rho: A density matrix in the Dicke basis. :type rho: `qutip.Qobj`

  Returns:
    res float

      Trace of a nonlinear function on rho.

energy_degeneracy(N, m)

  Calculate the number of Dicke states with same energy.

  The use of the Decimals class allows to explore N > 1000, unlike the built-in function scipy.special.binom

  Parameters:
    N: int

      The number of two-level systems.

    m: float

      Total spin z-axis projection eigenvalue. This is proportional to the total energy.

  Returns:
    degeneracy: int

      The energy degeneracy

entropy_vn_dicke(rho)

  Von Neumann Entropy of a Dicke-basis density matrix.

  Parameters:
    rho `qutip.Qobj`

      A 2D block-diagonal matrix of ones with dimension (nds,nds), where nds is the number of Dicke states for N two-level systems.

  Returns:
    entropy_dm: float

      Entropy. Use degeneracy to multiply each block.

excited(N, basis='dicke')

  Generate the density matrix for the excited state.

  This state is given by (N/2, N/2) in the default Dicke basis. If the argument basis is “uncoupled” then it generates the state in a 2**N dim Hilbert space.

  Parameters:
    N: int

      The number of two-level systems.

    basis: str

      The basis to use. Either “dicke” or “uncoupled”.

  Returns:
    state: :class: qutip.Qobj

      The excited state density matrix in the requested basis.

ghz(N, basis='dicke')

  Generate the density matrix of the GHZ state.

  If the argument basis is “uncoupled” then it generates the state in a \(2^N\)-dimensional Hilbert space.

  Parameters:
    N: int

      The number of two-level systems.

    basis: str

      The basis to use. Either “dicke” or “uncoupled”.

  Returns:
    state: :class: qutip.Qobj

      The GHZ state density matrix in the requested basis.

ground(N, basis='dicke')

  Generate the density matrix of the ground state.

  This state is given by (N/2, -N/2) in the Dicke basis. If the argument basis is “uncoupled” then it generates the state in a \(2^N\)-dimensional Hilbert space.

  Parameters:
    N: int

      The number of two-level systems.

    basis: str

      The basis to use. Either “dicke” or “uncoupled”

  Returns:
    state: :class: qutip.Qobj

      The ground state density matrix in the requested basis.

identity_uncoupled(N)

  Generate the identity in a \(2^N\)-dimensional Hilbert space.

  The identity matrix is formed from the tensor product of N TLSs.

  Parameters:
    N: int

      The number of two-level systems.

  Returns:
    identity: :class: qutip.Qobj

      The identity matrix.

isdiagonal(mat)

  Check if the input matrix is diagonal.

  Parameters:
    mat: ndarray/Qobj

      A 2D numpy array

  Returns:
    diag: bool

      True/False depending on whether the input matrix is diagonal.

jspin(N, op=None, basis='dicke')

  Calculate the list of collective operators of the total algebra.

  The Dicke basis \(\lvert j,m\rangle\langle j,m'\rvert\) is used by default. Otherwise with “uncoupled” the operators are in a \(2^N\) space.

  Parameters:
    N: int

      Number of two-level systems.

    op: str

      The operator to return ‘x’,’y’,’z’,’+’,’-‘. If no operator given, then output is the list of operators for [‘x’,’y’,’z’].

    basis: str

      The basis of the operators - “dicke” or “uncoupled” default: “dicke”.

  Returns:
    j_alg: list or :class: qutip.Qobj

      A list of qutip.Qobj representing all the operators in the “dicke” or “uncoupled” basis or a single operator requested.

m_degeneracy(N, m)

  Calculate the number of Dicke states \(\lvert j, m\rangle\) with same energy.

  Parameters:
    N: int

      The number of two-level systems.

    m: float

      Total spin z-axis projection eigenvalue (proportional to the total energy).

  Returns:
    degeneracy: int

      The m-degeneracy.

num_dicke_ladders(N)

  Calculate the total number of ladders in the Dicke space.

  For a collection of N two-level systems it counts how many different “j” exist or the number of blocks in the block-diagonal matrix.

  Parameters:
    N: int

      The number of two-level systems.

  Returns:
    Nj: int

      The number of Dicke ladders.

num_dicke_states(N)

  Calculate the number of Dicke states.

  Parameters:
    N: int

      The number of two-level systems.

  Returns:
    nds: int

      The number of Dicke states.

num_tls(nds)

  Calculate the number of two-level systems.

  Parameters:
    nds: int

      The number of Dicke states.

  Returns:
    N: int

      The number of two-level systems.

purity_dicke(rho)

  Calculate purity of a density matrix in the Dicke basis. It accounts for the degenerate blocks in the density matrix.

  Parameters:
    rho `qutip.Qobj`

      Density matrix in the Dicke basis of qutip.piqs.jspin(N), for N spins.

  Returns:
    purity float

      The purity of the quantum state. It’s 1 for pure states, 0<=purity<1 for mixed states.

spin_algebra(N, op=None)

  Create the list [sx, sy, sz] with the spin operators.

  The operators are constructed for a collection of N two-level systems (TLSs). Each element of the list, i.e., sx, is a vector of qutip.Qobj objects (spin matrices), as it cointains the list of the SU(2) Pauli matrices for the N TLSs. Each TLS operator sx[i], with i = 0, …, (N-1), is placed in a \(2^N\)-dimensional Hilbert space.

  Parameters:
    N: int

      The number of two-level systems.

  Returns:
    spin_operators: list or :class: qutip.Qobj

      A list of qutip.Qobj operators - [sx, sy, sz] or the requested operator.

  Notes

  sx[i] is \(\frac{\sigma_x}{2}\) in the composite Hilbert space.

state_degeneracy(N, j)

  Calculate the degeneracy of the Dicke state.

  Each state \(\lvert j, m\rangle\) includes D(N,j) irreducible representations \(\lvert j, m, \alpha\rangle\).

  Uses Decimals to calculate higher numerator and denominators numbers.

  Parameters:
    N: int

      The number of two-level systems.

    j: float

      Total spin eigenvalue (cooperativity).

  Returns:
    degeneracy: int

      The state degeneracy.

superradiant(N, basis='dicke')

  Generate the density matrix of the superradiant state.

  This state is given by (N/2, 0) or (N/2, 0.5) in the Dicke basis. If the argument basis is “uncoupled” then it generates the state in a 2**N dim Hilbert space.

  Parameters:
    N: int

      The number of two-level systems.

    basis: str

      The basis to use. Either “dicke” or “uncoupled”.

  Returns:
    state: :class: qutip.Qobj

      The superradiant state density matrix in the requested basis.

tau_column(tau, k, j)

  Determine the column index for the non-zero elements of the matrix for a particular row k and the value of j from the Dicke space.

  Parameters:
    tau: str

      The tau function to check for this k and j.

    k: int

      The row of the matrix M for which the non zero elements have to be calculated.

    j: float

      The value of j for this row.

## Lattice

### Lattice Properties

cell_structures(val_s=None, val_t=None, val_u=None)

  Returns two matrices H_cell and cell_T to help the user form the inputs for defining an instance of Lattice1d and Lattice2d classes. The two matrices are the intra and inter cell Hamiltonians with the tensor structure of the specified site numbers and/or degrees of freedom defined by the user.

  Parameters:
    val_s list of str/str

      The first list of str’s specifying the sites/degrees of freedom in the unitcell

    val_t list of str/str

      The second list of str’s specifying the sites/degrees of freedom in the unitcell

    val_u list of str/str

      The third list of str’s specifying the sites/degrees of freedom in the unitcell

  Returns:
    H_cell_s list of list of str

      tensor structure of the cell Hamiltonian elements

    T_inter_cell_s list of list of str

      tensor structure of the inter cell Hamiltonian elements

    H_cell Qobj

      A Qobj initiated with all 0s with proper shape for an input as Hamiltonian_of_cell in Lattice1d.__init__()

    T_inter_cell Qobj

      A Qobj initiated with all 0s with proper shape for an input as inter_hop in Lattice1d.__init__()

### Topology

berry_curvature(eigfs)

  Computes the discretized Berry curvature on the two dimensional grid of parameters. The function works well for cases with no band mixing.

  Parameters:
    eigfs numpy ndarray

      4 dimensional numpy ndarray where the first two indices are for the two discrete values of the two parameters and the third is the index of the occupied bands. The fourth dimension holds the eigenfunctions.

  Returns:
    b_curv numpy ndarray

      A two dimensional array of the discretized Berry curvature defined for the values of the two parameters defined in the eigfs.

plot_berry_curvature(eigfs)

  Plots the discretized Berry curvature on the two dimensional grid of parameters. The function works well for cases with no band mixing.

## Visualization

### Pseudoprobability Functions

qfunc(state: Qobj, xvec, yvec, g: float = 1.4142135623730951, precompute_memory: float = 1024)

  Husimi-Q function of a given state vector or density matrix at phase-space points `0.5 * g * (xvec + i*yvec)`.

  Parameters:
    state `Qobj`

      A state vector or density matrix. This cannot have tensor-product structure.

    xvec, yvec array_like

      x- and y-coordinates at which to calculate the Husimi-Q function.

    g float, 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\).

    precompute_memory real, default 1024

      Size in MB that may be used during calculations as working space when dealing with density-matrix inputs. This is ignored for state-vector inputs. The bound is not quite exact due to other, order-of-magnitude smaller, intermediaries being necessary, but is a good approximation. If you want to use the same iterative algorithm for density matrices that is used for single kets, set `precompute_memory=None`.

  Returns:
    ndarray

      Values representing the Husimi-Q function calculated over the specified range `[xvec, yvec]`.

  See also

  `QFunc`

    a class-based version, more efficient if you want to calculate the Husimi-Q function for several states over the same coordinates.

spin_q_function(rho, theta, phi)

  The Husimi Q function for spins is defined as `Q(theta, phi) = SCS.dag() * rho * SCS` for the spin coherent state `SCS = spin_coherent( j, theta, phi)` where j is the spin length. The implementation here is more efficient as it doesn’t generate all of the SCS at theta and phi (see references).

  The spin Q function is normal when integrated over the surface of the sphere

  \[\frac{4 \pi}{2j + 1}\int_\phi \int_\theta Q(\theta, \phi) \sin(\theta) d\theta d\phi = 1\]
  Parameters:
    state qobj

      A state vector or density matrix for a spin-j quantum system.

    theta array_like

      Polar (colatitude) angle at which to calculate the Husimi-Q function.

    phi array_like

      Azimuthal angle at which to calculate the Husimi-Q function.

  Returns:
    Q, THETA, PHI 2d-array

      Values representing the spin Husimi Q function at the values specified by THETA and PHI.

  References

  [1] Lee Loh, Y., & Kim, M. (2015). American J. of Phys., 83(1), 30–35. https://doi.org/10.1119/1.4898595

spin_wigner(rho, theta, phi)

  Wigner function for a spin-j system.

  The spin W function is normal when integrated over the surface of the sphere

  \[\sqrt{\frac{4 \pi}{2j + 1}}\int_\phi \int_\theta W(\theta,\phi) \sin(\theta) d\theta d\phi = 1\]
  Parameters:
    state qobj

      A state vector or density matrix for a spin-j quantum system.

    theta array_like

      Polar (colatitude) angle at which to calculate the W function.

    phi array_like

      Azimuthal angle at which to calculate the W function.

  Returns:
    W, THETA, PHI 2d-array

      Values representing the spin Wigner function at the values specified by THETA and PHI.

  References

  [1] Agarwal, G. S. (1981). Phys. Rev. A, 24(6), 2889–2896. https://doi.org/10.1103/PhysRevA.24.2889

  [2] Dowling, J. P., Agarwal, G. S., & Schleich, W. P. (1994). Phys. Rev. A, 49(5), 4101–4109. https://doi.org/10.1103/PhysRevA.49.4101

  [3] Conversion between Wigner 3-j symbol and Clebsch-Gordan coefficients taken from Wikipedia (https://en.wikipedia.org/wiki/3-j_symbol)

wigner(psi, xvec, yvec, method='clenshaw', g=1.4142135623730951, sparse=False, parfor=False)

  Wigner function for a state vector or density matrix at points xvec + i * yvec.

  Parameters:
    state qobj

      A state vector or density matrix.

    xvec array_like

      x-coordinates at which to calculate the Wigner function.

    yvec array_like

      y-coordinates at which to calculate the Wigner function. Does not apply to the ‘fft’ method.

    g float

      Scaling factor for a = 0.5 * g * (x + iy), default g = sqrt(2). The value of g is related to the value of hbar in the commutation relation [x, y] = i * hbar via hbar=2/g^2 giving the default value hbar=1.

    method string {‘clenshaw’, ‘iterative’, ‘laguerre’, ‘fft’}

      Select method ‘clenshaw’ ‘iterative’, ‘laguerre’, or ‘fft’, where ‘clenshaw’ and ‘iterative’ use an iterative method to evaluate the Wigner functions for density matrices \(|m><n|\), while ‘laguerre’ uses the Laguerre polynomials in scipy for the same task. The ‘fft’ method evaluates the Fourier transform of the density matrix. The ‘iterative’ method is default, and in general recommended, but the ‘laguerre’ method is more efficient for very sparse density matrices (e.g., superpositions of Fock states in a large Hilbert space). The ‘clenshaw’ method is the preferred method for dealing with density matrices that have a large number of excitations (>~50). ‘clenshaw’ is a fast and numerically stable method.

    sparse bool {False, True}

      Tells the default solver whether or not to keep the input density matrix in sparse format. As the dimensions of the density matrix grow, setthing this flag can result in increased performance.

    parfor bool {False, True}

      Flag for calculating the Laguerre polynomial based Wigner function method=’laguerre’ in parallel using the parfor function.

  Returns:
    W array

      Values representing the Wigner function calculated over the specified range [xvec,yvec].

    yvex array

      FFT ONLY. Returns the y-coordinate values calculated via the Fourier transform.

  Notes

  The ‘fft’ method accepts only an xvec input for the x-coordinate. The y-coordinates are calculated internally.

  References

  Ulf Leonhardt, Measuring the Quantum State of Light, (Cambridge University Press, 1997)

### Graphs and Visualization

Functions for visualizing results of quantum dynamics simulations, visualizations of quantum states and processes.

hinton(rho, xlabels=None, ylabels=None, title=None, ax=None, cmap=None, label_top=True, color_style='scaled')

  Draws a Hinton diagram for visualizing a density matrix or superoperator.

  Parameters:
    rho qobj

      Input density matrix or superoperator.

    xlabels list of strings or False

      list of x labels

    ylabels list of strings or False

      list of y labels

    title string

      title of the plot (optional)

    ax a matplotlib axes instance

      The axes context in which the plot will be drawn.

    cmap a matplotlib colormap instance

      Color map to use when plotting.

    label_top bool

      If True, x-axis labels will be placed on top, otherwise they will appear below the plot.

    color_style string

      Determines how colors are assigned to each square:

      - If set to `"scaled"` (default), each color is chosen by passing the absolute value of the corresponding matrix element into cmap with the sign of the real part.

      - If set to `"threshold"`, each square is plotted as the maximum of cmap for the positive real part and as the minimum for the negative part of the matrix element; note that this generalizes “threshold” to complex numbers.

      - If set to `"phase"`, each color is chosen according to the angle of the corresponding matrix element.

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

  Raises:
    ValueError

      Input argument is not a quantum object.

  Examples

      >>> import qutip
      >>>
      >>> dm = qutip.rand_dm(4)
      >>> fig, ax = qutip.hinton(dm)
      >>> fig.show()
      >>>
      >>> qutip.settings.colorblind_safe = True
      >>> fig, ax = qutip.hinton(dm, color_style="threshold")
      >>> fig.show()
      >>> qutip.settings.colorblind_safe = False
      >>>
      >>> fig, ax = qutip.hinton(dm, color_style="phase")
      >>> fig.show()

matrix_histogram(M, xlabels=None, ylabels=None, title=None, limits=None, colorbar=True, fig=None, ax=None, options=None)

  Draw a histogram for the matrix M, with the given x and y labels and title.

  Parameters:
    M Matrix of Qobj

      The matrix to visualize

    xlabels list of strings

      list of x labels

    ylabels list of strings

      list of y labels

    title string

      title of the plot (optional)

    limits list/array with two float numbers

      The z-axis limits [min, max] (optional)

    ax a matplotlib axes instance

      The axes context in which the plot will be drawn.

    colorbar bool (default: True)

      show colorbar

    options dict

      A dictionary containing extra options for the plot. The names (keys) and values of the options are described below:

      ‘zticks’list of numbers

        A list of z-axis tick locations.

      ‘cmap’string (default: ‘jet’)

        The name of the color map to use.

      ‘cmap_min’float (default: 0.0)

        The lower bound to truncate the color map at. A value in range 0 - 1. The default, 0, leaves the lower bound of the map unchanged.

      ‘cmap_max’float (default: 1.0)

        The upper bound to truncate the color map at. A value in range 0 - 1. The default, 1, leaves the upper bound of the map unchanged.

      ‘bars_spacing’float (default: 0.1)

        spacing between bars.

      ‘bars_alpha’float (default: 1.)

        transparency of bars, should be in range 0 - 1

      ‘bars_lw’float (default: 0.5)

        linewidth of bars’ edges.

      ‘bars_edgecolor’color (default: ‘k’)

        The colors of the bars’ edges. Examples: ‘k’, (0.1, 0.2, 0.5) or ‘#0f0f0f80’.

      ‘shade’bool (default: True)

        Whether to shade the dark sides of the bars (True) or not (False). The shading is relative to plot’s source of light.

      ‘azim’float

        The azimuthal viewing angle.

      ‘elev’float

        The elevation viewing angle.

      ‘proj_type’string (default: ‘ortho’ if ax is not passed)

        The type of projection (‘ortho’ or ‘persp’)

      ‘stick’bool (default: False)

        Changes xlim and ylim in such a way that bars next to XZ and YZ planes will stick to those planes. This option has no effect if `ax` is passed as a parameter.

      ‘cbar_pad’float (default: 0.04)

        The fraction of the original axes between the colorbar and the new image axes. (i.e. the padding between the 3D figure and the colorbar).

      ‘cbar_to_z’bool (default: False)

        Whether to set the color of maximum and minimum z-values to the maximum and minimum colors in the colorbar (True) or not (False).

      ‘figsize’tuple of two numbers

        The size of the figure.

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

  Raises:
    ValueError

      Input argument is not valid.

matrix_histogram_complex(M, xlabels=None, ylabels=None, title=None, limits=None, phase_limits=None, colorbar=True, fig=None, ax=None, threshold=None)

  Draw a histogram for the amplitudes of matrix M, using the argument of each element for coloring the bars, with the given x and y labels and title.

  Parameters:
    M Matrix of Qobj

      The matrix to visualize

    xlabels list of strings

      list of x labels

    ylabels list of strings

      list of y labels

    title string

      title of the plot (optional)

    limits list/array with two float numbers

      The z-axis limits [min, max] (optional)

    phase_limits list/array with two float numbers

      The phase-axis (colorbar) limits [min, max] (optional)

    ax a matplotlib axes instance

      The axes context in which the plot will be drawn.

    threshold: float (None)

      Threshold for when bars of smaller height should be transparent. If not set, all bars are colored according to the color map.

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

  Raises:
    ValueError

      Input argument is not valid.

plot_energy_levels(H_list, N=0, labels=None, show_ylabels=False, figsize=(8, 12), fig=None, ax=None)

  Plot the energy level diagrams for a list of Hamiltonians. Include up to N energy levels. For each element in H_list, the energy levels diagram for the cummulative Hamiltonian sum(H_list[0:n]) is plotted, where n is the index of an element in H_list.

  Parameters:
    H_list List of Qobj

      A list of Hamiltonians.

    labels List of string

      A list of labels for each Hamiltonian

    show_ylabels Bool (default False)

      Show y labels to the left of energy levels of the initial Hamiltonian.

    N int

      The number of energy levels to plot

    figsize tuple (int,int)

      The size of the figure (width, height).

    fig a matplotlib Figure instance

      The Figure canvas in which the plot will be drawn.

    ax a matplotlib axes instance

      The axes context in which the plot will be drawn.

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

  Raises:
    ValueError

      Input argument is not valid.

plot_expectation_values(results, ylabels=[], title=None, show_legend=False, fig=None, axes=None, figsize=(8, 4))

  Visualize the results (expectation values) for an evolution solver. results is assumed to be an instance of Result, or a list of Result instances.

  Parameters:
    results(list of) `qutip.solver.Result`

      List of results objects returned by any of the QuTiP evolution solvers.

    ylabels list of strings

      The y-axis labels. List should be of the same length as results.

    title string

      The title of the figure.

    show_legend bool

      Whether or not to show the legend.

    fig a matplotlib Figure instance

      The Figure canvas in which the plot will be drawn.

    axes a matplotlib axes instance

      The axes context in which the plot will be drawn.

    figsize(width, height)

      The size of the matplotlib figure (in inches) if it is to be created (that is, if no ‘fig’ and ‘ax’ arguments are passed).

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

plot_fock_distribution(rho, offset=0, fig=None, ax=None, figsize=(8, 6), title=None, unit_y_range=True)

  Plot the Fock distribution for a density matrix (or ket) that describes an oscillator mode.

  Parameters:
    rho `qutip.Qobj`

      The density matrix (or ket) of the state to visualize.

    fig a matplotlib Figure instance

      The Figure canvas in which the plot will be drawn.

    ax a matplotlib axes instance

      The axes context in which the plot will be drawn.

    title string

      An optional title for the figure.

    figsize(width, height)

      The size of the matplotlib figure (in inches) if it is to be created (that is, if no ‘fig’ and ‘ax’ arguments are passed).

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

plot_qubism(ket, theme='light', how='pairs', grid_iteration=1, legend_iteration=0, fig=None, ax=None, figsize=(6, 6))

  Qubism plot for pure states of many qudits. Works best for spin chains, especially with even number of particles of the same dimension. Allows to see entanglement between first 2k particles and the rest.

  Parameters:
    ket Qobj

      Pure state for plotting.

    theme‘light’ (default) or ‘dark’

      Set coloring theme for mapping complex values into colors. See: complex_array_to_rgb.

    how‘pairs’ (default), ‘pairs_skewed’ or ‘before_after’

      Type of Qubism plotting. Options:

      - ‘pairs’ - typical coordinates,

      - ‘pairs_skewed’ - for ferromagnetic/antriferromagnetic plots,

      - ‘before_after’ - related to Schmidt plot (see also: plot_schmidt).

    grid_iteration int (default 1)

      Helper lines to be drawn on plot. Show tiles for 2*grid_iteration particles vs all others.

    legend_iteration int (default 0) or ‘grid_iteration’ or ‘all’

      Show labels for first `2*legend_iteration` particles. Option ‘grid_iteration’ sets the same number of particles as for grid_iteration. Option ‘all’ makes label for all particles. Typically it should be 0, 1, 2 or perhaps 3.

    fig a matplotlib figure instance

      The figure canvas on which the plot will be drawn.

    ax a matplotlib axis instance

      The axis context in which the plot will be drawn.

    figsize(width, height)

      The size of the matplotlib figure (in inches) if it is to be created (that is, if no ‘fig’ and ‘ax’ arguments are passed).

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

  Notes

  See also [1].

  References

  [1]

  J. Rodriguez-Laguna, P. Migdal, M. Ibanez Berganza, M. Lewenstein and G. Sierra, Qubism: self-similar visualization of many-body wavefunctions, New J. Phys. 14 053028, arXiv:1112.3560 (2012), open access.

plot_schmidt(ket, splitting=None, labels_iteration=(3, 2), theme='light', fig=None, ax=None, figsize=(6, 6))

  Plotting scheme related to Schmidt decomposition. Converts a state into a matrix (A_ij -> A_i^j), where rows are first particles and columns - last.

  See also: plot_qubism with how=’before_after’ for a similar plot.

  Parameters:
    ket Qobj

      Pure state for plotting.

    splitting int

      Plot for a number of first particles versus the rest. If not given, it is (number of particles + 1) // 2.

    theme‘light’ (default) or ‘dark’

      Set coloring theme for mapping complex values into colors. See: complex_array_to_rgb.

    labels_iteration int or pair of ints (default (3,2))

      Number of particles to be shown as tick labels, for first (vertical) and last (horizontal) particles, respectively.

    fig a matplotlib figure instance

      The figure canvas on which the plot will be drawn.

    ax a matplotlib axis instance

      The axis context in which the plot will be drawn.

    figsize(width, height)

      The size of the matplotlib figure (in inches) if it is to be created (that is, if no ‘fig’ and ‘ax’ arguments are passed).

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

plot_spin_distribution_2d(P, THETA, PHI, fig=None, ax=None, figsize=(8, 8))

  Plot a spin distribution function (given as meshgrid data) with a 2D projection where the surface of the unit sphere is mapped on the unit disk.

  Parameters:
    P matrix

      Distribution values as a meshgrid matrix.

    THETA matrix

      Meshgrid matrix for the theta coordinate.

    PHI matrix

      Meshgrid matrix for the phi coordinate.

    fig a matplotlib figure instance

      The figure canvas on which the plot will be drawn.

    ax a matplotlib axis instance

      The axis context in which the plot will be drawn.

    figsize(width, height)

      The size of the matplotlib figure (in inches) if it is to be created (that is, if no ‘fig’ and ‘ax’ arguments are passed).

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

plot_spin_distribution_3d(P, THETA, PHI, fig=None, ax=None, figsize=(8, 6))

  Plots a matrix of values on a sphere

  Parameters:
    P matrix

      Distribution values as a meshgrid matrix.

    THETA matrix

      Meshgrid matrix for the theta coordinate.

    PHI matrix

      Meshgrid matrix for the phi coordinate.

    fig a matplotlib figure instance

      The figure canvas on which the plot will be drawn.

    ax a matplotlib axis instance

      The axis context in which the plot will be drawn.

    figsize(width, height)

      The size of the matplotlib figure (in inches) if it is to be created (that is, if no ‘fig’ and ‘ax’ arguments are passed).

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

plot_wigner(rho, fig=None, ax=None, figsize=(6, 6), cmap=None, alpha_max=7.5, colorbar=False, method='clenshaw', projection='2d')

  Plot the the Wigner function for a density matrix (or ket) that describes an oscillator mode.

  Parameters:
    rho `qutip.Qobj`

      The density matrix (or ket) of the state to visualize.

    fig a matplotlib Figure instance

      The Figure canvas in which the plot will be drawn.

    ax a matplotlib axes instance

      The axes context in which the plot will be drawn.

    figsize(width, height)

      The size of the matplotlib figure (in inches) if it is to be created (that is, if no ‘fig’ and ‘ax’ arguments are passed).

    cmap a matplotlib cmap instance

      The colormap.

    alpha_max float

      The span of the x and y coordinates (both [-alpha_max, alpha_max]).

    colorbar bool

      Whether (True) or not (False) a colorbar should be attached to the Wigner function graph.

    method string {‘clenshaw’, ‘iterative’, ‘laguerre’, ‘fft’}

      The method used for calculating the wigner function. See the documentation for qutip.wigner for details.

    projection: string {‘2d’, ‘3d’}

      Specify whether the Wigner function is to be plotted as a contour graph (‘2d’) or surface plot (‘3d’).

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

plot_wigner_fock_distribution(rho, fig=None, axes=None, figsize=(8, 4), cmap=None, alpha_max=7.5, colorbar=False, method='iterative', projection='2d')

  Plot the Fock distribution and the Wigner function for a density matrix (or ket) that describes an oscillator mode.

  Parameters:
    rho `qutip.Qobj`

      The density matrix (or ket) of the state to visualize.

    fig a matplotlib Figure instance

      The Figure canvas in which the plot will be drawn.

    axes a list of two matplotlib axes instances

      The axes context in which the plot will be drawn.

    figsize(width, height)

      The size of the matplotlib figure (in inches) if it is to be created (that is, if no ‘fig’ and ‘ax’ arguments are passed).

    cmap a matplotlib cmap instance

      The colormap.

    alpha_max float

      The span of the x and y coordinates (both [-alpha_max, alpha_max]).

    colorbar bool

      Whether (True) or not (False) a colorbar should be attached to the Wigner function graph.

    method string {‘iterative’, ‘laguerre’, ‘fft’}

      The method used for calculating the wigner function. See the documentation for qutip.wigner for details.

    projection: string {‘2d’, ‘3d’}

      Specify whether the Wigner function is to be plotted as a contour graph (‘2d’) or surface plot (‘3d’).

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

plot_wigner_sphere(fig, ax, wigner, reflections)

  Plots a coloured Bloch sphere.

  Parameters:
    fig `matplotlib.figure.Figure`

      An instance of `Figure`.

    ax `matplotlib.axes.Axes`

      An axes instance in the given figure.

    wigner list of float

      The wigner transformation at steps different theta and phi.

    reflections bool

      If the reflections of the sphere should be plotted as well.

  Notes

  Special thanks to Russell P Rundle for writing this function.

sphereplot(theta, phi, values, fig=None, ax=None, save=False)

  Plots a matrix of values on a sphere

  Parameters:
    theta float

      Angle with respect to z-axis

    phi float

      Angle in x-y plane

    values array

      Data set to be plotted

    fig a matplotlib Figure instance

      The Figure canvas in which the plot will be drawn.

    ax a matplotlib axes instance

      The axes context in which the plot will be drawn.

    save bool {False , True}

      Whether to save the figure or not

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

orbital(theta, phi, *args)

  Calculates an angular wave function on a sphere. `psi = orbital(theta,phi,ket1,ket2,...)` calculates the angular wave function on a sphere at the mesh of points defined by theta and phi which is \(\sum_{lm} c_{lm} Y_{lm}(theta,phi)\) where \(C_{lm}\) are the coefficients specified by the list of kets. Each ket has 2l+1 components for some integer l. The first entry of the ket defines the coefficient c_{l,-l}, while the last entry of the ket defines the coefficient c_{l, l}.

  Parameters:
    theta int/float/list/array

      Polar angles in [0, pi]

    phi int/float/list/array

      Azimuthal angles in [0, 2*pi]

    args list/array

      `list` of ket vectors.

  Returns:
    `array` for angular wave function evaluated at all

      possible combinations of theta and phi

This module contains utility functions that enhance Matplotlib in one way or another.

complex_phase_cmap()

  Create a cyclic colormap for representing the phase of complex variables

  Returns:
    cmap

      A matplotlib linear segmented colormap.

wigner_cmap(W, levels=1024, shift=0, max_color='#09224F', mid_color='#FFFFFF', min_color='#530017', neg_color='#FF97D4', invert=False)

  A custom colormap that emphasizes negative values by creating a nonlinear colormap.

  Parameters:
    W array

      Wigner function array, or any array.

    levels int

      Number of color levels to create.

    shift float

      Shifts the value at which Wigner elements are emphasized. This parameter should typically be negative and small (i.e -1e-5).

    max_color str

      String for color corresponding to maximum value of data. Accepts any string format compatible with the Matplotlib.colors.ColorConverter.

    mid_color str

      Color corresponding to zero values. Accepts any string format compatible with the Matplotlib.colors.ColorConverter.

    min_color str

      Color corresponding to minimum data values. Accepts any string format compatible with the Matplotlib.colors.ColorConverter.

    neg_color str

      Color that starts highlighting negative values. Accepts any string format compatible with the Matplotlib.colors.ColorConverter.

    invert bool

      Invert the color scheme for negative values so that smaller negative values have darker color.

  Returns:
    Returns a Matplotlib colormap instance for use in plotting.

  Notes

  The ‘shift’ parameter allows you to vary where the colormap begins to highlight negative colors. This is beneficial in cases where there are small negative Wigner elements due to numerical round-off and/or truncation.

### Quantum Process Tomography

qpt(U, op_basis_list)

  Calculate the quantum process tomography chi matrix for a given (possibly nonunitary) transformation matrix U, which transforms a density matrix in vector form according to:

  > vec(rho) = U * vec(rho0)

  > or

  > rho = vec2mat(U * mat2vec(rho0))

  U can be calculated for an open quantum system using the QuTiP propagator function.

  Parameters:
    U Qobj

      Transformation operator. Can be calculated using QuTiP propagator function.

    op_basis_list list

      A list of Qobj’s representing the basis states.

  Returns:
    chi array

      QPT chi matrix

qpt_plot(chi, lbls_list, title=None, fig=None, axes=None)

  Visualize the quantum process tomography chi matrix. Plot the real and imaginary parts separately.

  Parameters:
    chi array

      Input QPT chi matrix.

    lbls_list list

      List of labels for QPT plot axes.

    title string

      Plot title.

    fig figure instance

      User defined figure instance used for generating QPT plot.

    axes list of figure axis instance

      User defined figure axis instance (list of two axes) used for generating QPT plot.

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

qpt_plot_combined(chi, lbls_list, title=None, fig=None, ax=None, figsize=(8, 6), threshold=None)

  Visualize the quantum process tomography chi matrix. Plot bars with height and color corresponding to the absolute value and phase, respectively.

  Parameters:
    chi array

      Input QPT chi matrix.

    lbls_list list

      List of labels for QPT plot axes.

    title string

      Plot title.

    fig figure instance

      User defined figure instance used for generating QPT plot.

    ax figure axis instance

      User defined figure axis instance used for generating QPT plot (alternative to the fig argument).

    threshold: float (None)

      Threshold for when bars of smaller height should be transparent. If not set, all bars are colored according to the color map.

  Returns:
    fig, ax tuple

      A tuple of the matplotlib figure and axes instances used to produce the figure.

## Quantum Information Processing

### Gates

berkeley(N=None, targets=[0, 1])

  Quantum object representing the Berkeley gate.

  Returns:
    berkeley_gate qobj

      Quantum object representation of Berkeley gate

  Examples

      >>> berkeley()
      Quantum object: dims = [[2, 2], [2, 2]], shape = [4, 4], type = oper, isHerm = True
      Qobj data =
          [[ cos(pi/8).+0.j  0.+0.j           0.+0.j           0.+sin(pi/8).j]
           [ 0.+0.j          cos(3pi/8).+0.j  0.+sin(3pi/8).j  0.+0.j]
           [ 0.+0.j          0.+sin(3pi/8).j  cos(3pi/8).+0.j  0.+0.j]
           [ 0.+sin(pi/8).j  0.+0.j           0.+0.j           cos(pi/8).+0.j]]

cnot(N=None, control=0, target=1)

  Quantum object representing the CNOT gate.

  Returns:
    cnot_gate qobj

      Quantum object representation of CNOT gate

  Examples

      >>> cnot()
      Quantum object: dims = [[2, 2], [2, 2]], shape = [4, 4], type = oper, isHerm = True
      Qobj data =
          [[ 1.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  1.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  1.+0.j]
           [ 0.+0.j  0.+0.j  1.+0.j  0.+0.j]]

controlled_gate(U, N=2, control=0, target=1, control_value=1)

  Create an N-qubit controlled gate from a single-qubit gate U with the given control and target qubits.

  Parameters:
    U Qobj

      Arbitrary single-qubit gate.

    N integer

      The number of qubits in the target space.

    control integer

      The index of the first control qubit.

    target integer

      The index of the target qubit.

    control_value integer (1)

      The state of the control qubit that activates the gate U.

  Returns:
    result qobj

      Quantum object representing the controlled-U gate.

cphase(theta, N=2, control=0, target=1)

  Returns quantum object representing the controlled phase shift gate.

  Parameters:
    theta float

      Phase rotation angle.

    N integer

      The number of qubits in the target space.

    control integer

      The index of the control qubit.

    target integer

      The index of the target qubit.

  Returns:
    U qobj

      Quantum object representation of controlled phase gate.

csign(N=None, control=0, target=1)

  Quantum object representing the CSIGN gate.

  Returns:
    csign_gate qobj

      Quantum object representation of CSIGN gate

  Examples

      >>> csign()
      Quantum object: dims = [[2, 2], [2, 2]], shape = [4, 4], type = oper, isHerm = True
      Qobj data =
          [[ 1.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  1.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  1.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  -1.+0.j]]

expand_operator(oper, N, targets, dims=None, cyclic_permutation=False)

  Expand a qubits operator to one that acts on a N-qubit system.

  Parameters:
    oper `qutip.Qobj`

      An operator acts on qubits, the type of the `qutip.Qobj` has to be an operator and the dimension matches the tensored qubit Hilbert space e.g. dims = `[[2, 2, 2], [2, 2, 2]]`

    N int

      The number of qubits in the system.

    targets int or list of int

      The indices of qubits that are acted on.

    dims list, optional

      A list of integer for the dimension of each composite system. E.g `[2, 2, 2, 2, 2]` for 5 qubits system. If None, qubits system will be the default option.

    cyclic_permutation boolean, optional

      Expand for all cyclic permutation of the targets. E.g. if `N=3` and oper is a 2-qubit operator, the result will be a list of three operators, each acting on qubits 0 and 1, 1 and 2, 2 and 0.

  Returns:
    expanded_oper `qutip.Qobj`

      The expanded qubits operator acting on a system with N qubits.

  Notes

  This is equivalent to gate_expand_1toN, gate_expand_2toN, gate_expand_3toN in `qutip.qip.gate.py`, but works for any dimension.

fredkin(N=None, control=0, targets=[1, 2])

  Quantum object representing the Fredkin gate.

  Returns:
    fredkin_gate qobj

      Quantum object representation of Fredkin gate.

  Examples

      >>> fredkin()
      Quantum object: dims = [[2, 2, 2], [2, 2, 2]], shape = [8, 8], type = oper, isHerm = True
      Qobj data =
          [[ 1.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  1.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  1.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  1.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  0.+0.j  1.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  1.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  1.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  1.+0.j]]

gate_expand_1toN(U, N, target)

  Create a Qobj representing a one-qubit gate that act on a system with N qubits.

  Parameters:
    U Qobj

      The one-qubit gate

    N integer

      The number of qubits in the target space.

    target integer

      The index of the target qubit.

  Returns:
    gate qobj

      Quantum object representation of N-qubit gate.

gate_expand_2toN(U, N, control=None, target=None, targets=None)

  Create a Qobj representing a two-qubit gate that act on a system with N qubits.

  Parameters:
    U Qobj

      The two-qubit gate

    N integer

      The number of qubits in the target space.

    control integer

      The index of the control qubit.

    target integer

      The index of the target qubit.

    targets list

      List of target qubits.

  Returns:
    gate qobj

      Quantum object representation of N-qubit gate.

gate_expand_3toN(U, N, controls=[0, 1], target=2)

  Create a Qobj representing a three-qubit gate that act on a system with N qubits.

  Parameters:
    U Qobj

      The three-qubit gate

    N integer

      The number of qubits in the target space.

    controls list

      The list of the control qubits.

    target integer

      The index of the target qubit.

  Returns:
    gate qobj

      Quantum object representation of N-qubit gate.

gate_sequence_product(U_list, left_to_right=True, inds_list=None, expand=False)

  Calculate the overall unitary matrix for a given list of unitary operations.

  Parameters:
    U_list: list

      List of gates implementing the quantum circuit.

    left_to_right: Boolean, optional

      Check if multiplication is to be done from left to right.

    inds_list: list of list of int, optional

      If expand=True, list of qubit indices corresponding to U_list to which each unitary is applied.

    expand: Boolean, optional

      Check if the list of unitaries need to be expanded to full dimension.

  Returns:
    U_overall qobj

      Unitary matrix corresponding to U_list.

    overall_inds list of int, optional

      List of qubit indices on which U_overall applies.

globalphase(theta, N=1)

  Returns quantum object representing the global phase shift gate.

  Parameters:
    theta float

      Phase rotation angle.

  Returns:
    phase_gate qobj

      Quantum object representation of global phase shift gate.

  Examples

      >>> phasegate(pi/4)
      Quantum object: dims = [[2], [2]], shape = [2, 2], type = oper, isHerm = False
      Qobj data =
      [[ 0.70710678+0.70710678j          0.00000000+0.j]
       [ 0.00000000+0.j          0.70710678+0.70710678j]]

hadamard_transform(N=1)

  Quantum object representing the N-qubit Hadamard gate.

  Returns:
    q qobj

      Quantum object representation of the N-qubit Hadamard gate.

iswap(N=None, targets=[0, 1])

  Quantum object representing the iSWAP gate.

  Returns:
    iswap_gate qobj

      Quantum object representation of iSWAP gate

  Examples

      >>> iswap()
      Quantum object: dims = [[2, 2], [2, 2]], shape = [4, 4], type = oper, isHerm = False
      Qobj data =
      [[ 1.+0.j  0.+0.j  0.+0.j  0.+0.j]
       [ 0.+0.j  0.+0.j  0.+1.j  0.+0.j]
       [ 0.+0.j  0.+1.j  0.+0.j  0.+0.j]
       [ 0.+0.j  0.+0.j  0.+0.j  1.+0.j]]

phasegate(theta, N=None, target=0)

  Returns quantum object representing the phase shift gate.

  Parameters:
    theta float

      Phase rotation angle.

  Returns:
    phase_gate qobj

      Quantum object representation of phase shift gate.

  Examples

      >>> phasegate(pi/4)
      Quantum object: dims = [[2], [2]], shape = [2, 2], type = oper, isHerm = False
      Qobj data =
      [[ 1.00000000+0.j          0.00000000+0.j        ]
       [ 0.00000000+0.j          0.70710678+0.70710678j]]

rotation(op, phi, N=None, target=0)

  Single-qubit rotation for operator op with angle phi.

  Returns:
    result qobj

      Quantum object for operator describing the rotation.

rx(phi, N=None, target=0)

  Single-qubit rotation for operator sigmax with angle phi.

  Returns:
    result qobj

      Quantum object for operator describing the rotation.

ry(phi, N=None, target=0)

  Single-qubit rotation for operator sigmay with angle phi.

  Returns:
    result qobj

      Quantum object for operator describing the rotation.

rz(phi, N=None, target=0)

  Single-qubit rotation for operator sigmaz with angle phi.

  Returns:
    result qobj

      Quantum object for operator describing the rotation.

snot(N=None, target=0)

  Quantum object representing the SNOT (Hadamard) gate.

  Returns:
    snot_gate qobj

      Quantum object representation of SNOT gate.

  Examples

      >>> snot()
      Quantum object: dims = [[2], [2]], shape = [2, 2], type = oper, isHerm = True
      Qobj data =
      [[ 0.70710678+0.j  0.70710678+0.j]
       [ 0.70710678+0.j -0.70710678+0.j]]

sqrtiswap(N=None, targets=[0, 1])

  Quantum object representing the square root iSWAP gate.

  Returns:
    sqrtiswap_gate qobj

      Quantum object representation of square root iSWAP gate

  Examples

      >>> sqrtiswap()
      Quantum object: dims = [[2, 2], [2, 2]], shape = [4, 4], type = oper, isHerm = False
      Qobj data =
      [[ 1.00000000+0.j   0.00000000+0.j          0.00000000+0.j          0.00000000+0.j]
       [ 0.00000000+0.j   0.70710678+0.j          0.00000000-0.70710678j  0.00000000+0.j]
       [ 0.00000000+0.j   0.00000000-0.70710678j       0.70710678+0.j          0.00000000+0.j]
       [ 0.00000000+0.j   0.00000000+0.j          0.00000000+0.j          1.00000000+0.j]]

sqrtnot(N=None, target=0)

  Single-qubit square root NOT gate.

  Returns:
    result qobj

      Quantum object for operator describing the square root NOT gate.

sqrtswap(N=None, targets=[0, 1])

  Quantum object representing the square root SWAP gate.

  Returns:
    sqrtswap_gate qobj

      Quantum object representation of square root SWAP gate

swap(N=None, targets=[0, 1])

  Quantum object representing the SWAP gate.

  Returns:
    swap_gate qobj

      Quantum object representation of SWAP gate

  Examples

      >>> swap()
      Quantum object: dims = [[2, 2], [2, 2]], shape = [4, 4], type = oper, isHerm = True
      Qobj data =
      [[ 1.+0.j  0.+0.j  0.+0.j  0.+0.j]
       [ 0.+0.j  0.+0.j  1.+0.j  0.+0.j]
       [ 0.+0.j  1.+0.j  0.+0.j  0.+0.j]
       [ 0.+0.j  0.+0.j  0.+0.j  1.+0.j]]

swapalpha(alpha, N=None, targets=[0, 1])

  Quantum object representing the SWAPalpha gate.

  Returns:
    swapalpha_gate qobj

      Quantum object representation of SWAPalpha gate

  Examples

      >>> swapalpha(alpha)
      Quantum object: dims = [[2, 2], [2, 2]], shape = [4, 4], type = oper, isHerm = True
      Qobj data =
      [[ 1.+0.j  0.+0.j                    0.+0.j                    0.+0.j]
       [ 0.+0.j  0.5*(1 + exp(j*pi*alpha)  0.5*(1 - exp(j*pi*alpha)  0.+0.j]
       [ 0.+0.j  0.5*(1 - exp(j*pi*alpha)  0.5*(1 + exp(j*pi*alpha)  0.+0.j]
       [ 0.+0.j  0.+0.j                    0.+0.j                    1.+0.j]]

toffoli(N=None, controls=[0, 1], target=2)

  Quantum object representing the Toffoli gate.

  Returns:
    toff_gate qobj

      Quantum object representation of Toffoli gate.

  Examples

      >>> toffoli()
      Quantum object: dims = [[2, 2, 2], [2, 2, 2]],                     shape = [8, 8], type = oper, isHerm = True
      Qobj data =
          [[ 1.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  1.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  1.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  1.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  0.+0.j  1.+0.j  0.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  1.+0.j  0.+0.j  0.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  1.+0.j]
           [ 0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  0.+0.j  1.+0.j  0.+0.j]]

### Qubits

qubit_states(N=1, states=[0])

  Function to define initial state of the qubits.

  Parameters:
    N Integer

      Number of qubits in the register.

    states List

      Initial state of each qubit.

  Returns:
    qstates Qobj

      List of qubits.

### Algorithms

This module provides the circuit implementation for Quantum Fourier Transform.

qft(N=1)

  Quantum Fourier Transform operator on N qubits.

  Parameters:
    N int

      Number of qubits.

  Returns:
    QFT: qobj

      Quantum Fourier transform operator.

qft_gate_sequence(N=1, swapping=True)

  Quantum Fourier Transform operator on N qubits returning the gate sequence.

  Parameters:
    N: int

      Number of qubits.

    swap: boolean

      Flag indicating sequence of swap gates to be applied at the end or not.

  Returns:
    qc: instance of QubitCircuit

      Gate sequence of Hadamard and controlled rotation gates implementing QFT.

qft_steps(N=1, swapping=True)

  Quantum Fourier Transform operator on N qubits returning the individual steps as unitary matrices operating from left to right.

  Parameters:
    N: int

      Number of qubits.

    swap: boolean

      Flag indicating sequence of swap gates to be applied at the end or not.

  Returns:
    U_step_list: list of qobj

      List of Hadamard and controlled rotation gates implementing QFT.

### Circuit

circuit_to_qasm_str(qc)

  Return QASM output of circuit object as string

  Parameters:
    qc: :class:`.QubitCircuit`

      circuit object to produce QASM output for.

  Returns:
    output: str

      string corresponding to QASM output.

print_qasm(qc)

  Print QASM output of circuit object.

  Parameters:
    qc: :class:`.QubitCircuit`

      circuit object to produce QASM output for.

read_qasm(qasm_input, mode='qiskit', version='2.0', strmode=False)

  Read OpenQASM intermediate representation (https://github.com/Qiskit/openqasm) and return a `QubitCircuit` and state inputs as specified in the QASM file.

  Parameters:
    qasm_input str

      File location or String Input for QASM file to be imported. In case of string input, the parameter strmode must be True.

    mode str

      QASM mode to be read in. When mode is “qiskit”, the “qelib1.inc” include is automatically included, without checking externally. Otherwise, each include is processed.

    version str

      QASM version of the QASM file. Only version 2.0 is currently supported.

    strmode bool

      if specified as True, indicates that qasm_input is in string format rather than from file.

  Returns:
    qc `QubitCircuit`

      Returns a `QubitCircuit` object specified in the QASM file.

save_qasm(qc, file_loc)

  Save QASM output of circuit object to file.

  Parameters:
    qc: :class:`.QubitCircuit`

      circuit object to produce QASM output for.

## Non-Markovian Solvers

This module contains an implementation of the non-Markovian transfer tensor method (TTM), introduced in [1].

[1] Javier Cerrillo and Jianshu Cao, Phys. Rev. Lett 112, 110401 (2014)

ttmsolve(dynmaps, rho0, times, e_ops=[], learningtimes=None, tensors=None, **kwargs)

  Solve time-evolution using the Transfer Tensor Method, based on a set of precomputed dynamical maps.

  Parameters:
    dynmaps list of `qutip.Qobj`

      List of precomputed dynamical maps (superoperators), or a callback function that returns the superoperator at a given time.

    rho0 `qutip.Qobj`

      Initial density matrix or state vector (ket).

    times array_like

      list of times \(t_n\) at which to compute \(\rho(t_n)\). Must be uniformily spaced.

    e_ops list of `qutip.Qobj` / callback function

      single operator or list of operators for which to evaluate expectation values.

    learningtimes array_like

      list of times \(t_k\) for which we have knowledge of the dynamical maps \(E(t_k)\).

    tensors array_like

      optional list of precomputed tensors \(T_k\)

    kwargs dictionary

      Optional keyword arguments. See `qutip.nonmarkov.transfertensor.TTMSolverOptions`.

  Returns:
    output: `qutip.solver.Result`

      An instance of the class `qutip.solver.Result`.

## Optimal control

Wrapper functions that will manage the creation of the objects, build the configuration, and execute the algorithm required to optimise a set of ctrl pulses for a given (quantum) system. The fidelity error is some measure of distance of the system evolution from the given target evolution in the time allowed for the evolution. The functions minimise this fidelity error wrt the piecewise control amplitudes in the timeslots

There are currently two quantum control pulse optmisations algorithms implemented in this library. There are accessible through the methods in this module. Both the algorithms use the scipy.optimize methods to minimise the fidelity error with respect to to variables that define the pulse.

### GRAPE

The default algorithm (as it was implemented here first) is GRAPE GRadient Ascent Pulse Engineering [1][2]. It uses a gradient based method such as BFGS to minimise the fidelity error. This makes convergence very quick when an exact gradient can be calculated, but this limits the factors that can taken into account in the fidelity.

### CRAB

The CRAB [3][4] algorithm was developed at the University of Ulm. In full it is the Chopped RAndom Basis algorithm. The main difference is that it reduces the number of optimisation variables by defining the control pulses by expansions of basis functions, where the variables are the coefficients. Typically a Fourier series is chosen, i.e. the variables are the Fourier coefficients. Therefore it does not need to compute an explicit gradient. By default it uses the Nelder-Mead method for fidelity error minimisation.

References

1. N Khaneja et. al. Optimal control of coupled spin dynamics: Design of NMR pulse sequences by gradient ascent algorithms. J. Magn. Reson. 172, 296–305 (2005).

2. Shai Machnes et.al DYNAMO - Dynamic Framework for Quantum Optimal Control arXiv.1011.4874

3. Doria, P., Calarco, T. & Montangero, S. Optimal Control Technique for Many-Body Quantum Dynamics. Phys. Rev. Lett. 106, 1–4 (2011).

4. Caneva, T., Calarco, T. & Montangero, S. Chopped random-basis quantum optimization. Phys. Rev. A - At. Mol. Opt. Phys. 84, (2011).

create_pulse_optimizer(drift, ctrls, initial, target, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-10, min_grad=1e-10, max_iter=500, max_wall_time=180, alg='GRAPE', alg_params=None, optim_params=None, optim_method='DEF', method_params=None, optim_alg=None, max_metric_corr=None, accuracy_factor=None, dyn_type='GEN_MAT', dyn_params=None, prop_type='DEF', prop_params=None, fid_type='DEF', fid_params=None, phase_option=None, fid_err_scale_factor=None, tslot_type='DEF', tslot_params=None, amp_update_mode=None, init_pulse_type='DEF', init_pulse_params=None, pulse_scaling=1.0, pulse_offset=0.0, ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, gen_stats=False)

  Generate the objects of the appropriate subclasses required for the pulse optmisation based on the parameters given Note this method may be preferable to calling optimize_pulse if more detailed configuration is required before running the optmisation algorthim, or the algorithm will be run many times, for instances when trying to finding global the optimum or minimum time optimisation

  Parameters:
    drift Qobj or list of Qobj

      The underlying dynamics generator of the system can provide list (of length num_tslots) for time dependent drift.

    ctrls List of Qobj or array like [num_tslots, evo_time]

      A list of control dynamics generators. These are scaled by the amplitudes to alter the overall dynamics. Array-like input can be provided for time dependent control generators.

    initial Qobj

      Starting point for the evolution. Typically the identity matrix.

    target Qobj

      Target transformation, e.g. gate or state, for the time evolution.

    num_tslots integer or None

      Number of timeslots. `None` implies that timeslots will be given in the tau array.

    evo_time float or None

      Total time for the evolution. `None` implies that timeslots will be given in the tau array.

    tau array[num_tslots] of floats or None

      Durations for the timeslots. If this is given then `num_tslots` and `evo_time` are dervived from it. `None` implies that timeslot durations will be equal and calculated as `evo_time/num_tslots`.

    amp_lbound float or list of floats

      Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    amp_ubound float or list of floats

      Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    fid_err_targ float

      Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

    mim_grad float

      Minimum gradient. When the sum of the squares of the gradients wrt to the control amplitudes falls below this value, the optimisation terminates, assuming local minima.

    max_iter integer

      Maximum number of iterations of the optimisation algorithm.

    max_wall_time float

      Maximum allowed elapsed time for the optimisation algorithm.

    alg string

      Algorithm to use in pulse optimisation. Options are:

      - ‘GRAPE’ (default) - GRadient Ascent Pulse Engineering

      - ‘CRAB’ - Chopped RAndom Basis

    alg_params Dictionary

      options that are specific to the algorithm see above

    optim_params Dictionary

      The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: method_params are applied afterwards and so may override these.

    optim_method string

      a scipy.optimize.minimize method that will be used to optimise the pulse for minimum fidelity error Note that FMIN, FMIN_BFGS & FMIN_L_BFGS_B will all result in calling these specific scipy.optimize methods Note the LBFGSB is equivalent to FMIN_L_BFGS_B for backwards capatibility reasons. Supplying DEF will given alg dependent result:

      - GRAPE - Default optim_method is FMIN_L_BFGS_B

      - CRAB - Default optim_method is Nelder-Mead

    method_params dict

      Parameters for the optim_method. Note that where there is an attribute of the `Optimizer` object or the termination_conditions matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the scipy.optimize.minimize method.

    optim_alg string

      Deprecated. Use optim_method.

    max_metric_corr integer

      Deprecated. Use method_params instead

    accuracy_factor float

      Deprecated. Use method_params instead

    dyn_type string

      Dynamics type, i.e. the type of matrix used to describe the dynamics. Options are UNIT, GEN_MAT, SYMPL (see Dynamics classes for details)

    dyn_params dict

      Parameters for the Dynamics object The key value pairs are assumed to be attribute name value pairs They applied after the object is created

    prop_type string

      Propagator type i.e. the method used to calculate the propagtors and propagtor gradient for each timeslot options are DEF, APPROX, DIAG, FRECHET, AUG_MAT DEF will use the default for the specific dyn_type (see PropagatorComputer classes for details)

    prop_params dict

      Parameters for the PropagatorComputer object The key value pairs are assumed to be attribute name value pairs They applied after the object is created

    fid_type string

      Fidelity error (and fidelity error gradient) computation method Options are DEF, UNIT, TRACEDIFF, TD_APPROX DEF will use the default for the specific dyn_type (See FidelityComputer classes for details)

    fid_params dict

      Parameters for the FidelityComputer object The key value pairs are assumed to be attribute name value pairs They applied after the object is created

    phase_option string

      Deprecated. Pass in fid_params instead.

    fid_err_scale_factor float

      Deprecated. Use scale_factor key in fid_params instead.

    tslot_type string

      Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: DEF, UPDATE_ALL, DYNAMIC UPDATE_ALL is the only one that currently works (See TimeslotComputer classes for details)

    tslot_params dict

      Parameters for the TimeslotComputer object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    amp_update_mode string

      Deprecated. Use tslot_type instead.

    init_pulse_type string

      type / shape of pulse(s) used to initialise the the control amplitudes. Options (GRAPE) include:

      > RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW DEF is RND

      (see PulseGen classes for details) For the CRAB the this the guess_pulse_type.

    init_pulse_params dict

      Parameters for the initial / guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    pulse_scaling float

      Linear scale factor for generated initial / guess pulses By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter

    pulse_offset float

      Linear offset for the pulse. That is this value will be added to any initial / guess pulses generated.

    ramping_pulse_type string

      Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

    ramping_pulse_params dict

      Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created

    log_level integer

      level of messaging output from the logger. Options are attributes of qutip.logging_utils, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN

    gen_stats boolean

      if set to True then statistics for the optimisation run will be generated - accessible through attributes of the stats object

  Returns:
    opt Optimizer

      Instance of an Optimizer, through which the Config, Dynamics, PulseGen, and TerminationConditions objects can be accessed as attributes. The PropagatorComputer, FidelityComputer and TimeslotComputer objects can be accessed as attributes of the Dynamics object, e.g. optimizer.dynamics.fid_computer The optimisation can be run through the optimizer.run_optimization

opt_pulse_crab(drift, ctrls, initial, target, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-05, max_iter=500, max_wall_time=180, alg_params=None, num_coeffs=None, init_coeff_scaling=1.0, optim_params=None, optim_method='fmin', method_params=None, dyn_type='GEN_MAT', dyn_params=None, prop_type='DEF', prop_params=None, fid_type='DEF', fid_params=None, tslot_type='DEF', tslot_params=None, guess_pulse_type=None, guess_pulse_params=None, guess_pulse_scaling=1.0, guess_pulse_offset=0.0, guess_pulse_action='MODULATE', ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, out_file_ext=None, gen_stats=False)

  Optimise a control pulse to minimise the fidelity error. The dynamics of the system in any given timeslot are governed by the combined dynamics generator, i.e. the sum of the drift+ctrl_amp[j]*ctrls[j] The control pulse is an [n_ts, n_ctrls] array of piecewise amplitudes. The CRAB algorithm uses basis function coefficents as the variables to optimise. It does NOT use any gradient function. A multivariable optimisation algorithm attempts to determines the optimal values for the control pulse to minimise the fidelity error The fidelity error is some measure of distance of the system evolution from the given target evolution in the time allowed for the evolution.

  Parameters:
    drift Qobj or list of Qobj

      the underlying dynamics generator of the system can provide list (of length num_tslots) for time dependent drift

    ctrls List of Qobj or array like [num_tslots, evo_time]

      a list of control dynamics generators. These are scaled by the amplitudes to alter the overall dynamics Array like imput can be provided for time dependent control generators

    initial Qobj

      Starting point for the evolution. Typically the identity matrix.

    target Qobj

      Target transformation, e.g. gate or state, for the time evolution.

    num_tslots integer or None

      Number of timeslots. `None` implies that timeslots will be given in the tau array.

    evo_time float or None

      Total time for the evolution. `None` implies that timeslots will be given in the tau array.

    tau array[num_tslots] of floats or None

      Durations for the timeslots. If this is given then `num_tslots` and `evo_time` are dervived from it. `None` implies that timeslot durations will be equal and calculated as `evo_time/num_tslots`.

    amp_lbound float or list of floats

      Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    amp_ubound float or list of floats

      Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    fid_err_targ float

      Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

    max_iter integer

      Maximum number of iterations of the optimisation algorithm.

    max_wall_time float

      Maximum allowed elapsed time for the optimisation algorithm.

    alg_params Dictionary

      Options that are specific to the algorithm see above.

    optim_params Dictionary

      The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: method_params are applied afterwards and so may override these.

    coeff_scaling float

      Linear scale factor for the random basis coefficients. By default these range from -1.0 to 1.0. Note this is overridden by alg_params (if given there).

    num_coeffs integer

      Number of coefficients used for each basis function. Note this is calculated automatically based on the dimension of the dynamics if not given. It is crucial to the performane of the algorithm that it is set as low as possible, while still giving high enough frequencies. Note this is overridden by alg_params (if given there).

    optim_method string

      Multi-variable optimisation method. The only tested options are ‘fmin’ and ‘Nelder-mead’. In theory any non-gradient method implemented in scipy.optimize.mininize could be used.

    method_params dict

      Parameters for the optim_method. Note that where there is an attribute of the `Optimizer` object or the termination_conditions matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the `scipy.optimize.minimize` method. The commonly used parameter are:

      - xtol - limit on variable change for convergence

      - ftol - limit on fidelity error change for convergence

    dyn_type string

      Dynamics type, i.e. the type of matrix used to describe the dynamics. Options are UNIT, GEN_MAT, SYMPL (see Dynamics classes for details).

    dyn_params dict

      Parameters for the `qutip.control.dynamics.Dynamics` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    prop_type string

      Propagator type i.e. the method used to calculate the propagtors and propagtor gradient for each timeslot options are DEF, APPROX, DIAG, FRECHET, AUG_MAT DEF will use the default for the specific dyn_type (see `PropagatorComputer` classes for details).

    prop_params dict

      Parameters for the `PropagatorComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    fid_type string

      Fidelity error (and fidelity error gradient) computation method. Options are DEF, UNIT, TRACEDIFF, TD_APPROX. DEF will use the default for the specific dyn_type. (See `FidelityComputer` classes for details).

    fid_params dict

      Parameters for the `FidelityComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    tslot_type string

      Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: DEF, UPDATE_ALL, DYNAMIC UPDATE_ALL is the only one that currently works. (See `TimeslotComputer` classes for details).

    tslot_params dict

      Parameters for the `TimeslotComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    guess_pulse_type string, default None

      Type / shape of pulse(s) used modulate the control amplitudes. Options include: RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW, GAUSSIAN.

    guess_pulse_params dict

      Parameters for the guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    guess_pulse_action string, default ‘MODULATE’

      Determines how the guess pulse is applied to the pulse generated by the basis expansion. Options are: MODULATE, ADD.

    pulse_scaling float

      Linear scale factor for generated guess pulses. By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter.

    pulse_offset float

      Linear offset for the pulse. That is this value will be added to any guess pulses generated.

    ramping_pulse_type string

      Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

    ramping_pulse_params dict

      Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    log_level integer

      level of messaging output from the logger. Options are attributes of `qutip.logging_utils`, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN.

    out_file_ext string or None

      Files containing the initial and final control pulse. Amplitudes are saved to the current directory. The default name will be postfixed with this extension. Setting this to `None` will suppress the output of files.

    gen_stats boolean

      If set to `True` then statistics for the optimisation run will be generated - accessible through attributes of the stats object.

  Returns:
    opt OptimResult

      Returns instance of OptimResult, which has attributes giving the reason for termination, final fidelity error, final evolution final amplitudes, statistics etc

opt_pulse_crab_unitary(H_d, H_c, U_0, U_targ, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-05, max_iter=500, max_wall_time=180, alg_params=None, num_coeffs=None, init_coeff_scaling=1.0, optim_params=None, optim_method='fmin', method_params=None, phase_option='PSU', dyn_params=None, prop_params=None, fid_params=None, tslot_type='DEF', tslot_params=None, guess_pulse_type=None, guess_pulse_params=None, guess_pulse_scaling=1.0, guess_pulse_offset=0.0, guess_pulse_action='MODULATE', ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, out_file_ext=None, gen_stats=False)

  Optimise a control pulse to minimise the fidelity error, assuming that the dynamics of the system are generated by unitary operators. This function is simply a wrapper for optimize_pulse, where the appropriate options for unitary dynamics are chosen and the parameter names are in the format familiar to unitary dynamics. The dynamics of the system in any given timeslot are governed by the combined Hamiltonian, i.e. the sum of the `H_d + ctrl_amp[j]*H_c[j]` The control pulse is an `[n_ts, n_ctrls]` array of piecewise amplitudes.

  The CRAB algorithm uses basis function coefficents as the variables to optimise. It does NOT use any gradient function. A multivariable optimisation algorithm attempts to determines the optimal values for the control pulse to minimise the fidelity error. The fidelity error is some measure of distance of the system evolution from the given target evolution in the time allowed for the evolution.

  Parameters:
    H_d Qobj or list of Qobj

      Drift (aka system) the underlying Hamiltonian of the system can provide list (of length num_tslots) for time dependent drift.

    H_c List of Qobj or array like [num_tslots, evo_time]

      A list of control Hamiltonians. These are scaled by the amplitudes to alter the overall dynamics. Array like imput can be provided for time dependent control generators.

    U_0 Qobj

      Starting point for the evolution. Typically the identity matrix.

    U_targ Qobj

      Target transformation, e.g. gate or state, for the time evolution.

    num_tslots integer or None

      Number of timeslots. `None` implies that timeslots will be given in the tau array.

    evo_time float or None

      Total time for the evolution. `None` implies that timeslots will be given in the tau array.

    tau array[num_tslots] of floats or None

      Durations for the timeslots. If this is given then `num_tslots` and `evo_time` are derived from it. `None` implies that timeslot durations will be equal and calculated as `evo_time/num_tslots`.

    amp_lbound float or list of floats

      Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    amp_ubound float or list of floats

      Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    fid_err_targ float

      Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

    max_iter integer

      Maximum number of iterations of the optimisation algorithm.

    max_wall_time float

      Maximum allowed elapsed time for the optimisation algorithm.

    alg_params Dictionary

      Options that are specific to the algorithm see above.

    optim_params Dictionary

      The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: `method_params` are applied afterwards and so may override these.

    coeff_scaling float

      Linear scale factor for the random basis coefficients. By default these range from -1.0 to 1.0. Note this is overridden by `alg_params` (if given there).

    num_coeffs integer

      Number of coefficients used for each basis function. Note this is calculated automatically based on the dimension of the dynamics if not given. It is crucial to the performance of the algorithm that it is set as low as possible, while still giving high enough frequencies. Note this is overridden by `alg_params` (if given there).

    optim_method string

      Multi-variable optimisation method. The only tested options are ‘fmin’ and ‘Nelder-mead’. In theory any non-gradient method implemented in `scipy.optimize.minimize` could be used.

    method_params dict

      Parameters for the `optim_method`. Note that where there is an attribute of the `Optimizer` object or the termination_conditions matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the `scipy.optimize.minimize` method. The commonly used parameter are:

      - xtol - limit on variable change for convergence

      - ftol - limit on fidelity error change for convergence

    phase_option string

      Determines how global phase is treated in fidelity calculations (`fid_type='UNIT'` only). Options:

      - PSU - global phase ignored

      - SU - global phase included

    dyn_params dict

      Parameters for the `Dynamics` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    prop_params dict

      Parameters for the `PropagatorComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    fid_params dict

      Parameters for the `FidelityComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    tslot_type string

      Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: DEF, UPDATE_ALL, DYNAMIC. UPDATE_ALL is the only one that currently works. (See `TimeslotComputer` classes for details).

    tslot_params dict

      Parameters for the `TimeslotComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    guess_pulse_type string, optional

      Type / shape of pulse(s) used modulate the control amplitudes. Options include: RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW, GAUSSIAN.

    guess_pulse_params dict

      Parameters for the guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    guess_pulse_action string, ‘MODULATE’

      Determines how the guess pulse is applied to the pulse generated by the basis expansion. Options are: MODULATE, ADD.

    pulse_scaling float

      Linear scale factor for generated guess pulses. By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter.

    pulse_offset float

      Linear offset for the pulse. That is this value will be added to any guess pulses generated.

    ramping_pulse_type string

      Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

    ramping_pulse_params dict

      Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    log_level integer

      Level of messaging output from the logger. Options are attributes of `qutip.logging_utils`, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL. Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN.

    out_file_ext string or None

      Files containing the initial and final control pulse amplitudes are saved to the current directory. The default name will be postfixed with this extension. Setting this to None will suppress the output of files.

    gen_stats boolean

      If set to `True` then statistics for the optimisation run will be generated - accessible through attributes of the stats object.

  Returns:
    opt OptimResult

      Returns instance of `OptimResult`, which has attributes giving the reason for termination, final fidelity error, final evolution final amplitudes, statistics etc.

optimize_pulse(drift, ctrls, initial, target, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-10, min_grad=1e-10, max_iter=500, max_wall_time=180, alg='GRAPE', alg_params=None, optim_params=None, optim_method='DEF', method_params=None, optim_alg=None, max_metric_corr=None, accuracy_factor=None, dyn_type='GEN_MAT', dyn_params=None, prop_type='DEF', prop_params=None, fid_type='DEF', fid_params=None, phase_option=None, fid_err_scale_factor=None, tslot_type='DEF', tslot_params=None, amp_update_mode=None, init_pulse_type='DEF', init_pulse_params=None, pulse_scaling=1.0, pulse_offset=0.0, ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, out_file_ext=None, gen_stats=False)

  Optimise a control pulse to minimise the fidelity error. The dynamics of the system in any given timeslot are governed by the combined dynamics generator, i.e. the sum of the `drift + ctrl_amp[j]*ctrls[j]`.

  The control pulse is an `[n_ts, n_ctrls]` array of piecewise amplitudes Starting from an initial (typically random) pulse, a multivariable optimisation algorithm attempts to determines the optimal values for the control pulse to minimise the fidelity error. The fidelity error is some measure of distance of the system evolution from the given target evolution in the time allowed for the evolution.

  Parameters:
    drift Qobj or list of Qobj

      The underlying dynamics generator of the system can provide list (of length `num_tslots`) for time dependent drift.

    ctrls List of Qobj or array like [num_tslots, evo_time]

      A list of control dynamics generators. These are scaled by the amplitudes to alter the overall dynamics. Array-like input can be provided for time dependent control generators.

    initial Qobj

      Starting point for the evolution. Typically the identity matrix.

    target Qobj

      Target transformation, e.g. gate or state, for the time evolution.

    num_tslots integer or None

      Number of timeslots. `None` implies that timeslots will be given in the tau array.

    evo_time float or None

      Total time for the evolution. `None` implies that timeslots will be given in the tau array.

    tau array[num_tslots] of floats or None

      Durations for the timeslots. If this is given then `num_tslots` and `evo_time` are derived from it. `None` implies that timeslot durations will be equal and calculated as `evo_time/num_tslots`.

    amp_lbound float or list of floats

      Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    amp_ubound float or list of floats

      Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    fid_err_targ float

      Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

    mim_grad float

      Minimum gradient. When the sum of the squares of the gradients wrt to the control amplitudes falls below this value, the optimisation terminates, assuming local minima.

    max_iter integer

      Maximum number of iterations of the optimisation algorithm.

    max_wall_time float

      Maximum allowed elapsed time for the optimisation algorithm.

    alg string

      Algorithm to use in pulse optimisation. Options are:

      - ‘GRAPE’ (default) - GRadient Ascent Pulse Engineering

      - ‘CRAB’ - Chopped RAndom Basis

    alg_params Dictionary

      Options that are specific to the algorithm see above.

    optim_params Dictionary

      The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: `method_params` are applied afterwards and so may override these.

    optim_method string

      A `scipy.optimize.minimize` method that will be used to optimise the pulse for minimum fidelity error. Note that `FMIN`, `FMIN_BFGS` & `FMIN_L_BFGS_B` will all result in calling these specific `scipy.optimize methods`. Note the `LBFGSB` is equivalent to `FMIN_L_BFGS_B` for backwards compatibility reasons. Supplying DEF will given alg dependent result:

      - GRAPE - Default `optim_method` is `FMIN_L_BFGS_B`

      - CRAB - Default `optim_method` is `FMIN`

    method_params dict

      Parameters for the `optim_method`. Note that where there is an attribute of the `Optimizer` object or the termination_conditions matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the `scipy.optimize.minimize` method.

    optim_alg string

      Deprecated. Use `optim_method`.

    max_metric_corr integer

      Deprecated. Use `method_params` instead.

    accuracy_factor float

      Deprecated. Use `method_params` instead.

    dyn_type string

      Dynamics type, i.e. the type of matrix used to describe the dynamics. Options are `UNIT`, `GEN_MAT`, `SYMPL` (see `Dynamics` classes for details).

    dyn_params dict

      Parameters for the `Dynamics` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    prop_type string

      Propagator type i.e. the method used to calculate the propagators and propagator gradient for each timeslot options are DEF, APPROX, DIAG, FRECHET, AUG_MAT. DEF will use the default for the specific `dyn_type` (see `PropagatorComputer` classes for details).

    prop_params dict

      Parameters for the `PropagatorComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    fid_type string

      Fidelity error (and fidelity error gradient) computation method. Options are DEF, UNIT, TRACEDIFF, TD_APPROX. DEF will use the default for the specific `dyn_type` (See `FidelityComputer` classes for details).

    fid_params dict

      Parameters for the `FidelityComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    phase_option string

      Deprecated. Pass in `fid_params` instead.

    fid_err_scale_factor float

      Deprecated. Use `scale_factor` key in `fid_params` instead.

    tslot_type string

      Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: DEF, UPDATE_ALL, DYNAMIC. UPDATE_ALL is the only one that currently works. (See `TimeslotComputer` classes for details.)

    tslot_params dict

      Parameters for the `TimeslotComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    amp_update_mode string

      Deprecated. Use `tslot_type` instead.

    init_pulse_type string

      Type / shape of pulse(s) used to initialise the control amplitudes. Options (GRAPE) include: RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW. Default is RND. (see `PulseGen` classes for details). For the CRAB the this the `guess_pulse_type`.

    init_pulse_params dict

      Parameters for the initial / guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    pulse_scaling float

      Linear scale factor for generated initial / guess pulses. By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter.

    pulse_offset float

      Linear offset for the pulse. That is this value will be added to any initial / guess pulses generated.

    ramping_pulse_type string

      Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

    ramping_pulse_params dict

      Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    log_level integer

      Level of messaging output from the logger. Options are attributes of `qutip.logging_utils`, in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL. Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN.

    out_file_ext string or None

      Files containing the initial and final control pulse amplitudes are saved to the current directory. The default name will be postfixed with this extension. Setting this to None will suppress the output of files.

    gen_stats boolean

      If set to True then statistics for the optimisation run will be generated - accessible through attributes of the stats object.

  Returns:
    opt OptimResult

      Returns instance of `OptimResult`, which has attributes giving the reason for termination, final fidelity error, final evolution final amplitudes, statistics etc.

optimize_pulse_unitary(H_d, H_c, U_0, U_targ, num_tslots=None, evo_time=None, tau=None, amp_lbound=None, amp_ubound=None, fid_err_targ=1e-10, min_grad=1e-10, max_iter=500, max_wall_time=180, alg='GRAPE', alg_params=None, optim_params=None, optim_method='DEF', method_params=None, optim_alg=None, max_metric_corr=None, accuracy_factor=None, phase_option='PSU', dyn_params=None, prop_params=None, fid_params=None, tslot_type='DEF', tslot_params=None, amp_update_mode=None, init_pulse_type='DEF', init_pulse_params=None, pulse_scaling=1.0, pulse_offset=0.0, ramping_pulse_type=None, ramping_pulse_params=None, log_level=0, out_file_ext=None, gen_stats=False)

  Optimise a control pulse to minimise the fidelity error, assuming that the dynamics of the system are generated by unitary operators. This function is simply a wrapper for optimize_pulse, where the appropriate options for unitary dynamics are chosen and the parameter names are in the format familiar to unitary dynamics The dynamics of the system in any given timeslot are governed by the combined Hamiltonian, i.e. the sum of the `H_d + ctrl_amp[j]*H_c[j]` The control pulse is an `[n_ts, n_ctrls]` array of piecewise amplitudes Starting from an initial (typically random) pulse, a multivariable optimisation algorithm attempts to determines the optimal values for the control pulse to minimise the fidelity error The maximum fidelity for a unitary system is 1, i.e. when the time evolution resulting from the pulse is equivalent to the target. And therefore the fidelity error is `1 - fidelity`.

  Parameters:
    H_d Qobj or list of Qobj

      Drift (aka system) the underlying Hamiltonian of the system can provide list (of length `num_tslots`) for time dependent drift.

    H_c List of Qobj or array like [num_tslots, evo_time]

      A list of control Hamiltonians. These are scaled by the amplitudes to alter the overall dynamics. Array-like input can be provided for time dependent control generators.

    U_0 Qobj

      Starting point for the evolution. Typically the identity matrix.

    U_targ Qobj

      Target transformation, e.g. gate or state, for the time evolution.

    num_tslots integer or None

      Number of timeslots. `None` implies that timeslots will be given in the tau array.

    evo_time float or None

      Total time for the evolution. `None` implies that timeslots will be given in the tau array.

    tau array[num_tslots] of floats or None

      Durations for the timeslots. If this is given then `num_tslots` and `evo_time` are derived from it. `None` implies that timeslot durations will be equal and calculated as `evo_time/num_tslots`.

    amp_lbound float or list of floats

      Lower boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    amp_ubound float or list of floats

      Upper boundaries for the control amplitudes. Can be a scalar value applied to all controls or a list of bounds for each control.

    fid_err_targ float

      Fidelity error target. Pulse optimisation will terminate when the fidelity error falls below this value.

    mim_grad float

      Minimum gradient. When the sum of the squares of the gradients wrt to the control amplitudes falls below this value, the optimisation terminates, assuming local minima.

    max_iter integer

      Maximum number of iterations of the optimisation algorithm.

    max_wall_time float

      Maximum allowed elapsed time for the optimisation algorithm.

    alg string

      Algorithm to use in pulse optimisation. Options are:

      - ‘GRAPE’ (default) - GRadient Ascent Pulse Engineering

      - ‘CRAB’ - Chopped RAndom Basis

    alg_params Dictionary

      options that are specific to the algorithm see above

    optim_params Dictionary

      The key value pairs are the attribute name and value used to set attribute values. Note: attributes are created if they do not exist already, and are overwritten if they do. Note: `method_params` are applied afterwards and so may override these.

    optim_method string

      A `scipy.optimize.minimize` method that will be used to optimise the pulse for minimum fidelity error Note that `FMIN`, `FMIN_BFGS` & `FMIN_L_BFGS_B` will all result in calling these specific scipy.optimize methods Note the `LBFGSB` is equivalent to `FMIN_L_BFGS_B` for backwards compatibility reasons. Supplying `DEF` will given algorithm-dependent result:

      - GRAPE - Default `optim_method` is FMIN_L_BFGS_B

      - CRAB - Default `optim_method` is FMIN

    method_params dict

      Parameters for the `optim_method`. Note that where there is an attribute of the `Optimizer` object or the `termination_conditions` matching the key that attribute. Otherwise, and in some case also, they are assumed to be method_options for the `scipy.optimize.minimize` method.

    optim_alg string

      Deprecated. Use `optim_method`.

    max_metric_corr integer

      Deprecated. Use `method_params` instead.

    accuracy_factor float

      Deprecated. Use `method_params` instead.

    phase_option string

      Determines how global phase is treated in fidelity calculations (`fid_type='UNIT'` only). Options:

      - PSU - global phase ignored

      - SU - global phase included

    dyn_params dict

      Parameters for the `Dynamics` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    prop_params dict

      Parameters for the `PropagatorComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    fid_params dict

      Parameters for the `FidelityComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    tslot_type string

      Method for computing the dynamics generators, propagators and evolution in the timeslots. Options: `DEF`, `UPDATE_ALL`, `DYNAMIC`. `UPDATE_ALL` is the only one that currently works. (See `TimeslotComputer` classes for details.)

    tslot_params dict

      Parameters for the `TimeslotComputer` object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    amp_update_mode string

      Deprecated. Use `tslot_type` instead.

    init_pulse_type string

      Type / shape of pulse(s) used to initialise the control amplitudes. Options (GRAPE) include: RND, LIN, ZERO, SINE, SQUARE, TRIANGLE, SAW. DEF is RND. (see `PulseGen` classes for details.) For the CRAB the this the guess_pulse_type.

    init_pulse_params dict

      Parameters for the initial / guess pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    pulse_scaling float

      Linear scale factor for generated initial / guess pulses. By default initial pulses are generated with amplitudes in the range (-1.0, 1.0). These will be scaled by this parameter.

    pulse_offset float

      Linear offset for the pulse. That is this value will be added to any initial / guess pulses generated.

    ramping_pulse_type string

      Type of pulse used to modulate the control pulse. It’s intended use for a ramping modulation, which is often required in experimental setups. This is only currently implemented in CRAB. GAUSSIAN_EDGE was added for this purpose.

    ramping_pulse_params dict

      Parameters for the ramping pulse generator object. The key value pairs are assumed to be attribute name value pairs. They applied after the object is created.

    log_level integer

      Level of messaging output from the logger. Options are attributes of `qutip.logging_utils` in decreasing levels of messaging, are: DEBUG_INTENSE, DEBUG_VERBOSE, DEBUG, INFO, WARN, ERROR, CRITICAL Anything WARN or above is effectively ‘quiet’ execution, assuming everything runs as expected. The default NOTSET implies that the level will be taken from the QuTiP settings file, which by default is WARN.

    out_file_ext string or None

      Files containing the initial and final control pulse amplitudes are saved to the current directory. The default name will be postfixed with this extension. Setting this to `None` will suppress the output of files.

    gen_stats boolean

      If set to `True` then statistics for the optimisation run will be generated - accessible through attributes of the stats object.

  Returns:
    opt OptimResult

      Returns instance of `OptimResult`, which has attributes giving the reason for termination, final fidelity error, final evolution final amplitudes, statistics etc.

Pulse generator - Generate pulses for the timeslots Each class defines a gen_pulse function that produces a float array of size num_tslots. Each class produces a differ type of pulse. See the class and gen_pulse function descriptions for details

create_pulse_gen(pulse_type='RND', dyn=None, pulse_params=None)

  Create and return a pulse generator object matching the given type. The pulse generators each produce a different type of pulse, see the gen_pulse function description for details. These are the random pulse options:

  > RND - Independent random value in each timeslot RNDFOURIER - Fourier series with random coefficients RNDWAVES - Summation of random waves RNDWALK1 - Random change in amplitude each timeslot RNDWALK2 - Random change in amp gradient each timeslot

  These are the other non-periodic options:

  > LIN - Linear, i.e. contant gradient over the time ZERO - special case of the LIN pulse, where the gradient is 0

  These are the periodic options

  > SINE - Sine wave SQUARE - Square wave SAW - Saw tooth wave TRIANGLE - Triangular wave

  If a Dynamics object is passed in then this is used in instantiate the PulseGen, meaning that some timeslot and amplitude properties are copied over.

## Utility Functions

### Graph Theory Routines

This module contains a collection of graph theory routines used mainly to reorder matrices for iterative steady state solvers.

breadth_first_search(A, start)

  Breadth-First-Search (BFS) of a graph in CSR or CSC matrix format starting from a given node (row). Takes Qobjs and CSR or CSC matrices as inputs.

  This function requires a matrix with symmetric structure. Use A+trans(A) if original matrix is not symmetric or not sure.

  Parameters:
    A csc_matrix, csr_matrix

      Input graph in CSC or CSR matrix format

    start int

      Staring node for BFS traversal.

  Returns:
    order array

      Order in which nodes are traversed from starting node.

    levels array

      Level of the nodes in the order that they are traversed.

graph_degree(A)

  Returns the degree for the nodes (rows) of a symmetric graph in sparse CSR or CSC format, or a qobj.

  Parameters:
    A qobj, csr_matrix, csc_matrix

      Input quantum object or csr_matrix.

  Returns:
    degree array

      Array of integers giving the degree for each node (row).

maximum_bipartite_matching(A, perm_type='row')

  Returns an array of row or column permutations that removes nonzero elements from the diagonal of a nonsingular square CSC sparse matrix. Such a permutation is always possible provided that the matrix is nonsingular. This function looks at the structure of the matrix only.

  The input matrix will be converted to CSC matrix format if necessary.

  Parameters:
    A sparse matrix

      Input matrix

    perm_type str {‘row’, ‘column’}

      Type of permutation to generate.

  Returns:
    perm array

      Array of row or column permutations.

  Notes

  This function relies on a maximum cardinality bipartite matching algorithm based on a breadth-first search (BFS) of the underlying graph[1]_.

  References

  I. S. Duff, K. Kaya, and B. Ucar, “Design, Implementation, and Analysis of Maximum Transversal Algorithms”, ACM Trans. Math. Softw. 38, no. 2, (2011).

reverse_cuthill_mckee(A, sym=False)

  Returns the permutation array that orders a sparse CSR or CSC matrix in Reverse-Cuthill McKee ordering. Since the input matrix must be symmetric, this routine works on the matrix A+Trans(A) if the sym flag is set to False (Default).

  It is assumed by default (sym=False) that the input matrix is not symmetric. This is because it is faster to do A+Trans(A) than it is to check for symmetry for a generic matrix. If you are guaranteed that the matrix is symmetric in structure (values of matrix element do not matter) then set sym=True

  Parameters:
    A csc_matrix, csr_matrix

      Input sparse CSC or CSR sparse matrix format.

    sym bool {False, True}

      Flag to set whether input matrix is symmetric.

  Returns:
    perm array

      Array of permuted row and column indices.

  Notes

  This routine is used primarily for internal reordering of Lindblad superoperators for use in iterative solver routines.

  References

  E. Cuthill and J. McKee, “Reducing the Bandwidth of Sparse Symmetric Matrices”, ACM ‘69 Proceedings of the 1969 24th national conference, (1969).

weighted_bipartite_matching(A, perm_type='row')

  Returns an array of row permutations that attempts to maximize the product of the ABS values of the diagonal elements in a nonsingular square CSC sparse matrix. Such a permutation is always possible provided that the matrix is nonsingular.

  This function looks at both the structure and ABS values of the underlying matrix.

  Parameters:
    A csc_matrix

      Input matrix

    perm_type str {‘row’, ‘column’}

      Type of permutation to generate.

  Returns:
    perm array

      Array of row or column permutations.

  Notes

  This function uses a weighted maximum cardinality bipartite matching algorithm based on breadth-first search (BFS). The columns are weighted according to the element of max ABS value in the associated rows and are traversed in descending order by weight. When performing the BFS traversal, the row associated to a given column is the one with maximum weight. Unlike other techniques[1]_, this algorithm does not guarantee the product of the diagonal is maximized. However, this limitation is offset by the substantially faster runtime of this method.

  References

  I. S. Duff and J. Koster, “The design and use of algorithms for permuting large entries to the diagonal of sparse matrices”, SIAM J. Matrix Anal. and Applics. 20, no. 4, 889 (1997).

### Utility Functions

This module contains utility functions that are commonly needed in other qutip modules.

clebsch(j1, j2, j3, m1, m2, m3)

  Calculates the Clebsch-Gordon coefficient for coupling (j1,m1) and (j2,m2) to give (j3,m3).

  Parameters:
    j1 float

      Total angular momentum 1.

    j2 float

      Total angular momentum 2.

    j3 float

      Total angular momentum 3.

    m1 float

      z-component of angular momentum 1.

    m2 float

      z-component of angular momentum 2.

    m3 float

      z-component of angular momentum 3.

  Returns:
    cg_coeff float

      Requested Clebsch-Gordan coefficient.

convert_unit(value, orig='meV', to='GHz')

  Convert an energy from unit orig to unit to.

  Parameters:
    value float / array

      The energy in the old unit.

    orig string

      The name of the original unit (“J”, “eV”, “meV”, “GHz”, “mK”)

    to string

      The name of the new unit (“J”, “eV”, “meV”, “GHz”, “mK”)

  Returns:
    value_new_unit float / array

      The energy in the new unit.

n_thermal(w, w_th)

  Return the number of photons in thermal equilibrium for an harmonic oscillator mode with frequency ‘w’, at the temperature described by ‘w_th’ where \(\omega_{\rm th} = k_BT/\hbar\).

  Parameters:
    w float or array

      Frequency of the oscillator.

    w_th float

      The temperature in units of frequency (or the same units as w).

  Returns:
    n_avg float or array

      Return the number of average photons in thermal equilibrium for a an oscillator with the given frequency and temperature.

### File I/O Functions

file_data_read(filename, sep=None)

  Retrieves an array of data from the requested file.

  Parameters:
    filename str or pathlib.Path

      Name of file containing reqested data.

    sep str

      Seperator used to store data.

  Returns:
    data array_like

      Data from selected file.

file_data_store(filename, data, numtype='complex', numformat='decimal', sep=',')

  Stores a matrix of data to a file to be read by an external program.

  Parameters:
    filename str or pathlib.Path

      Name of data file to be stored, including extension.

    data: array_like

      Data to be written to file.

    numtype str {‘complex, ‘real’}

      Type of numerical data.

    numformat str {‘decimal’,’exp’}

      Format for written data.

    sep str

      Single-character field seperator. Usually a tab, space, comma, or semicolon.

qload(name)

  Loads data file from file named ‘filename.qu’ in current directory.

  Parameters:
    name str or pathlib.Path

      Name of data file to be loaded.

  Returns:
    qobject instance / array_like

      Object retrieved from requested file.

qsave(data, name='qutip_data')

  Saves given data to file named ‘filename.qu’ in current directory.

  Parameters:
    data instance/array_like

      Input Python object to be stored.

    filename str or pathlib.Path

      Name of output data file.

### Parallelization

This function provides functions for parallel execution of loops and function mappings, using the builtin Python module multiprocessing.

parallel_map(task, values, task_args=(), task_kwargs={}, **kwargs)

  Parallel execution of a mapping of values to the function task. This is functionally equivalent to:

      result = [task(value, *task_args, **task_kwargs) for value in values]

  Parameters:
    task a Python function

      The function that is to be called for each value in `task_vec`.

    values array / list

      The list or array of values for which the `task` function is to be evaluated.

    task_args list / dictionary

      The optional additional argument to the `task` function.

    task_kwargs list / dictionary

      The optional additional keyword argument to the `task` function.

    progress_bar ProgressBar

      Progress bar class instance for showing progress.

  Returns:
    result list

      The result list contains the value of `task(value, *task_args, **task_kwargs)` for each value in `values`.

parfor(func, *args, **kwargs)

  Executes a multi-variable function in parallel on the local machine.

  Parallel execution of a for-loop over function func for multiple input arguments and keyword arguments.

  Note

  From QuTiP 3.1, we recommend to use `qutip.parallel.parallel_map` instead of this function.

  Parameters:
    func function_type

      A function to run in parallel on the local machine. The function ‘func’ accepts a series of arguments that are passed to the function as variables. In general, the function can have multiple input variables, and these arguments must be passed in the same order as they are defined in the function definition. In addition, the user can pass multiple keyword arguments to the function.

    The following keyword argument is reserved:
    num_cpus int

      Number of CPU’s to use. Default uses maximum number of CPU’s. Performance degrades if num_cpus is larger than the physical CPU count of your machine.

  Returns:
    result list

      A `list` with length equal to number of input parameters containing the output from func.

serial_map(task, values, task_args=(), task_kwargs={}, **kwargs)

  Serial mapping function with the same call signature as parallel_map, for easy switching between serial and parallel execution. This is functionally equivalent to:

      result = [task(value, *task_args, **task_kwargs) for value in values]

  This function work as a drop-in replacement of `qutip.parallel.parallel_map`.

  Parameters:
    task a Python function

      The function that is to be called for each value in `task_vec`.

    values array / list

      The list or array of values for which the `task` function is to be evaluated.

    task_args list / dictionary

      The optional additional argument to the `task` function.

    task_kwargs list / dictionary

      The optional additional keyword argument to the `task` function.

    progress_bar ProgressBar

      Progress bar class instance for showing progress.

  Returns:
    result list

      The result list contains the value of `task(value, *task_args, **task_kwargs)` for each value in `values`.

### Semidefinite Programming

This module implements internal-use functions for semidefinite programming.

### IPython Notebook Tools

This module contains utility functions for using QuTiP with IPython notebooks.

parallel_map(task, values, task_args=None, task_kwargs=None, client=None, view=None, progress_bar=None, show_scheduling=False, **kwargs)

  Call the function `task` for each value in `values` using a cluster of IPython engines. The function `task` should have the signature `task(value, *args, **kwargs)`.

  The `client` and `view` are the IPython.parallel client and load-balanced view that will be used in the parfor execution. If these are `None`, new instances will be created.

  Parameters:
    task: a Python function

      The function that is to be called for each value in `task_vec`.

    values: array / list

      The list or array of values for which the `task` function is to be evaluated.

    task_args: list / dictionary

      The optional additional argument to the `task` function.

    task_kwargs: list / dictionary

      The optional additional keyword argument to the `task` function.

    client: IPython.parallel.Client

      The IPython.parallel Client instance that will be used in the parfor execution.

    view: a IPython.parallel.Client view

      The view that is to be used in scheduling the tasks on the IPython cluster. Preferably a load-balanced view, which is obtained from the IPython.parallel.Client instance client by calling, view = client.load_balanced_view().

    show_scheduling: bool {False, True}, default False

      Display a graph showing how the tasks (the evaluation of `task` for for the value in `task_vec1`) was scheduled on the IPython engine cluster.

    show_progressbar: bool {False, True}, default False

      Display a HTML-based progress bar during the execution of the parfor loop.

  Returns:
    result list

      The result list contains the value of `task(value, task_args, task_kwargs)` for each value in `values`.

parfor(task, task_vec, args=None, client=None, view=None, show_scheduling=False, show_progressbar=False)

  Call the function `tast` for each value in `task_vec` using a cluster of IPython engines. The function `task` should have the signature `task(value, args)` or `task(value)` if `args=None`.

  The `client` and `view` are the IPython.parallel client and load-balanced view that will be used in the parfor execution. If these are `None`, new instances will be created.

  Parameters:
    task: a Python function

      The function that is to be called for each value in `task_vec`.

    task_vec: array / list

      The list or array of values for which the `task` function is to be evaluated.

    args: list / dictionary

      The optional additional argument to the `task` function. For example a dictionary with parameter values.

    client: IPython.parallel.Client

      The IPython.parallel Client instance that will be used in the parfor execution.

    view: a IPython.parallel.Client view

      The view that is to be used in scheduling the tasks on the IPython cluster. Preferably a load-balanced view, which is obtained from the IPython.parallel.Client instance client by calling, view = client.load_balanced_view().

    show_scheduling: bool {False, True}, default False

      Display a graph showing how the tasks (the evaluation of `task` for for the value in `task_vec1`) was scheduled on the IPython engine cluster.

    show_progressbar: bool {False, True}, default False

      Display a HTML-based progress bar duing the execution of the parfor loop.

  Returns:
    result list

      The result list contains the value of `task(value, args)` for each value in `task_vec`, that is, it should be equivalent to `[task(v, args) for v in task_vec]`.

version_table(verbose=False)

  Print an HTML-formatted table with version numbers for QuTiP and its dependencies. Use it in a IPython notebook to show which versions of different packages that were used to run the notebook. This should make it possible to reproduce the environment and the calculation later on.

  Returns:
    version_table: string

      Return an HTML-formatted string containing version information for QuTiP dependencies.

### Miscellaneous

about()

  About box for QuTiP. Gives version numbers for QuTiP, NumPy, SciPy, Cython, and MatPlotLib.

simdiag(ops, evals: bool = True, *, tol: float = 1e-14, safe_mode: bool = True)

  Simultaneous diagonalization of commuting Hermitian matrices.

  Parameters:
    ops list/array

      `list` or `array` of qobjs representing commuting Hermitian operators.

    evals bool [True]

      Whether to return the eigenvalues for each ops and eigenvectors or just the eigenvectors.

    tol float [1e-14]

      Tolerance for detecting degenerate eigenstates.

    safe_mode bool [True]

      Whether to check that all ops are Hermitian and commuting. If set to `False` and operators are not commuting, the eigenvectors returned will often be eigenvectors of only the first operator.

  Returns:
    eigs tuple

      Tuple of arrays representing eigvecs and eigvals of quantum objects corresponding to simultaneous eigenvectors and eigenvalues for each operator.