# deteqt

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

## Documentation

- [Main website](https://deteqt-d9f77a.gitlab.io/)
- [Usage](https://deteqt-d9f77a.gitlab.io/usage/)
- [API reference](https://deteqt-d9f77a.gitlab.io/api/)

## Install

```zsh
# 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 for local development:

```zsh
uv pip install -e . --group all
```

## Configure settings

```python
from deteqt import write_settings_file

settings_path = write_settings_file(
    url="https://deteqt.duckdns.org",
    org="YOUR_ORG",
    bucket="YOUR_BUCKET",
    token="YOUR_WRITE_TOKEN",
)
print(settings_path)  # settings.toml
```

This creates `settings.toml` in your current working directory.

You can also create it manually:

```toml
url = "https://deteqt.duckdns.org"
org = "YOUR_ORG"
bucket = "YOUR_BUCKET"
token = "YOUR_WRITE_TOKEN"
```

## Write one point

```python
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={
        "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)

```python
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": {
                "area_of_interest": "sweetspot",
                "long_label": "Q1 frequency",
            },
            "extra_fields": {"temperature_mK": 12.3},
        },
        {
            "qoi": "phase",
            "nominal_value": 0.12,
            "run_ID": "run-001",
            "extra_tags": {
                "area_of_interest": "sweetspot",
                "long_label": "Q1 frequency",
            },
            "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`

Partner-specific keys `area_of_interest` and `long_label` are treated as
optional extra tags.
If your settings file is elsewhere, pass `settings_path=".../settings.toml"`.

## Recursive ingest/write (single mode)

```python
from deteqt import ingest_and_write

summary = ingest_and_write(folder="quantify-data")
print(summary)
```

The recursive path is JSON-only and always hybrid:

- values come from `quantities_of_interest*.json`
- metadata/tags come from `snapshot*.json`
- only standard SCQT transmon QoIs are kept

Supported analysis aliases are normalized to standard names (for example:
`T1 -> t1`, `Qi -> resonator_qi`, `Qc -> resonator_qc`, `fr -> resonator_freq_low` and
`resonator_freq_high`).
