0
# Composite Systems
1

2
Tools for building and analyzing coupled qubit-oscillator systems with arbitrary interaction terms. Enables simulation of circuit QED architectures, multi-qubit systems, and complex quantum devices.
3

4
## Capabilities
5

6
### Hilbert Space Construction
7

8
Container class for managing multiple quantum subsystems and their interactions, providing a unified interface for composite system analysis.
9

10
```python { .api }
11
class HilbertSpace:
12
    def __init__(self, subsystem_list: list = None, interaction_list: list = None,
13
                 ignore_low_overlap: bool = False, evals_method: str = None,
14
                 evals_method_options: dict = None, esys_method: str = None,
15
                 esys_method_options: dict = None):
16
        """
17
        Composite quantum system container.
18
        
19
        Parameters:
20
        - subsystem_list (list): List of quantum systems to include
21
        - interaction_list (list): Optional list of interaction terms
22
        - ignore_low_overlap (bool): Whether to ignore low overlap warnings
23
        - evals_method (str): Method for eigenvalue calculations
24
        - evals_method_options (dict): Options for eigenvalue method
25
        - esys_method (str): Method for eigensystem calculations
26
        - esys_method_options (dict): Options for eigensystem method
27
        """
28
        
29
    def add_system(self, subsystem) -> int:
30
        """
31
        Add a quantum system to the composite space.
32
        
33
        Parameters:
34
        - subsystem: Quantum system object (qubit, oscillator, etc.)
35
        
36
        Returns:
37
        - int: Index of the added subsystem
38
        """
39
        
40
    def add_interaction(self, check_validity: bool = True, id_str: str = None, **kwargs):
41
        """
42
        Add interaction term between subsystems. Supports multiple interfaces.
43
        
44
        Parameters:
45
        - check_validity (bool): Whether to validate the interaction
46
        - id_str (str): Optional identifier for the interaction
47
        - **kwargs: Interaction specification (varies by interface used)
48
        """
49
        
50
    def eigenvals(self, evals_count: int = 6) -> np.ndarray:
51
        """Calculate dressed eigenvalues of composite system."""
52
        
53
    def eigensys(self, evals_count: int = 6) -> tuple:
54
        """Calculate dressed eigenvalues and eigenvectors."""
55
        
56
    def hamiltonian(self) -> np.ndarray:
57
        """Full Hamiltonian matrix including interactions."""
58
        
59
    def bare_hamiltonian(self) -> np.ndarray:
60
        """Bare Hamiltonian without interactions."""
61
        
62
    def interaction_hamiltonian(self) -> np.ndarray:  
63
        """Interaction Hamiltonian only."""
64
        
65
    def generate_lookup(self) -> None:
66
        """Generate lookup tables for dressed states."""
67
        
68
    def bare_eigenvals(self, subsys: int, evals_count: int = 6) -> np.ndarray:
69
        """Eigenvalues of individual subsystem."""
70
        
71
    def subsystem_count(self) -> int:
72
        """Number of subsystems in composite space."""
73
        
74
    def dimension(self) -> int:
75
        """Total Hilbert space dimension."""
76
        
77
    def subsystem_dims(self) -> list:
78
        """Dimensions of individual subsystems."""
79
```
80

81
### Interaction Terms
82

83
Classes for specifying coupling between quantum subsystems with flexible operator definitions.
84

85
```python { .api }
86
class InteractionTerm:
87
    def __init__(self, g_strength: float, op1, op2, subsys1: int, subsys2: int):
88
        """
89
        Interaction term between two subsystems.
90
        
91
        Parameters:
92
        - g_strength (float): Coupling strength coefficient
93
        - op1: Operator matrix for first subsystem
94
        - op2: Operator matrix for second subsystem  
95
        - subsys1 (int): Index of first subsystem
96
        - subsys2 (int): Index of second subsystem
97
        """
98
        
99
    def hamiltonian_term(self, subsystem_list: list) -> np.ndarray:
100
        """Generate Hamiltonian contribution for this interaction."""
101

102
class InteractionTermStr:
103
    def __init__(self, g_strength: float, operator1_name: str, subsys1: int,
104
                 operator2_name: str, subsys2: int):
105
        """
106
        String-based interaction term specification.
107
        
108
        Parameters:
109
        - g_strength (float): Coupling strength
110
        - operator1_name (str): Name of operator on first subsystem
111
        - subsys1 (int): Index of first subsystem
112
        - operator2_name (str): Name of operator on second subsystem
113
        - subsys2 (int): Index of second subsystem
114
        """
115
```
116

117
### Oscillator Classes
118

119
Harmonic and anharmonic oscillator implementations for modeling cavity modes and other coherent degrees of freedom.
120

121
```python { .api }
122
class Oscillator:
123
    def __init__(self, E_osc: float, truncated_dim: int):
124
        """
125
        Harmonic oscillator for cavity modes.
126
        
127
        Parameters:
128
        - E_osc (float): Oscillator frequency
129
        - truncated_dim (int): Number of Fock states to include
130
        """
131
        
132
    def eigenvals(self, evals_count: int = 6) -> np.ndarray:
133
        """Harmonic oscillator eigenvalues."""
134
        
135
    def eigensys(self, evals_count: int = 6) -> tuple:
136
        """Harmonic oscillator eigensystem."""
137
        
138
    @property
139
    def annihilation_operator(self) -> np.ndarray:
140
        """Lowering operator matrix."""
141
        
142
    @property  
143
    def creation_operator(self) -> np.ndarray:
144
        """Raising operator matrix."""
145
        
146
    @property
147
    def number_operator(self) -> np.ndarray:
148
        """Number operator matrix."""
149
        
150
    @property
151
    def position_operator(self) -> np.ndarray:
152
        """Position quadrature operator."""
153
        
154
    @property
155
    def momentum_operator(self) -> np.ndarray:
156
        """Momentum quadrature operator."""
157

158
class KerrOscillator:
159
    def __init__(self, E_osc: float, K: float, truncated_dim: int):
160
        """
161
        Kerr-nonlinear oscillator.
162
        
163
        Parameters:
164
        - E_osc (float): Linear oscillator frequency
165
        - K (float): Kerr nonlinearity strength
166
        - truncated_dim (int): Fock space truncation
167
        """
168
        
169
    def hamiltonian(self) -> np.ndarray:
170
        """Kerr oscillator Hamiltonian including nonlinearity."""
171
```
172

173
## Usage Examples
174

175
### Transmon-Cavity System
176

177
```python
178
import scqubits as scq
179
import numpy as np
180

181
# Create subsystems
182
transmon = scq.Transmon(EJ=25.0, EC=0.2, ng=0.0, ncut=30)
183
cavity = scq.Oscillator(E_osc=6.0, truncated_dim=4)
184

185
# Create composite system
186
hilbert_space = scq.HilbertSpace([transmon, cavity])
187

188
# Add dispersive interaction (chi coupling)
189
g = 0.1  # coupling strength in GHz
190
hilbert_space.add_interaction(
191
    g_strength=g,
192
    op1=transmon.n_operator,
193
    op2=cavity.creation_operator + cavity.annihilation_operator
194
)
195

196
# Calculate dressed spectrum
197
dressed_evals = hilbert_space.eigenvals(evals_count=12)
198
print("Dressed energy levels:", dressed_evals)
199

200
# Compare to bare energies
201
bare_transmon = transmon.eigenvals(evals_count=3)
202
bare_cavity = cavity.eigenvals(evals_count=4)
203
print("Bare transmon levels:", bare_transmon)
204
print("Bare cavity levels:", bare_cavity)
205
```
206

207
### Two-Qubit System
208

209
```python
210
# Create two qubits
211
qubit1 = scq.Transmon(EJ=20.0, EC=0.3, ng=0.0, ncut=25)
212
qubit2 = scq.Transmon(EJ=18.0, EC=0.25, ng=0.0, ncut=25)
213

214
# Create composite system
215
two_qubit_system = scq.HilbertSpace([qubit1, qubit2])
216

217
# Add capacitive coupling
218
J = 0.02  # coupling strength
219
two_qubit_system.add_interaction(
220
    g_strength=J,
221
    op1=qubit1.n_operator,
222
    op2=qubit2.n_operator
223
)
224

225
# Calculate spectrum
226
spectrum = two_qubit_system.eigenvals(evals_count=16)
227

228
# Analyze level structure
229
from scqubits.utils.misc import make_bare_labels
230
bare_labels = make_bare_labels([qubit1, qubit2])
231
```
232

233
### Parametric Analysis
234

235
```python
236
# Parameter sweep of composite system
237
cavity = scq.Oscillator(E_osc=6.0, truncated_dim=3)
238
transmon = scq.Transmon(EJ=25.0, EC=0.2, ng=0.0, ncut=20)
239
system = scq.HilbertSpace([transmon, cavity])
240

241
# Add interaction
242
system.add_interaction(
243
    g_strength=0.15,
244
    op1=transmon.n_operator,
245
    op2=cavity.number_operator
246
)
247

248
# Sweep transmon frequency
249
EJ_vals = np.linspace(20, 30, 51)
250
sweep = scq.ParameterSweep(
251
    hilbert_space=system,
252
    paramvals_by_name={'EJ': EJ_vals},
253
    evals_count=10,
254
    subsys_update_list=[0]  # Update only transmon
255
)
256

257
sweep.run()
258
sweep.plot_evals_vs_paramvals()
259
```
260

261
### Multi-Mode Cavity
262

263
```python
264
# Transmon coupled to multiple cavity modes
265
transmon = scq.Transmon(EJ=25.0, EC=0.2, ng=0.0, ncut=30)
266
cavity1 = scq.Oscillator(E_osc=6.0, truncated_dim=3)
267
cavity2 = scq.Oscillator(E_osc=8.5, truncated_dim=3)
268

269
# Create three-body system
270
system = scq.HilbertSpace([transmon, cavity1, cavity2])
271

272
# Add coupling to both modes
273
g1, g2 = 0.1, 0.08
274

275
system.add_interaction(
276
    g_strength=g1,
277
    op1=transmon.n_operator,
278
    op2=cavity1.creation_operator + cavity1.annihilation_operator
279
)
280

281
system.add_interaction(
282
    g_strength=g2, 
283
    op1=transmon.n_operator,
284
    op2=cavity2.creation_operator + cavity2.annihilation_operator
285
)
286

287
# Add cavity-cavity coupling
288
J_cc = 0.01
289
system.add_interaction(
290
    g_strength=J_cc,
291
    op1=cavity1.creation_operator,
292
    op2=cavity2.annihilation_operator
293
)
294

295
# Add conjugate term
296
system.add_interaction(
297
    g_strength=J_cc,
298
    op1=cavity1.annihilation_operator,
299
    op2=cavity2.creation_operator
300
)
301

302
# Analyze three-body spectrum
303
spectrum = system.eigenvals(evals_count=20)
304
```