How to Perform Unit Conversion for Hamiltonian Parameters (qubit_frequency_GHz, kappa_kHz, anharmonicity_MHz) in SQuADDS

SQuADDS stores Hamiltonian parameters in raw SI units (Hz) and automatically converts them to engineering units (GHz, kHz, MHz) using the _fix_cavity_claw_df() method in squadds/core/analysis.py alongside helper utilities in squadds/core/utils.py.

Working with superconducting qubit designs in the lfl-lab/squadds repository requires careful handling of frequency and energy units. The database stores physical parameters like qubit frequencies and cavity loss rates in base SI units (Hz), but analysis pipelines and user interfaces expect convenient engineering scales. This guide explains how SQuADDS handles unit conversion for Hamiltonian parameters including qubit_frequency_GHz, kappa_kHz, and anharmonicity_MHz.

Internal Storage vs. Display Units

SQuADDS follows a strict convention: all raw simulation data is stored in SI base units (Hz), while the analysis layer exposes engineering units for readability.

Parameter	Stored Unit	Display Unit	Conversion Factor
qubit_frequency	Hz	GHz	× 1e-9
kappa	Hz	kHz	× 1e-3
anharmonicity	Hz	MHz	× 1e-6

This conversion is handled automatically when loading data into the analysis pipeline.

Converting Simulation Data with _fix_cavity_claw_df

The primary conversion logic resides in squadds/core/analysis.py within the _fix_cavity_claw_df method. According to the lfl-lab/squadds source code, this function renames columns and applies scaling factors to convert raw Hz values to GHz and kHz.

# squadds/core/analysis.py (lines 191-199)

if ("cavity_frequency" in self.df.columns) or ("kappa" in self.df.columns):
    self.df = self.df.rename(columns={"cavity_frequency": "cavity_frequency_GHz",
                                     "kappa": "kappa_kHz"})
    self.df["cavity_frequency_GHz"] = self.df["cavity_frequency_GHz"] * 1e-9
    self.df["kappa_kHz"] = self.df["kappa_kHz"] * 1e-3

When you instantiate the Analysis class and call this method, your dataframe columns are automatically transformed from raw Hz to the labeled engineering units.

String and Float Utilities for UI Inputs

For user interface components that accept string inputs with units (e.g., "5.2GHz"), SQuADDS provides helper functions in squadds/core/utils.py. The float_to_string and string_to_float functions handle the conversion between numeric values and their string representations.

# squadds/core/utils.py (lines 18-30)

def float_to_string(value, units):
    """Convert a float to a string with units."""
    return f"{value}{units}"

def string_to_float(string):
    """Parse a number that ends with a two-character unit."""
    return float(string[:-2])

These utilities ensure that UI widgets in squadds/ui/app.py can accept human-readable inputs while the backend maintains numeric precision.

Energy-Based Conversions with pyEPR

Beyond frequency units, SQuADDS handles energy-to-inductance conversions using the pyEPR.calcs.Convert module. As implemented in lfl-lab/squadds, functions like Convert.Lj_from_Ej translate between Josephson energy (in GHz) and junction inductance (in nanohenries).

from pyEPR.calcs import Convert

# Convert Josephson energy to inductance

Lj = Convert.Lj_from_Ej(EJ, units_in="GHz", units_out="nH")

This conversion is utilized in squadds/calcs/transmon_cross.py and within the interpolation utilities at squadds/interpolations/utils.py (line 62) to maintain consistent physical units across the Hamiltonian parameter chain.

Practical Implementation Workflow

To perform unit conversion for Hamiltonian parameters in your own analysis pipeline, follow this pattern:

from squadds.core.analysis import Analysis
import pandas as pd

# Load raw simulation data (stored in Hz)

df = pd.read_parquet("simulation_results.parquet")

# Initialize the analysis helper

analysis = Analysis(df=df, selected_system="cavity_claw")

# Convert Hz to GHz/kHz and rename columns

analysis._fix_cavity_claw_df()

# Access converted values

print(analysis.df[["cavity_frequency_GHz", "kappa_kHz"]].head())

The resulting dataframe now contains cavity_frequency_GHz and kappa_kHz ready for plotting or UI display. To convert back to SI units for downstream physics solvers:

# Convert back to Hz for numerical simulations

analysis.df["cavity_frequency_Hz"] = analysis.df["cavity_frequency_GHz"] * 1e9
analysis.df["kappa_Hz"] = analysis.df["kappa_kHz"] * 1e3

Summary

• SQuADDS stores all Hamiltonian parameters in base SI units (Hz) internally to maintain precision and consistency across the database.
• The _fix_cavity_claw_df() method in squadds/core/analysis.py (lines 191-199) automatically converts these values to GHz and kHz for analysis and visualization.
• Helper functions float_to_string and string_to_float in squadds/core/utils.py (lines 18-30) bridge the gap between numeric code and string-based UI inputs.
• Energy-based conversions leverage pyEPR.calcs.Convert utilities, particularly for translating between Josephson energy (GHz) and junction inductance (nH) in transmon calculations.

Frequently Asked Questions

What base units does SQuADDS use for storing Hamiltonian parameters?

According to the lfl-lab/squadds source code, the database stores all frequency-related Hamiltonian parameters—including qubit frequencies, cavity kappa values, and anharmonicities—in raw SI units (Hz). This convention ensures consistency across different simulation backends and prevents unit mismatch errors during numerical computations.

How do I convert existing Hz-based data to GHz for SQuADDS analysis?

Import the Analysis class from squadds.core.analysis and invoke the _fix_cavity_claw_df() method after loading your dataframe. This method, located at lines 191-199 of squadds/core/analysis.py, multiplies cavity frequencies by 1e-9 to convert Hz to GHz and kappa values by 1e-3 to convert Hz to kHz, while renaming the columns to include the unit suffixes.

Does SQuADDS handle anharmonicity unit conversion automatically?

While the raw storage uses Hz, the transmon-cross Hamiltonian builder in squadds/calcs/transmon_cross.py expects anharmonicity in MHz as part of the standard scqubits model interface. The conversion factor of 1e-6 (Hz to MHz) is handled implicitly within the physics calculations, though you can apply it manually if working directly with the raw dataframe columns.

Where are the string-parsing utilities for unit conversion located?

The float_to_string and string_to_float helper functions are defined in squadds/core/utils.py at lines 18-30. These functions strip or append two-character unit suffixes (like "GHz" or "kHz") to enable seamless integration with Streamlit UI components in squadds/ui/app.py, allowing users to input values like "4.5GHz" while the backend receives the numeric value 4.5.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}