uniqc.circuit_builder.classical_program module

Classical / control-flow program tree for OriginIR-ext.

This module extends the flat opcode_list circuit representation with a structured program tree expressing mid-circuit measurement, a runtime classical-register (CREG) store, classical bit instructions, and classical control flow:

• GateOp — an ordinary gate / QRAM-call opcode (same tuple layout as uniqc.circuit_builder.qcircuit.OpcodeType).

• MeasureOp — MEASURE q[i], c[j]: measure one qubit and write its outcome into CREG bit j (valid both mid-circuit and terminally).

• ResetOp — RESET q[i]: mid-circuit reset of one qubit to |0>.

• ClassicalOp — a classical bit instruction AND/OR/XOR/MOV/NOT (RISC three-operand, destination-first, non-destructive; operands are CREG bits c[k] or immediates 0/1).

• IfBlock — QIF <cond> ... [QELSE ...] ENDQIF.

• WhileBlock — QWHILE <cond> ... ENDQWHILE (surface syntax carries no iteration bound; the simulator enforces an internal watchdog).

Conditions (Cond) are pure boolean logic over single-bit CREG cells: bit references c[i], the literals 0/1, the unary not/~ and the binary and/&, xor/^, or/| (lowercase keywords and symbols are interchangeable), with parentheses. A bare c[i] is true iff its bit is 1. Conditions are parsed by parse_cond() and re-serialized fully parenthesized with symbol operators for unambiguous round-tripping.

Circuit (see uniqc.circuit_builder.qcircuit) holds a structured program in Circuit.dynamic_program (None for ordinary flat circuits). This module owns serialization (serialize_program()), parsing (parse_program_body()), and a structural deep-copy helper (clone_program()).

class uniqc.circuit_builder.classical_program.BinCond(op, left, right)

Bases: Cond

A binary boolean op over single bits: and (&), xor (^), or (|).

evaluate(creg)

Evaluate against creg (a list of single-bit ints), returning 0/1.

left

op

right

to_str()

Serialize to a parseable, fully parenthesized string.

class uniqc.circuit_builder.classical_program.BitRef(index)

Bases: Cond

A reference to CREG bit c[index] (true iff the bit is 1).

evaluate(creg)

Evaluate against creg (a list of single-bit ints), returning 0/1.

index

to_str()

Serialize to a parseable, fully parenthesized string.

class uniqc.circuit_builder.classical_program.ClassicalOp(op, dest, srcs)

Bases: object

A classical bit instruction AND/OR/XOR/MOV/NOT writing CREG bit dest.

dest

evaluate(srcs)

Compute the destination bit value from already-read srcs (0/1).

execute(creg)

Read this instruction’s source operands from creg and return the resulting destination bit (0/1). Does not mutate creg.

op

srcs

class uniqc.circuit_builder.classical_program.Cond

Bases: object

Base class for classical condition AST nodes.

evaluate(creg)

Evaluate against creg (a list of single-bit ints), returning 0/1.

to_str()

Serialize to a parseable, fully parenthesized string.

class uniqc.circuit_builder.classical_program.ConstBit(value)

Bases: Cond

A constant bit literal (0 or 1).

evaluate(creg)

Evaluate against creg (a list of single-bit ints), returning 0/1.

to_str()

Serialize to a parseable, fully parenthesized string.

value

class uniqc.circuit_builder.classical_program.GateOp(opcode)

Bases: object

An ordinary gate or QRAM-call opcode within a program.

opcode

class uniqc.circuit_builder.classical_program.IfBlock(cond, then_body=<factory>, else_body=None)

Bases: object

QIF <cond> ... [QELSE ...] ENDQIF.

cond

else_body = None

then_body

class uniqc.circuit_builder.classical_program.MeasureOp(qubit, cbit)

Bases: object

MEASURE q[qubit], c[cbit] — measure qubit, write outcome to CREG cbit.

cbit

qubit

class uniqc.circuit_builder.classical_program.NotCond(operand)

Bases: Cond

Logical/bitwise NOT of a single-bit condition (~x / not x).

evaluate(creg)

Evaluate against creg (a list of single-bit ints), returning 0/1.

operand

to_str()

Serialize to a parseable, fully parenthesized string.

class uniqc.circuit_builder.classical_program.Operand(is_imm, value)

Bases: object

A classical-instruction source operand: a CREG bit or a 0/1 immediate.

is_imm

read(creg)

to_str()

value

class uniqc.circuit_builder.classical_program.ResetOp(qubit)

Bases: object

RESET q[qubit] — reset qubit to |0>.

qubit

class uniqc.circuit_builder.classical_program.WhileBlock(cond, body=<factory>, max_iterations=1000000)

Bases: object

QWHILE <cond> ... ENDQWHILE (internal watchdog max_iterations).

body

cond

max_iterations = 1000000

uniqc.circuit_builder.classical_program.clone_program(nodes)

Recursively clone a program body list.

Returns (new_list, list_map, node_map) where list_map maps id(old_list) -> new_list for every body list (top-level plus every nested if/while body) and node_map maps id(old_node) -> new_node for every IfBlock/WhileBlock. Leaf nodes are recreated as fresh value holders.

uniqc.circuit_builder.classical_program.contains_dynamic_keywords(originir_str)

Return True if originir_str uses the classical / control-flow extension.

Detects control-flow and classical-instruction keywords, and also mid-circuit measurement (a MEASURE line followed by any later gate / classical / control-flow statement — terminal-only measurement does not count).

uniqc.circuit_builder.classical_program.imm(value)

Construct an immediate 0/1 source operand for a classical instruction (e.g. circuit.c_xor(2, 0, imm(1)) for c[2] = c[0] ^ 1).

This disambiguates immediates from CREG bit indices, since a bare int passed to the Circuit.c_* builders denotes a CREG bit index c[int].

uniqc.circuit_builder.classical_program.parse_cond(text)

Parse a condition string into a Cond AST.

Accepts CREG bit references c[i], the literals 0/1, the unary not/~ and the binary and/&, xor/^, or/| (lowercase keywords and symbols interchangeable), with parentheses. Returns text unchanged if it is already a Cond.

uniqc.circuit_builder.classical_program.parse_operand(text)

Parse a single classical-instruction operand (c[k] or 0/1).

uniqc.circuit_builder.classical_program.parse_originir_ext_dynamic(originir_str)

Parse dynamic OriginIR-ext text into a Circuit.

The QRAMDECL/QINIT/CREG header is parsed via OriginIR_BaseParser; the body (gates, MEASURE/RESET, classical instructions, and QIF/QWHILE blocks) is parsed via parse_program_body() and replayed through the Circuit builder API.

Returns:

A new Circuit with its dynamic_program populated.

uniqc.circuit_builder.classical_program.parse_program_body(lines, start=0)

Parse a program body starting at lines[start].

Stops (without consuming) at a QELSE, ENDQIF, or ENDQWHILE line at this nesting level, or at end of input. Returns (body, next_index).

Ordinary gate / QRAM-call lines are parsed per-line via OriginIR_LineParser.parse_line. Block-form CONTROL/DAGGER regions are not supported inside a classical program body — use the inline dagger / controlled_by(...) suffixes instead.

uniqc.circuit_builder.classical_program.serialize_program(nodes)

Serialize a program body list to OriginIR-ext text lines.