Skip to content

tavis_cummings

Open cavity–emitter (Tavis–Cummings–like) model factory.

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

tavis_cummings

tavis_cummings(
    *,
    omega_c: float = _DEFAULT_OMEGA_C,
    omega_e: FloatOrSeq = _DEFAULT_OMEGA_E,
    kappa: float = _DEFAULT_KAPPA,
    gamma: FloatOrSeq = _DEFAULT_GAMMA,
    g: FloatOrSeq = _DEFAULT_G,
    n_emitters: int = 1,
    cavity_levels: int = 4,
    initial_fock: int = 2,
) -> TavisCummingsModel

Build an open cavity–emitter (Tavis–Cummings–like) model.

The cavity Fock space is truncated to four levels and encoded on two qubits; each emitter is a two-level system on its own qubit. Only cavity_levels=4 is supported in v1. The one-emitter case is jaynes_cummings. n_emitters=1 with default frequencies/couplings reproduces README Example 2 / examples/simple_algo_benchmark.py.

kappa and gamma are Lindblad amplitudes (as in the historical examples), not decay rates. omega_e, gamma, and g may be scalars (broadcast to every emitter) or sequences of length n_emitters.

Parameters:

  • omega_c (float, default: _DEFAULT_OMEGA_C ) –

    Cavity frequency.

  • omega_e (FloatOrSeq, default: _DEFAULT_OMEGA_E ) –

    Emitter frequency (scalar or per-emitter).

  • kappa (float, default: _DEFAULT_KAPPA ) –

    Cavity Lindblad amplitude.

  • gamma (FloatOrSeq, default: _DEFAULT_GAMMA ) –

    Emitter Lindblad amplitude (scalar or per-emitter).

  • g (FloatOrSeq, default: _DEFAULT_G ) –

    Cavity–emitter coupling strength (scalar or per-emitter).

  • n_emitters (int, default: 1 ) –

    Number of emitters (at least 1).

  • cavity_levels (int, default: 4 ) –

    Fock truncation. Must be 4.

  • initial_fock (int, default: 2 ) –

    Initial cavity Fock occupation in 0..3 (emitters start in the ground state).

Returns:

Raises:

  • ValueError –

    If n_emitters < 1, cavity_levels is not 4, initial_fock is outside 0..3, or a per-emitter sequence has the wrong length.

Source code in shadowsim/models/tavis_cummings.py
def tavis_cummings(
    *,
    omega_c: float = _DEFAULT_OMEGA_C,
    omega_e: FloatOrSeq = _DEFAULT_OMEGA_E,
    kappa: float = _DEFAULT_KAPPA,
    gamma: FloatOrSeq = _DEFAULT_GAMMA,
    g: FloatOrSeq = _DEFAULT_G,
    n_emitters: int = 1,
    cavity_levels: int = 4,
    initial_fock: int = 2,
) -> TavisCummingsModel:
    """Build an open cavity–emitter (Tavis–Cummings–like) model.

    The cavity Fock space is truncated to four levels and encoded on two qubits;
    each emitter is a two-level system on its own qubit. Only ``cavity_levels=4``
    is supported in v1. The one-emitter case is ``jaynes_cummings``.
    ``n_emitters=1`` with default frequencies/couplings reproduces README
    Example 2 / ``examples/simple_algo_benchmark.py``.

    ``kappa`` and ``gamma`` are Lindblad amplitudes (as in the historical
    examples), not decay rates. ``omega_e``, ``gamma``, and ``g`` may be scalars
    (broadcast to every emitter) or sequences of length ``n_emitters``.

    Args:
        omega_c: Cavity frequency.
        omega_e: Emitter frequency (scalar or per-emitter).
        kappa: Cavity Lindblad amplitude.
        gamma: Emitter Lindblad amplitude (scalar or per-emitter).
        g: Cavity–emitter coupling strength (scalar or per-emitter).
        n_emitters: Number of emitters (at least 1).
        cavity_levels: Fock truncation. Must be 4.
        initial_fock: Initial cavity Fock occupation in ``0..3`` (emitters start
            in the ground state).

    Returns:
        A ``TavisCummingsModel`` with full and local operators ready for
        simulators.

    Raises:
        ValueError: If ``n_emitters < 1``, ``cavity_levels`` is not 4,
            ``initial_fock`` is outside ``0..3``, or a per-emitter sequence has
            the wrong length.
    """
    block = _cavity_block(
        omega_c=omega_c,
        omega_e=omega_e,
        kappa=kappa,
        gamma=gamma,
        g=g,
        n_emitters=n_emitters,
        cavity_levels=cavity_levels,
        initial_fock=initial_fock,
    )
    num_qubits = _tavis_cummings_qubits(n_emitters=n_emitters)
    return TavisCummingsModel(
        full_hamiltonians=[Hamiltonian(matrix) for matrix in block.full_hamiltonians],
        local_hamiltonians=[LocalHamiltonian(matrix, sites) for matrix, sites in block.local_hamiltonians],
        c_ops_full=[Operator(matrix) for matrix in block.c_ops_full],
        c_ops_local=[LocalOperator(matrix, sites) for matrix, sites in block.c_ops_local],
        psi0=State(block.state, num_qubits),
        e_ops=[Operator(matrix) for matrix in block.e_ops],
        measurements=_block_measurements(0, n_emitters),
        num_qubits=num_qubits,
        n_emitters=n_emitters,
    )