Serializing and Loading Quantum Programs

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:

from b01t import (
    exact_program_to_json,
    exact_program_from_json,
    exact_program_to_dict,
    exact_program_from_dict,
)

To JSON

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:

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:

{
  "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

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

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

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.

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:

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.

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.

Get Started

Core Concepts

Guides

Algorithm Zoo

Serializing and Loading Quantum Programs

Serializing an ExactProgram

To JSON

To dict

The JSON format

Deserializing

From JSON

From dict

Round-trip example

Managing collections with PackageRegistry

​Serializing an ExactProgram

​To JSON

​To dict

​The JSON format

​Deserializing

​From JSON

​From dict

​Round-trip example

​Managing collections with PackageRegistry

Serializing an ExactProgram

To JSON

To dict

The JSON format

Deserializing

From JSON

From dict

Round-trip example

Managing collections with PackageRegistry