Skip to content

models

Reusable physical model factories.

IsingModel dataclass

Bundled operators for a classical or transverse-field Ising Hamiltonian.

Qubits are labeled 0 .. num_qubits - 1. Couplings act on the edge set edges; single-site fields are on every qubit. Every ZZ edge and every single-site field is a LocalHamiltonian. A long-range edge, including the periodic wrap, names its two endpoints. Embedding that term puts identity on the sites in between.

Attributes:

  • full_hamiltonians (list[Hamiltonian]) –

    Hamiltonian terms in the full Hilbert space.

  • local_hamiltonians (list[LocalHamiltonian]) –

    One ZZ term per edge and one single-site field per qubit.

  • c_ops_full (list[Operator]) –

    Lindblad operators in the full space (empty; closed system).

  • c_ops_local (list[LocalOperator]) –

    Local Lindblad operators (empty; closed system).

  • psi0 (State) –

    Default initial state (all-|0⟩ classical, all-|+⟩ transverse).

  • e_ops (list[Operator]) –

    Per-site Z observables.

  • measurements (list[Measurement]) –

    Per-site Z expectations from shot counts, matching e_ops.

  • pauli_sum (PauliSum) –

    Full Hamiltonian as a sparse Pauli sum.

  • edges (list[tuple[int, int]]) –

    Resolved undirected interaction pairs (i, j) with i < j.

  • num_qubits (int) –

    Number of qubits.

  • J (float) –

    Coupling strength.

  • h (float) –

    Field strength.

  • field (FieldKind) –

    "classical" (Z field) or "transverse" (X field).

  • topology (TopologyKind) –

    "chain" or "custom" when edges was supplied.

  • boundary (BoundaryKind) –

    Boundary condition used for chain presets ("open" for custom).

Source code in shadowsim/models/ising.py
@dataclass(frozen=True)
class IsingModel:
    """Bundled operators for a classical or transverse-field Ising Hamiltonian.

    Qubits are labeled ``0 .. num_qubits - 1``. Couplings act on the edge set
    ``edges``; single-site fields are on every qubit. Every ZZ edge and every
    single-site field is a ``LocalHamiltonian``. A long-range edge, including
    the periodic wrap, names its two endpoints. Embedding that term puts
    identity on the sites in between.

    Attributes:
        full_hamiltonians: Hamiltonian terms in the full Hilbert space.
        local_hamiltonians: One ZZ term per edge and one single-site field per qubit.
        c_ops_full: Lindblad operators in the full space (empty; closed system).
        c_ops_local: Local Lindblad operators (empty; closed system).
        psi0: Default initial state (all-|0⟩ classical, all-|+⟩ transverse).
        e_ops: Per-site ``Z`` observables.
        measurements: Per-site ``Z`` expectations from shot counts, matching ``e_ops``.
        pauli_sum: Full Hamiltonian as a sparse Pauli sum.
        edges: Resolved undirected interaction pairs ``(i, j)`` with ``i < j``.
        num_qubits: Number of qubits.
        J: Coupling strength.
        h: Field strength.
        field: ``"classical"`` (Z field) or ``"transverse"`` (X field).
        topology: ``"chain"`` or ``"custom"`` when ``edges`` was supplied.
        boundary: Boundary condition used for chain presets (``"open"`` for custom).
    """

    full_hamiltonians: list[Hamiltonian]
    local_hamiltonians: list[LocalHamiltonian]
    c_ops_full: list[Operator]
    c_ops_local: list[LocalOperator]
    psi0: State
    e_ops: list[Operator]
    measurements: list[Measurement]
    pauli_sum: PauliSum
    edges: list[tuple[int, int]]
    num_qubits: int
    J: float
    h: float
    field: FieldKind
    topology: TopologyKind
    boundary: BoundaryKind

    @property
    def hamiltonian(self) -> Hamiltonian:
        """Return the combined full-space Hamiltonian."""
        return Hamiltonian(self.pauli_sum)

hamiltonian property

hamiltonian: Hamiltonian

Return the combined full-space Hamiltonian.

JaynesCummingsModel dataclass

Bases: TavisCummingsModel

Bundled operators for the single-emitter Jaynes–Cummings open system.

This is a TavisCummingsModel with n_emitters fixed at 1. Qubit layout is two cavity qubits (Fock truncation 4) followed by one emitter qubit: sites [0, 1] then [2].

Source code in shadowsim/models/jaynes_cummings.py
@dataclass(frozen=True)
class JaynesCummingsModel(TavisCummingsModel):
    """Bundled operators for the single-emitter Jaynes–Cummings open system.

    This is a ``TavisCummingsModel`` with ``n_emitters`` fixed at 1.
    Qubit layout is two cavity qubits (Fock truncation 4) followed by one
    emitter qubit: sites ``[0, 1]`` then ``[2]``.
    """

    def __post_init__(self) -> None:
        """Require the single-emitter qubit layout."""
        if self.n_emitters != 1 or self.num_qubits != _jaynes_cummings_qubits():
            raise ValueError(
                "JaynesCummingsModel is the single-emitter case: "
                f"n_emitters must be 1 and num_qubits must be 3, got {self.n_emitters} and {self.num_qubits}"
            )

__post_init__

__post_init__() -> None

Require the single-emitter qubit layout.

Source code in shadowsim/models/jaynes_cummings.py
def __post_init__(self) -> None:
    """Require the single-emitter qubit layout."""
    if self.n_emitters != 1 or self.num_qubits != _jaynes_cummings_qubits():
        raise ValueError(
            "JaynesCummingsModel is the single-emitter case: "
            f"n_emitters must be 1 and num_qubits must be 3, got {self.n_emitters} and {self.num_qubits}"
        )

JaynesCummingsHubbardModel dataclass

Bases: TavisCummingsHubbardModel

Bundled operators for the single-emitter Jaynes–Cummings–Hubbard open system.

This is a TavisCummingsHubbardModel with n_emitters fixed at 1. Each cavity is two Fock qubits followed by one emitter, so num_qubits is 3 * n_cavities.

Source code in shadowsim/models/jaynes_cummings_hubbard.py
@dataclass(frozen=True)
class JaynesCummingsHubbardModel(TavisCummingsHubbardModel):
    """Bundled operators for the single-emitter Jaynes–Cummings–Hubbard open system.

    This is a ``TavisCummingsHubbardModel`` with ``n_emitters`` fixed at 1.
    Each cavity is two Fock qubits followed by one emitter, so ``num_qubits``
    is ``3 * n_cavities``.
    """

    def __post_init__(self) -> None:
        """Require one emitter on every cavity."""
        if self.n_emitters != 1 or self.num_qubits != _jaynes_cummings_hubbard_qubits(n_cavities=self.n_cavities):
            raise ValueError(
                "JaynesCummingsHubbardModel is the single-emitter case: "
                "n_emitters must be 1 and num_qubits must be 3 * n_cavities, "
                f"got {self.n_emitters} and {self.num_qubits}"
            )

__post_init__

__post_init__() -> None

Require one emitter on every cavity.

Source code in shadowsim/models/jaynes_cummings_hubbard.py
def __post_init__(self) -> None:
    """Require one emitter on every cavity."""
    if self.n_emitters != 1 or self.num_qubits != _jaynes_cummings_hubbard_qubits(n_cavities=self.n_cavities):
        raise ValueError(
            "JaynesCummingsHubbardModel is the single-emitter case: "
            "n_emitters must be 1 and num_qubits must be 3 * n_cavities, "
            f"got {self.n_emitters} and {self.num_qubits}"
        )

TavisCummingsModel dataclass

Bundled operators and helpers for the cavity–emitter open system.

Qubit layout is two cavity qubits (Fock truncation 4) followed by one qubit per emitter: sites [0, 1] then [2, ..., 1 + n_emitters].

Attributes:

  • full_hamiltonians (list[Hamiltonian]) –

    Hamiltonian terms embedded in the full Hilbert space (QuTiP path).

  • local_hamiltonians (list[LocalHamiltonian]) –

    Hamiltonian terms on contiguous qubit blocks (Split-J path).

  • c_ops_full (list[Operator]) –

    Lindblad operators in the full Hilbert space.

  • c_ops_local (list[LocalOperator]) –

    Lindblad operators on local qubit blocks.

  • psi0 (State) –

    Initial state (cavity Fock ⊗ all emitters in ground).

  • e_ops (list[Operator]) –

    Observables for QuTiP (cavity population, then each emitter).

  • measurements (list[Measurement]) –

    Shot-count measurements matching e_ops (cavity population on qubits 0 and 1, then each emitter's population).

  • num_qubits (int) –

    2 + n_emitters.

  • n_emitters (int) –

    Number of two-level emitters.

Source code in shadowsim/models/tavis_cummings.py
@dataclass(frozen=True)
class TavisCummingsModel:
    """Bundled operators and helpers for the cavity–emitter open system.

    Qubit layout is two cavity qubits (Fock truncation 4) followed by one qubit
    per emitter: sites ``[0, 1]`` then ``[2, ..., 1 + n_emitters]``.

    Attributes:
        full_hamiltonians: Hamiltonian terms embedded in the full Hilbert space
            (QuTiP path).
        local_hamiltonians: Hamiltonian terms on contiguous qubit blocks
            (Split-J path).
        c_ops_full: Lindblad operators in the full Hilbert space.
        c_ops_local: Lindblad operators on local qubit blocks.
        psi0: Initial state (cavity Fock ⊗ all emitters in ground).
        e_ops: Observables for QuTiP (cavity population, then each emitter).
        measurements: Shot-count measurements matching ``e_ops`` (cavity
            population on qubits 0 and 1, then each emitter's population).
        num_qubits: ``2 + n_emitters``.
        n_emitters: Number of two-level emitters.
    """

    full_hamiltonians: list[Hamiltonian]
    local_hamiltonians: list[LocalHamiltonian]
    c_ops_full: list[Operator]
    c_ops_local: list[LocalOperator]
    psi0: State
    e_ops: list[Operator]
    measurements: list[Measurement]
    num_qubits: int
    n_emitters: int

TavisCummingsHubbardModel dataclass

Bases: TavisCummingsModel

Bundled operators for the Tavis–Cummings–Hubbard open system.

n_cavities blocks are concatenated. Each block is two cavity qubits (Fock truncation 4) followed by n_emitters emitter qubits, so n_emitters is the count on every cavity. num_qubits is n_cavities * (2 + n_emitters).

Source code in shadowsim/models/tavis_cummings_hubbard.py
@dataclass(frozen=True)
class TavisCummingsHubbardModel(TavisCummingsModel):
    """Bundled operators for the Tavis–Cummings–Hubbard open system.

    ``n_cavities`` blocks are concatenated. Each block is two cavity qubits
    (Fock truncation 4) followed by ``n_emitters`` emitter qubits, so
    ``n_emitters`` is the count on every cavity. ``num_qubits`` is
    ``n_cavities * (2 + n_emitters)``.
    """

    n_cavities: int = 1