0
# Scqubits
1

2
A comprehensive Python library for simulating superconducting qubits, providing tools for energy spectra calculations, plotting capabilities for energy levels as functions of external parameters, and matrix element computations. Features seamless integration with QuTiP for composite Hilbert spaces, leveraging NumPy and SciPy for numerical computations and Matplotlib for visualization.
3

4
## Package Information
5

6
- **Package Name**: scqubits
7
- **Language**: Python
8
- **Installation**: `pip install scqubits` or `conda install -c conda-forge scqubits`
9

10
## Core Imports
11

12
```python
13
import scqubits as scq
14
```
15

16
For specific components:
17

18
```python
19
from scqubits import Transmon, Fluxonium, HilbertSpace, ParameterSweep
20
from scqubits import Grid1d, DataStore, SpectrumData, GenericQubit, Cos2PhiQubit, TunableTransmon
21
from scqubits.utils.spectrum_utils import matrix_element, get_matrixelement_table, identity_wrap
22
from scqubits.core.units import get_units, set_units
23
from scqubits.core.noise import calc_therm_ratio
24
from scqubits.utils.misc import about, cite
25
```
26

27
## Basic Usage
28

29
```python
30
import scqubits as scq
31
import numpy as np
32

33
# Create a transmon qubit
34
transmon = scq.Transmon(
35
    EJ=25.0,        # Josephson energy in GHz
36
    EC=0.2,         # Charging energy in GHz  
37
    ng=0.0,         # Offset charge
38
    ncut=30         # Charge basis cutoff
39
)
40

41
# Calculate eigenvalues
42
evals = transmon.eigenvals(evals_count=6)
43
print("Energy levels (GHz):", evals)
44

45
# Plot energy levels vs external parameter
46
ng_vals = np.linspace(-2, 2, 100)
47
transmon.plot_evals_vs_paramvals(
48
    param_name='ng',
49
    param_vals=ng_vals,
50
    evals_count=4
51
)
52

53
# Create composite system with oscillator
54
oscillator = scq.Oscillator(E_osc=6.0, truncated_dim=4)
55
hilbert_space = scq.HilbertSpace([transmon, oscillator])
56

57
# Add interaction
58
g_strength = 0.1  # coupling strength in GHz
59
hilbert_space.add_interaction(
60
    g_strength=g_strength,
61
    op1=transmon.n_operator,
62
    op2=oscillator.creation_operator + oscillator.annihilation_operator
63
)
64

65
# Calculate dressed spectrum
66
evals = hilbert_space.eigenvals(evals_count=10)
67
```
68

69
## Architecture
70

71
Scqubits follows a modular architecture organized around quantum system classes:
72

73
- **Qubit Classes**: Individual superconducting circuit implementations (Transmon, Fluxonium, etc.)
74
- **Composite Systems**: HilbertSpace for coupled qubit-oscillator systems
75
- **Parameter Sweeps**: Efficient parameter space exploration with caching
76
- **Storage Layer**: Data management with HDF5/CSV support
77
- **Visualization**: Matplotlib-based plotting for spectra and wavefunctions
78
- **Units System**: Consistent frequency unit handling (GHz, MHz, etc.)
79

80
Each qubit class inherits from a base `QuantumSystem` class providing consistent interfaces for eigenvalue problems, plotting, and data management.
81

82
## Capabilities
83

84
### Superconducting Qubit Models
85

86
Complete set of superconducting qubit implementations including transmon, fluxonium, flux qubit, and protected qubit designs. Each provides customizable circuit parameters and built-in analysis tools.
87

88
```python { .api }
89
class Transmon:
90
    def __init__(self, EJ: float, EC: float, ng: float = 0.0, ncut: int = 30, truncated_dim: int = None): ...
91
    def eigenvals(self, evals_count: int = 6) -> np.ndarray: ...
92
    def eigensys(self, evals_count: int = 6) -> tuple: ...
93
    def hamiltonian(self) -> np.ndarray: ...
94

95
class TunableTransmon:
96
    def __init__(self, EJmax: float, EC: float, d: float = 0.0, flux: float = 0.0, 
97
                 ng: float = 0.0, ncut: int = 30, truncated_dim: int = None): ...
98

99
class Fluxonium:
100
    def __init__(self, EJ: float, EC: float, EL: float, flux: float, cutoff: int = 110, truncated_dim: int = None): ...
101

102
class FluxQubit:
103
    def __init__(self, EJ1: float, EJ2: float, EJ3: float, ECJ1: float, ECJ2: float, ECJ3: float, 
104
                 ECg1: float, ECg2: float, ng1: float = 0.0, ng2: float = 0.0, flux: float = 0.0, 
105
                 ncut: int = 10, truncated_dim: int = None): ...
106

107
class Cos2PhiQubit:
108
    def __init__(self, EJ1: float, EJ2: float, ECJ: float, ECg: float, flux: float, 
109
                 ng: float = 0.0, ncut: int = 30, truncated_dim: int = None): ...
110

111
class ZeroPi:
112
    def __init__(self, EJ: float, EL: float, ECJ: float, ECg: float, flux: float, 
113
                 ng: float = 0.0, ncut: int = 30, ncut_phi: int = 10, truncated_dim: int = None): ...
114

115
class FullZeroPi:
116
    def __init__(self, EJ: float, EL: float, ECJ: float, ECg: float, flux: float, 
117
                 ng: float = 0.0, ncut: int = 30, ncut_phi: int = 10, truncated_dim: int = None): ...
118

119
class GenericQubit:
120
    def __init__(self, hilbert_space_dimension: int, hamiltonian_func: callable = None): ...
121
```
122

123
[Qubit Models](./qubit-models.md)
124

125
### Composite Quantum Systems
126

127
Tools for building and analyzing coupled qubit-oscillator systems with arbitrary interaction terms, enabling simulation of circuit QED architectures and multi-qubit systems.
128

129
```python { .api }
130
class HilbertSpace:
131
    def __init__(self, subsystem_list: list = None): ...
132
    def add_system(self, subsystem) -> int: ...
133
    def add_interaction(self, g_strength: float, op1, op2, subsys1: int = None, subsys2: int = None): ...
134
    def eigenvals(self, evals_count: int = 6) -> np.ndarray: ...
135
    def eigensys(self, evals_count: int = 6) -> tuple: ...
136

137
class InteractionTerm:
138
    def __init__(self, g_strength: float, op1, op2, subsys1: int, subsys2: int): ...
139
```
140

141
[Composite Systems](./composite-systems.md)
142

143
### Parameter Sweeps and Analysis
144

145
Efficient parameter space exploration with built-in caching, parallel processing, and visualization tools for analyzing qubit behavior across parameter ranges.
146

147
```python { .api }
148
class ParameterSweep:
149
    def __init__(self, hilbert_space: HilbertSpace, paramvals_by_name: dict, evals_count: int = 6,
150
                 subsys_update_list: list = None, update_hilbert_space=None, num_cpus: int = None): ...
151
    def run(self) -> None: ...
152
    def plot_evals_vs_paramvals(self, which: int = -1, **kwargs): ...
153
    def transitions(self, initial_state_ind: int, final_state_ind: int) -> np.ndarray: ...
154
```
155

156
[Parameter Sweeps](./parameter-sweeps.md)
157

158
### Spectrum Analysis and Matrix Elements
159

160
Comprehensive tools for calculating matrix elements, transition rates, and spectroscopic properties including absorption and emission spectra.
161

162
```python { .api }
163
def matrix_element(state1: np.ndarray, operator: np.ndarray, state2: np.ndarray) -> complex: ...
164
def get_matrixelement_table(qubit_system, operator, evecs: np.ndarray = None, evals_count: int = None) -> np.ndarray: ...
165
def absorption_spectrum(transitions: dict, initial_state_labels: list, lineshape_func, **kwargs) -> tuple: ...
166
def emission_spectrum(transitions: dict, initial_state_labels: list, lineshape_func, **kwargs) -> tuple: ...
167
```
168

169
[Spectrum Analysis](./spectrum-analysis.md)
170

171
### File I/O and Data Management
172

173
Flexible data persistence supporting HDF5 and CSV formats with object serialization for storing and retrieving qubit calculations and parameter sweep results.
174

175
```python { .api }
176
def read(filename: str) -> object: ...
177
def write(obj: object, filename: str, file_handle=None, overwrite: bool = False) -> None: ...
178

179
class SpectrumData:
180
    def __init__(self, energy_table: np.ndarray, system_params: dict = None, state_table: np.ndarray = None): ...
181
    
182
class DataStore:
183
    def __init__(self, system_params: dict = None): ...
184
```
185

186
[File I/O](./file-io.md)
187

188
### Units and Settings
189

190
Flexible units system supporting multiple frequency scales (GHz, MHz, kHz, Hz) with global settings for computation optimization and event management.
191

192
```python { .api }
193
def get_units() -> str: ...
194
def set_units(units: str) -> None: ...
195
def show_supported_units() -> None: ...
196
def to_standard_units(value: float) -> float: ...
197
def from_standard_units(value: float) -> float: ...
198
```
199

200
[Units and Settings](./units-settings.md)
201

202
### Circuit Analysis
203

204
Symbolic circuit analysis tools for custom superconducting circuits, enabling automated quantization and Hamiltonian generation from circuit descriptions.
205

206
```python { .api }
207
class Circuit:
208
    def __init__(self, input_string: str, from_file: bool = False, ext_basis: str = None, 
209
                 initiate_sym_calc: bool = True, truncated_dim: int = None): ...
210
    def hamiltonian(self) -> np.ndarray: ...
211
    def eigenvals(self, evals_count: int = 6) -> np.ndarray: ...
212

213
class SymbolicCircuit:
214
    def __init__(self, nodes_dict: dict, branches_dict: dict, initiate: bool = True): ...
215
```
216

217
[Circuit Analysis](./circuit-analysis.md)
218

219
### Noise Analysis
220

221
Comprehensive noise modeling and coherence time calculations for superconducting qubits, including thermal effects, decoherence channels, and environmental coupling analysis.
222

223
```python { .api }
224
def calc_therm_ratio(omega: float, T: float, omega_in_standard_units: bool = False) -> float: ...
225

226
class NoiseChannel:
227
    def __init__(self, noise_op, system, truncated_dim: int = None): ...
228
    def spectrum(self, omega: float, esys: tuple = None, **kwargs) -> float: ...
229
    def t1_effective(self, esys: tuple = None, **kwargs) -> float: ...
230
    def t2_effective(self, esys: tuple = None, **kwargs) -> float: ...
231

232
class DephasingNoise(NoiseChannel): ...
233
class RelaxationNoise(NoiseChannel): ...
234
```
235

236
[Noise Analysis](./noise-analysis.md)
237

238
### Utility Functions
239

240
Essential utility functions for thermal calculations, spectrum analysis, and package information.
241

242
```python { .api }
243
def calc_therm_ratio(omega: float, T: float, omega_in_standard_units: bool = False) -> float: ...
244
def identity_wrap(operator, subsystem, subsys_index: int, op_in_eigenbasis: bool = False, evecs: np.ndarray = None) -> np.ndarray: ...
245
def about() -> None: ...
246
def cite() -> str: ...
247
```
248

249
## Types
250

251
```python { .api }
252
class Grid1d:
253
    """One-dimensional discretization grid for continuous variables."""
254
    def __init__(self, min_val: float, max_val: float, pt_count: int): ...
255
    @property
256
    def grid_spacing(self) -> float: ...
257
    def first_derivative_matrix(self, prefactor: float = 1.0, stencil: int = 3) -> csc_matrix: ...
258
    def second_derivative_matrix(self, prefactor: float = 1.0, stencil: int = 3) -> csc_matrix: ...
259

260
class DataStore:
261
    """Base class for storing and processing spectral data from parameter sweeps."""
262
    def __init__(self, system_params: dict = None): ...
263
    def write(self, filename: str) -> None: ...
264
    
265
class SpectrumData(DataStore):
266
    """Container for energy and state data as function of parameter values."""
267
    def __init__(self, energy_table: np.ndarray, system_params: dict = None, 
268
                 param_name: str = None, param_vals: np.ndarray = None): ...
269
    def plot_evals_vs_paramvals(self, **kwargs): ...
270
    
271
class Oscillator:
272
    """Harmonic oscillator for cavity modes."""
273
    def __init__(self, E_osc: float, truncated_dim: int): ...
274
    def creation_operator(self) -> np.ndarray: ...
275
    def annihilation_operator(self) -> np.ndarray: ...
276
    
277
class KerrOscillator:  
278
    """Kerr-nonlinear oscillator."""
279
    def __init__(self, E_osc: float, K: float, truncated_dim: int): ...
280

281
class WaveFunction:
282
    """Container for wavefunction data and visualization."""
283
    def __init__(self, basis_labels: np.ndarray, amplitudes: np.ndarray, energy: float = None): ...
284
    def rescale(self, scale_factor: float) -> None: ...
285
    
286
class GenericQubit:
287
    """Generic qubit interface for custom implementations."""
288
    def __init__(self, hilbert_space_dimension: int): ...
289
    def eigenvals(self, evals_count: int = 6) -> np.ndarray: ...
290
    def eigensys(self, evals_count: int = 6) -> tuple: ...
291
```