QRAM YAML memory format

oracq.infrastructure.qram_schema

Parsing, loading and writing of QRAM memory definition files (*.qram.yaml).

class oracq.infrastructure.qram_schema.RegisteredQRAM(name, address_length, word_length, cells)

Bases: object

An immutable host-side memory snapshot, separate from its RIR declaration.

Registration allocates no native backend object. Unspecified cells contain zero, and snapshot returns a fresh mapping suitable for execution.

name

address_length

word_length

cells

property type

RIR resource type, retaining both declared bit widths.

snapshot()

Copy the registered words; missing addresses read as zero.

database()

Build an XOR query oracle with this bank’s resource name.

oracq.infrastructure.qram_schema.register_qram(data, address_length, word_length, *, name=None)

Snapshot unsigned QRAM words without creating a backend dependency.

A sequence uses its indices as addresses; a mapping may be sparse. The default name is derived from the widths and contents. Explicit names must identify the same contents when multiple inputs share a bank.

class oracq.infrastructure.qram_schema.QramSegment(name, address_length, word_length, type, data)

Bases: object

One segment in a qram YAML file.

Variables:

• name (str) – storage name, indexed by entry resource name at execution time.

• address_length (int) – address bit width, 1..64, corresponding to the RIR QRAM address_width.

• word_length (int) – data word bit width, 1..64, corresponding to the RIR QRAM data_width.

• type (str) – data type, see QRAM_DATA_TYPES; data is interpreted under this type.

• data (tuple[int, ...] | tuple[float, ...]) – dense source data array with the index as the address; cells above it are zero-padded when shorter than 2^address_length.

name

address_length

word_length

type

data

oracq.infrastructure.qram_schema.parse_qram_yaml(document)

Parse and validate one qram YAML memory definition text.

Parameters:

document – YAML text whose top level contains only the qram_segments list.

Returns:

segment tuple in order of appearance in the file; data keeps the source values, interpreted per type.

Return type:

tuple

Raises:

ValidationError – the text is not valid YAML, the structure does not match, a segment name is missing or duplicated, a bit width is out of range, the data type is unsupported, or the source data falls outside the range set by type and word_length.

oracq.infrastructure.qram_schema.load_qram_yaml(path)

Load a qram YAML memory definition file into the memory mapping accepted by executors.

Source data is encoded per segment type into unsigned words (sint takes the two’s-complement bit pattern, fixedpoint multiplies by 2^word_length then truncates toward zero) and zero-padded to 2^address_length length; the resource name set and data ranges are cross-checked against program declarations by check_memory at execution time.

Parameters:

path – YAML file path.

Returns:

mapping from resource names to dense word arrays, the same shape as the memory parameter of execution entry points such as simulate.

Return type:

dict

oracq.infrastructure.qram_schema.dump_qram_yaml(program, memory)

Write the entry’s QRAM binding data as qram YAML text.

The data is first normalized and cross-checked by check_memory (sparse dicts densified, with zero cells and missing high cells both treated as zero), then segments are generated in entry resource declaration order; on the executor side the words are already unsigned integers within the bit width, so the segment type is always uint; the dense array avoids the string-key ambiguity of sparse dicts.

Parameters:

• program – closed RIR program providing resource name and bit width declarations.

• memory – data provided by resource name; each item is a word sequence or a sparse address -> word dict, and None is treated as all zeros. The resource set must exactly match the entry declaration.

Returns:

qram YAML text, written to disk or hashed by the caller.

Return type:

str