or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

circuit-analysis.mdcomposite-systems.mdfile-io.mdindex.mdnoise-analysis.mdparameter-sweeps.mdqubit-models.mdspectrum-analysis.mdunits-settings.md
tile.json

tessl/pypi-scqubits

Python library for simulating superconducting qubits with energy spectra, plotting, and QuTiP integration

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/scqubits@4.3.x

To install, run

npx @tessl/cli install tessl/pypi-scqubits@4.3.0

index.mddocs/

Scqubits

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.

Package Information

  • Package Name: scqubits
  • Language: Python
  • Installation: pip install scqubits or conda install -c conda-forge scqubits

Core Imports

import scqubits as scq

For specific components:

from scqubits import Transmon, Fluxonium, HilbertSpace, ParameterSweep
from scqubits import Grid1d, DataStore, SpectrumData, GenericQubit, Cos2PhiQubit, TunableTransmon
from scqubits.utils.spectrum_utils import matrix_element, get_matrixelement_table, identity_wrap
from scqubits.core.units import get_units, set_units
from scqubits.core.noise import calc_therm_ratio
from scqubits.utils.misc import about, cite

Basic Usage

import scqubits as scq
import numpy as np

# Create a transmon qubit
transmon = scq.Transmon(
    EJ=25.0,        # Josephson energy in GHz
    EC=0.2,         # Charging energy in GHz  
    ng=0.0,         # Offset charge
    ncut=30         # Charge basis cutoff
)

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

# Plot energy levels vs external parameter
ng_vals = np.linspace(-2, 2, 100)
transmon.plot_evals_vs_paramvals(
    param_name='ng',
    param_vals=ng_vals,
    evals_count=4
)

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

# Add interaction
g_strength = 0.1  # coupling strength in GHz
hilbert_space.add_interaction(
    g_strength=g_strength,
    op1=transmon.n_operator,
    op2=oscillator.creation_operator + oscillator.annihilation_operator
)

# Calculate dressed spectrum
evals = hilbert_space.eigenvals(evals_count=10)

Architecture

Scqubits follows a modular architecture organized around quantum system classes:

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

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

Capabilities

Superconducting Qubit Models

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.

class Transmon:
    def __init__(self, EJ: float, EC: float, ng: float = 0.0, ncut: int = 30, truncated_dim: int = None): ...
    def eigenvals(self, evals_count: int = 6) -> np.ndarray: ...
    def eigensys(self, evals_count: int = 6) -> tuple: ...
    def hamiltonian(self) -> np.ndarray: ...

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

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

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

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

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

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

class GenericQubit:
    def __init__(self, hilbert_space_dimension: int, hamiltonian_func: callable = None): ...

Qubit Models

Composite Quantum Systems

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

class HilbertSpace:
    def __init__(self, subsystem_list: list = None): ...
    def add_system(self, subsystem) -> int: ...
    def add_interaction(self, g_strength: float, op1, op2, subsys1: int = None, subsys2: int = None): ...
    def eigenvals(self, evals_count: int = 6) -> np.ndarray: ...
    def eigensys(self, evals_count: int = 6) -> tuple: ...

class InteractionTerm:
    def __init__(self, g_strength: float, op1, op2, subsys1: int, subsys2: int): ...

Composite Systems

Parameter Sweeps and Analysis

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

class ParameterSweep:
    def __init__(self, hilbert_space: HilbertSpace, paramvals_by_name: dict, evals_count: int = 6,
                 subsys_update_list: list = None, update_hilbert_space=None, num_cpus: int = None): ...
    def run(self) -> None: ...
    def plot_evals_vs_paramvals(self, which: int = -1, **kwargs): ...
    def transitions(self, initial_state_ind: int, final_state_ind: int) -> np.ndarray: ...

Parameter Sweeps

Spectrum Analysis and Matrix Elements

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

def matrix_element(state1: np.ndarray, operator: np.ndarray, state2: np.ndarray) -> complex: ...
def get_matrixelement_table(qubit_system, operator, evecs: np.ndarray = None, evals_count: int = None) -> np.ndarray: ...
def absorption_spectrum(transitions: dict, initial_state_labels: list, lineshape_func, **kwargs) -> tuple: ...
def emission_spectrum(transitions: dict, initial_state_labels: list, lineshape_func, **kwargs) -> tuple: ...

Spectrum Analysis

File I/O and Data Management

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

def read(filename: str) -> object: ...
def write(obj: object, filename: str, file_handle=None, overwrite: bool = False) -> None: ...

class SpectrumData:
    def __init__(self, energy_table: np.ndarray, system_params: dict = None, state_table: np.ndarray = None): ...
    
class DataStore:
    def __init__(self, system_params: dict = None): ...

File I/O

Units and Settings

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

def get_units() -> str: ...
def set_units(units: str) -> None: ...
def show_supported_units() -> None: ...
def to_standard_units(value: float) -> float: ...
def from_standard_units(value: float) -> float: ...

Units and Settings

Circuit Analysis

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

class Circuit:
    def __init__(self, input_string: str, from_file: bool = False, ext_basis: str = None, 
                 initiate_sym_calc: bool = True, truncated_dim: int = None): ...
    def hamiltonian(self) -> np.ndarray: ...
    def eigenvals(self, evals_count: int = 6) -> np.ndarray: ...

class SymbolicCircuit:
    def __init__(self, nodes_dict: dict, branches_dict: dict, initiate: bool = True): ...

Circuit Analysis

Noise Analysis

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

def calc_therm_ratio(omega: float, T: float, omega_in_standard_units: bool = False) -> float: ...

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

class DephasingNoise(NoiseChannel): ...
class RelaxationNoise(NoiseChannel): ...

Noise Analysis

Utility Functions

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

def calc_therm_ratio(omega: float, T: float, omega_in_standard_units: bool = False) -> float: ...
def identity_wrap(operator, subsystem, subsys_index: int, op_in_eigenbasis: bool = False, evecs: np.ndarray = None) -> np.ndarray: ...
def about() -> None: ...
def cite() -> str: ...

Types

class Grid1d:
    """One-dimensional discretization grid for continuous variables."""
    def __init__(self, min_val: float, max_val: float, pt_count: int): ...
    @property
    def grid_spacing(self) -> float: ...
    def first_derivative_matrix(self, prefactor: float = 1.0, stencil: int = 3) -> csc_matrix: ...
    def second_derivative_matrix(self, prefactor: float = 1.0, stencil: int = 3) -> csc_matrix: ...

class DataStore:
    """Base class for storing and processing spectral data from parameter sweeps."""
    def __init__(self, system_params: dict = None): ...
    def write(self, filename: str) -> None: ...
    
class SpectrumData(DataStore):
    """Container for energy and state data as function of parameter values."""
    def __init__(self, energy_table: np.ndarray, system_params: dict = None, 
                 param_name: str = None, param_vals: np.ndarray = None): ...
    def plot_evals_vs_paramvals(self, **kwargs): ...
    
class Oscillator:
    """Harmonic oscillator for cavity modes."""
    def __init__(self, E_osc: float, truncated_dim: int): ...
    def creation_operator(self) -> np.ndarray: ...
    def annihilation_operator(self) -> np.ndarray: ...
    
class KerrOscillator:  
    """Kerr-nonlinear oscillator."""
    def __init__(self, E_osc: float, K: float, truncated_dim: int): ...

class WaveFunction:
    """Container for wavefunction data and visualization."""
    def __init__(self, basis_labels: np.ndarray, amplitudes: np.ndarray, energy: float = None): ...
    def rescale(self, scale_factor: float) -> None: ...
    
class GenericQubit:
    """Generic qubit interface for custom implementations."""
    def __init__(self, hilbert_space_dimension: int): ...
    def eigenvals(self, evals_count: int = 6) -> np.ndarray: ...
    def eigensys(self, evals_count: int = 6) -> tuple: ...