qamomile.circuit.transpiler

Compile prepared Qamomile semantics through explicit target pipelines.

Design center¶

The stable user workflow remains circuit-first: an engine Transpiler accepts a qkernel, preserves compile-time bindings and runtime parameters, and returns an ExecutableProgram. Internally, compilation now separates frontend preparation from target lowering so circuit SDKs and program-graph targets do not have to pretend to consume the same abstraction.

Shared preparation¶

QamomileCompiler.prepare() performs the target-independent prefix:

::

QKernelLike
   │  trace + validate entrypoint
   │  substitute configured callables
   │  resolve parameter-array shapes
   ▼
PreparedModule
   ├─ hierarchical semantic entrypoint
   ├─ reachable callable definitions
   ├─ call graph
   └─ public classical ABI

PreparedModule deliberately preserves structured control flow and callable boundaries. It is the last representation shared by every target family.

Target families¶

Circuit-family SDKs such as Qiskit, QURI Parts, CUDA-Q, and PyQret retain the existing Transpiler execution UX and take the host-orchestrated path:

::

PreparedModule
   │  inline + recursion unroll + affine/borrow validation
   │  partial evaluation + classical lowering + shape validation
   │  segment into C → Q → C
   ▼
ProgramPlan
   │  lower quantum segments once
   ▼
CircuitProgram                (immutable engine-neutral codegen IR)
   │  verify ordered linear wires, regions, calls, and expressions
   │  legalize + verify target capability declarations
   │  materialize native SDK objects
   ▼
ExecutableProgram[ArtifactT]  (sampling/expectation orchestration)

Program-graph targets such as HUGR compile the preserved program structure directly instead of passing through circuit segmentation:

::

PreparedModule
   │  CompilationTarget.plan()
   │  CompilationTarget.compile()
   │  CompilationTarget.validate()
   ▼
CompiledProgram[ArtifactT]    (artifact + ABI + diagnostics + metadata)

The two results are intentionally different. ExecutableProgram represents Qamomile’s host-driven execution model; CompiledProgram packages a native module or graph whose runtime model belongs to the target.

Program-graph executables reuse the shared jobs, execution handles, capabilities, and public ABI exported by this facade. Targets retain control of native execution while presenting the same result and lifecycle contracts.

Design principles¶

• Keep semantic IR abstract and lower late. Per-qubit encoding, native gate selection, transformed-call expansion, and runtime control-flow syntax are target concerns. Segmentation lowers semantics only when separating host and quantum execution requires it.

• Use an immutable circuit boundary. Circuit engines consume verified CircuitProgram values rather than walking mutable semantic IR or sharing engine objects through emit-context side channels. The current semantic-to-circuit implementation reuses the established walk internally, but that walker is not an engine extension API.

• Make target pipelines explicit. A CompilationTarget owns planning, lowering/materialization, and native validation. Circuit targets declare the complete input language accepted by their materializer; shared legalization fixes realization choices and target verification enforces that declaration before native object construction begins.

• Preserve dependency direction. This package and qamomile.circuit do not import SDK engines. Engine packages depend on the public compiler, circuit-IR, executable, and artifact contracts.

• Keep bindings and parameters disjoint. Bindings determine compile-time values and structure; parameters survive as runtime artifact inputs. Overlap is rejected before compilation, and structural decisions such as classical-value branches and range bounds must use bindings.

• Keep the common user surface small. Engine users normally interact with an engine Transpiler and executor. Materializers, source writers, and engine artifact wrappers are implementation details unless a target exposes a distinct native compilation product intentionally.

Overview¶

Constants¶

• EstimationAccuracy: TypeAlias = Exact | ShotBased | TargetPrecision

• TranspilerConfig = CompilerConfig Backward name for :class:CompilerConfig during engine migration.

Functions¶

aggregate_typed_results [source]¶

def aggregate_typed_results(results: Iterable[tuple[T, int]]) -> list[tuple[T, int]]

Combine counts whose converted public result values are equal.

Engine raw bitstrings can differ only on qubits that are not part of the program output. After result conversion those rows represent the same public value and must appear as one SampleResult entry.

Parameters:

Returns:

list[tuple[T, int]] — list[tuple[T, int]]: Stable first-seen values with duplicate counts summed.

dict_param_key [source]¶

def dict_param_key(dict_name: str, key: Any) -> str

Format the engine-parameter name for one entry of a Dict parameter.

The key is formatted with repr rather than str so the helper is collision-proof on its own: str("0") and str(0) both yield "coeffs[0]", but repr keeps the string key distinct ("coeffs['0']"). Callers pass keys already normalized to plain int / tuple-of-int (see :func:normalize_dict_binding_key), for which repr and str produce identical text (repr(3) == '3', repr((0, 1)) == '(0, 1)'), so the emitted names are unchanged.

Parameters:

Returns:

str — The engine parameter name, e.g. "coeffs[3]" for an int key or "coeffs[(0, 1)]" for a tuple key.

flatten_user_bindings [source]¶

def flatten_user_bindings(bindings: Mapping[str, Any] | None) -> dict[str, Any]

Flatten public arrays and dictionaries into scalar ABI keys.

Parameters:

Returns:

dict[str, Any] — dict[str, Any]: Scalar and dictionary entries keyed by emitted ABI names.

inline_callables [source]¶

def inline_callables(
    block: Block,
    *,
    body_selector: Callable[[InvokeOperation], Block | None] | None = None,
) -> Block

Expand inline-policy callables once with the compiler’s default policy.

Boxed calls, transformed calls, and recursive calls that remain after one pass are preserved. Direct program-graph targets use this narrow helper at target legalization boundaries without depending on the configurable compiler pass implementation.

Parameters:

Returns:

Block — Block after one default callable-inlining pass.

Raises:

• QubitConsumedError — If an invocation binds the same quantum resource to multiple formal operands.

lower_compile_time_ifs_preserving_loop_conditions [source]¶

def lower_compile_time_ifs_preserving_loop_conditions(block: Block, bindings: dict[str, Any] | None = None) -> Block

Specialize compile-time branches without erasing loop conditions.

Parameters:

Returns:

Block — Specialized block with loop-carried conditions preserved.

Raises:

• ValidationError — If specialization encounters invalid IR.

pair_block_operands [source]¶

def pair_block_operands(
    block: Block,
    operands: Sequence[ValueBase],
) -> list[tuple[ValueBase, ValueBase]]

Pair all block inputs with category-grouped call-site operands.

Parameters:

Returns:

list[tuple[ValueBase, ValueBase]] — list[tuple[ValueBase, ValueBase]]: Formal/actual pairs in the block’s list[tuple[ValueBase, ValueBase]] — declaration order.

prepare_module [source]¶

def prepare_module(entrypoint: Block, bindings: Mapping[str, Any] | None = None) -> PreparedModule

Collect a hierarchical block into an immutable program-level view.

The collector follows calls in nested control-flow regions, SELECT case Blocks, and every body carried by a callable definition. Definitions remain Qamomile semantic IR; this function does not inline, clone, or lower operations.

Parameters:

Returns:

PreparedModule — Entrypoint, reachable definitions, call graph, and public ABI. :class:QamomileCompiler creates a deep target-owned snapshot before invoking a target pipeline.

validate_program_graph_semantics [source]¶

def validate_program_graph_semantics(program: PreparedModule) -> None

Validate shared semantics for a direct program-graph target.

Circuit-family planning runs these checks during partial evaluation, analysis, and segmentation. A direct program-graph target preserves the prepared structure, so this helper runs only the non-destructive semantic checks. Inline-policy callables are expanded in the validation view so their formal values retain call-site provenance; the prepared program itself remains hierarchical.

Parameters:

Raises:

• ValidationError — If a while condition is not measurement-backed.

• AffineTypeError — If structured control flow discards a quantum value.

• QubitConsumedError — If callable inlining binds one quantum resource to multiple formal operands.

Classes¶

CallableDefinitionConflictError [source]¶

class CallableDefinitionConflictError(QamomileCompileError)

Report two incompatible definitions claiming one callable symbol.

Parameters:

Example:

Correct — give independently implemented callables distinct origins
or explicit namespaces::

    configure_composite(left, namespace="example.left")
    configure_composite(right, namespace="example.right")

Incorrect — attaching two different bodies to the same explicit
symbol causes this error during preparation::

    configure_composite(left, namespace="example.shared", name="op")
    configure_composite(right, namespace="example.shared", name="op")

Constructor¶

def __init__(self, symbol: str) -> None

Initialize a callable-definition collision diagnosis.

Parameters:

Attributes¶

• symbol: str

ClassicalExecutor [source]¶

class ClassicalExecutor

Executes classical segments in Python.

Methods¶

execute¶

def execute(self, segment: ClassicalSegment, context: ExecutionContext) -> dict[str, Any]

Execute classical operations and return outputs.

Interprets the operations list directly using Python.

Parameters:

Returns:

dict[str, Any] — dict[str, Any]: Computed classical values keyed by result UUID.

Raises:

• ExecutionError — If an operation is unsupported or a required runtime value is unavailable.

resolve_value¶

def resolve_value(self, value: ValueLike, context: ExecutionContext) -> Any

Resolve a typed classical output using the execution interpreter.

Parameters:

Returns:

Any — Concrete value with tuple and dictionary structure retained.

Raises:

• ExecutionError — If a required value is absent from the context and its compile-time metadata.

ClassicalSegment [source]¶

class ClassicalSegment(Segment)

A segment of pure classical operations.

Contains arithmetic, comparisons, and control flow. Will be executed directly in Python.

Constructor¶

def __init__(
    self,
    operations: list[Operation] = list(),
    input_refs: list[str] = list(),
    output_refs: list[str] = list(),
) -> None

Attributes¶

• kind: SegmentKind

CompilationDiagnostic [source]¶

class CompilationDiagnostic

Describe one target-independent or target-specific diagnostic.

Parameters:

Constructor¶

def __init__(
    self,
    severity: DiagnosticSeverity,
    message: str,
    code: str | None = None,
    source: str | None = None,
) -> None

Attributes¶

• code: str | None

• message: str

• severity: DiagnosticSeverity

• source: str | None

CompilationMetadata [source]¶

class CompilationMetadata

Record how a target artifact was produced.

Parameters:

Constructor¶

def __init__(
    self,
    target: str,
    pipeline: str,
    properties: Mapping[str, Any] = dict(),
) -> None

Attributes¶

• pipeline: str

• properties: Mapping[str, Any]

• target: str

CompilationTarget [source]¶

class CompilationTarget(Protocol[PlanT, ArtifactT])

Define the contract implemented by every compilation target.

Attributes¶

• name: str Return the stable target name.

Methods¶

compile¶

def compile(self, program: PreparedModule, plan: PlanT) -> CompiledProgram[ArtifactT]

Lower and materialize a prepared program for this target.

Parameters:

Returns:

CompiledProgram[ArtifactT] — CompiledProgram[ArtifactT]: Target-native artifact and metadata.

plan¶

def plan(self, program: PreparedModule) -> PlanT

Choose target-specific lowering decisions for a program.

Parameters:

Returns:

PlanT — Immutable target-specific compilation plan.

validate¶

def validate(self, artifact: ArtifactT) -> None

Validate a materialized artifact with target-native rules.

Parameters:

Raises:

• Exception — If target-native validation rejects the artifact.

CompiledProgram [source]¶

class CompiledProgram(Generic[ArtifactT])

Package an artifact with its ABI, diagnostics, and provenance.

Parameters:

Constructor¶

def __init__(
    self,
    artifact: ArtifactT,
    abi: ProgramABI,
    metadata: CompilationMetadata,
    diagnostics: tuple[CompilationDiagnostic, ...] = (),
) -> None

Attributes¶

• abi: ProgramABI

• artifact: ArtifactT

• diagnostics: tuple[CompilationDiagnostic, ...]

• metadata: CompilationMetadata

CompilerConfig [source]¶

class CompilerConfig

Configure semantic preparation and target-independent rewrites.

Parameters:

Constructor¶

def __init__(
    self,
    decomposition: DecompositionConfig = DecompositionConfig(),
    substitutions: SubstitutionConfig = SubstitutionConfig(),
) -> None

Attributes¶

• decomposition: DecompositionConfig

• substitutions: SubstitutionConfig

Methods¶

with_strategies¶

@classmethod
def with_strategies(
    cls,
    strategy_overrides: dict[str, str] | None = None,
    **kwargs: Any = {},
) -> 'CompilerConfig'

Create configuration with named decomposition strategies.

Parameters:

Returns:

'CompilerConfig' — Configuration containing matching decomposition and substitution rules.

CompletedExecutionHandle [source]¶

class CompletedExecutionHandle(ExecutionHandle[ResultT])

Wrap an already available result for synchronous executors.

Parameters:

Constructor¶

def __init__(self, value: ResultT) -> None

Initialize an immediately completed execution.

Parameters:

Methods¶

result¶

def result(self, timeout: float | None = None) -> ResultT

Return the completed value without waiting.

Parameters:

Returns:

ResultT — Stored execution value.

snapshot¶

def snapshot(self) -> ExecutionSnapshot

Capture the already available raw result without waiting.

Returns:

ExecutionSnapshot — Owned, type-preserving local value.

Raises:

• TypeError — If the value contains unsupported result objects.

• ValueError — If the value is nonfinite or cyclic.

status¶

def status(self) -> JobStatus

Return the completed status.

Returns:

JobStatus — Always :attr:JobStatus.COMPLETED.

CompositeExecutionHandle [source]¶

class CompositeExecutionHandle(ExecutionHandle[tuple[ResultT, ...]])

Aggregate several independently submitted executions.

Parameters:

Constructor¶

def __init__(self, handles: Sequence[ExecutionHandle[ResultT]]) -> None

Initialize an ordered execution aggregate.

Parameters:

Attributes¶

• native: object | None Return every child provider-native task.

Methods¶

cancel¶

def cancel(self) -> None

Attempt cancellation of every child not known to be terminal.

A status lookup failure leaves the child’s state unknown, so cancellation is still attempted. Failures are reported together after all children have been visited, retaining the original exceptions and tracebacks.

Raises:

• ExceptionGroup — If any child status lookup or cancellation fails.

metadata¶

def metadata(self) -> Mapping[str, Any]

Return metadata grouped by child index.

Returns:

Mapping[str, Any] — Mapping[str, Any]: Child metadata sequence.

raw_status¶

def raw_status(self) -> object

Return every child provider status.

Returns:

object — Tuple of child raw statuses.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Return the legacy one-reference-per-child view.

This flat view cannot preserve child boundaries when a child exposes zero or multiple references. Use :meth:snapshot to retain local results and nested groups in their original positions.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Ordered child references, or an empty tuple when any child does not expose exactly one.

result¶

def result(self, timeout: float | None = None) -> tuple[ResultT, ...]

Return all child results in submission order.

Parameters:

Returns:

tuple[ResultT, ...] — tuple[ResultT, ...]: Ordered child results.

Raises:

• TimeoutError — If the total wait budget expires.

• Exception — Any child execution failure.

result_async¶

def result_async(self, timeout: float | None = None) -> tuple[ResultT, ...]

Return all child results asynchronously.

Parameters:

Returns:

tuple[ResultT, ...] — tuple[ResultT, ...]: Ordered child results.

Raises:

• TimeoutError — If the total wait budget expires.

• Exception — Any child execution failure.

snapshot¶

def snapshot(self) -> ExecutionSnapshot

Capture all children with their original tuple boundaries.

Returns:

ExecutionSnapshot — Ordered nested execution structure.

Raises:

• ValueError — If a child has no supported reconstruction contract.

• TypeError — If a local child contains unsupported result objects.

status¶

def status(self) -> JobStatus

Aggregate child statuses without hiding partial completion.

Returns:

JobStatus — Aggregate execution status.

DiagnosticSeverity [source]¶

class DiagnosticSeverity(enum.Enum)

Classify the severity of a compilation diagnostic.

Attributes¶

• ERROR

• INFO

• WARNING

EmitError [source]¶

class EmitError(QamomileCompileError)

Report an engine failure to emit one semantic operation.

Parameters:

Example:

Correct — identify the unsupported operation at its target boundary::

    raise EmitError(
        "HUGR cannot emit a symbolic gate power",
        operation="ControlledUOperation",
    )

Incorrect — silently dropping an unsupported operation can change the
compiled program's meaning::

    if not target_supports(operation):
        return

Constructor¶

def __init__(self, message: str, operation: str | None = None)

Initialize an engine emission diagnosis.

Parameters:

Attributes¶

• operation

Exact [source]¶

class Exact

Request an analytic expectation value without shot noise.

Constructor¶

def __init__(self) -> None

ExecutionCapabilities [source]¶

class ExecutionCapabilities

Declare the execution features implemented by one executor.

Parameters:

Raises:

• ValueError — If an unknown estimation policy type is declared or estimation features are declared without estimation support.

Constructor¶

def __init__(
    self,
    supports_async_sampling: bool = False,
    supports_async_estimation: bool = False,
    supports_estimation: bool = False,
    supports_cancellation: bool = False,
    supports_restoration: bool = False,
    supports_native_batch: bool = False,
    supports_native_parameter_inputs: bool = False,
    estimation_accuracy: frozenset[EstimationPolicyType] = frozenset(),
) -> None

Attributes¶

• estimation_accuracy: frozenset[EstimationPolicyType]

• supports_async_estimation: bool

• supports_async_sampling: bool

• supports_cancellation: bool

• supports_estimation: bool

• supports_native_batch: bool

• supports_native_parameter_inputs: bool

• supports_restoration: bool

ExecutionContext [source]¶

class ExecutionContext

Holds global state during program execution.

Constructor¶

def __init__(self, initial_bindings: dict[str, Any] | None = None)

Methods¶

copy¶

def copy(self) -> 'ExecutionContext'

Clone the execution context.

get¶

def get(self, key: str) -> Any

get_many¶

def get_many(self, keys: list[str]) -> dict[str, Any]

has¶

def has(self, key: str) -> bool

set¶

def set(self, key: str, value: Any) -> None

update¶

def update(self, values: dict[str, Any]) -> None

ExecutionError [source]¶

class ExecutionError(QamomileCompileError)

Error during program execution.

ExecutionHandle [source]¶

class ExecutionHandle(ABC, Generic[ResultT])

Expose an engine execution without forcing immediate result retrieval.

Attributes¶

• native: object | None Return the wrapped provider-native task when available.

Methods¶

cancel¶

def cancel(self) -> None

Request best-effort cancellation.

Cancellation is intentionally not reported as a boolean because providers may accept a request after execution has already started. Call :meth:status to observe the eventual state.

metadata¶

def metadata(self) -> Mapping[str, Any]

Return optional provider execution metadata.

Returns:

Mapping[str, Any] — Mapping[str, Any]: Provider metadata such as timestamps or usage.

raw_status¶

def raw_status(self) -> object

Return provider-specific status information.

Returns:

object — Provider status value, or the normalized status when no richer value exists.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Return serializable remote execution references.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Secret-free provider references.

result¶

def result(self, timeout: float | None = None) -> ResultT

Wait for and return the engine-neutral raw result.

Parameters:

Returns:

ResultT — Raw result normalized by the engine executor.

Raises:

• TimeoutError — If the local wait expires before completion.

result_async¶

def result_async(self, timeout: float | None = None) -> ResultT

Wait asynchronously for the engine-neutral raw result.

Parameters:

Returns:

ResultT — Raw result normalized by the engine executor.

Raises:

• TimeoutError — If the local wait expires before completion.

snapshot¶

def snapshot(self) -> ExecutionSnapshot

Capture one remote execution without fetching its result.

Adapters exposing several logical references must override this method with an explicit reconstruction structure. A provider reference may itself contain multiple physical job IDs.

Returns:

ExecutionSnapshot — One opaque provider execution.

Raises:

• ValueError — If references are absent or their grouping is unknown.

status¶

def status(self) -> JobStatus

Return the current provider-independent execution status.

Returns:

JobStatus — Current normalized status.

ExecutionReference [source]¶

class ExecutionReference

Store secret-free identifiers needed to restore remote execution.

Parameters:

Raises:

• ValueError — If the provider name or any job identifier is empty.

• TypeError — If identifiers or context have incompatible types.

Constructor¶

def __init__(
    self,
    provider: str,
    job_ids: tuple[str, ...],
    target: str | None = None,
    group_id: str | None = None,
    context: Mapping[str, str] = dict(),
) -> None

Attributes¶

• context: Mapping[str, str]

• group_id: str | None

• job_ids: tuple[str, ...]

• provider: str

• target: str | None

Methods¶

from_dict¶

@classmethod
def from_dict(cls, data: Mapping[str, Any]) -> ExecutionReference

Reconstruct a provider reference from JSON-compatible data.

Parameters:

Returns:

ExecutionReference — Validated provider execution reference.

Raises:

• KeyError — If a required provider or job identifier field is absent.

• TypeError — If a field has an incompatible type.

• ValueError — If provider or job identifiers are empty.

to_dict¶

def to_dict(self) -> dict[str, Any]

Convert the provider reference to JSON-compatible data.

Returns:

dict[str, Any] — dict[str, Any]: Provider identifiers and decoding context without credentials or SDK objects.

ExecutionSnapshot [source]¶

class ExecutionSnapshot

Store a remote leaf, a local value, or an ordered execution group.

Provider leaves may identify several physical jobs or produce native batch results. Composite children retain their result boundaries independently of the number of provider identifiers. Local values contain raw engine-neutral results, before the executable applies its public result conversion. Trees and local values support at most 100 levels of nesting.

Parameters:

Raises:

• TypeError — If fields or local result types are unsupported.

• ValueError — If fields conflict with the node kind or values are invalid.

Constructor¶

def __init__(
    self,
    kind: str | ExecutionSnapshotKind,
    reference: ExecutionReference | None = None,
    value: Any = None,
    children: tuple[ExecutionSnapshot, ...] = (),
) -> None

Attributes¶

• children: tuple[ExecutionSnapshot, ...]

• kind: str | ExecutionSnapshotKind

• reference: ExecutionReference | None

• value: Any

Methods¶

from_dict¶

@classmethod
def from_dict(cls, data: Mapping[str, Any]) -> ExecutionSnapshot

Reconstruct an execution tree with strict node and value validation.

Parameters:

Returns:

ExecutionSnapshot — Validated execution structure.

Raises:

• TypeError — If node fields have incompatible types.

• ValueError — If kinds, fields, references, or local values are invalid.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Collect provider leaves in order without discarding tree structure.

This list supports diagnostics; restoration uses the complete tree.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Detached remote references in order.

Raises:

• TypeError — If mutable reference fields became incompatible.

• ValueError — If mutable reference fields became invalid.

restore¶

def restore(
    self,
    restore_reference: Callable[[ExecutionReference], ExecutionHandle[Any]],
) -> ExecutionHandle[Any]

Reattach remote leaves and rebuild local values and ordered groups.

The callback must reattach an existing provider execution. This method neither retrieves remote results nor submits any execution.

Parameters:

Returns:

ExecutionHandle[Any] — ExecutionHandle[Any]: Reconstructed raw execution lifecycle.

Raises:

• TypeError — If local data is unsupported or the callback returns an incompatible handle.

• ValueError — If local values or references became invalid.

• Exception — If the provider restoration callback fails.

to_dict¶

def to_dict(self) -> dict[str, Any]

Serialize the execution tree and type-preserving local values.

Returns:

dict[str, Any] — dict[str, Any]: JSON-compatible execution tree.

Raises:

• TypeError — If mutable local data was changed to unsupported types.

• ValueError — If mutable local data or references became invalid.

ExecutionSnapshotKind [source]¶

class ExecutionSnapshotKind(StrEnum)

Identify the reconstruction contract of an execution snapshot node.

Attributes¶

• COMPOSITE

• LOCAL

• REMOTE

ExpvalJob [source]¶

class ExpvalJob(Job[float])

Job for expectation value computation.

Returns a single float representing <psi|H|psi>.

Constructor¶

def __init__(self, exp_val: float | ExecutionHandle[float]) -> None

Initialize expval job.

Parameters:

Methods¶

result¶

def result(self, timeout: float | None = None) -> float

Wait for and return the expectation value.

Parameters:

Returns:

float — Expectation value.

result_async¶

def result_async(self, timeout: float | None = None) -> float

Wait asynchronously for and return the expectation value.

Parameters:

Returns:

float — Expectation value.

Job [source]¶

class Job(ABC, Generic[T])

Abstract base class for quantum execution jobs.

A Job represents a quantum execution that can be awaited for results.

Constructor¶

def __init__(
    self,
    handle: ExecutionHandle[Any],
    kind: JobKind,
    shots: int | None = None,
) -> None

Initialize a public job around an execution handle.

Parameters:

Attributes¶

• native: object | None Return the wrapped provider-native task when available.

Methods¶

cancel¶

def cancel(self) -> None

Request best-effort cancellation of the underlying execution.

metadata¶

def metadata(self) -> Mapping[str, Any]

Return provider execution metadata.

Returns:

Mapping[str, Any] — Mapping[str, Any]: Provider-specific metadata.

raw_status¶

def raw_status(self) -> object

Return provider-specific status information.

Returns:

object — Provider status or aggregate status values.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Return the execution handle’s legacy provider-reference view.

Use :meth:snapshot for typed restoration of local values or nested groups, which a flat reference list cannot represent completely.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Provider execution references.

result¶

def result(self, timeout: float | None = None) -> T

Wait for and return the result.

Blocks until the job completes.

Parameters:

Returns:

T — Execution result with the appropriate public type.

Raises:

• ExecutionError — If the job failed.

result_async¶

def result_async(self, timeout: float | None = None) -> T

Wait asynchronously for and return the public result.

Parameters:

Returns:

T — Execution result with the appropriate public type.

snapshot¶

def snapshot(self) -> JobSnapshot

Capture secret-free information needed for typed restoration.

Returns:

JobSnapshot — Public metadata, local values, and remote references with ordered execution boundaries. No remote results are read.

Raises:

• ValueError — If execution grouping or mapping cannot be restored, or a local value is nonfinite or cyclic.

• TypeError — If a local result contains unsupported objects.

status¶

def status(self) -> JobStatus

Return the current job status.

Returns:

JobStatus — Current normalized status.

JobKind [source]¶

class JobKind(StrEnum)

Identify the public operation needed to reconstruct a typed job.

Attributes¶

• RUN

• SAMPLE

JobSnapshot [source]¶

class JobSnapshot

Store operation metadata and lossless raw execution reconstruction.

Runtime bindings are intentionally excluded. They can contain arbitrary application data, so callers supply them again to :meth:ExecutableProgram.restore instead of persisting them implicitly.

Parameters:

Raises:

• ValueError — If legacy references are empty, the reference inventory disagrees with the tree, or shots disagree with the operation kind.

• TypeError — If operation kind, references, tree, or shots have incompatible types.

Constructor¶

def __init__(
    self,
    kind: JobKind,
    executions: tuple[ExecutionReference, ...],
    shots: int | None = None,
    execution: ExecutionSnapshot | None = None,
) -> None

Attributes¶

• execution: ExecutionSnapshot | None

• executions: tuple[ExecutionReference, ...]

• kind: JobKind

• shots: int | None

Methods¶

from_dict¶

@classmethod
def from_dict(cls, data: Mapping[str, Any]) -> JobSnapshot

Reconstruct a validated snapshot from JSON-compatible data.

Parameters:

Returns:

JobSnapshot — Validated typed-job restoration snapshot.

Raises:

• KeyError — If operation kind, references, or a version 2 tree is absent.

• TypeError — If metadata, references, or local values have wrong types.

• ValueError — If a version, field, tree, or reference is invalid.

to_dict¶

def to_dict(self) -> dict[str, Any]

Convert the snapshot to JSON-compatible data.

Returns:

dict[str, Any] — dict[str, Any]: Version 2 operation metadata and execution tree, or the original legacy format for a flat-reference snapshot.

Raises:

• TypeError — If local values were mutated to unsupported types.

• ValueError — If local values or references were mutated to invalid data.

JobStatus [source]¶

class JobStatus(Enum)

Describe a provider-independent execution state.

The numeric values of the original four states remain stable for serialization compatibility.

Attributes¶

• CANCELLED

• CANCELLING

• COMPLETED

• FAILED

• PARTIAL

• PENDING

• QUEUED

• RUNNING

• UNKNOWN

MappedExecutionHandle [source]¶

class MappedExecutionHandle(ExecutionHandle[MappedT], Generic[ResultT, MappedT])

Lazily transform another execution handle’s result.

Parameters:

Constructor¶

def __init__(
    self,
    source: ExecutionHandle[ResultT],
    transform: Callable[[ResultT], MappedT],
    *,
    snapshot_source: bool = False,
) -> None

Initialize a lazy mapped execution.

Parameters:

Attributes¶

• native: object | None Return the source provider-native task.

Methods¶

cancel¶

def cancel(self) -> None

Forward a cancellation request to the source execution.

metadata¶

def metadata(self) -> Mapping[str, Any]

Return source execution metadata.

Returns:

Mapping[str, Any] — Mapping[str, Any]: Source metadata.

raw_status¶

def raw_status(self) -> object

Return the source provider status.

Returns:

object — Provider-specific source status.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Return source execution references.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Source references.

result¶

def result(self, timeout: float | None = None) -> MappedT

Retrieve and transform the source result once.

Parameters:

Returns:

MappedT — Cached transformed result.

Raises:

• Exception — Any source or transformation failure.

result_async¶

def result_async(self, timeout: float | None = None) -> MappedT

Retrieve and transform the source result asynchronously.

Parameters:

Returns:

MappedT — Cached transformed result.

Raises:

• Exception — Any source or transformation failure.

snapshot¶

def snapshot(self) -> ExecutionSnapshot

Capture a source whose mapping is rebuilt by its owning executable.

Python callables are never serialized. Arbitrary mappings must supply an adapter-specific restoration recipe instead of losing conversion.

Returns:

ExecutionSnapshot — Source reconstruction structure.

Raises:

• ValueError — If the mapping has no declared restoration contract.

• TypeError — If a local source value cannot be saved.

status¶

def status(self) -> JobStatus

Return the source execution status.

Returns:

JobStatus — Current mapped execution status.

PreparedModule [source]¶

class PreparedModule

Hold a prepared entrypoint and its reachable callable definitions.

Parameters:

Constructor¶

def __init__(
    self,
    entrypoint_ref: CallableRef,
    entrypoint: Block,
    definitions: Mapping[CallableRef, CallableDef],
    definition_variants: Mapping[CallableRef, tuple[CallableDef, ...]],
    call_graph: Mapping[CallableRef, frozenset[CallableRef]],
    abi: ProgramABI,
    bindings: Mapping[str, Any],
) -> None

Attributes¶

• abi: ProgramABI

• bindings: Mapping[str, Any]

• call_graph: Mapping[CallableRef, frozenset[CallableRef]]

• definition_variants: Mapping[CallableRef, tuple[CallableDef, ...]]

• definitions: Mapping[CallableRef, CallableDef]

• entrypoint: Block

• entrypoint_ref: CallableRef

Methods¶

body¶

def body(self, ref: CallableRef) -> Block

Return the semantic body associated with a program symbol.

Parameters:

Returns:

Block — Hierarchical semantic body for ref.

Raises:

• KeyError — If ref is neither the entrypoint nor a reachable body-backed callable definition.

owned_snapshot¶

def owned_snapshot(self) -> PreparedModule

Create a deep, target-owned snapshot of prepared semantics.

The semantic IR intentionally remains mutable while compiler passes are being developed. Copying the entrypoint and definition registry as one object graph preserves shared callable bodies while preventing one target from mutating the source module observed by another.

Returns:

PreparedModule — Deep snapshot with read-only definition and call graph registries.

ProgramABI [source]¶

class ProgramABI

Runtime-visible ABI for a segmented program.

Constructor¶

def __init__(
    self,
    public_inputs: dict[str, ValueLike] = dict(),
    output_values: list[ValueLike] = list(),
) -> None

Attributes¶

• output_values: list[ValueLike]

• public_inputs: dict[str, ValueLike]

QKernelLike [source]¶

class QKernelLike(Protocol)

Describe the frontend surface required by compiler entrypoints.

This protocol is intentionally structural. It lets decorator-created composites reuse the qkernel inspection and build interface without making them inherit from QKernel or exposing the compiler-facing callable descriptor model as a frontend concept.

Attributes¶

• block: Block Return the cached hierarchical body block.

• effects: KernelEffect Return cached semantic effects of the qkernel body.

• input_types: dict[str, Any] Return frontend input annotations by parameter name.

• name: str Return the user-facing callable name.

• output_types: list[Any] Return frontend output annotations.

• signature: inspect.Signature Return the Python call signature.

Methods¶

build¶

def build(self, parameters: list[str] | None = None, **kwargs: Any = {}) -> Block

Build a traced body block.

Parameters:

Returns:

Block — Traced hierarchical body block.

QamomileCompiler [source]¶

class QamomileCompiler

Prepare Qamomile semantics and dispatch explicit target compilation.

Parameters:

Constructor¶

def __init__(self, config: CompilerConfig | None = None) -> None

Initialize the target-neutral compiler.

Parameters:

Attributes¶

• config

Methods¶

compile¶

def compile(
    self,
    kernel: QKernelLike,
    target: CompilationTarget[PlanT, ArtifactT],
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> CompiledProgram[ArtifactT]

Compile a qkernel with an explicit target implementation.

Parameters:

Returns:

CompiledProgram[ArtifactT] — CompiledProgram[ArtifactT]: Validated target-native artifact.

Raises:

• Exception — If semantic preparation, target compilation, or target-native validation fails.

prepare¶

def prepare(
    self,
    kernel: QKernelLike,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> PreparedModule

Prepare a hierarchical semantic module without destroying calls.

Parameters:

Returns:

PreparedModule — Program-level semantic input for target planning.

Raises:

• ValueError — If bindings overlap runtime parameters.

• EntrypointValidationError — If the top-level kernel has quantum inputs or outputs.

to_block¶

def to_block(
    self,
    kernel: QKernelLike,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> Block

Trace a qkernel-like object into a hierarchical semantic block.

Parameters:

Returns:

Block — Hierarchical Qamomile semantic block.

Raises:

• ValueError — If bindings and parameters overlap or frontend argument construction fails.

• TypeError — If specialization is requested for a block-only qkernel-like object that has no build method.

RunJob [source]¶

class RunJob(Job[T], Generic[T])

Job for single execution.

Returns a single result value matching the kernel’s return type.

Constructor¶

def __init__(
    self,
    raw_counts: dict[str, int] | ExecutionHandle[dict[str, int]] | None,
    result_converter: Callable[[str], T] | None,
    *,
    value_handle: ExecutionHandle[T] | None = None,
) -> None

Initialize run job.

Parameters:

Raises:

• ValueError — If neither a valid counts source nor value_handle is supplied.

Methods¶

from_handle¶

@classmethod
def from_handle(cls, handle: ExecutionHandle[T]) -> RunJob[T]

Create a run job whose handle already returns the public value.

Parameters:

Returns:

RunJob[T] — RunJob[T]: Public run job delegating to handle.

result¶

def result(self, timeout: float | None = None) -> T

Wait for and return the single public result.

Parameters:

Returns:

T — Public kernel return value.

result_async¶

def result_async(self, timeout: float | None = None) -> T

Wait asynchronously for the single public result.

Parameters:

Returns:

T — Public kernel return value.

SampleResult [source]¶

class SampleResult(Generic[T])

Result of a sample() execution.

Contains results as a list of (value, count) tuples.

Example:

result.results  # [(0.25, 500), (0.75, 500)]

Constructor¶

def __init__(self, results: list[tuple[T, int]], shots: int) -> None

Attributes¶

• results: list[tuple[T, int]] List of (value, count) tuples.

• shots: int Total number of shots executed.

Methods¶

most_common¶

def most_common(self, n: int = 1) -> list[tuple[T, int]]

Return the n most common results.

Parameters:

Returns:

list[tuple[T, int]] — List of (result, count) tuples sorted by count descending.

probabilities¶

def probabilities(self) -> list[tuple[T, float]]

Return probability distribution over results.

Returns:

list[tuple[T, float]] — List of (value, probability) tuples.

ShotBased [source]¶

class ShotBased

Request a shot-based expectation value.

Parameters:

Raises:

• ValueError — If shots is not positive.

Constructor¶

def __init__(self, shots: int) -> None

Attributes¶

• shots: int

TargetCapabilityError [source]¶

class TargetCapabilityError(EmitError)

A program requires a capability the selected target does not declare.

Raised by circuit-IR target-legality verification before any engine materialization starts. The message always names the target and the missing capability axis, so the failure reads as a target restriction rather than a Qamomile language error.

Parameters:

Example:

Correct — bind the runtime parameter before selecting a
concrete-angle-only target::

    transpiler.transpile(kernel, bindings={"theta": 0.5})

Incorrect — keeping ``theta`` symbolic on such a target raises this
error::

    transpiler.transpile(kernel, parameters=["theta"])

Constructor¶

def __init__(self, message: str, target: str | None = None, operation: str | None = None)

Initialize a target-capability diagnosis.

Parameters:

Attributes¶

• target: str | None

TargetPrecision [source]¶

class TargetPrecision

Request an expectation value at a provider target precision.

Parameters:

Raises:

• ValueError — If precision is not positive.

Constructor¶

def __init__(self, precision: float) -> None

Attributes¶

• precision: float

qamomile.circuit.transpiler.artifact¶

Target-neutral containers for compiled artifacts and diagnostics.

Overview¶

Classes¶

CompilationDiagnostic [source]¶

class CompilationDiagnostic

Describe one target-independent or target-specific diagnostic.

Parameters:

Constructor¶

def __init__(
    self,
    severity: DiagnosticSeverity,
    message: str,
    code: str | None = None,
    source: str | None = None,
) -> None

Attributes¶

• code: str | None

• message: str

• severity: DiagnosticSeverity

• source: str | None

CompilationMetadata [source]¶

class CompilationMetadata

Record how a target artifact was produced.

Parameters:

Constructor¶

def __init__(
    self,
    target: str,
    pipeline: str,
    properties: Mapping[str, Any] = dict(),
) -> None

Attributes¶

• pipeline: str

• properties: Mapping[str, Any]

• target: str

CompiledProgram [source]¶

class CompiledProgram(Generic[ArtifactT])

Package an artifact with its ABI, diagnostics, and provenance.

Parameters:

Constructor¶

def __init__(
    self,
    artifact: ArtifactT,
    abi: ProgramABI,
    metadata: CompilationMetadata,
    diagnostics: tuple[CompilationDiagnostic, ...] = (),
) -> None

Attributes¶

• abi: ProgramABI

• artifact: ArtifactT

• diagnostics: tuple[CompilationDiagnostic, ...]

• metadata: CompilationMetadata

DiagnosticSeverity [source]¶

class DiagnosticSeverity(enum.Enum)

Classify the severity of a compilation diagnostic.

Attributes¶

• ERROR

• INFO

• WARNING

ProgramABI [source]¶

class ProgramABI

Runtime-visible ABI for a segmented program.

Constructor¶

def __init__(
    self,
    public_inputs: dict[str, ValueLike] = dict(),
    output_values: list[ValueLike] = list(),
) -> None

Attributes¶

• output_values: list[ValueLike]

• public_inputs: dict[str, ValueLike]

qamomile.circuit.transpiler.block_parameter_binding¶

Shared call-site pairing for operation-owned blocks.

Overview¶

Functions¶

align_formal_operands [source]¶

def align_formal_operands(
    formals: Sequence[ValueBase],
    quantum_operands: Sequence[ValueBase],
    parameter_operands: Sequence[ValueBase],
) -> list[ValueBase]

Align split call-site operand pools to formal declaration order.

Operation-owned call sites store quantum operands separately from classical/object operands, while a block keeps the Python declaration order and may interleave those categories. Reweaving the two pools here gives every consumer one canonical formal-to-actual convention.

Parameters:

Returns:

list[ValueBase] — list[ValueBase]: Actual operands aligned with formals. The list stops at the first category shortfall so a downstream positional pairing cannot silently consume an operand of the wrong category.

block_parameter_binding_keys [source]¶

def block_parameter_binding_keys(parameter: ValueBase) -> tuple[str, ...]

Return the sanctioned emit-binding keys for an inner formal.

Emit resolution accepts a kernel parameter name before its UUID for public API compatibility, so an operation-owned fresh scope must write both keys. Keeping the key choice here prevents individual emit paths from reviving a parent binding that merely shares the inner formal’s display name.

Parameters:

Returns:

tuple[str, ...] — tuple[str, ...]: UUID followed by the formal parameter provenance name and nonempty display-name compatibility key, without duplicates.

pair_block_operands [source]¶

def pair_block_operands(
    block: Block,
    operands: Sequence[ValueBase],
) -> list[tuple[ValueBase, ValueBase]]

Pair all block inputs with category-grouped call-site operands.

Parameters:

Returns:

list[tuple[ValueBase, ValueBase]] — list[tuple[ValueBase, ValueBase]]: Formal/actual pairs in the block’s list[tuple[ValueBase, ValueBase]] — declaration order.

pair_block_parameter_operands [source]¶

def pair_block_parameter_operands(
    block: Block,
    param_operands: Sequence[ValueBase],
) -> list[tuple[ValueBase, ValueBase]]

Pair a block’s classical/object inputs with call-site operands.

Both compile-time lowering and emission bind an operation-owned block’s non-quantum inputs by their declaration order. Keeping the filtering and pairing here ensures those stages cannot adopt different positional conventions.

Parameters:

Returns:

list[tuple[ValueBase, ValueBase]] — list[tuple[ValueBase, ValueBase]]: (formal, actual) pairs in list[tuple[ValueBase, ValueBase]] — declaration order. Missing actual operands leave trailing formals list[tuple[ValueBase, ValueBase]] — unpaired, so they can remain symbolic and be provided at emit time.

Classes¶

Block [source]¶

class Block

Unified block representation for all pipeline stages.

Replaces the older traced and callable IR wrappers with a single structure. The kind field indicates which pipeline stage this block is at.

Constructor¶

def __init__(
    self,
    name: str = '',
    label_args: list[str] = list(),
    input_values: list[ValueLike] = list(),
    output_values: list[ValueLike] = list(),
    output_names: list[str] = list(),
    operations: list['Operation'] = list(),
    kind: BlockKind = BlockKind.HIERARCHICAL,
    parameters: dict[str, Value] = dict(),
    param_slots: tuple[ParamSlot, ...] = tuple(),
    static_bindings: tuple[StaticBindingSlot, ...] = tuple(),
) -> None

Attributes¶

• effects: ‘KernelEffect’ Return lazily cached semantic effects for this block.

• input_values: list[ValueLike]

• kind: BlockKind

• label_args: list[str]

• measurement_result_indices: frozenset[int] Return public output positions derived from measurement.

• name: str

• operations: list[‘Operation’]

• output_names: list[str]

• output_values: list[ValueLike]

• param_slots: tuple[ParamSlot, ...]

• parameters: dict[str, Value]

• static_bindings: tuple[StaticBindingSlot, ...]

Methods¶

call¶

def call(self, **kwargs: ValueLike = {}) -> 'InvokeOperation'

Create an inline callable invocation against this block.

Parameters:

Returns:

'InvokeOperation' — Inline-policy invocation whose callable definition points at this block.

Raises:

• KeyError — If a required label in self.label_args is missing from kwargs.

is_affine¶

def is_affine(self) -> bool

Return whether this block has passed affine validation.

Returns:

bool — True for AFFINE and ANALYZED blocks.

unbound_parameters¶

def unbound_parameters(self) -> list[str]

Return list of unbound parameter names.

ValueBase [source]¶

class ValueBase

Nominal base for every typed IR value.

Runtime compiler passes inspect values in their innermost loops. A nominal base keeps those checks constant-time; a runtime-checkable protocol would repeatedly scan the protocol members on Python versions that do not cache structural checks.

Attributes¶

• logical_id: str

• metadata: ValueMetadata

• name: str

• type: ValueType Return the static IR type carried by this value.

• uuid: str

Methods¶

get_const¶

def get_const(self) -> int | float | bool | None

Return the scalar constant carried by this value.

Returns:

int | float | bool | None — int | float | bool | None: Constant value, or None when the value is not constant.

is_constant¶

def is_constant(self) -> bool

Return whether this value carries a scalar constant.

Returns:

bool — Whether scalar constant metadata is present.

is_parameter¶

def is_parameter(self) -> bool

Return whether this value represents a runtime parameter.

Returns:

bool — Whether parameter metadata is present.

next_version¶

def next_version(self) -> ValueBase

Create the next SSA version of this value.

Returns:

ValueBase — A value with a fresh version UUID and preserved logical identity.

parameter_name¶

def parameter_name(self) -> str | None

Return the public parameter name carried by this value.

Returns:

str | None — str | None: Parameter name, or None for a non-parameter value.

qamomile.circuit.transpiler.circuit_ir¶

Engine-neutral circuit code-generation IR.

This module is intentionally lower-level than Qamomile’s semantic IR and higher-level than any SDK object. It contains virtual quantum wires, target-neutral scalar expressions, structured control flow, and reusable circuit calls. Circuit-family targets legalize and materialize this IR; program-graph targets such as HUGR do not pass through it.

The semantic-to-circuit lowering currently reuses the established emit walker to preserve frontend behavior; the immutable CircuitProgram boundary is where that mutable traversal ends.

Two rules govern what survives into this IR and how targets consume it:

• Lowering may erase how a program was written, never what it means. Semantic values, slices, bindings, and call machinery are erased; intent a target could exploit — semantic identity and immutable semantic arguments (:class:CallableIdentity), deferred call transforms, structured control flow, Pauli-evolution semantics — is preserved until a target explicitly decides otherwise. Erasure is irreversible while preservation costs one tag, so the default is to preserve.

• Capabilities declare, legalization decides, materializers execute. Each target owns an immutable :class:CircuitCapabilities declaration; :func:legalize_program rewrites a program under that declaration and the user’s :class:CompilationPolicy; :func:verify_target_legal proves the result before materialization, so a materializer only ever converts a program it has already declared it accepts.

Overview¶

Constants¶

• ALL_BINARY_OPERATORS: frozenset[BinaryOperator] = frozenset(BinaryOperator) Every binary operator in the circuit scalar vocabulary.

• ALL_PRIMITIVE_GATES: frozenset[GateKind] = frozenset(GateKind) - {GateKind.MEASURE} Every gate kind valid in GateInstruction.

• ALL_UNARY_OPERATORS: frozenset[UnaryOperator] = frozenset(UnaryOperator) Every unary operator in the circuit scalar vocabulary.

• ARITHMETIC_BINARY_OPERATORS: frozenset[BinaryOperator] Binary operators that produce arithmetic scalar values.

• CircuitInstruction: TypeAlias

• DEFAULT_POLICY = CompilationPolicy() Policy used when an engine transpiler does not supply one.

• IQFT_SEMANTIC_KEY = SemanticOpKey('qamomile.stdlib', 'iqft') Semantic key for the exact inverse quantum Fourier transform.

• MULTI_CONTROLLED_X_SEMANTIC_KEY = SemanticOpKey('qamomile.stdlib', 'multi_controlled_x') Semantic key for an arbitrary-width multi-controlled X operation.

• QFT_SEMANTIC_KEY = SemanticOpKey('qamomile.stdlib', 'qft') Semantic key for the exact standard quantum Fourier transform.

• RIPPLE_CARRY_ADD_SEMANTIC_KEY = SemanticOpKey('qamomile.stdlib', 'ripple_carry_add') Semantic key for the full reversible ripple-carry adder.

• SELECT_SEMANTIC_KEY = SemanticOpKey('qamomile.circuit', 'select') Semantic key for a fallback-defined, index-addressed quantum multiplexer.

• STATE_PREPARATION_SEMANTIC_KEY = SemanticOpKey('qamomile.stdlib', 'state_preparation') Semantic key for preparing one concrete normalized state vector.

• ScalarExpr: TypeAlias

Functions¶

has_mid_circuit_measurement [source]¶

def has_mid_circuit_measurement(operations: tuple[CircuitInstruction, ...]) -> bool

Return whether measured quantum state is consumed again in a region.

Static-sampling engines may defer terminal measurements to the end of a shot, but doing so is incorrect when a later gate, reset, call, or control region consumes the post-measurement wire. The circuit IR uses versioned wires, so this scan can distinguish those two cases without engine SDK knowledge.

Parameters:

Returns:

bool — True when the region or a nested reusable/control-flow body contains a non-terminal measurement.

legalize_program [source]¶

def legalize_program(
    program: CircuitProgram,
    capabilities: CircuitCapabilities,
    policy: CompilationPolicy,
) -> CircuitProgram

Rewrite one circuit program until it is legal for a target.

Calls whose semantic key the target implements natively receive a target-owned realization identifier. Every other call retains its semantic identity and recursively legalized fallback body.

Parameters:

Returns:

CircuitProgram — Rebuilt program with freshly numbered wires.

lower_circuit_plan [source]¶

def lower_circuit_plan(
    plan: ProgramPlan,
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
) -> ExecutableProgram[CircuitProgram]

Lower every quantum segment in a plan to immutable circuit IR.

Classical and expectation-value orchestration metadata remains in the returned executable container. Only engine-native quantum artifacts are replaced with verified :class:CircuitProgram objects.

Parameters:

Returns:

ExecutableProgram[CircuitProgram] — ExecutableProgram[CircuitProgram]: Execution structure containing immutable engine-neutral quantum programs.

Raises:

• EmitError — If the semantic operations cannot be lowered to the circuit-family instruction set.

• ValueError — If structural verification rejects a lowered circuit.

materialize_executable [source]¶

def materialize_executable(
    executable: ExecutableProgram[CircuitProgram],
    materializer: CircuitMaterializer[ArtifactT],
) -> ExecutableProgram[ArtifactT]

Materialize every quantum segment while preserving orchestration.

Parameters:

Returns:

ExecutableProgram[ArtifactT] — ExecutableProgram[ArtifactT]: Execution structure containing native engine circuits and unchanged ABI, classical, expectation-value, mapping, and parameter metadata.

verify_circuit [source]¶

def verify_circuit(program: CircuitProgram) -> None

Verify wire linearity, regions, expressions, and slot bounds.

Parameters:

Raises:

• ValueError — If the program contains duplicate wire definitions, consumes a non-live wire, has malformed structured-region yields, references an invalid classical bit or loop variable, or reports incorrect outputs.

verify_target_legal [source]¶

def verify_target_legal(program: CircuitProgram, capabilities: CircuitCapabilities) -> None

Prove a legalized program against declared target capabilities.

Parameters:

Raises:

• TargetCapabilityError — If any instruction requires a gate kind, semantic realization, control-flow construct, reset, Pauli evolution, or scalar-expression shape the target does not declare.

Classes¶

BarrierInstruction [source]¶

class BarrierInstruction

Separate scheduling regions without changing wire versions.

Parameters:

Constructor¶

def __init__(self, wires: tuple[WireId, ...]) -> None

Attributes¶

• wires: tuple[WireId, ...]

BinaryExpr [source]¶

class BinaryExpr(_ScalarOperators)

Apply a binary scalar operation.

Parameters:

Constructor¶

def __init__(self, operator: BinaryOperator, left: ScalarExpr, right: ScalarExpr) -> None

Attributes¶

• left: ScalarExpr

• operator: BinaryOperator

• right: ScalarExpr

BinaryOperator [source]¶

class BinaryOperator(enum.Enum)

Enumerate scalar operations preserved until target materialization.

Attributes¶

• ADD

• AND

• DIV

• EQ

• FLOORDIV

• GE

• GT

• LE

• LT

• MOD

• MUL

• NEQ

• OR

• POW

• SUB

CallControlMode [source]¶

class CallControlMode(enum.Enum)

Enumerate how a target realizes controls on reusable calls.

Attributes¶

• DISTRIBUTE

• UNSUPPORTED

• WHOLE_CALL

CallInstruction [source]¶

class CallInstruction

Invoke a reusable circuit over versioned wires.

Parameters:

Constructor¶

def __init__(
    self,
    callee: ReusableCircuit,
    inputs: tuple[WireId, ...],
    outputs: tuple[WireId, ...],
) -> None

Attributes¶

• callee: ReusableCircuit

• inputs: tuple[WireId, ...]

• outputs: tuple[WireId, ...]

CallPhaseMode [source]¶

class CallPhaseMode(enum.Enum)

Enumerate how a target realizes phase in coherently controlled calls.

NATIVE_BODY means the target call itself preserves the reusable body’s phase. EXPLICIT_CORRECTION means the materializer emits a separate phase correction alongside the call. UNSUPPORTED rejects a body phase once coherent controls make it observable.

Attributes¶

• EXPLICIT_CORRECTION

• NATIVE_BODY

• UNSUPPORTED

CallTransformCapabilities [source]¶

class CallTransformCapabilities

Declare reusable-call forms accepted by a target realization.

Parameters:

Constructor¶

def __init__(
    self,
    supports_power: bool,
    supports_inverse: bool,
    max_controls: int | None,
    supports_nonunitary_body: bool = False,
    supports_barrier_body: bool = False,
    control_mode: CallControlMode = CallControlMode.WHOLE_CALL,
    controlled_gate_kinds: frozenset[GateKind] = frozenset(),
    controlled_pauli_time: ScalarCapabilities | None = None,
    phase_mode: CallPhaseMode = CallPhaseMode.UNSUPPORTED,
    controlled_phase_scalars: ScalarCapabilities | None = None,
) -> None

Attributes¶

• control_mode: CallControlMode

• controlled_gate_kinds: frozenset[GateKind]

• controlled_pauli_time: ScalarCapabilities | None

• controlled_phase_scalars: ScalarCapabilities | None

• max_controls: int | None

• phase_mode: CallPhaseMode

• supports_barrier_body: bool

• supports_inverse: bool

• supports_nonunitary_body: bool

• supports_power: bool

Methods¶

accepts¶

def accepts(self, callee: ReusableCircuit, inherited_controls: int = 0) -> bool

Return whether this declaration accepts a concrete call shape.

Parameters:

Returns:

bool — Whether power, inverse, and control transforms are accepted.

CallableIdentity [source]¶

class CallableIdentity

Preserve the semantic identity of a reusable circuit body.

Parameters:

Constructor¶

def __init__(
    self,
    key: SemanticOpKey,
    symbol: str,
    arguments: SemanticArguments = SemanticArguments(),
) -> None

Attributes¶

• arguments: SemanticArguments

• key: SemanticOpKey

• symbol: str

CircuitBuilder [source]¶

class CircuitBuilder

Build immutable circuit IR while assigning fresh wire versions.

Parameters:

Constructor¶

def __init__(self, num_qubits: int, num_clbits: int, name: str = 'main') -> None

Initialize a circuit builder.

Parameters:

Raises:

• ValueError — If either slot count is negative.

Attributes¶

• name

• num_clbits

• num_qubits

• operations: list[CircuitInstruction] Return the current region instruction list.

Methods¶

add_global_phase¶

def add_global_phase(self, phase: ScalarExpr | bool | int | float) -> None

Accumulate a global phase in the current lexical region.

Parameters:

append_barrier¶

def append_barrier(self, qubits: tuple[int, ...]) -> None

Append a scheduling barrier without changing wire versions.

Parameters:

append_call¶

def append_call(self, callee: ReusableCircuit, qubits: tuple[int, ...]) -> None

Append a reusable-circuit call and advance its wires.

Parameters:

append_gate¶

def append_gate(
    self,
    kind: GateKind,
    qubits: tuple[int, ...],
    parameters: tuple[ScalarExpr, ...] = (),
) -> None

Append a primitive gate and advance all participating wires.

Parameters:

append_measure¶

def append_measure(self, qubit: int, clbit: int) -> None

Append a measurement.

Parameters:

Raises:

• IndexError — If clbit is outside the allocated classical slots.

append_measure_vector¶

def append_measure_vector(self, qubits: tuple[int, ...], clbits: tuple[int, ...]) -> None

Append one ordered vector measurement.

Parameters:

Raises:

• ValueError — If qubit and classical-bit arities differ or either sequence contains duplicate slots.

• IndexError — If a classical-bit slot is outside the circuit.

append_pauli_evolution¶

def append_pauli_evolution(
    self,
    qubits: tuple[int, ...],
    hamiltonian: Any,
    time: ScalarExpr | bool | int | float,
) -> None

Append an abstract Pauli evolution and advance its wires.

Parameters:

Raises:

• ValueError — If a Qamomile Hamiltonian has a non-Hermitian identity coefficient.

append_reset¶

def append_reset(self, qubit: int) -> None

Append reset and advance the affected wire.

Parameters:

begin_else¶

def begin_else(self, context: _IfContext) -> None

Close a true region and open its false region.

Parameters:

Raises:

• RuntimeError — If context is not the innermost open conditional or an else branch has already started.

begin_for¶

def begin_for(self, indexset: range) -> LoopVariableExpr

Open a structured for-loop body.

Parameters:

Returns:

LoopVariableExpr — Induction expression available inside the body.

begin_if¶

def begin_if(self, condition: ScalarExpr) -> _IfContext

Open the true region of a structured conditional.

Parameters:

Returns:

_IfContext — Opaque builder token used to select the else branch.

begin_while¶

def begin_while(self, condition: ScalarExpr) -> _WhileContext

Open a structured while-loop body.

Parameters:

Returns:

_WhileContext — Opaque builder token used to close the loop.

current_wire¶

def current_wire(self, qubit: int) -> WireId

Return the current wire version for a qubit slot.

Parameters:

Returns:

WireId — Current version of the slot.

Raises:

• KeyError — If qubit is outside the allocated slot range.

end_for¶

def end_for(self) -> None

Close the innermost structured for-loop body.

Raises:

• RuntimeError — If the innermost open region is not a for loop.

end_if¶

def end_if(self, context: _IfContext) -> None

Close a structured conditional and merge its wire states.

Parameters:

Raises:

• RuntimeError — If context is not the innermost open conditional.

end_while¶

def end_while(self, context: _WhileContext) -> None

Close a structured while-loop body.

Parameters:

Raises:

• RuntimeError — If context is not the innermost open while loop.

freeze¶

def freeze(self) -> CircuitProgram

Finalize the root region into immutable circuit IR.

Returns:

CircuitProgram — Immutable circuit program.

Raises:

• RuntimeError — If a structured region is still open.

fresh_wire¶

def fresh_wire(self) -> WireId

Allocate a fresh module-local virtual wire version.

Returns:

WireId — Newly allocated wire identifier.

restore_state¶

def restore_state(self, snapshot: _CircuitBuilderSnapshot) -> None

Restore a checkpoint after an append-only emission attempt.

Parameters:

Raises:

• RuntimeError — If emission removed or replaced state that existed before the checkpoint instead of only appending new state.

snapshot_state¶

def snapshot_state(self) -> _CircuitBuilderSnapshot

Capture state that can be restored after declined emission.

Returns:

_CircuitBuilderSnapshot — Append-only builder checkpoint for the current structured region.

CircuitCapabilities [source]¶

class CircuitCapabilities

Declare the complete circuit-IR language accepted by one target.

Parameters:

Constructor¶

def __init__(
    self,
    name: str,
    primitive_gates: frozenset[GateKind],
    native_semantic_ops: tuple[NativeSemanticOpCapabilities, ...],
    gate_parameters: ScalarCapabilities,
    predicates: ScalarCapabilities,
    pauli_time: ScalarCapabilities,
    global_phase: GlobalPhaseCapabilities | ScalarCapabilities | None,
    generic_calls: CallTransformCapabilities,
    supports_dynamic_if: bool,
    supports_dynamic_while: bool,
    supports_reset: bool,
    pauli_realizations: frozenset[PauliEvolutionRealization],
) -> None

Attributes¶

• gate_parameters: ScalarCapabilities

• generic_calls: CallTransformCapabilities

• global_phase: GlobalPhaseCapabilities | ScalarCapabilities | None

• name: str

• native_semantic_ops: tuple[NativeSemanticOpCapabilities, ...]

• normalized_global_phase: GlobalPhaseCapabilities | None Return standalone phase requirements in the extended form.

• pauli_realizations: frozenset[PauliEvolutionRealization]

• pauli_time: ScalarCapabilities

• predicates: ScalarCapabilities

• primitive_gates: frozenset[GateKind]

• supports_dynamic_if: bool

• supports_dynamic_while: bool

• supports_reset: bool

Methods¶

native_semantic_op¶

def native_semantic_op(self, key: SemanticOpKey) -> NativeSemanticOpCapabilities | None

Return the native declaration for one semantic operation.

Parameters:

Returns:

NativeSemanticOpCapabilities | None — NativeSemanticOpCapabilities | None: Matching declaration, or NativeSemanticOpCapabilities | None — None when the target has no native realization.

CircuitEngineEmitPass [source]¶

class CircuitEngineEmitPass(EmitPass[ArtifactT])

Lower, legalize, verify, and materialize a circuit-family plan.

The pass runs the three phases in order and never interleaves them: shared lowering produces engine-neutral circuit IR, target legalization rewrites it under the materializer’s declared capabilities and the compilation policy, target verification proves the result, and only then does the materializer convert it mechanically.

Parameters:

Constructor¶

def __init__(
    self,
    materializer: CircuitMaterializer[ArtifactT],
    bindings: dict[str, Any] | None = None,
    parameters: list[str] | None = None,
    policy: CompilationPolicy | None = None,
) -> None

Initialize a circuit-family lowering and materialization pass.

Parameters:

Attributes¶

• materializer

• parameter_names

• policy

Methods¶

run¶

def run(self, input: ProgramPlan) -> ExecutableProgram[ArtifactT]

Lower, legalize, verify, and materialize every quantum segment.

Parameters:

Returns:

ExecutableProgram[ArtifactT] — ExecutableProgram[ArtifactT]: Engine-native executable structure.

Raises:

• TargetCapabilityError — If a legalized segment still requires a capability the target does not declare.

• ValueError — If a legalized segment fails structural verification.

CircuitGateEmitter [source]¶

class CircuitGateEmitter

Emit primitive operations into engine-neutral circuit IR.

Attributes¶

• measurement_mode: MeasurementMode Return native measurement mode for explicit circuit IR.

Methods¶

append_gate¶

def append_gate(
    self,
    circuit: CircuitBuilder,
    gate: ReusableCircuit,
    qubits: list[int],
) -> None

Append a reusable circuit call.

Parameters:

circuit_to_gate¶

def circuit_to_gate(
    self,
    circuit: CircuitBuilder | CircuitProgram,
    name: str = 'U',
) -> ReusableCircuit

Freeze a circuit as a reusable circuit value.

Parameters:

Returns:

ReusableCircuit — Reusable body without target-native state.

combine_symbolic¶

def combine_symbolic(
    self,
    kind: BinOpKind,
    lhs: ScalarExpr | bool | int | float,
    rhs: ScalarExpr | bool | int | float,
) -> BinaryExpr | None

Combine symbolic operands without creating engine expressions.

Parameters:

Returns:

BinaryExpr | None — BinaryExpr | None: Target-neutral expression, or None for an unsupported operation kind.

create_circuit¶

def create_circuit(self, num_qubits: int, num_clbits: int) -> CircuitBuilder

Create an empty circuit IR builder.

Parameters:

Returns:

CircuitBuilder — Empty engine-neutral builder.

create_parameter¶

def create_parameter(self, name: str) -> ParameterExpr

Create a target-neutral runtime parameter expression.

Parameters:

Returns:

ParameterExpr — Parameter reference preserved until materialization.

emit_barrier¶

def emit_barrier(self, circuit: CircuitBuilder, qubits: list[int]) -> None