Skip to content

qutip

QuTiP ↔ ShadowSim conversion helpers.

Convert QuTiP Qobj values to ShadowSim core types and back::

from shadowsim.interop.qutip import from_qutip, to_qutip

H = from_qutip(qutip_H)                 # → Hamiltonian
ops = [from_qutip(c) for c in c_ops]    # → Operator
psi = from_qutip(psi0)                  # → State (ket)
rho = from_qutip(qutip_rho)             # → DensityOperator

Hermitian PSD unit-trace opers become DensityOperator. Override with kind="hamiltonian" or kind="operator" when needed (e.g. a projector used as an observable).

from_qutip

from_qutip(
    qobj: Qobj,
    *,
    kind: Kind | None = None,
    num_qubits: int | None = None,
    local_dim: int | None = None,
) -> State | DensityOperator | Hamiltonian | Operator

Convert a QuTiP Qobj to a ShadowSim core type.

When kind is omitted, inference is:

  • ket or bra → State
  • square Hermitian PSD unit-trace oper → DensityOperator
  • other square Hermitian oper → Hamiltonian
  • other square oper → Operator

Parameters:

  • qobj (Qobj) –

    QuTiP quantum object to convert.

  • kind (Kind | None, default: None ) –

    Optional override: "state", "hamiltonian", "operator", or "density".

  • num_qubits (int | None, default: None ) –

    Override inferred site count when building a State.

  • local_dim (int | None, default: None ) –

    Override inferred local dimension when building a State.

Returns:

Raises:

  • TypeError –

    If qobj is not a Qobj, or kind is invalid.

  • ValueError –

    If the object type cannot be converted, or state dims are ambiguous / inconsistent.

Source code in shadowsim/interop/qutip.py
def from_qutip(
    qobj: Qobj,
    *,
    kind: Kind | None = None,
    num_qubits: int | None = None,
    local_dim: int | None = None,
) -> State | DensityOperator | Hamiltonian | Operator:
    """Convert a QuTiP ``Qobj`` to a ShadowSim core type.

    When ``kind`` is omitted, inference is:

    - ket or bra → ``State``
    - square Hermitian PSD unit-trace oper → ``DensityOperator``
    - other square Hermitian oper → ``Hamiltonian``
    - other square oper → ``Operator``

    Args:
        qobj: QuTiP quantum object to convert.
        kind: Optional override: ``"state"``, ``"hamiltonian"``, ``"operator"``,
            or ``"density"``.
        num_qubits: Override inferred site count when building a ``State``.
        local_dim: Override inferred local dimension when building a ``State``.

    Returns:
        The corresponding ShadowSim object.

    Raises:
        TypeError: If ``qobj`` is not a ``Qobj``, or ``kind`` is invalid.
        ValueError: If the object type cannot be converted, or state dims are
            ambiguous / inconsistent.
    """
    if not isinstance(qobj, Qobj):
        raise TypeError(f"qobj must be a qutip.Qobj; got {type(qobj)!r}")
    if kind is not None and kind not in _VALID_KINDS:
        raise TypeError(f"kind must be one of {sorted(_VALID_KINDS)}; got {kind!r}")
    if qobj.issuper:
        raise ValueError("cannot convert QuTiP superoperators; expected ket, bra, or oper")

    resolved = kind if kind is not None else _infer_kind(qobj)

    if resolved == "state":
        return _to_state(qobj, num_qubits=num_qubits, local_dim=local_dim)
    if resolved == "density":
        return _to_density_operator(qobj)
    if resolved == "hamiltonian":
        return _to_hamiltonian(qobj)
    return _to_operator(qobj)

to_qutip

to_qutip(
    obj: State | Operator | Hamiltonian | DensityOperator,
) -> Qobj

Convert a ShadowSim core type to a QuTiP Qobj.

Parameters:

Returns:

  • Qobj –

    A ket Qobj for State (flat dims [[dim], [1]]), or an oper

  • Qobj –

    Qobj for operators (including Hamiltonian and DensityOperator).

  • Qobj –

    Flat state dims match dense Hamiltonians passed to QuTiP solvers.

Raises:

  • TypeError –

    If obj is not a supported ShadowSim type.

Source code in shadowsim/interop/qutip.py
def to_qutip(obj: State | Operator | Hamiltonian | DensityOperator) -> Qobj:
    """Convert a ShadowSim core type to a QuTiP ``Qobj``.

    Args:
        obj: ShadowSim object to convert.

    Returns:
        A ket ``Qobj`` for ``State`` (flat dims ``[[dim], [1]]``), or an oper
        ``Qobj`` for operators (including ``Hamiltonian`` and ``DensityOperator``).
        Flat state dims match dense Hamiltonians passed to QuTiP solvers.

    Raises:
        TypeError: If ``obj`` is not a supported ShadowSim type.
    """
    if isinstance(obj, State):
        # Flat dims match ``Qobj(ndarray)`` / mesolve with dense Hamiltonian matrices.
        dim = obj.get_local_dim() ** obj.get_num_qubits()
        return Qobj(np.asarray(obj.state, dtype=np.complex128), dims=[[dim], [1]])

    if isinstance(obj, Operator):
        matrix = np.asarray(obj.matrix, dtype=np.complex128)
        return Qobj(matrix)

    raise TypeError(f"obj must be a shadowsim State, Operator, Hamiltonian, or DensityOperator; got {type(obj)!r}")