> ## Documentation Index
> Fetch the complete documentation index at: https://b01t.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Serializing and Loading Quantum Programs

> Save ExactProgram values to JSON or dict, reload them with full structural validation, and manage collections of programs with PackageRegistry.

Once you have built and certified an `ExactProgram`, you can serialize it to JSON for storage, transmission, or caching. b01t includes a round-trip serialization format called `exact-oracle-v1` that captures the full program structure — registers, operations, ancilla discipline, and certification level — and re-validates all structural invariants on load.

## Serializing an ExactProgram

Import the serialization functions from `b01t`:

```python theme={null}
from b01t import (
    exact_program_to_json,
    exact_program_from_json,
    exact_program_to_dict,
    exact_program_from_dict,
)
```

### To JSON

```python theme={null}
from b01t import coherent, QReg, cx, z, Certification
from b01t import ancilla, compute, phase, uncompute
from b01t import exact_program_to_json

@coherent
def oracle(sys: QReg):
    with ancilla(1) as anc:
        compute(lambda: cx(sys[0], anc[0]))
        phase(lambda: z(anc[0]))
        uncompute()

prog = oracle.build_exact(("sys", 1))
json_str = exact_program_to_json(prog)
print(json_str)
```

`exact_program_to_json()` returns a deterministic, sorted-key JSON string. The output is always consistent for the same program.

### To dict

If you need to embed the program data in a larger JSON object or manipulate it as a Python dictionary:

```python theme={null}
from b01t import exact_program_to_dict

data = exact_program_to_dict(prog)
print(data["format"])   # "exact-oracle-v1"
print(data["name"])     # "oracle"
print(data["certification"])  # "safe"
```

## The JSON format

The serialized format uses the tag `"exact-oracle-v1"` in the `"format"` field. Here is an example of what the JSON looks like for the single-qubit oracle above:

```json theme={null}
{
  "certification": "safe",
  "format": "exact-oracle-v1",
  "name": "oracle",
  "ops": [
    {
      "ancilla": {
        "kind": "anc",
        "name": "anc0",
        "size": 1
      },
      "compute": [
        {
          "gate": "CX",
          "op": "gate",
          "wires": [
            {"index": 0, "kind": "sys", "reg": "sys"},
            {"index": 0, "kind": "anc", "reg": "anc0"}
          ]
        }
      ],
      "middle": [
        {
          "gate": "Z",
          "op": "gate",
          "wires": [{"index": 0, "kind": "anc", "reg": "anc0"}]
        }
      ],
      "middle_kind": "phase",
      "op": "ancilla",
      "uncompute": [
        {
          "gate": "CX",
          "op": "gate",
          "wires": [
            {"index": 0, "kind": "sys", "reg": "sys"},
            {"index": 0, "kind": "anc", "reg": "anc0"}
          ]
        }
      ]
    }
  ],
  "regs": [
    {"kind": "sys", "name": "sys", "size": 1},
    {"kind": "anc", "name": "anc0", "size": 1}
  ]
}
```

Each operation is tagged with `"op"`: `"gate"` for a single gate, `"ancilla"` for an ancilla block, and `"par"` for parallel composition. Ancilla blocks include the `"middle_kind"` field — either `"phase"` for the CPU pattern or `"apply"` for the CMA pattern.

## Deserializing

### From JSON

```python theme={null}
from b01t import exact_program_from_json

restored = exact_program_from_json(json_str)
print(restored.name)           # "oracle"
print(restored.certification)  # Certification.SAFE
```

### From dict

```python theme={null}
from b01t import exact_program_from_dict

restored = exact_program_from_dict(data)
```

Deserialization validates the `"format"` field. If it is missing or wrong, a `DSLValidationError` is raised:

```
DSLValidationError: unsupported exact oracle format: 'my-format' (expected 'exact-oracle-v1')
```

All structural invariants — wire declarations, ancilla discipline, gate classifications — are re-checked on load. A program that was safe when serialized is safe when restored.

## Round-trip example

```python theme={null}
from b01t import coherent, QReg, cx, z, Certification
from b01t import ancilla, compute, phase, uncompute
from b01t import exact_program_to_json, exact_program_from_json

@coherent
def oracle(sys: QReg):
    with ancilla(1) as anc:
        compute(lambda: cx(sys[0], anc[0]))
        phase(lambda: z(anc[0]))
        uncompute()

# Build
prog = oracle.build_exact(("sys", 1))
assert prog.certification == Certification.SAFE

# Serialize
json_str = exact_program_to_json(prog)

# Deserialize
restored = exact_program_from_json(json_str)

# Verify
assert restored.name == prog.name
assert restored.certification == prog.certification
assert len(restored.ops) == len(prog.ops)
```

## Managing collections with PackageRegistry

`PackageRegistry` lets you publish, save, and load a collection of programs. Each entry is a `PackageMeta` that holds a program alongside metadata like tags, version, and documentation.

```python theme={null}
from b01t import PackageRegistry, PackageMeta, Certification
from b01t import coherent, QReg, cx, z
from b01t import ancilla, compute, phase, uncompute

registry = PackageRegistry()

# Build a program
@coherent
def oracle(sys: QReg):
    with ancilla(1) as anc:
        compute(lambda: cx(sys[0], anc[0]))
        phase(lambda: z(anc[0]))
        uncompute()

prog = oracle.build_exact(("sys", 1))

# Publish it to the registry
registry.publish(PackageMeta(
    name="oracle",
    effect="coherent",
    safe=True,
    tags=["oracle", "phase"],
    docs="Single-qubit phase oracle.",
    inputs=[("sys", 1)],
    exact_program=prog,
))

# Save the entire registry to a file
registry.save("my_programs.json")
```

Load the registry back later:

```python theme={null}
registry2 = PackageRegistry()
registry2.load("my_programs.json")

meta = registry2.get("oracle")
print(meta.exact_program.certification)  # Certification.SAFE
```

The saved file is a JSON array. Each entry that has an `exact_program` includes it under the `"exact_oracle"` key in `exact-oracle-v1` format, with full structural validation on load.

<Tip>
  Use `registry.find_by_tag("oracle")` to retrieve all programs with a particular tag. This is useful when you have a collection of related circuits and want to filter by purpose.
</Tip>