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

> Learn how to convert Hamiltonian parameters like qubit_frequency_GHz, kappa_kHz, and anharmonicity_MHz in SQuADDS. Discover automatic unit handling for your quantum simulations.

- Repository: [Levenson-Falk Lab/squadds](https://github.com/lfl-lab/squadds)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/analysis.py) alongside helper utilities in [`squadds/core/utils.py`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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.

```python

# 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`](https://github.com/lfl-lab/squadds/blob/main/squadds/core/utils.py). The `float_to_string` and `string_to_float` functions handle the conversion between numeric values and their string representations.

```python

# 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`](https://github.com/lfl-lab/squadds/blob/main/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).

```python
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`](https://github.com/lfl-lab/squadds/blob/main/squadds/calcs/transmon_cross.py) and within the interpolation utilities at [`squadds/interpolations/utils.py`](https://github.com/lfl-lab/squadds/blob/main/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:

```python
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:

```python

# 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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/squadds/ui/app.py), allowing users to input values like "4.5GHz" while the backend receives the numeric value 4.5.