mimiqcircuits.backends.passes

Optimization-pass framework.

A pass transforms a Circuit before evolution; the PassPipeline runs them in order and tracks qubit permutations so amplitude and expectation queries can be unscrambled back to the user’s original qubit space at the end.

Parameters travel over the wire (to remote backends) through a JSON-safe ADT, PassParam, instead of a loose dict: the tagged variants preserve type information that a plain dict would silently lose.

Custom passes subclass AbstractPass and implement spec() (a declarative PassSpec) and apply() (the actual rewrite). See Implementing a Custom Backend for a worked example.

Functions

apply_passes(pipeline, ctx, circuit)	Run pipeline against circuit.
invert_perm(perm)	Inverse of a 1-based permutation.
to_pass_param(x)	Coerce a common Python value into a PassParam.

Classes

AbstractPass()	Base class for circuit-transformation passes.
PBool(value)
PDict(items)
PFloat(value)
PInt(value)
PList(items)
PStr(value)
PSym(value)	Pass parameter that is semantically a Symbol (Julia) or enum.Enum-like in Python.
PassContext([backend, rng, bitstrings, features])	Inputs a pass needs but should not fetch from global state.
PassParam()	Base class for the JSON-safe sum used to serialise pass parameters.
PassPipeline([passes])	An ordered, iterable sequence of passes.
PassResult([qubit_permutation, metadata])	Side effects returned from AbstractPass.apply().
PassSpec(name[, parameters, requires, conflicts])	Declarative summary of a pass.

Exceptions

RemotePassOrderError(backend_name)	Raised when an ordered pipeline is submitted to a remote backend that does not advertise the "pass_order_honored" capability while strict_pass_order=True.
UnacceptedPassError(backend_name, pass_name)	Raised when a pipeline contains a pass the backend rejects.

class mimiqcircuits.backends.passes.PassParam

Bases: object

Base class for the JSON-safe sum used to serialise pass parameters.

The tagged variants (PStr, PInt, PFloat, PBool, PSym, PList, PDict) keep type information a plain dict would lose on the wire — e.g. "greedy" (a PStr) must not silently degrade and come back as a PSym. Equality is tag-sensitive: PSym("x") != PStr("x").

class mimiqcircuits.backends.passes.PStr(value: 'str')

Bases: PassParam

value: str

__init__(value)

class mimiqcircuits.backends.passes.PInt(value: 'int')

Bases: PassParam

value: int

__init__(value)

class mimiqcircuits.backends.passes.PFloat(value: 'float')

Bases: PassParam

value: float

__init__(value)

class mimiqcircuits.backends.passes.PBool(value: 'bool')

Bases: PassParam

value: bool

__init__(value)

class mimiqcircuits.backends.passes.PSym(value)

Bases: PassParam

Pass parameter that is semantically a Symbol (Julia) or enum.Enum-like in Python. Distinct from PStr at the tag level.

value: str

__init__(value)

class mimiqcircuits.backends.passes.PList(items: 'tuple[PassParam, ...]')

Bases: PassParam

items: tuple[PassParam, ...]

__init__(items)

class mimiqcircuits.backends.passes.PDict(items: 'tuple[tuple[str, PassParam], ...]')

Bases: PassParam

items: tuple[tuple[str, PassParam], ...]

__init__(items)

mimiqcircuits.backends.passes.to_pass_param(x)

Coerce a common Python value into a PassParam.

The bool-before-int check is load-bearing: bool is a subclass of int in Python, so isinstance(True, int) is True and reversing the order would tag every boolean as PInt.

class mimiqcircuits.backends.passes.PassSpec(name, parameters=(), requires=(), conflicts=())

Bases: object

Declarative summary of a pass.

Used for equality / memoisation (two passes with the same spec have the same hash and compare equal), for remote dispatch (the spec is the only thing shipped over the wire), and for observability. Equality is structural.

requires names other passes that must run before this one; conflicts names passes that cannot coexist with this one in the same pipeline. Both are advisory.

name: str

parameters: tuple[tuple[str, PassParam], ...] = ()

requires: tuple[str, ...] = ()

conflicts: tuple[str, ...] = ()

static from_dict(name, parameters=None, requires=(), conflicts=())

__init__(name, parameters=(), requires=(), conflicts=())

class mimiqcircuits.backends.passes.PassResult(qubit_permutation=None, metadata=<factory>)

Bases: object

Side effects returned from AbstractPass.apply().

qubit_permutation is None when the pass leaves qubit indices unchanged. Any pass that does relabel qubits must return the relabel here so the pipeline can compose permutations and un-shuffle downstream outputs.

metadata is free-form pass-specific information (timings, gate counts, …) surfaced for observability.

qubit_permutation: list[int] | None = None

metadata: dict[str, Any]

__init__(qubit_permutation=None, metadata=<factory>)

class mimiqcircuits.backends.passes.PassContext(backend=None, rng=<factory>, bitstrings=<factory>, features=<factory>)

Bases: object

Inputs a pass needs but should not fetch from global state.

backend is the Backend the pipeline is compiling for, or None for backend-agnostic runs. rng is the dedicated pass-internal RNG. bitstrings are user-supplied amplitude targets in the original qubit space; the pipeline rewrites them into post-pass space as permutations compose. features are detected on the input circuit and filter passes via AbstractPass.preserves().

backend: Any | None = None

rng: Random

bitstrings: list

features: set[str]

__init__(backend=None, rng=<factory>, bitstrings=<factory>, features=<factory>)

class mimiqcircuits.backends.passes.AbstractPass

Bases: ABC

Base class for circuit-transformation passes.

Subclasses implement:

• spec() — return a PassSpec describing the pass (used for equality, serialisation, and remote dispatch).

• apply() — return (new_circuit, PassResult).

• preserves() — override when the pass breaks a circuit feature; the default returns True for every feature. The pipeline filters passes by feature when the input circuit has a feature that the pass must preserve.

Recognised feature tokens: "feed_forward", "midcircuit_measure", "parametric", "loss", "exact_equivalence", "strict_qubit_count".

abstract spec()

abstract apply(ctx, circuit)

preserves(feature)

class mimiqcircuits.backends.passes.PassPipeline(passes=<factory>)

Bases: object

An ordered, iterable sequence of passes.

Run via apply_passes(), which composes each pass’s qubit_permutation into a single permutation. Callers use the inverse of that permutation to map samples and Amplitude / ExpectationValue results back to the user’s original qubit space.

passes: list[AbstractPass]

__init__(passes=<factory>)

exception mimiqcircuits.backends.passes.UnacceptedPassError(backend_name, pass_name)

Bases: Exception

Raised when a pipeline contains a pass the backend rejects.

The backend’s Backend.accepts_pass() is the gate; the pipeline fails loudly rather than silently dropping a pass the user explicitly requested.

__init__(backend_name, pass_name)

exception mimiqcircuits.backends.passes.RemotePassOrderError(backend_name)

Bases: Exception

Raised when an ordered pipeline is submitted to a remote backend that does not advertise the "pass_order_honored" capability while strict_pass_order=True.

Pass strict_pass_order=False to opt into an unordered submission (recognised passes are translated into the server’s flat option set; unrecognised passes are dropped with a warning).

__init__(backend_name)

mimiqcircuits.backends.passes.invert_perm(perm)

Inverse of a 1-based permutation.

mimiqcircuits.backends.passes.apply_passes(pipeline, ctx, circuit)

Run pipeline against circuit.

Returns (transformed_circuit, composed_permutation, per_pass_results). composed_permutation is None when every pass left qubit indices unchanged.

Raises UnacceptedPassError if the backend rejects any pass. When the backend reports delegates_pass(p) is True the pass is not run here: the pipeline records a marker result and the backend handles the pass natively inside its compile or evolve.