cryowire 0.0.6

JSON Schema validation for cryowire configuration files

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

Command	Description
cryowire init [dir]	Initialize a new data project
cryowire new <cryo>	Create a new cooldown under <cryo>/<YYYY>/cdNNN/
cryowire build <dir>	Build cooldown.yaml, expand modules, generate diagram and README
cryowire validate <dir>	Validate YAML against schema and Pydantic models
cryowire diagram <dir>	Generate a wiring diagram (SVG/PNG)
cryowire summary <dir>	Print wiring summary table

Features

Module	Description
models	Pydantic v2 models (Stage, Component types, WiringConfig)
validate	JSON Schema validation against cryowire-spec
loader	YAML loading, module expansion, component catalog
builder	Programmatic cooldown generation from Python code
summary	Wiring summary tables (terminal, Markdown, HTML)
diagram	Publication-quality wiring diagrams (matplotlib)
cli	Command-line interface (init, new, build, validate, diagram, summary)

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

Class	Fields	Diagram Label	Example
Attenuator	value_dB	10 dB	Attenuator(model="XMA-10dB", value_dB=10)
Filter	filter_type	Lowpass / FLT	Filter(model="K&L", filter_type="Lowpass")
Isolator	—	ISO	Isolator(model="LNF-ISC4_12A")
Amplifier	amplifier_type, gain_dB	+40 dB	Amplifier(model="HEMT", gain_dB=40)

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:

Schema	Function	Validates
wiring.schema.json	validate_wiring()	control.yaml, readout_send.yaml, readout_return.yaml
metadata.schema.json	validate_metadata()	metadata.yaml
components.schema.json	validate_components()	components.yaml
chip.schema.json	validate_chip()	chip.yaml

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