cryowire

Python library and CLI for dilution refrigerator wiring configuration — data models, validation, diagram generation, and programmatic building.

Installation

pip install cryowire

CLI

Initialize a data project

cryowire init ./my-data
cd my-data

Generates .cryowire.yaml, components.yaml, and templates/ directory. Edit these to match your lab's components and standard wiring modules.

Create a new cooldown

cryowire new your-cryo --qubits 8 --chip-name "sample-8q"

Build & validate

cryowire build your-cryo/2026/cd001/     # cooldown.yaml, wiring.svg, README.md
cryowire validate your-cryo/2026/cd001/  # JSON Schema + Pydantic validation
cryowire diagram your-cryo/2026/cd001/   # wiring diagram only
cryowire summary your-cryo/2026/cd001/   # summary table

Commands

Features

Python API

Build a cooldown

from cryowire import (
    Amplifier, Attenuator, ChipConfig, CooldownBuilder,
    CooldownMetadata, Filter, Isolator, Stage,
)

# 1. Component catalog
catalog = {
    "XMA-10dB": Attenuator(model="XMA-2082-6431-10", value_dB=10),
    "XMA-20dB": Attenuator(model="XMA-2082-6431-20", value_dB=20),
    "Eccosorb": Filter(model="XMA-EF-03", filter_type="Eccosorb"),
    "K&L-LPF": Filter(model="K&L-5VLF", filter_type="Lowpass"),
    "RT-AMP": Amplifier(model="MITEQ-AFS3", amplifier_type="RT", gain_dB=20),
    "LNF-HEMT": Amplifier(model="LNF-LNC03_14A", amplifier_type="HEMT", gain_dB=40),
    "LNF-ISO": Isolator(model="LNF-ISC4_12A"),
}

# 2. Build cooldown (reference components by key)
cooldown = (
    CooldownBuilder(
        chip=ChipConfig(name="sample-8q", num_qubits=8, qubits_per_readout_line=4),
        metadata=CooldownMetadata(cryo="your-cryo", cooldown_id="cd001", date="2026-03-06"),
        catalog=catalog,
        control={
            Stage.K50: ["XMA-10dB"],
            Stage.K4: ["XMA-20dB"],
            Stage.MXC: ["XMA-20dB", "Eccosorb"],
        },
        readout_send={Stage.K50: ["XMA-10dB"], Stage.K4: ["XMA-10dB"]},
        readout_return={
            Stage.RT: ["RT-AMP"],
            Stage.K50: ["LNF-HEMT"],
            Stage.CP: ["LNF-ISO", "LNF-ISO"],
        },
    )
    .add("C00", Stage.STILL, "K&L-LPF")
    .remove("RR00", Stage.CP, index=1)
    .build()
)

# 3. Per-line overrides (context manager)
with cooldown.for_lines("C03", "C05") as lines:
    lines.remove(Stage.MXC, component_type=Filter)
    lines.replace(Stage.K4, 0, "XMA-10dB")

# Summary (terminal / markdown / html)
cooldown.summary()
md = cooldown.summary(fmt="markdown")

# Publication-quality SVG diagram
cooldown.diagram(output="wiring.svg", representative=True)

# Export YAML files
cooldown.write("output/")

Load & inspect an existing cooldown

from cryowire import load_cooldown, print_summary, generate_diagram

metadata, control, readout_send, readout_return = load_cooldown("path/to/cooldown")

print_summary(control, readout_send, readout_return)
generate_diagram(control, readout_send, readout_return, output="wiring.svg")

Template-based generation

from cryowire import build_cooldown

build_cooldown(
    output_dir="your-cryo/2026/cd001",
    cryo="your-cryo",
    chip_name="sample-chip",
    num_qubits=16,
)

Validate YAML files

from cryowire import validate_wiring, validate_metadata
import yaml

with open("control.yaml") as f:
    data = yaml.safe_load(f)

validate_wiring(data)      # raises jsonschema.ValidationError on failure
validate_metadata(meta)

Component Types

All components share model and serial fields, and expose label, summary_label, attenuation, gain properties.

Schemas

This package bundles JSON Schema files from cryowire-spec:

Documentation

Full documentation is available at cryowire.github.io/cryowire.

Examples

A Jupyter notebook tutorial is available in the examples/notebooks/ directory.

pip install cryowire jupyter
jupyter notebook examples/notebooks/tutorial.ipynb

The notebook covers builder usage, summary tables, SVG diagram rendering, and component add/remove/replace operations.

Try it online in the Playground — no installation required.

Development

uv sync
uv run pytest