Serialization: Save and Load Exact Programs

b01t provides four functions for serializing and deserializing ExactProgram values. The format is exact-oracle-v1 — a JSON schema that captures the full program structure including certification level, register layout, and every op. On deserialization, b01t re-validates the structural invariants, so a corrupted or tampered file is rejected rather than silently accepted.

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

exact_program_to_json

exact_program_to_json(prog: ExactProgram) -> str

Serializes an ExactProgram to a deterministic JSON string. Keys are sorted alphabetically and the output is indented with two spaces, making the format suitable for version control.

prog

ExactProgram

required

The exact program to serialize. Obtain one from .build_exact() on a @coherent or @primitive function.

Returns: a UTF-8 JSON string in exact-oracle-v1 format.

from b01t import coherent, QReg, h, cx, exact_program_to_json

@coherent
def bell(a: QReg, b: QReg) -> None:
    h(a[0])
    cx(a[0], b[0])

prog = bell.build_exact(("a", 1), ("b", 1))
json_str = exact_program_to_json(prog)
print(json_str)

exact_program_from_json

exact_program_from_json(s: str) -> ExactProgram

Deserializes an ExactProgram from a JSON string. Validates the format version, then re-checks all structural invariants before returning.

str

required

A JSON string previously produced by exact_program_to_json.

Returns: a fully validated ExactProgram. Raises: DSLValidationError if the format version is not exact-oracle-v1, or if any structural invariant is violated.

from b01t import exact_program_from_json

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

exact_program_to_dict

exact_program_to_dict(prog: ExactProgram) -> dict

Serializes an ExactProgram to a plain Python dict. Use this when you want to embed the program in a larger data structure (such as a registry entry) without converting to a string first.

prog

ExactProgram

required

The exact program to serialize.

Returns: a dict with the same structure as the JSON schema below.

from b01t import exact_program_to_dict

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

exact_program_from_dict

exact_program_from_dict(d: dict) -> ExactProgram

Deserializes an ExactProgram from a plain Python dict. Validates the format version and structural invariants.

dict

required

A dict previously produced by exact_program_to_dict, or parsed from a JSON file in exact-oracle-v1 format.

Returns: a fully validated ExactProgram. Raises: DSLValidationError if the format version is wrong or any invariant is violated.

from b01t import exact_program_from_dict

restored = exact_program_from_dict(d)

JSON schema

The exact-oracle-v1 format has the following top-level structure:

{
  "format": "exact-oracle-v1",
  "name": "bell",
  "certification": "safe",
  "regs": [
    { "name": "a", "size": 1, "kind": "sys" },
    { "name": "b", "size": 1, "kind": "sys" }
  ],
  "ops": [
    {
      "op": "gate",
      "gate": "H",
      "wires": [{ "reg": "a", "index": 0, "kind": "sys" }]
    },
    {
      "op": "gate",
      "gate": "CX",
      "wires": [
        { "reg": "a", "index": 0, "kind": "sys" },
        { "reg": "b", "index": 0, "kind": "sys" }
      ]
    }
  ]
}

Op types

Each entry in "ops" has an "op" field that is one of:

`"op"` value	Description
`"gate"`	A single gate application. Has `"gate"` (enum value) and `"wires"`.
`"ancilla"`	An ancilla block. Has `"ancilla"` (reg dict), `"compute"`, `"middle"`, `"middle_kind"`, `"uncompute"`.
`"par"`	Parallel composition. Has `"left"` and `"right"` (lists of ops).

Certification values

`"certification"`	Decorator
`"safe"`	`@coherent`
`"primitive"`	`@primitive`

Round-trip example

from b01t import (
    coherent, QReg, h, cx,
    exact_program_to_json,
    exact_program_from_json,
    Certification,
)

@coherent
def bell(a: QReg, b: QReg) -> None:
    h(a[0])
    cx(a[0], b[0])

# Build
original = bell.build_exact(("a", 1), ("b", 1))
assert original.certification == Certification.SAFE

# Serialize
json_str = exact_program_to_json(original)

# Deserialize and verify
restored = exact_program_from_json(json_str)
assert restored.name == original.name
assert restored.certification == original.certification
assert len(restored.regs) == len(original.regs)
assert len(restored.ops) == len(original.ops)

Saving to a file

import pathlib
from b01t import exact_program_to_json, exact_program_from_json

# Write
pathlib.Path("bell.json").write_text(exact_program_to_json(original))

# Read
text = pathlib.Path("bell.json").read_text()
restored = exact_program_from_json(text)

Decorators

Gates

Kit

Types

Serialization: Save and Load Exact Programs

exact_program_to_json

exact_program_from_json

exact_program_to_dict

exact_program_from_dict

JSON schema

Op types

Certification values

Round-trip example

Saving to a file

​exact_program_to_json

​exact_program_from_json

​exact_program_to_dict

​exact_program_from_dict

​JSON schema

​Op types

​Certification values

​Round-trip example

​Saving to a file

exact_program_to_json

exact_program_from_json

exact_program_to_dict

exact_program_from_dict

JSON schema

Op types

Certification values

Round-trip example

Saving to a file