DeteQT project¶

Python client for DeteQT metrology and quantum-chip diagnostics on InfluxDB v2.

Quick setup¶

If uv is not installed yet on your machine, install it first:

Linux/macOS¶

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows¶

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install `deteqt`¶

# Create and activate a virtual environment:
uv venv deteqt-env --python 3.13  # any supported version >=3.12
source deteqt-env/bin/activate  # Linux/macOS
# .\deteqt-env\Scripts\activate  # Windows

# Install from PyPI:
uv pip install deteqt

# Verify:
uv run --active python -c "import deteqt; print(deteqt.__version__)"

If you cloned this repository (contributor / local dev), use uv sync instead. This installs the exact versions locked in uv.lock for fully reproducible results:

uv sync --all-groups

Logging¶

Add this once at the top of your script or notebook to see progress in your terminal:

import logging
logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")

Write one point (full schema)¶

from deteqt import TUID, write_point

run_tuid: TUID = TUID("20260213-143319-249-01d39d")

summary = write_point(
    {
        "qoi": "frequency",
        "nominal_value": 1.01,
        "uncertainty": 0.01,
        "tuid": run_tuid,
        "element": "q1",
        "label": "f01",
        "unit": "GHz",
        "element_label": "qubit-01",
        "device_ID": "chip-a",
        "run_ID": "run-001",
        "cycle_ID": "cycle-01",
        "condition": "4K",
        "extra_tags": {
            "sample_id": "S-42",
            "operator": "alice",
            "area_of_interest": "sweetspot",
            "long_label": "Q1 frequency",
        },
        "extra_fields": {"temperature_mK": 12.3, "passed_qc": True},
    }
)
print(
    summary
)  # {'records_total': 1, 'records_written': 1, 'records_failed': 0}

Write batch (with optional extras)¶

from deteqt import write_batch

summary = write_batch(
    [
        {
            "qoi": "frequency",
            "nominal_value": 1.01,
            "uncertainty": 0.01,
            "run_ID": "run-001",
            "cycle_ID": "cycle-01",
            "extra_tags": {"sample_id": "S-42"},
            "extra_fields": {"temperature_mK": 12.3},
        },
        {
            "qoi": "phase",
            "nominal_value": 0.12,
            "run_ID": "run-001",
            "extra_tags": {
                "sample_id": "S-42",
                "area_of_interest": "sweetspot",
            },
            "extra_fields": {"passed_qc": True},
        },
    ]
)

Common schema policy¶

Use these common keys across all integrations:

measurement: qoi
tags: element, label, unit, element_label, device_ID, run_ID, cycle_ID, condition
fields: nominal_value, uncertainty, tuid
optional timestamp key: time (RFC3339 string, datetime, or unix epoch)

Partner-specific keys area_of_interest and long_label are treated as optional extra tags.

Recursive ingest/write¶

Use ingest_data(...) or ingest_and_write(...) for recursive JSON ingest. This flow is single-mode hybrid ingest:

values come from quantities_of_interest*.json (plain .json)
metadata/tags come from snapshot*.json (commonly compressed in exports; supports .json.xz, .json.gz, .json.bz2, and plain .json)
only standard SCQT transmon QoIs are kept
folders named analysis_BasicAnalysis and .ipynb_checkpoints are ignored
if hybrid merge returns no records for a run, that run falls back to snapshot-only parsing

Next step¶

Usage: copy-paste patterns.
API Reference: concise function contracts.