QRAM memory definition (qram YAML)¶

English · 简体中文

Memory data is not written into the program serialization text (see RIR); it is bound separately as an execution input. This document defines the format of the binding file *.qram.yaml: one file describes a set of QRAM segments (the qram_segments list), cross-checked against the program by entry resource name at execution time.

qram_segments:
  - name: values            # storage name, indexed by this name in code
    address_length: 2       # address bit width
    word_length: 3          # data word bit width
    type: uint              # data type: uint / sint / fixedpoint
    data: [1, 2, 4, 7]      # concrete data, dense array, index is the address

Fields¶

field	type	constraint	description
`qram_segments`	list	required, sole top-level key	a set of QRAM definitions
`name`	string	non-empty, unique within the file	storage name; matched exactly against entry resource names at execution
`address_length`	integer	1..64	address bit width; corresponds to `address_width` of the RIR QRAM
`word_length`	integer	1..64	data word bit width; corresponds to `data_width` of the RIR QRAM
`type`	string	`uint` / `sint` / `fixedpoint`	source data type of `data`; encoded as an unsigned word on load
`data`	array	see the table below	dense source data array; the index is the address

Value ranges and encodings of the three data types:

type	data element range	encoded on load as an unsigned word
`uint`	unsigned integer, 0 .. 2^`word_length` − 1	unchanged
`sint`	signed integer, −2^(`word_length`−1) .. 2^(`word_length`−1) − 1	two’s-complement bit pattern
`fixedpoint`	fixed-point number in [0, 1)	multiplied by 2^`word_length` then truncated toward zero (same convention as `FixedFormat.encode`)

Semantic rules¶

At load time each source datum is validated locally against word_length (ranges in the table above); an out-of-range value is an error. The length of data must not exceed 2^address_length; when shorter, high-address cells are zero-padded (padding).
Segment names must be unique within the file.
At execution time the QRAM declarations inside the program are authoritative: check_memory requires the segment resource-name set to match the entry declarations exactly, no more and no less; encoded words must fall within the program-declared bit widths, and an address_length/word_length disagreeing with the program declaration is not reported as a separate error.
Segments produced by dump_qram_yaml always have type uint (the executor-side words are already unsigned integers within the declared bit width).

Python API¶

from oracq import dump_qram_yaml, load_qram_yaml, simulate

memory = load_qram_yaml("memory.qram.yaml")  # -> {"values": [1, 2, 4, 7]}
state = simulate(program, memory)             # fully compatible with the existing memory argument

text = dump_qram_yaml(program, memory)        # emits text after canonical validation; the caller writes it to disk

load_qram_yaml returns a mapping from resource names to dense word arrays (already encoded per type and zero-padded to full length), shaped like the memory parameter of simulate, run_pysparq, and run_originir. dump_qram_yaml first cross-validates through check_memory and densifies the sparse dictionary, then emits segments in the order of the entry’s resource declarations; when the entry declares no QRAM resource it emits an empty qram_segments.

CLI¶

oracq run closed.rir.yaml --memory memory.qram.yaml

--memory accepts only this format. When the structure or data is invalid it reports a Chinese-language error with exit code 2 and never truncates silently. See Command line for all subcommands.

Schema¶

The structural constraints are in qram-memory.schema.json, including the data element type constraints branched on type. Cross-field constraints (array length versus address_length, word value range versus word_length and type, segment-name uniqueness) cannot be expressed in JSON Schema and are enforced by the Python loader.