Extending NWQLib¶

This page lists the classes and functions for adding a method: the Method base class and its hooks, the checker and registry for a new method, the Program (NWQLib's description of a circuit as named steps), the blocks a Program calls, the readouts it requests and the hooks that save its data. Add a Method states every requirement of a Method, and Run your own circuit builds the smallest Method step by step.

from nwqlib.algorithms import AlgorithmDescriptor, ApplicabilityError, Method
from nwqlib.algorithms.authoring import MethodCase, check_method
from nwqlib.blocks import SelectedConstruction, lower_qiskit, select_preparation
from nwqlib.ir import (
    Allocate, BlockCall, Definition, Measure, Program, Register, Sequence,
)

The Program records and expressions import from nwqlib.ir, the block functions and records from nwqlib.blocks, and Experiment, ObservationSpec, ReadoutDetails, ObservationPoint, ObservableEstimateSpec, ReductionContext, Reducer, registered_reducer, Realization and RandomStreams from nwqlib.core.planning. PreparedHandle, ObservationChunk, Histogram, PreparedArtifact and ReducedValues import from nwqlib.execution, AmplitudeReadout from nwqlib.amplitudes, InputRef from nwqlib.core.records, MethodCase and check_method from nwqlib.algorithms.authoring, and the registry entries from nwqlib.algorithms.

A new Method provides a case() function that returns a MethodCase, and check_method runs it. The reference Hadamard Method lives in the repository's test suite, tests/_hadamard_method.py, and is not part of the installed package. In a source checkout with tests/ on the import path, its case passes the check:

from nwqlib.algorithms.authoring import check_method
from _hadamard_method import case

report = check_method(case())
print(report["status"], report["method"])
# CONFORMANT example.hadamard_pauli_expectation

From a shell, python -m nwqlib check-method my_methods:case runs the same check on the case() of your module my_methods.

Task	Entries
Write the Method class	`Method`, `AlgorithmDescriptor`, `ApplicabilityError`
Tie a Plan and a Result to their inputs and data	`Plan._bind`, `Result._attach`, `Result.validate_plan`
Inspect a prepared circuit and its resources	`PreparedHandle`
Check a Method against its case	`MethodCase`, `check_method`
Register a Method and resolve it by name	`Registration`, `AlgorithmRegistry`, `direct_method`
Describe the circuit as a Program	`Program`, registers and block signatures, nodes
Give a Program named parameters and expressions	`Parameter`, `Expression`
Make the blocks a Program calls and build the Qiskit circuit	`select_preparation`, `transform_block`, `SelectedConstruction`, `lower_qiskit`
Request readouts and read the observations	`Experiment`, `ObservationSpec`, `ObservationChunk`, `Histogram`
Save and reload a Method's data	`ArchiveFiles`, `write_blocks`, `read_blocks`

Implement a method¶

Subclass Method, give it a descriptor, and implement plan and analyze. The other hooks have defaults. Plan and Result have four protected hooks that a Method's code calls or overrides: Plan._bind, Result._attach, Result._validate_common_plan and Result._summary_lines. They keep each input and its data tied to the Plan and run no extra computation, and Supported protected extension hooks states what each must do. A Method's Result type overrides validate_plan, and a new Problem type defines default_output.

Method ¶

Bases: Record

Base class of every method: an immutable configuration that plans, runs and analyzes one kind of problem.

Subclass it to add a method. Declare the class attribute descriptor: ClassVar[AlgorithmDescriptor] and the method's configuration fields, and implement plan and analyze. Users pass an instance as method= to solve, plan or compare. A Method is kept separate from the Problem it solves, so one problem can be approached with different initial states, trial spaces, degrees or estimators and compared on equal terms. A Method is an immutable Record, so its content hash enters every Plan it makes, and changing a field gives a different Plan. Running, preparation, submission, saving and reports call the hooks below and never branch on the method's family, so a new Method needs no change elsewhere in NWQLib. Add a Method states every requirement, including the protected hooks of Plan and Result below, and Run your own circuit shows the smallest Method.

Hooks a Method implements or may override:

plan: choose and bind the Plan. Required.
analyze: turn existing run data into the Result. Required.
prepare and execute: defaults for a fixed set of circuits. A Method that chooses later circuits from earlier results overrides them.
prepare_all_refusal: why settings="all" cannot be served, asked before a Run exists.
query_catalog_reason: why the Plan's experiments are templates of queries whose parameter values the iteration chooses, asked by the resource estimate of a whole Plan.
error_model: the known and unavailable error sources of a Plan.
verify and recover_analysis: explicit extra operations, unavailable by default.
reduction_allowance(self, plan, point, *, observation, width, run) -> int, required when a Plan reduces data while it is collected. It receives the Plan, the point's Realization, its resolved trajectory ObservationSpec, the Program's logical width and the Run. It checks the reduction's workspace, raises ValueError if the point exceeds the limit, and returns the remaining nonnegative work allowance in the registered reducers' work units. It reads the work already used without changing it. The base Method supplies no implementation.
before_submit: check data collection before its submission is recorded.
validate_point, specialize_experiment and selected_kernels: check and derive one resolved point without planning again.

Attributes:

descriptor (AlgorithmDescriptor) –

Class attribute that every subclass sets: the AlgorithmDescriptor.

plan ¶

plan(problem, *, output, execution, shots, rng, accuracy=None)

Choose the circuits and readout for a problem and return the bound Plan.

nwqlib.plan calls it. The Plan must keep the original problem, this Method, the output, the execution mode, the requested accuracy and the state of each named random stream after the planning draws. nwqlib.plan rejects a Plan that replaced the problem, Method or output object, or whose random state or accuracy differs. accuracy is a requested criterion, and the Plan must not record it as an achieved error bound. Raise ApplicabilityError when this Method cannot solve the problem or output.

Parameters:

problem (Record) –

The problem.
output (Record) –

The requested output.
execution (str) –

The requested execution, such as "quantum" or "classical".
shots (int | None) –

Requested shots. None selects exact readout or the Method's default. Exact readout provides probabilities, Pauli expectation values, amplitudes or classically computed scalars without shot sampling. Numerical errors can remain.
rng (RandomStreams) –

The Plan's named random streams. Draw from them, so that one seed reproduces the same choice.
accuracy (Accuracy | None, default: None ) –

Requested accuracy criterion. It is passed only when the caller gives one.

Returns:

plan ( Plan ) –

The bound Plan.

analyze ¶

analyze(plan, data, *, settings)

Turn the collected data of a Plan into its Result, with explicit settings and without collecting new data.

Result.analyze and the end of a Run call it. Return an instance of the Method's Result class computed from this Plan and the exact data used. The caller attaches it with Result._attach, which runs the supported Plan and data checks, including validate_plan, so analyze need not call validate_plan itself. A Result that analyze has already attached to the same Plan and data is accepted as well.

Parameters:

plan (Plan) –

The Plan.
data (RunData) –

The collected data.
settings (dict) –

Analysis settings.

Returns:

result ( Result ) –

The Result for plan and data, attached or not yet attached.

prepare ¶

prepare(plan, *, run, settings='first')

Prepare circuits of the Plan in the Run without submitting them.

The default prepares the first setting, or every setting for settings="all". A Method that chooses its next circuit from earlier results overrides it to prepare that circuit. NWQLib passes settings on every call, and passes "all" only after prepare_all_refusal returned None.

Parameters:

plan (Plan) –

The Plan.
run (Run) –

The Run that holds the prepared circuits.
settings (str, default: 'first' ) –

"first" or "all".

prepare_all_refusal ¶

prepare_all_refusal()

Return why prepare(plan, settings="all") cannot serve this Method, or None when it can.

nwqlib.prepare asks before it creates a Run, so a refusal leaves no Run folder. A Method whose later settings depend on earlier outcomes overrides it to return its reason and what can be prepared instead. Otherwise the inherited preparation would prepare, and count against the Run's limits, every setting of the Plan, including ones the Method never submits. The default returns None.

Returns:

reason ( str | None ) –

The reason, or None.

query_catalog_reason ¶

query_catalog_reason()

Return why the experiments of this Method's Plans are templates of queries rather than the workload of a Run, or None.

A Method overrides it when one experiment of its Plan can serve any number of queries whose parameter values its iteration chooses from earlier outcomes, so that the counts of the Plan's construction are not the totals of a Run. The reason says why and how to estimate one query. By returning a reason, the Method asserts that every query it runs is a point of one experiment of the Plan, bound by Plan.resolve, and that the construction of that point keeps the experiment's measurement batch, observation kind and repetitions. The resource estimate of a whole Plan, from nwqlib.estimate(plan) with or without a profile, compare or scan, then passes the reason to nwqlib.resources.estimate as catalog. That estimate reports a count as zero only when no query can contribute to it. It leaves the other counts unavailable with the reason, except root_setting_declarations and root_repetitions, the setting declarations and body repetitions of a MeasurementBatch at the root of the Program, which keep their values. It labels each width and byte peak as a footprint of the templates. The forecast of one point with every parameter value bound estimates that point's construction without the reason. The default returns None, and the resource estimate of a Plan adds up its construction as the workload of a Run.

Returns:

reason ( str | None ) –

The reason, or None.

execute ¶

execute(plan, *, run)

Advance the Run's work and return the Result when it is complete, or None while it is pending.

The default runs the Plan's experiments in order, one attempt each, never submits an existing attempt again, and analyzes once every experiment has its data. A Method that chooses later circuits from earlier results overrides it.

Parameters:

plan (Plan) –

The Plan.
run (Run) –

The Run.

Returns:

result ( Result | None ) –

The Result, or None while work is pending.

error_model ¶

error_model(plan)

Return the known and unavailable error sources of a Plan, each with the quantity and unit it refers to.

The default returns the error model recorded in the Plan (plan.error_model).

Parameters:

plan (Plan) –

The Plan.

Returns:

model ( ErrorModel | None ) –

The error model, or None.

verify ¶

verify(plan, result, *, checks)

Run checks the caller selected explicitly on a Result, at their own cost.

Result.verify(checks=...) calls it. Override it only for checks the Method supports. The default refuses.

Parameters:

plan (Plan) –

The Plan.
result (Result) –

The Result to check.
checks (object) –

The selected checks, as Result.verify received them.

Raises:

ValueError –

Always, in the default.

recover_analysis ¶

recover_analysis(plan, *, run)

Finish an analysis that a saved Run interrupted, without submitting earlier work again.

Only a Method that saves an interrupted analysis overrides it. The default raises.

Parameters:

plan (Plan) –

The Plan.
run (Run) –

The reopened Run.

Raises:

ValueError –

Always, in the default.

before_submit ¶

before_submit(plan, prepared, *, run)

Check the prepared circuits or classical routines (host kernels in the code) of one submission before the Run records it, and raise to refuse it.

The Run calls it with the tuple of PreparedHandle objects that the submission sends, before it records the submission, so a refusal leaves no attempt behind. The default accepts every submission.

Parameters:

plan (Plan) –

The Plan.
prepared (tuple[PreparedHandle, ...]) –

The prepared work of the submission.
run (Run) –

The Run that submits them.

validate_point ¶

validate_point(plan, experiment, values)

Check the parameter values of one experiment point against the Method's own rules, and raise to refuse the point.

It runs when Plan.resolve or a preparation resolves a point, after each value has passed the checks of its Program parameter and, in a measurement batch, of its range axis. The default accepts every point.

Parameters:

plan (Plan) –

The Plan.
experiment (Experiment) –

The experiment of the point.
values (Mapping[str, object]) –

Read-only mapping from each bound Program parameter name to its value.

specialize_experiment ¶

specialize_experiment(plan, experiment, values)

Return the experiment of one point with its readout fitted to the point's parameter values.

It is called after validate_point, with the same values. A Method whose readout depends on those values, such as the labels a point measures, returns a revised Experiment with the same name, setting, batch and setting index. The default returns the experiment unchanged.

Parameters:

plan (Plan) –

The Plan.
experiment (Experiment) –

The planned experiment of the point.
values (Mapping[str, object]) –

Read-only mapping from each bound Program parameter name to its value.

Returns:

experiment ( Experiment ) –

The experiment to run at this point.

selected_kernels ¶

selected_kernels(plan, experiment, program)

Return the declarations of the classical routines that one point runs on this computer.

It is called when the construction of a point is built. A Method may revise a declaration of the Plan's construction.kernels for the point, for example its scalar labels and its work per invocation, but each returned declaration must be a revision of the Plan's declaration of the same name, with the same implementation, inputs and dependencies, so that a point cannot substitute another routine or another input. The default returns the Plan's declarations unchanged.

Parameters:

plan (Plan) –

The Plan.
experiment (Experiment) –

The experiment of the point.
program (Program) –

The point's Program, with every parameter bound.

Returns:

kernels ( tuple[SelectedKernel, ...] ) –

The declarations of the point.

AlgorithmDescriptor ¶

Bases: Record

What a Method declares about itself: name, version, the problems and outputs it handles, its coverage, limitations and references.

Build it with keyword arguments, for example AlgorithmDescriptor(method="hadamard_expectation", version="1", problem_families=("expectation",)), and set it as the class attribute descriptor of a Method subclass. method and version are required. The descriptor states scope and references. Whether a Method applies to a given problem is decided by its plan, and a descriptor neither proves that nor qualifies a backend.

Attributes:

method (Text) –

Required. Registered method name, such as "lchs".
version (Text) –

Required. Method version. The pair (method, version) identifies the implementation.
problem_families (tuple[Text, ...]) –

Default (). Problem kinds the Method declares, such as "linear_dynamics".
output_families (tuple[Text, ...]) –

Default (). Output kinds it declares, such as "solution".
access_families (tuple[Text, ...]) –

Default (). Input representations it declares, such as "dense".
resource_coverage (tuple[Text, ...]) –

Default (). What its resource estimates cover.
evidence_coverage (tuple[Text, ...]) –

Default (). What its error evidence covers.
limitations (tuple[Text, ...]) –

Default (). Known limitations stated to users.
references (tuple[Source, ...]) –

Default (). Sources of the implemented method, such as its paper.
maintenance (Text) –

Default "experimental research method". Maintainer or status label.

source ¶

source

The Source that names this method and version.

Registrations and saved results use it to identify the implementation.

ApplicabilityError ¶

Bases: ValueError

Raised when a configured Method cannot solve the given problem or output.

A Method's plan raises it, for example for an unsupported problem type, input representation or output. It is a ValueError.

RandomStreams ¶

RandomStreams(seed=None)

The two random streams of a Plan, one for the Method's choices and one for backend execution seeds, from one recorded seed.

Method.plan receives it as rng, and a Method draws its random choices from rng.method. The root SeedSequence spawns two independent PCG64 streams. The method stream serves the Method's random choices (for example a default random initial state). The backend stream only generates execution seeds. Keeping them apart means that the number of backend seeds drawn never shifts the method's draws, so one seed reproduces the same choices however often the Plan is executed. snapshot records the exact generator states in the Plan, and restore resumes them without replaying earlier draws.

Parameters:

seed (int | None, default: None ) –

Nonnegative integer root seed of numpy.random.SeedSequence, or None for fresh entropy.

Attributes:

method –

The numpy.random.Generator of the Method's draws.
backend –

The numpy.random.Generator of the execution seeds.

Raises:

ValueError –

If seed is neither None nor a nonnegative integer.

nwqlib.problems.records.ProblemRecord.default_output ¶

default_output()

Return the output that plan and compare use when no output is given.

Each built-in Problem returns its default output, such as Eigenvalue() for an Eigenproblem. A Problem type of a Method author defines its own, as Run your own circuit shows. This base raises, so a Problem without its own default needs an explicit output.

Returns:

output ( OutputRecord ) –

The default output.

Raises:

TypeError –

Always, on this base.

nwqlib.core.planning.Plan._bind ¶

_bind(*, blocks=(), **native)

Bind the planned circuit blocks and named live inputs (in-memory objects that are not part of the Plan's saved record) to this Plan once, and return the Plan.

A supported hook for Method authors (Add a Method). It compiles nothing, measures nothing and does not rebuild the inputs. A Method's load_archive hook restores the same blocks with it instead of planning again.

Parameters:

blocks (tuple, default: () ) –

The live circuit blocks of the construction.
**native (object, default: {} ) –

Named live inputs that the Method keeps with the Plan.

Returns:

plan ( Plan ) –

This Plan.

Raises:

ValueError –

If live data is already bound to this Plan.

nwqlib.core.planning.Plan.resolve ¶

resolve(experiment: str, *, bindings: tuple[Binding, ...] = ()) -> Realization

Bind the open Program parameters of one experiment, without changing the Plan.

Only values that pass the Program's checks are bound. The result depends on the Plan and the bindings alone, and nothing is prepared.

Parameters:

experiment (str) –

Name of one of this Plan's experiments.
bindings (tuple[Binding, ...], default: () ) –

Values for Program parameters that the Plan and the experiment's setting leave unbound, such as a point of a range axis. A value that differs from an existing binding is rejected.

Returns:

realization ( Realization ) –

The Plan's content hash, the experiment name and every parameter value, in parameter-name order.

Realization ¶

Bases: Record

One experiment of a Plan with every parameter value bound, referring to the Plan by its content hash.

Plan.resolve returns it, and PreparedArtifact.realization records the one a preparation used. It refers to the Plan by plan_id and does not contain it, so a Plan with N experiments is stored once, not once in each of its N Realization records. Loading a Realization alone does not check it against its Plan. validate_plan(plan) checks that plan is the referenced Plan and that the bindings are the ones Plan.resolve returns, and returns the experiment.

Attributes:

plan_id (ContentID) –

Content hash of the Plan.
experiment (Text) –

Name of one of the Plan's experiments.
bindings (tuple[Binding, ...]) –

Default (). Every Program parameter value of the experiment, in parameter-name order.

nwqlib.core.analysis.Result._attach ¶

_attach(plan, data)

Attach the Plan and run data to a Result once, and return the Result.

A supported hook for Method authors (Add a Method). It checks that the Result names this Plan and these observations, that every part of the observations it uses is in the data, and calls validate_plan before attaching. It measures nothing and creates no missing observation.

Parameters:

plan (Plan) –

The Plan the Result was computed from.
data (RunData) –

The run data the Result was computed from.

Returns:

result ( Result ) –

This Result, with plan and data attached.

Raises:

ValueError –

If the Result names another Plan or other observations, uses an observation absent from the data, or is already attached to another Plan or data.

nwqlib.core.analysis.Result.validate_plan ¶

validate_plan(plan)

Check that this Result belongs to plan, before the Plan is attached.

The base check compares plan_id with the Plan's content hash. A Method's Result type overrides it to call _validate_common_plan and then check its own relation between the Plan and its fields (Add a Method).

Parameters:

plan (Plan) –

The Plan to check against.

Raises:

ValueError –

If the Result names another Plan.

nwqlib.core.analysis.Result._validate_common_plan ¶

_validate_common_plan(plan, plan_type)

Check the Plan type, the Plan's content hash and the Method that analyzed the Result.

A supported hook for Method authors. Call it from validate_plan before checking the Method's own relation between the Plan and the Result (Add a Method).

Parameters:

plan (Plan) –

The Plan to check against.
plan_type (type) –

The exact Plan class that the Method produces.

Raises:

TypeError –

If plan is not exactly of type plan_type.
ValueError –

If the Result names another Plan, or its origin names another Method than the Plan's.

nwqlib.core.analysis.Result._summary_lines ¶

_summary_lines()

Return the first lines of print(result), built from the values the Result holds.

A supported hook for Method authors (Add a Method). An override must not measure, reanalyze, load arrays or recompute error evidence.

Returns:

lines ( tuple[str, ...] ) –

The lines.

PreparedHandle ¶

PreparedHandle()

The prepared circuit of one experiment for one backend, with its preparation record.

Submission uses exactly this circuit, so the circuit that executes is the one the preparation record describes. After Run.release_native the circuit is dropped from memory and read back from the Run's saved QPY file (Qiskit's binary circuit format) when needed, without building or transpiling it again. Method authors receive handles from the Run's preparation calls. The fields below are read-only.

Attributes:

record (PreparedArtifact) –

The preparation record (PreparedArtifact), with the readout and the backend.
realization (Realization) –

The experiment's concrete parameter values and construction (Realization).

inspect_circuit ¶

inspect_circuit()

Return a copy of the prepared Qiskit circuit.

QuantumCircuit.copy gives the copy its own instruction list and its own operation objects (checked against the installed Qiskit), so changing the copy leaves the circuit that executes unchanged.

Returns:

circuit ( QuantumCircuit ) –

The copy.

Raises:

ValueError –

If this preparation is a classical computation (execution="host_kernel") without a circuit.

inspect_resources ¶

inspect_resources(*, transpile_options=None, max_operations=100000, max_bytes=DEFAULT_MAX_BYTES)

Count the operations of the prepared circuit, without changing or running it.

Each top-level instruction of the circuit counts once under its operation name, measurements, barriers, simulator saves, Clifford objects and user-defined gates included, and names are reported as they are. Gate definitions and control-flow bodies are not expanded. With transpile_options, a transpiled copy is counted instead, with the simulator saves removed first. The circuit that executes is never changed or run.

Parameters:

transpile_options (dict | None, default: None ) –

Options for Qiskit's transpile. None, the default, counts the prepared circuit as it is.
max_operations (int, default: 100000 ) –

Default 100_000. Largest number of operations of the circuit, and of its transpiled copy.
max_bytes (int, default: DEFAULT_MAX_BYTES ) –

Default 10 GB (decimal, 10_000_000_000). Largest size of the known inspection data and options. It does not bound the compiler's own memory.

Returns:

inventory ( dict ) –

circuit (a text description of the counted circuit), basis (the gate basis label), compiler (Qiskit version and options, or None), operations (count by name), total_operations, num_qubits, num_clbits and depth (Qiskit's default depth, which skips directives such as barriers and simulator saves).

Raises:

ValueError –

If this preparation has no circuit or a limit is exceeded.

Check and register a method¶

MethodCase ¶

MethodCase(method: Method, problem: Record, evaluate: Callable[[Plan], Result], accepts: Callable[[Result], bool], invalid_result: Callable[[Result], Result], output: Record | None = None, execution: str = 'quantum', shots: int | None = None, seed: int | None = None)

One small test case for a new Method: a problem, how to run it, an independent check of the answer and a deliberately wrong answer.

Build it with keyword arguments, usually in a case() function next to the Method, and pass it to check_method or run python -m nwqlib check-method my_methods:case. method, problem, evaluate, accepts and invalid_result are required. The checker computes no reference answer of its own. accepts holds the independent expected relation, and evaluate decides whether the case prepares and submits circuits or analyzes data supplied with it. The Method's archive hooks are trusted code and run under the ordinary archive byte limits. The reference Hadamard Method, tests/_hadamard_method.py, defines such a case().

Parameters:

method (Method) –

The configured Method under test.
problem (Record) –

The problem of this case.
evaluate (Callable[[Plan], Result]) –

Called with the Plan, returns that Plan's attached Result, for example by prepare, submit and run.wait().
accepts (Callable[[Result], bool]) –

Called with the Result, returns True when the independent expected relation holds, for example abs(result.value - 1.0) < 1e-12.
invalid_result (Callable[[Result], Result]) –

Called with the Result, returns a Result of the same class and Plan with a scientific field changed so that it is valid as a record but wrong for this Plan, for example result.revise(value=-1.0).
output (Record | None, default: None ) –

Requested output, or None for the problem's default.
execution (str, default: 'quantum' ) –

"quantum" or "classical".
shots (int | None, default: None ) –

Requested shots, or None for exact readout or the Method's default.
seed (int | None, default: None ) –

Seed of the Plan's random streams, or None for fresh entropy.

check_method ¶

check_method(case: MethodCase) -> dict

Check a new Method against its test case: the expected answer, the Plan checks and a saved-result round trip.

The check plans the case through the public plan, evaluates the Plan with the case's callback, and requires the case's independent relation to accept the Result. The Method's error_model must equal the Plan's, and its result_type must name the Result class. The wrong Result from invalid_result must be a valid record that the Method's validate_plan rejects. The original Result must save, reload unchanged and still pass the relation. The wrong-answer step shows that the Method's own Plan and Result check catches a scientifically wrong answer under the same Plan, which a record's own field checks cannot do. Nothing beyond the case's callback is computed, neither a reference solve nor extra circuits. "CONFORMANT" means this one case passed. It does not certify other inputs, physical accuracy, backend support or cost. The example at the top of Extending NWQLib runs it on the reference Hadamard Method.

Parameters:

case (MethodCase) –

The test case.

Returns:

report ( dict ) –

A dict with status ("CONFORMANT"), method (the descriptor's method name), plan_id, result_id, scope and qualification.

Raises:

TypeError –

If the case, the Method or its Result class does not meet the Method protocol.
ValueError –

If the expected relation, the wrong-answer check or the saved round trip fails.

Registration ¶

Registration(source: Source, factory: str, descriptor: AlgorithmDescriptor | None = None, method_type: type[Method] | None = None)

An entry that makes a Method findable by name and version: its Source and a trusted factory path.

Build it with keyword arguments, for example Registration(source=MyMethod.descriptor.source, factory="my_methods:MyMethod"), in a module that does not import the Method itself, and pass it to AlgorithmRegistry. source and factory are required. Building it imports nothing. A saved Source string never loads code. Only a registration in the running process does. Explicit trusted registration shows the metadata module of the reference Method.

Parameters:

source (Source) –

Source naming the method and version, as descriptor.source gives it.
factory (str) –

"module:attribute" path of a callable that returns the Method, called only by AlgorithmRegistry.resolve.
descriptor (AlgorithmDescriptor | None, default: None ) –

The Method's AlgorithmDescriptor when already known, with the same method and version as source. None avoids importing the Method to read it.
method_type (type[Method] | None, default: None ) –

The Method class when already known. Its descriptor must equal descriptor.

Raises:

ValueError –

If factory is not a module:attribute path, or the descriptor's method and version differ from source or from method_type.descriptor.
TypeError –

If method_type is not a Method subclass.

AlgorithmRegistry ¶

AlgorithmRegistry(registrations: Iterable[Registration] = ())

A list of trusted Method registrations that finds a Method by name and version and builds it on request.

Build it as AlgorithmRegistry((registration, ...)). Without registrations it is empty. discover lists the registrations without running any factory, and resolve runs only the factory of the requested Source. A registry is not a security sandbox, and a registration does not qualify a backend.

Parameters:

registrations (Iterable[Registration], default: () ) –

The registrations, at most one per method and version.

Raises:

ValueError –

If two registrations share a method and version.

discover ¶

discover() -> tuple[Registration, ...]

Return the registrations in method and version order, without importing any factory.

Returns:

registrations ( tuple[Registration, ...] ) –

The registrations.

resolve ¶

resolve(source: Source, *, expected_type: type[T] = Method, **configuration) -> T

Build the registered Method for a Source by calling its factory with the given configuration.

Only the factory of that Source runs, with exactly the configuration supplied, and no earlier configuration is reused. The built Method must match the registered method, version, descriptor and class.

Parameters:

source (Source) –

Source of the method and version, equal to the registered one.
expected_type (type, default: Method ) –

Class the result must be an instance of, which keeps a caller's concrete type.
**configuration (object, default: {} ) –

Keyword arguments for the factory, such as Method settings.

Returns:

method ( Method ) –

The configured Method.

Raises:

LookupError –

If no registration has this method and version.
ValueError –

If source differs from the registered Source, or the built Method differs from the registration.
TypeError –

If the built object is not a complete Method of expected_type.

builtin_registrations ¶

builtin_registrations() -> tuple[Registration, ...]

Return a registration for each built-in Method, without constructing or planning one.

It imports the built-in configuration modules, which can load NumPy, SciPy and their dependencies, but no quantum SDK. Installed extensions are not included. Their configuration fields, defaults and required fields come from each Method class's schema.

Returns:

registrations ( tuple[Registration, ...] ) –

The registrations, in method and version order.

third_party_registrations ¶

third_party_registrations() -> tuple[Registration, ...]

Return a registration for each installed nwqlib.algorithms entry point, without loading its code.

Each entry point must be named method@version, and its value is the factory path. The descriptor and Method class of these registrations stay None until code is loaded explicitly. builtin_registrations does not call this function, so installed extensions are found only when third_party_registrations is called.

Returns:

registrations ( tuple[Registration, ...] ) –

The registrations, sorted by method, version and factory.

Raises:

ValueError –

If an entry-point name is not method@version.

direct_method ¶

direct_method(method: object, *, expected_type: type[T] = Method) -> T

Check that an object is a complete Method and return it, without running a factory.

A complete Method has a descriptor and implements plan and analyze.

Parameters:

method (object) –

The object to check.
expected_type (type, default: Method ) –

Class the object must be an instance of.

Returns:

method ( Method ) –

The same object.

Raises:

TypeError –

If it is not an instance of expected_type, has no descriptor, or does not implement plan and analyze.

options_schema ¶

options_schema(registration: Registration) -> dict

Return the JSON schema of a registered Method's configuration, with its required fields and defaults.

nwqlib options METHOD prints it. The schema comes from the Method class (model_json_schema()), so no required input is guessed.

Parameters:

registration (Registration) –

A registration whose method_type is known.

Returns:

schema ( dict ) –

The JSON schema.

Raises:

ValueError –

If the registration's Method class is not loaded, as for an installed extension found by third_party_registrations. Select the extension's code explicitly in Python first.

Describe a circuit as a Program¶

A Program lists named nodes: register allocation, block calls, measurements, repeats and their order. It is checked when it is built. Describe a circuit as a Program explains the nodes and Program checks the rules of that check.

Program ¶

Bases: Record

A circuit described as named steps: registers, block calls, measurements and their order, checked when it is built.

Build it with keyword arguments and use it in a SelectedConstruction. root and definitions are required. Every node is a Definition with an ID, and nodes refer to each other by ID, so a shared body is stored once however often it runs, and the checking work grows with its distinct contexts rather than its run count. The root starts with no allocated registers or classical values. Registers still allocated at the end of the root stay available to code that uses the quantum output, while the body of a measurement batch must release its registers. Construction runs the full structural check of the declared effects, so an illegal lifecycle or a graph over its limits is rejected before anything uses the Program. Unresolved requirements, such as an unbound width, do not reject it but make it not ready.

One Program is the single description of a construction that the structural check, resource estimate, circuit building and readout all read, so a cost, a circuit and a readout cannot describe different constructions. Its content hash covers every table, binding and limit. Run your own circuit builds a Program around a supplied circuit, and Describe a circuit as a Program explains the nodes.

Attributes:

root (Text) –

Required. Definition ID of the root node.
definitions (tuple[Definition, ...]) –

Required. The Definition records.
expressions (tuple[Expression, ...]) –

Default (). Expression records that widths, counts and arguments refer to.
parameters (tuple[Parameter, ...]) –

Default (). Declared Parameter records.
constraints (tuple[ExprRef, ...]) –

Default (). Bool expressions that every bound point must satisfy.
registers (tuple[Register, ...]) –

Default (). Quantum Register records.
classical (tuple[ClassicalValue, ...]) –

Default (). ClassicalValue records.
signatures (tuple[BlockSignature, ...]) –

Default (). BlockSignature records of the blocks called.
bindings (tuple[Binding, ...]) –

Default (). Parameter values bound so far.
limits (AdmissionLimits) –

Default AdmissionLimits(). The AdmissionLimits on the stored structure and on the work of checking it.
premises (tuple[Text, ...]) –

Default (). Stated assumptions of the construction.
schema_version (Literal[2]) –

Fixed 2. Version of the saved record format.

Raises:

ValueError –

If the structure breaks a lifecycle rule, refers to an unknown ID, or exceeds limits.

Examples:

Allocate a two-qubit register and measure it.

>>> from nwqlib.ir import (Allocate, ClassicalValue, Definition, Measure,
...                        Program, Register, Sequence)
>>> program = Program(
...     root="main",
...     definitions=(
...         Definition(id="allocate", node=Allocate(wire="q")),
...         Definition(id="measure", node=Measure(wire="q", result="bits")),
...         Definition(id="main",
...                    node=Sequence(children=("allocate", "measure"))),
...     ),
...     registers=(Register(name="q", width=2),),
...     classical=(ClassicalValue(name="bits", dtype="bits", width=2),),
... )
>>> program.check_readiness().ready
True

check_readiness ¶

check_readiness() -> Readiness

Return the result of this Program's structural check.

The check runs once per Program object, when it is built, and its result is kept for later calls. Copies and unpickled Programs check again on first use. It covers every concrete rule and lists unresolved requirements as blockers. expression_evaluations + lifecycle_steps of the result is the checking work it measured.

Returns:

readiness ( Readiness ) –

The result of the check.

bind ¶

bind(**values)

Return a copy of the Program with parameter values bound, keeping shared bodies.

The copy runs the structural check again.

Parameters:

**values (int | Float64, default: {} ) –

Parameter values by name, an exact integer or a Float64.

Returns:

program ( Program ) –

The bound Program.

Raises:

ValueError –

If the bound Program fails the structural check.

select_experiment ¶

select_experiment(batch_id: str, setting_index: int, **axis_values)

Return a Program for one experiment of a measurement batch, without expanding any range or product.

The returned Program's root is the batch with the one selected setting and no axes. It keeps every definition that batch depends on, every global constraint and the register layout, and the selected values also bind the global constraints. It creates no observation or execution ID, because the original Program identifies the whole source graph. Use it before lower_qiskit, which builds the circuit of one static experiment, a Program that describes exactly one circuit.

Parameters:

batch_id (str) –

Definition ID of the measurement batch.
setting_index (int) –

Index of the setting.
**axis_values (int, default: {} ) –

One value for each range axis of the batch.

Returns:

program ( Program ) –

The Program of the selected experiment.

Raises:

ValueError –

If the batch, setting or axis values are invalid.

iter_definitions ¶

iter_definitions()

Return an iterator over the stored definitions, each once in declaration order, without expanding anything.

Returns:

definitions ( Iterator[Definition] ) –

The definitions.

Definition ¶

Bases: Record

One node of a Program with its ID. Nodes refer to each other by ID, so a shared body is stored once.

Build it as Definition(id="main", node=Sequence(children=(...))) and pass it in definitions= of a Program. Both arguments are required.

Attributes:

id (Text) –

Required. Unique ID within the Program.
node (Node) –

Required. One node: Sequence, Repeat, BlockCall, CoherentRegion, Allocate, Release, Measure, Reset, Branch, ClassicalStage, AdaptiveLoop, MeasurementBatch or Parallel.

Readiness ¶

Bases: Record

The result of a Program's structural check: what is still unresolved, and the checking work it took.

Program.check_readiness returns it. The fields below are read-only. A ready Program is structurally valid. It is not a check of the blocks' promised actions or an approval to run.

Attributes:

blockers (tuple[Text, ...]) –

Sorted unresolved requirements, such as an unbound width or an unknown block effect. Empty when the Program is ready.
expression_evaluations (NonnegativeInt) –

Expression evaluations of this check.
lifecycle_steps (NonnegativeInt) –

Other checking work units of this check, not quantum events or algorithm costs.

ready ¶

ready: bool

Whether no requirement is unresolved, that is, blockers is empty.

require_ready ¶

require_ready()

Return this result, or raise when a requirement is still unresolved.

Returns:

readiness ( Readiness ) –

This result.

Raises:

ValueError –

If blockers is not empty. The message lists them.

AdmissionLimits ¶

Bases: Record

Limits on the size of a Program's stored structure and on the work of checking it.

Pass it as limits= to Program. Every argument is optional. A caller can make a Program's metadata arbitrarily large or deep, and these limits make the structural check and the resource estimate reject it before their work or memory passes a fixed size. They limit the stored structure and the checking work, never the size of the workload the Program describes, and repeat counts and range lengths are not expanded. A Method with a max_admission_steps setting uses it as max_steps of its Programs, and Program checks explains how planning work is counted.

Attributes:

max_definitions (PositiveInt) –

Default 1_000_000. Positive limit on the stored definitions, expressions, parameters, registers, classical values and signatures together. This limit covers a sampled FixedGCIM plan with three basis states and a 20-qubit, 8,083-term molecular Hamiltonian in 1,285 measurement groups, with 11,565 circuits and 25,731 declarations when both the real and imaginary parts are measured, and real-only measurement needs fewer. It has over sixfold margin over the 161,691 declarations of singleton grouping (the Program inventory row of Engineering constants). Stored-field and checking-work limits apply independently, and no space is reserved from this limit alone.
max_depth (PositiveInt) –

Default 128, also the largest accepted value. Limit on the longest chain of references, which is also the recursion limit of the lifecycle check.
max_steps (PositiveInt) –

Default 100000. Positive limit on the checking work units of one check, and separately on the number of stored fields.
max_integer_bits (PositiveInt) –

Default 4096. Positive limit on the bit length of any integer the check accepts. A sum or product computed during the check can exceed it by one bit before the check rejects it.

Registers, values and block signatures¶

Register ¶

Bases: Record

A quantum register of a Program, allocated explicitly by an Allocate node.

Build it as Register(name="q", width=2) and pass it in registers= of a Program. name and width are required.

Attributes:

name (Text) –

Required. Register name, used by ports, allocation and measurement.
width (Integer) –

Required. Number of qubits, an integer or an ExprRef.
location (Text) –

Default "logical_device". Device location on which the resource estimate places the register.
role (Literal['system', 'clean_ancilla', 'dirty_ancilla']) –

Default "system". "system", "clean_ancilla" or "dirty_ancilla", reported separately in memory and qubit counts.

ClassicalValue ¶

Bases: Record

A named classical value of a Program, such as measured bits or a computed scalar.

Build it as ClassicalValue(name="bits", dtype="bits", width=2) and pass it in classical= of a Program. name and dtype are required. Bits have a positive width, and the other types have none.

Attributes:

name (Text) –

Required. Value name.
dtype (Literal['bits', 'bool', 'integer', 'real']) –

Required. "bits", "bool", "integer" or "real".
width (Integer | None) –

Default None. Number of bits, positive and required for "bits", None otherwise.

Raises:

ValueError –

If width is missing or not positive for bits, or given for another type.

BlockSignature ¶

Bases: Record

The declared interface of a block that a Program calls: its target action, ports and parameters.

Build it with keyword arguments, for example BlockSignature(name="h", target=source, quantum=(QuantumPort(name="system", width=1),)), and pass it in signatures= of a Program. name and target are required. A BlockCall names the signature, and the selected definition bound to it supplies the action, its declared costs and the circuit constructor. The signature declares an interface. It does not prove that an implementation performs the action.

Attributes:

name (Text) –

Required. Signature name, used by block calls and by the selected definition.
target (Source) –

Required. Versioned Source of the action a selection must implement.
quantum (tuple[QuantumPort, ...]) –

Default (). Ordered QuantumPort records.
parameters (tuple[Parameter, ...]) –

Default (). Scalar Parameter records with their domains.
interface (Literal['declared', 'unknown']) –

Default "declared". "unknown" keeps an undeclared block in the Program, which is then not ready.
coupling (Literal['joint', 'independent']) –

Default "joint", when the call may correlate its ports, or "independent" when it promises not to.
obligations (tuple[Text, ...]) –

Default (). Promises that the selected implementation must meet.

QuantumPort ¶

Bases: Record

A port of a block signature: a whole register the block acts on, with the state it needs and the effect it promises.

Build it as QuantumPort(name="system", width=2) and pass it in quantum= of a BlockSignature. name and width are required. A call maps each port, in signature order, to a register that no other port of the call uses. The zero state counts as coherent. A "unitary" effect keeps the register's coherence epoch (the generation counter that StateClaim defines) but clears a known zero state, and "preserve" promises that the state is restored exactly. A "zero" or "coherent" output asserts a newly prepared state, which the block's implementation must guarantee. An "unknown" effect makes the Program not ready and cannot satisfy a later state requirement.

Attributes:

name (Text) –

Required. Port name.
width (Integer) –

Required. Number of qubits, an integer or an ExprRef.
requires (Literal['live', 'zero', 'coherent']) –

Default "live". Input state the port needs: any allocated ("live") state, "zero" or "coherent".
ensures (Literal['unitary', 'preserve', 'zero', 'coherent', 'unknown']) –

Default "unitary". Effect on the register: "unitary", "preserve", "zero", "coherent" or "unknown".

parameter (Text) –

Required. Parameter name.
start (NonnegativeInt) –

Required. Nonnegative first value.
stop (NonnegativeInt) –

Required. Nonnegative end, excluded and greater than start.
step (NonnegativeInt) –

Default 1. Positive step.

Raises:

ValueError –

If the range is empty.

MetadataRef ¶

Bases: Record

A reference to method metadata attached to a setting, in a format the method defines. It is never decoded by the check.

Build it as MetadataRef(format=source, data=input_ref). Both arguments are required.

Attributes:

format (Source) –

Required. Source of the metadata format.
data (InputRef) –

Required. InputRef of the stored metadata.

Parameters and expressions¶

Parameter ¶

Bases: Record

A named integer or real parameter of a Program, with optional inclusive bounds.

Build it with keyword arguments, for example Parameter(name="steps", domain="integer", lower=1), and pass it in parameters= of a Program or a BlockSignature. name and domain are required. A real value is a finite binary64 number given as Float64.

Attributes:

name (Text) –

Required. Parameter name.
domain (Literal['integer', 'real']) –

Required. "integer" or "real".
lower (Value | None) –

Default None. Inclusive lower bound, an exact integer for an integer domain.
upper (Value | None) –

Default None. Inclusive upper bound, not below lower.

Raises:

ValueError –

If an integer domain has a non-integer bound, or lower exceeds upper.

admit ¶

admit(value)

Check a value against the parameter's domain and bounds, without rounding, and return it as a number.

Parameters:

value (int | Float64) –

An exact integer for an integer domain, or a Float64 for a real domain.

Returns:

value ( int | float ) –

The value as a number.

Raises:

ValueError –

If the value has the wrong type or lies outside the bounds.

Binding ¶

Bases: Record

A concrete value for one parameter, part of the content hash of the record that holds it.

Build it as Binding(parameter="steps", value=4) and pass it in bindings= of a Program, a Setting or a selected definition. Both arguments are required.

Attributes:

parameter (Text) –

Required. Parameter name.
value (Value) –

Required. An exact integer or a Float64.

Expression ¶

Bases: Record

A named expression of a Program: a constant, a parameter value or an operation on two expressions.

Build it as Expression(id="width", value=Constant(value=3)) and pass it in expressions= of a Program. Both arguments are required, and the ID is unique within the Program.

Attributes:

id (Text) –

Required. Unique ID within the Program.
value (Constant | ParameterRef | Binary) –

Required. A Constant, a ParameterRef or a Binary.

Constant ¶

Bases: Record

An exact integer or finite Float64 literal, the value of an expression.

Build it as Constant(value=3) and wrap it in an Expression.

Attributes:

value (Value) –

Required. An exact integer or a Float64.
kind (Literal['constant']) –

Fixed "constant". Names the expression type in the saved record.

ParameterRef ¶

Bases: Record

The value of a declared parameter, as an expression.

Build it as ParameterRef(parameter="steps") and wrap it in an Expression. While the parameter is unbound, the structural check treats the value as unknown and the resource estimate keeps it symbolic. It is never read as zero.

Attributes:

parameter (Text) –

Required. Name of a declared parameter.
kind (Literal['parameter']) –

Fixed "parameter". Names the expression type in the saved record.

Binary ¶

Bases: Record

An operation on two expressions of the Program, such as a sum or an exact ceiling division.

Build it as Binary(op="multiply", left="n", right="two") and wrap it in an Expression. Both operands must have the same numeric domain. "eq", "lt" and "le" return a bool, and "ceildiv" is exact, requires integers and a positive denominator.

Attributes:

op (Literal['add', 'multiply', 'ceildiv', 'min', 'max', 'eq', 'lt', 'le']) –

Required. "add", "multiply", "ceildiv", "min", "max", "eq", "lt" or "le".
left (Text) –

Required. ID of the left operand's expression.
right (Text) –

Required. ID of the right operand's expression.
kind (Literal['binary']) –

Fixed "binary". Names the expression type in the saved record.

ExprRef ¶

Bases: Record

A reference to an expression of the Program by its ID, used wherever a width, count or argument may be computed.

Build it as ExprRef(expression="width"). The ID names an entry of Program.expressions. It is never source code.

Attributes:

expression (Text) –

Required. ID of the expression.

Select blocks and build the Qiskit circuit¶

A Program calls blocks by signature name. Each select_* function returns a SelectedBlock whose record states the block's promised action, recipe and declared costs, and lower_qiskit builds the Qiskit circuit from the Program and its blocks. Compose blocks composes a Pauli block encoding from these functions.

select_preparation ¶

select_preparation(name: str, state: StateInput, *, choice: str = 'native', per_bit: bool = False) -> SelectedBlock

Build the state preparation block of a state input, U|0> = state, with the cheapest exact recipe its form allows.

Pass a StateInput from state_input or the ingest_* functions. Selection reads only the stored representation. It never normalizes, hashes the data again, synthesizes or simulates. An occupation, basis or uniform state gets an exact gate recipe, with the physical global phase as a phase gate. A prefix-uniform, general or product state uses the direct preparation and its CX upper bound, and a product state is counted as q one-qubit preparations, not one q-qubit vector. A supplied Qiskit circuit becomes its own block with unknown synthesis cost and error, because its content cannot be recognized. The block promises only U|0>, the normalized state, with the physical global phase kept, including under control. choice="hzh" prepares each occupied site of an occupation input with H, Z, H instead of X. The two recipes are equal as full operators and are different choices, with different content hashes and gate counts.

Parameters:

name (str) –

Signature name of the block.
state (StateInput) –

The state input.
choice (str, default: 'native' ) –

"native", or "hzh" for an occupation input.
per_bit (bool, default: False ) –

With True, the block has one one-qubit port system_<j> per qubit, in the same order, for a caller that measures or connects single sites.

Returns:

block ( SelectedBlock ) –

The preparation block, with port system of q qubits, or the per-qubit ports.

Raises:

ValueError –

If the state's preparation has no circuit constructor, the state was rebuilt by StateInput.from_record and holds no data, choice is unknown, or "hzh" is used for an input that is not an occupation.
TypeError –

If per_bit is not a bool.

select_block_encoding ¶

select_block_encoding(name, encoding, *, operator, max_bytes=DEFAULT_INPUT_BYTES)

Wrap a block-encoding circuit you built as a block that a Program can call.

Pass a BlockEncoding, for example from build_block_encoding, and the operator input A it encodes. The block promises the (alpha, a, epsilon) block encoding of Gilyén, Su, Low and Wiebe, arXiv:1806.01838v1, Sec. 4.1, Definition 43 (p. 41), ||A - alpha (<0_a| tensor I) U (|0_a> tensor I)|| <= epsilon, with alpha and epsilon in the units of A. The formula writes the ancillas first, as the paper does. NWQLib's encodings place them on the low-order qubits, so in a Qiskit dense matrix the block is (I tensor <0_a|) U (I tensor |0_a>). The relation and error are the caller's assertion. Selection checks the widths, alpha and the error's domain, and does not extract or verify the dense block. The circuit is copied once, so an encoding with equal shapes or metadata cannot attach another circuit later. When the encoding's family and gate counts are known (dense dilation, banded, Pauli LCU or multiplexed Pauli), the block carries a CX-per-query estimate from them, recorded as the caller's assertion rather than a verified gate count. Qiskit is imported only by this call.

Parameters:

name (str) –

Signature name of the block.
encoding (BlockEncoding) –

The encoding circuit and its metadata.
operator (OperatorInput) –

The operator input A.
max_bytes (int, default: DEFAULT_INPUT_BYTES ) –

Default 10 GB (decimal, 10_000_000_000 bytes). Limit on the stored data of the copied circuit.

Returns:

block ( SelectedBlock ) –

The block, with ports ancillas (a qubits, omitted when a = 0) and system.

Raises:

TypeError –

If encoding is not a BlockEncoding.
ValueError –

If the circuit width is not ancillas plus system qubits, the system width is not log2 of A's power-of-two dimension, alpha is not finite and positive, or a given error bound is not finite and nonnegative.

select_signed_pauli ¶

select_signed_pauli(name: str, operator: OperatorInput, *, max_bytes=DEFAULT_INPUT_BYTES) -> SelectedBlock

Build the signed Pauli SELECT block of a Hermitian Pauli operator, the core of its LCU block encoding.

For A = sum_j c_j P_j with real c_j, alpha = sum_j |c_j| and |G> = PREP|0> = sum_j sqrt(|c_j| / alpha) |j>, SELECT applies sign(c_j) P_j on label j. Then (<G| tensor I) SELECT (|G> tensor I) = A / alpha, written with the label register first as the papers do. The block places the label register on the low-order qubits, so a Qiskit dense matrix of it, whose qubit 0 is the least significant index, reads (I tensor <G|) SELECT (I tensor |G>). The recorded relation string keeps the paper order. This is the LCU relation of An, Childs and Lin, arXiv:2312.03916v2, Appendix A.3, Lemma 24, Eq. (178), with each coefficient's sign moved from the two preparation oracles into SELECT. Both oracles then coincide, so the unpreparation is the exact adjoint of PREP and a single real preparation serves both sides. Kirby, Motta and Mezzacapo, arXiv:2208.00567v4, Eqs. (2)-(4), p. 3, use the same form, with nonnegative weights and each Pauli carrying its sign. Their weights have unit L1 norm, so their alpha_i, P_i and H are |c_j|/alpha, sign(c_j) P_j and A/alpha here. Every branch sign(c_j) P_j is Hermitian and unitary, so SELECT squares to the identity. That is their Eq. (5), p. 4, the assumption of the Chebyshev walk in their Lemma 1.

Identity terms are included, and no centering or coefficient threshold is applied. Padding labels apply the identity and get PREP amplitude zero. One term gives a = 0 and P = 1. The zero operator, and an empty or zero-alpha input, has no positive-alpha encoding and is rejected. The coefficients are the real parts of the stored complex128 coefficients, copied bit for bit, alpha is fsum(abs(c)) over them and each amplitude keeps the operand order sqrt(abs(c_j)) / sqrt(alpha). A saved block derives them again from the restored operator in the same way, so alpha, the coefficients and the PREP amplitudes are equal before saving and after loading. Selection does O(M*q + 2**a) work.

max_bytes limits the m*(q+16) + 32P bytes, with m = M terms and P = 2**a >= m, of the label strings with their 16-byte coefficients and of the selection arrays.

Parameters:

name (str) –

Signature name of the SELECT block in the Program.
operator (OperatorInput) –

Hermitian Pauli operator A with M terms on q qubits, from ingest_pauli.
max_bytes (int, default: DEFAULT_INPUT_BYTES ) –

Default 10 GB (decimal, 10_000_000_000 bytes). Nonnegative limit on the bytes above.

Returns:

block ( SelectedBlock ) –

The SELECT, with ports index (a = ceil(log2 M) qubits, omitted for M = 1) and system (q qubits). Its record.semantics.alpha is sum_j |c_j| in the units of A.

Raises:

ValueError –

If the operator has no Hermitian Pauli terms, max_bytes is negative or too small, or alpha is zero or not finite.

select_pauli_preparation ¶

select_pauli_preparation(name: str, select: SelectedBlock, *, max_bytes=DEFAULT_INPUT_BYTES) -> SelectedBlock

Build the coefficient preparation PREP of a signed Pauli SELECT, PREP|0> = sum_j sqrt(|c_j| / alpha) |j>.

The amplitudes come from the SELECT block, so the PREP is tied to that SELECT and the pair encodes A/alpha as select_signed_pauli states. The PREP's input is the coefficient vector, while the SELECT keeps the physical operator A. Use the PREP, the SELECT and the adjoint of the PREP (from transform_block) in that order on the label register. A single-term SELECT has no label register and needs no PREP.

Parameters:

name (str) –

Signature name of the PREP block.
select (SelectedBlock) –

The untransformed signed Pauli SELECT.
max_bytes (int, default: DEFAULT_INPUT_BYTES ) –

Default 10 GB (decimal, 10_000_000_000 bytes). Limit on the bytes of the amplitude vector input.

Returns:

block ( SelectedBlock ) –

The PREP block on the label register.

Raises:

ValueError –

If select is not an untransformed signed Pauli SELECT, or it has a single term.

select_pauli_readout ¶

select_pauli_readout(name: str, select: SelectedBlock) -> SelectedBlock

Build the readout block of a signed Pauli SELECT, a label-controlled change to the basis of each Pauli term.

Controlled on the label register, the block V applies H for X, H S^dagger for Y, and the identity for Z, I and padding labels on each system qubit. A computational measurement after V is read with the diagonal value D: the coefficient sign times the parity of the non-identity system qubits for a used label, and zero for a padding label. Then V^dagger D V = Pi_used SELECT Pi_used, the SELECT restricted to the used labels, not the full identity-padded SELECT. No postselection is needed. The label register is kept and may remain entangled. The block reuses the SELECT's data and reads no input again. Its gate tables are built when the circuit is built, and its CX count is bounded by pauli_readout_cx_bound.

Parameters:

name (str) –

Signature name of the readout block.
select (SelectedBlock) –

The untransformed signed Pauli SELECT.

Returns:

block ( SelectedBlock ) –

The readout block, with the same ports as select.

Raises:

ValueError –

If select is not an untransformed signed Pauli SELECT.

select_zero_reflection ¶

select_zero_reflection(name: str, num_qubits: int) -> SelectedBlock

Build the reflection 2|0><0| - I on q qubits, the sign step of the Lanczos Chebyshev walk.

Conjugated by the coefficient PREP G, this block is the reflection R = (2|G><G| - I) (x) I of Kirby, Motta and Mezzacapo, arXiv:2208.00567v4, Lemma 1, Eq. (6), p. 4, with the label register written first as in select_signed_pauli. With the self-inverse signed SELECT U of an operator A, their Eq. (7) gives (<G| (x) I)(R U)**k (|G> (x) I) = T_k(A/alpha). Their H has coefficients of unit L1 norm, which is A/alpha here. The Lanczos method reads expectations of these Chebyshev polynomials. The sign convention matters under control, because control makes the global phase relative. The recipe applies X on every qubit, a multi-controlled Z, X again and a global phase pi, so |0> gets +1 and every other basis state -1. It uses no extra qubits, and zero width gives the identity.

Parameters:

name (str) –

Signature name of the block.
num_qubits (int) –

Nonnegative width q.

Returns:

block ( SelectedBlock ) –

The block, with port system of q qubits.

Raises:

ValueError –

If num_qubits is negative or not an integer.

transform_block ¶

transform_block(name: str, block: SelectedBlock, *, control=False, adjoint=False) -> SelectedBlock

Build the controlled version, the adjoint, or both, of a selected block, keeping its global phase.

A block's promise usually fixes only part of the operator, for a preparation only U|0>. Control and inversion act on the whole selected circuit, including its global phase, which control makes observable. The new block therefore keeps the base block's promise as its base_semantics and declares its own error unknown, because a state or projected-block error of the base does not bound the transformed operator. A transformed block cannot be transformed again, so every transform refers to one concrete base. Adding a control adds the construction work of the controlled base, counted by a fixed formula for each kind of base, and a direct preparation's CX count switches to its controlled form. The Pauli SELECT and readout counts read the controlled flag instead. A dense-dilation encoding adds the work of the exact synthesis of its unitary and of Qiskit's control of the synthesized gates, and a supplied preparation or encoding adds the same for each dense unitary in its circuit. lower_qiskit counts these syntheses before they start, against its max_synthesis_work, or in a Run against ExecutionLimits.max_synthesis_work.

Parameters:

name (str) –

Signature name of the new block.
block (SelectedBlock) –

The untransformed base block.
control (bool, default: False ) –

Add one coherent control, as a first port control of one qubit.
adjoint (bool, default: False ) –

Take the adjoint.

Returns:

block ( SelectedBlock ) –

The transformed block.

Raises:

ValueError –

If neither control nor adjoint is set, block is already transformed or has parameters, or its promise does not allow the transformation.

signed_pauli_cx_bound ¶

signed_pauli_cx_bound(index_qubits: int, system_qubits: int, *, controlled=False) -> int

Return an upper bound on the CX gates of a signed Pauli SELECT, optionally with one control.

With a = index_qubits, L = 2**a labels and q = system_qubits, the bound counts the CX positions of the signed Pauli SELECT construction of select_signed_pauli:

Each system qubit receives one uniformly controlled one-qubit gate (UCG) with a controls. Qiskit's exact UCGate construction (up_to_diagonal=False) uses L one-qubit core gates and L-1 CX, followed by an exact completion diagonal on a+1 qubits. This core is the decomposition of Bergholm, Vartiainen, Mottonen and Salomaa, arXiv:quant-ph/0410066v2, Sec. III, pp. 3-4, drawn in Fig. 6(a), p. 5, which implements a UCG with k controls by 2**k one-qubit gates and 2**k - 1 CNOTs up to one diagonal (k+1)-qubit gate. In Qiskit 2.6.0, the lower bound of the declared dependency, a random UCGate with a = 1, ..., 4 transpiles to exactly 3(L-1) CX at optimization level 0, matching the per-UCG total below.
A diagonal on m qubits costs 2**m - 2 CX and 2**m - 1 Rz rotations. Shende, Bullock and Markov, arXiv:quant-ph/0406176v5, Theorem 7 (p. 10) splits a diagonal into a multiplexed Rz with m-1 select bits and a diagonal on the remaining m-1 qubits. Their Theorem 8 (p. 11) gives 2**k CX for a multiplexed rotation with k select bits. Summing over k = 1, ..., m-1 gives the count. The completion diagonal (m = a+1) therefore adds 2L-2 CX, so each UCG costs 3(L-1) CX.
The coefficient sign diagonal on the index register (m = a) adds at most L-2 CX and L-1 rotations.

The uncontrolled total is 3q(L-1) + max(0, L-2). With one control, each CX becomes a Toffoli of 6 CX and one-qubit gates, and each of the q(3L-1) + L-1 one-qubit operations becomes a controlled one-qubit gate of at most 2 CX (the two-CX circuit of Shende, Bullock and Markov, arXiv:quant-ph/0406176v5, Sec. 3.1, p. 9). The six-CX Toffoli is the textbook circuit reproduced by Shende and Markov, arXiv:0803.2316v1, Fig. 1, p. 3. Their Theorem 1 shows that no Toffoli circuit of CX and one-qubit gates uses fewer CX. A global phase becomes a one-qubit phase under control, which costs zero CX but is not zero work. Removing exact dependencies can lower these counts, and hardware cost is unknown.

Parameters:

index_qubits (int) –

Nonnegative width a of the label register.
system_qubits (int) –

Nonnegative system width q.
controlled (bool, default: False ) –

Count one added coherent control.

Returns:

bound ( int ) –

The bound 3q(L-1) + max(0, L-2), or with controlled=True 6 (3q(L-1) + max(0, L-2)) + 2 (q(3L-1) + L-1).

Raises:

ValueError –

If a width is negative or not an integer, or controlled is not a bool.

pauli_readout_cx_bound ¶

pauli_readout_cx_bound(index_qubits: int, system_qubits: int, *, controlled=False) -> int

Return an upper bound on the CX gates of a Pauli label readout block, optionally with one control.

The readout uses the same UCG core and completion diagonal per system qubit as signed_pauli_cx_bound, without the coefficient sign diagonal. With L = 2**a, the bound is that function's value minus max(0, L-2) uncontrolled, or minus 6 max(0, L-2) + 2 (L-1) with one control.

Parameters:

index_qubits (int) –

Nonnegative width a of the label register.
system_qubits (int) –

Nonnegative system width q.
controlled (bool, default: False ) –

Count one added coherent control.

Returns:

bound ( int ) –

The CX bound.

Raises:

ValueError –

If a width is negative or not an integer, or controlled is not a bool.

SelectedBlock ¶

SelectedBlock(*args, **kwargs)

A selected block: its saved record and the trusted code that builds its circuit.

The select_* functions and transform_block return it, and SelectedBlock.bind builds one for a new kind of block. A Plan binds the blocks its Program calls, and lower_qiskit accepts a block only when its record is exactly the selected definition the Program names, so a record loaded from JSON or an equal-looking input cannot attach a different circuit. A controlled or adjoint block keeps its live base block instead of its own constructor, so the base's gates and global phase remain the single source of the transformed action. Direct construction raises TypeError.

Attributes:

record (SelectedDefinition) –

The SelectedDefinition.

bind ¶

bind(record, *, payload=None, base=None, constructor=None)

Bind trusted code to a selected definition and its inputs, for a new kind of block.

A leaf block gets a constructor that receives (block, arguments, method_context) and returns a Qiskit circuit, after the common checks of lower_qiskit. method_context(factory) returns the context object of the Run, or of a standalone lower_qiskit call, which factory() creates on first use, and method_context.max_direct_amplitudes is the limit that lower_qiskit checked direct state preparations against. The constructor must implement the record's promised action and work rule, and must not keep method_context or the Run. A controlled or adjoint block gets its base instead of a constructor. Loading a SelectedDefinition from a file never recreates this binding.

Parameters:

record (SelectedDefinition) –

The selected definition.
payload (object | None, default: None ) –

The checked input or construction data the constructor reads.
base (SelectedBlock | None, default: None ) –

The base block of a control or adjoint, whose content hash equals record.base_selection_id.
constructor (Callable | None, default: None ) –

The leaf constructor, required unless record names a blocker or a base.

Returns:

block ( SelectedBlock ) –

The bound block.

Raises:

TypeError –

If record is not a SelectedDefinition or constructor is not callable.
ValueError –

If the base and constructor do not match the record.

SelectedConstruction ¶

Bases: Record

A Program with the selected definition of every block it calls: what estimates, circuit building and OpenQASM export read.

Build it with keyword arguments, for example SelectedConstruction(program=program, selections=tuple(b.record for b in blocks)), or read it as plan.construction. program and selections are required. It is not a Plan, and holds no problem, method or data. Saved JSON keeps the sharing of Program.definitions, and executable code is bound again by exact record when the circuit is built, never from saved code. The checks require exactly one selected definition per Program signature, with an identical signature, so every block call resolves to one selection, and every stage that names a classical routine is a "host" stage that names its exact SelectedKernel declaration. A Pauli encoding with a label register must be the ordered PREP, SELECT, PREP-adjoint Sequence on that register, where the PREP was selected from this SELECT's coefficients and the adjoint is of that same PREP. A single-term encoding has no label register and is the SELECT alone. That structure is what makes <0|U|0> = A/alpha hold for the subgraph.

Attributes:

program (Program) –

Required. The Program that estimates, circuit building and export read.
selections (tuple[SelectedDefinition, ...]) –

Required. One SelectedDefinition per Program signature.
encodings (tuple[PauliEncoding, ...]) –

Default (). PauliEncoding subgraphs, checked as PREP, SELECT and PREP-adjoint.
kernels (tuple[SelectedKernel, ...]) –

Default (). Declarations of classical routines (SelectedKernel), each named by at least one ClassicalStage with boundary="host".
schema_version (Literal[2]) –

Fixed 2. Version of the saved record format.

Raises:

ValueError –

If a signature lacks exactly one matching selection, a "host" stage and its kernel do not match, or an encoding breaks the PREP, SELECT, PREP-adjoint structure.

encoding_semantics ¶

encoding_semantics(root: str) -> BlockSemantics

Return the block-encoding promise of one checked Pauli encoding: A, alpha, label convention and error.

The relation is the LCU block encoding of An, Childs and Lin, arXiv:2312.03916v2, Appendix A.3, Lemma 24, Eq. (178), in the real-coefficient form where both preparation oracles equal PREP and sign(c_j) sits in SELECT. With alpha = sum_j |c_j| the label-zero block is A/alpha. This is an exact block encoding in the sense of their Definition 23 (Appendix A.2). Measuring the label register in |0> succeeds with probability ||A psi||^2 / alpha^2, and the label register is not restored in general.

Parameters:

root (str) –

Definition ID of the encoding's Sequence.

Returns:

semantics ( BlockSemantics ) –

The SELECT's promise, restated as a block encoding.

Raises:

ValueError –

If no checked encoding has this root.

PauliEncoding ¶

Bases: Record

Names the PREP, SELECT and PREP-adjoint calls that form one Pauli LCU block encoding in a Program.

Build it with keyword arguments, for example PauliEncoding(root="encoding", select="select", prepare="prep", unprepare="unprep"), and pass it in encodings= of SelectedConstruction, which checks the structure. root and select are required. The normalization, the physical operator A and the error come from the checked SELECT, so this record holds no second copy of them. With the label register in |0> the subgraph acts as A/alpha.

Attributes:

root (Text) –

Required. Definition ID of the Sequence that forms the encoding.
select (Text) –

Required. Signature name of the signed Pauli SELECT.
prepare (Text | None) –

Default None. Signature name of the coefficient PREP, None for a single-term encoding.
unprepare (Text | None) –

Default None. Signature name of the adjoint of that PREP, None for a single-term encoding.

SelectedDefinition ¶

Bases: Record

The saved part of a selected block: its interface, promised action, chosen recipe and declared costs.

Read it as block.record of a SelectedBlock, or from SelectedConstruction.selections. The select_* functions build it. It holds everything resource estimates, saved archives and reports need, and its content hash covers every field. The executable part is the SelectedBlock that binds trusted code to this exact record. The recipe is the chosen way of building the block's circuit. Two recipes for the same full operator, such as X and HZH, are different selections with different content hashes and gate counts. decomposition lists the recipe's exact gates in order when such a list exists. cost_law names the registered cost function of the construction when one applies, such as a CX bound of the construction or the count of its ordered gate list, and resource_laws holds its cost rules (ResourceLaw). An unknown cost stays unresolved and never becomes zero. construction_work counts the documented size formula, not CPU time or memory. The fields below are read-only.

Attributes:

signature (BlockSignature) –

Declared interface, equal to the Program's signature of the same name.
semantics (BlockSemantics) –

The promised action and its approximation: kind, input, relation, normalization alpha, projectors, error epsilon and its norm, whether control and adjoint are allowed, and the phase convention.
implementation (Source) –

Versioned Source of the implementation.
choice (Text) –

Recipe label within the implementation. A supplied circuit gets a fresh unique label.
decomposition (tuple[Primitive, ...] | None) –

The exact gates of the recipe in order, as Primitive records, or None when the recipe has no exact gate list.
cost_law (Source | None) –

Source of the registered cost function, a CX bound or the count of an ordered gate list, or None when there is none.
cost_parameters (tuple[Binding, ...]) –

Exact arguments of that function for this selection.
cost_context (Text) –

Scope and limits of that function, carried into resource quantities.
construction_work (Count | None) –

Work units of building the block's circuit definition by its size formula, or None when unknown.
controlled (StrictBool) –

Whether this selection adds one coherent control to its base.
adjoint (StrictBool) –

Whether this selection is the adjoint of its base.
base_selection_id (Text | None) –

Content hash of the base selection of a control or adjoint.
coefficient_selection_id (ContentID | None) –

Content hash of the SELECT whose coefficients this PREP prepares.
blocker (Text | None) –

Why the selection cannot run, for a block that only declares its costs or an unsupported block.
resource_laws (tuple[ResourceLaw, ...]) –

Per-call cost rules (ResourceLaw).
workspace (tuple[Workspace, ...]) –

Workspace bytes per call, by location. An empty tuple means unknown, not zero.

BlockSemantics ¶

Bases: Record

The action a circuit block promises: its relation, projectors, normalization, error and phase convention.

SelectedDefinition.semantics holds it, and SelectedConstruction.encoding_semantics derives it for a Pauli encoding. epsilon is algorithmic error only. This record gives no bound on floating-point roundoff of the synthesis. No QSP, evolution, or hardware accuracy is implied by this record.

It states what the block's circuit must do and what code that uses the block may rely on. Keeping it with the block's selection lets a Method derive, for example, an encoding's A/alpha relation from the chosen SELECT block instead of storing a second copy that could disagree.

Attributes:

kind (Literal['preparation', 'signed_pauli_select', 'pauli_readout', 'zero_reflection', 'block_encoding', 'unitary_transform', 'unknown']) –

Block kind: "preparation", "signed_pauli_select", "pauli_readout", "zero_reflection", "block_encoding", "unitary_transform" (a control or adjoint of another block), or "unknown" for a promise of none of these kinds.
input (InputRef | None) –

Reference (InputRef) to the input the block encodes, or None.
basis (Basis) –

System basis, dimension and bit ordering of the action.
relation (Text) –

The promised mathematical relation, as text.
alpha (Real | None) –

Positive physical normalization for Pauli SELECT and block encodings.
index_qubits (Count) –

Width of the index or encoding ancilla register.
input_projector (Text) –

Input subspace on which the relation holds.
output_projector (Text) –

Output subspace that carries the relation.
success (Text) –

Postselection event and its probability, or deterministic.
workspace (Count | None) –

Extra quantum workspace in qubits, or None when unknown.
restoration (Text) –

What happens to index or workspace registers.
epsilon (Real | None) –

Algorithmic error of the relation in approximation_metric, or None when unknown.
approximation_metric (Text) –

Norm in which epsilon is stated.
approximation_evidence (Text) –

Why epsilon has its value.
inverse_legal (StrictBool) –

Whether an adjoint may be selected.
control_legal (StrictBool) –

Whether one coherent control may be added.
phase (Text) –

Global-phase convention, which becomes observable under control.
preparation (StatePreparationSpec | None) –

Specification (StatePreparationSpec) of the input state the block prepares: the whole action of a preparation block, required for that kind, or the first step of a composite block such as an ADAPT query.
base_semantics (BlockSemantics | None) –

For a "unitary_transform", and only for it, the promised action of the block before the control or adjoint.

SelectedKernel ¶

Bases: Record

Declaration of a classical routine that a Program runs on this computer: its inputs, outputs, work and dependencies.

SelectedConstruction.kernels holds the declarations, and a ClassicalStage with boundary="host" names one to run it. The declaration is saved with the Plan. The callable that reads the input data is not saved. The Method attaches it to the Plan as a BoundKernel with Plan._bind. construction_work and invocation_work are declared size units counted against the Run, not CPU-instruction counts. The resource_laws entries specify the numerical work covered, its assumptions and whether the count is exact, an upper bound or an estimate. Without an applicable entry, the total numerical work is unknown. Workspace declarations keep known bytes and unknown components separately.

Attributes:

name (Text) –

Name of the routine, referenced by the Program's ClassicalStage with boundary="host".
implementation (Source) –

Versioned Source of the classical algorithm.
inputs (tuple[InputRef, ...]) –

References (InputRef) to the inputs the routine reads.
scalars (tuple[Text, ...]) –

Ordered labels of the scalar statistics it returns.
scalar_frames (tuple[Literal['physical', 'unit', 'encoded_branch'], ...]) –

Frame of each scalar, physical for physical units, unit for a normalized direction, or encoded_branch for a branch mass or norm in the encoded frame that the Method declares.
outputs (tuple[ArrayOutput, ...]) –

Declared named arrays it may return.
resource_laws (tuple[ResourceLaw, ...]) –

Fixed classical_work cost rules (ResourceLaw) of the routine, without parameter bindings, control or adjoint.
workspace (tuple[Workspace, ...]) –

Per-invocation memory declarations (Workspace). An entry with unknown bytes keeps that component unknown.
construction_work (Count) –

Size units counted against the Run when the routine is bound at preparation.
invocation_work (Count) –

Size units counted against the Run for each invocation.
dependencies (tuple[Text, ...]) –

Python package names, such as numpy, whose installed versions each preparation of the routine records.
application_bytes (Count) –

Upper bound, using the Run's JSON byte accounting, on the saved size of the sequence of KernelApplication records returned by each invocation when the Method fixes them at selection. The Run sets aside this many bytes along with the declared outputs. At completion, the smaller of this value and the returned sequence's JSON byte bound is deducted from the metadata byte count before it is compared with ExecutionLimits.max_completion_metadata_bytes. Bytes beyond the declared bound count toward that metadata allowance. The default, 0, leaves all these bytes to the metadata allowance.

Primitive ¶

Bases: Record

One exact gate in a block's gate decomposition. A global phase has no target qubits and becomes observable under control.

SelectedDefinition.decomposition lists these in order. Build it with keyword arguments, for example Primitive(gate="cx", qubits=(0, 1)). gate is required.

Attributes:

gate (Literal['x', 'h', 'z', 'sdg', 'cx', 'mc_z', 'phase']) –

Required. "x", "h", "z" or "sdg" on one qubit, "cx" on (control, target), "mc_z" on two or more qubits, or a global "phase" with no qubits.
qubits (tuple[Count, ...]) –

Default (). Distinct local qubit indices in the block's ports concatenated in signature order, index 0 being the least significant.
angle (Real) –

Default 0.0. Phase angle in radians, nonzero only for "phase", which multiplies the block by exp(i*angle).

Raises:

ValueError –

If the qubits repeat, their number does not match the gate, or a gate other than "phase" has an angle.

lower_qiskit ¶

lower_qiskit(construction: SelectedConstruction, *, blocks: tuple[SelectedBlock, ...], max_operations=100000, max_qubits=4096, max_clbits=4096, max_direct_amplitudes=DEFAULT_MAX_DIRECT_AMPLITUDES, max_synthesis_work=1000000000) -> LogicalCircuit

Build the Qiskit circuit of one experiment of a selected construction, after checking its size.

The construction must be one static experiment, a Program that describes exactly one circuit, for example from Program.select_experiment. It supports sequences, bound repeats, block calls, coherent regions, allocation, release, computational measurement and reset. Reallocation and a register lifetime split across jobs are not supported, and there is no OpenQASM fallback. A counting pass first checks every reachable binding, width, direct-preparation size and supported node and counts the repeats arithmetically, so an oversized or unbound construction is rejected before Qiskit is imported. It reads the same Program and selected definitions as the resource estimate, so the circuit and the estimate describe one construction. Each block call is built by the SelectedBlock whose record is the selection the Program names. A final measurement batch gives one circuit, whatever its repetitions or observation kind, and running it is the Run's task.

Parameters:

construction (SelectedConstruction) –

The Program and its selected definitions.
blocks (tuple[SelectedBlock, ...]) –

The bound blocks of the reachable selections, matched to them by their exact records.
max_operations (int, default: 100000 ) –

Positive, inclusive limit on the Program node visits, repeat counts included.
max_qubits (int, default: 4096 ) –

Limit on the total declared qubits.
max_clbits (int, default: 4096 ) –

Limit on the total declared classical bits.
max_direct_amplitudes (int, default: DEFAULT_MAX_DIRECT_AMPLITUDES ) –

Default 65536. Positive limit on the amplitudes of each reachable direct state preparation, whose synthesis work grows as q * 2**q.
max_synthesis_work (int, default: 1000000000 ) –

Positive limit on the total work of the exact dense-unitary syntheses, and Qiskit's control of them, that the controlled blocks of this circuit make, in the work units of the dense synthesis size rule (Circuit-free synthesis laws). Each synthesis is counted before it starts.

Returns:

circuit ( LogicalCircuit ) –

The circuit with its register and measurement layouts.

Raises:

ValueError –

If a limit is invalid or exceeded, the root is not one static experiment, a block is missing or does not match its selection, or a node is outside the supported subset.

LogicalCircuit ¶

LogicalCircuit(construction_id: str, circuit: object, quantum_layout: tuple, measurement_layout: tuple, dynamic_visits: int, construction_work: int, defined_selections: tuple[str, ...])

A Qiskit circuit built from a selected construction, with its register and measurement layouts, before compilation.

lower_qiskit returns it. The fields below are read-only. Bit and qubit indices are little-endian, index 0 being the least significant.

Attributes:

construction_id (str) –

Content hash of the construction the circuit was built from.
circuit (object) –

The Qiskit circuit. It is not compiled or run.
quantum_layout (tuple) –

(register, qubit indices) pairs in declaration order.
measurement_layout (tuple) –

(classical value, bit indices) pairs.
dynamic_visits (int) –

Program node visits counted while building the circuit, not a gate count.
construction_work (int) –

Sum of the size rules of the selected definitions, not measured work or a limit.
defined_selections (tuple[str, ...]) –

Content hashes of the gate definitions used, base definitions included. Several calls with different arguments can share one definition.

Request readouts and reduce observations¶

A Plan's experiments name the readout each circuit returns. Reducers that turn a saved state into statistics during data collection are registered by name in nwqlib.core.planning.READOUT_REDUCERS, and the modules of the built-in reducers are listed in nwqlib.core.planning.BUILTIN_REDUCER_MODULES. The reduction-allowance row of Add a Method describes the registration.

Experiment ¶

Bases: Record

One measurement of a Plan: a direct readout, or one setting of a measurement batch of the Program.

A Method's planning step builds the experiments of its Plan with keyword arguments, as Run your own circuit shows. Experiment(name="ghz", setting="computational", observation=ObservationSpec(kind="counts", shots=shots)) declares a direct readout. An experiment of a measurement batch gives batch, setting_index and readout instead, and the batch fixes the readout kind, the setting and the number of repetitions. name is required.

Attributes:

name (Text) –

Required. Name of the experiment, unique in the Plan.
setting (Text | None) –

Default None. Readout setting label of a direct experiment. A batch experiment takes it from the batch.
observation (ObservationSpec | None) –

Default None. The readout (ObservationSpec) of a direct experiment.
readout (ReadoutDetails | None) –

Default None. The Method's readout details of a batch experiment (ReadoutDetails).
batch (Text | None) –

Default None. Definition id of the Program's MeasurementBatch, or None for a direct experiment.
setting_index (Count | None) –

Default None. Index of the setting in that batch.

Raises:

ValueError –

If a direct experiment lacks setting or observation or has readout, if a batch experiment has setting or observation or lacks readout, or if only one of batch and setting_index is given.

ObservationSpec ¶

Bases: ReadoutDetails

The readout of one experiment: what is measured and with how many shots.

A Method's planning step builds it with keyword arguments, for example ObservationSpec(kind="counts", shots=1000), as Run your own circuit shows. kind is required, and the other fields below have defaults. Bit and qubit positions count from the least significant. Each kind accepts only the fields it uses:

counts: 1 <= shots <= 2**63 - 1 (the int64 count range), no labels, qubits or position, and the unconditional population. The Program's classical bits fix the measured bits.
probabilities: distinct qubits for the marginal, with no labels, shots or position.
pauli_expectation: distinct Pauli labels over I, X, Y and Z and an optional position, with no qubits or shots.
host_scalars: distinct labels naming the statistics, with no qubits, shots or position, and the unconditional population.
amplitudes: an amplitudes declaration, with no labels, qubits, shots or position, on the unconditional final state.
estimated_observable: an estimate, with no amplitudes, labels, qubits, shots or position, on the unconditional final state.
trajectory: at least one point in positions, zero shots and the unconditional population, with the single-readout fields empty. An empty request is algebraic work without a measurement, so it declares no experiment.

Only a trajectory has positions. Pauli expectations are read before the logical instruction at position, and None means the end. Counts use the Program's measurements in the computational basis, and probability marginals are read after the final measurements are removed. No full state is saved.

An exact trajectory declares readouts that do not disturb one coherent evolution, at several points of it. Its shot count is zero. Each result is kept with its point ID and its label or outcome, and the saved values are reductions of the simulator state at those points. Sampled readouts describe the Program's measurements and use their declared positive shot counts. The readouts of a trajectory are deterministic, and its zero shots do not allow measurement-conditioned, reset, postselected, noisy or outcome-dependent evolution. host_scalars, amplitude, sampled and provider-estimate readouts keep their own meanings.

Readout requests are combined only when they have the same body, position, readout view (a basis change applied for the readout and then undone), readout kind and population. Two requests share one saved value only when they also name the same label, outcome or amplitude declaration, or the same reducer with the same parameters. A union of distinct requested labels still holds one item per distinct label, and every association of a point with its result is kept when a value is shared. The limit check counts the items of every declared point, N_items = sum_k L_k with L_k the number of items of point k.

Attributes:

kind (Literal['pauli_expectation', 'counts', 'probabilities', 'host_scalars', 'amplitudes', 'estimated_observable', 'trajectory']) –

Required. "pauli_expectation", "counts", "probabilities", "host_scalars", "amplitudes", "estimated_observable" or "trajectory".
shots (Count) –

Default 0. Positive number of shots for counts, and zero for the readouts without a prescribed number of shots, a trajectory included.
amplitudes (AmplitudeReadout | None) –

Default None. The amplitude output of the amplitudes kind (AmplitudeReadout).
estimate (ObservableEstimateSpec | None) –

Default None. The weighted Pauli sum whose expectation a provider estimates, for the estimated_observable kind (ObservableEstimateSpec).
position (Count | None) –

Default None, which means the end of the body. Number of bound logical operations before the readout point. Zero reads the initial state, and the body length reads the final state. The end is resolved before the circuit is prepared. Building the circuit keeps this boundary when it expands operations and, on a backend that runs readout views, inserts them there.
labels (tuple[Text, ...]) –

Default (). Pauli or host_scalars labels, in the order of the returned values.
qubits (tuple[Count, ...]) –

Default (). Measured or marginal qubit positions, least significant first.
population (Literal['unconditional', 'native_conditioned']) –

Default "unconditional". The declared conditioning of an exact readout, "unconditional" or "native_conditioned". The value "native_conditioned", accepted only for Pauli expectation and probability readouts, marks a preceding measurement or reset that can condition the simulator state from which the readout is computed. Every other readout kind, sampled counts included, uses "unconditional".
padding (Text) –

Default "no padding; all returned bit patterns belong to the declared registers". Meaning of any padding, and which returned coordinates belong to the system.
positions (tuple[ObservationPoint, ...]) –

Default (). The points of a trajectory, in order. Each point names a boundary in the planned coherent body, its readout kind and its ordered labels or marginal qubits, and may name a readout view. The points share one preparation and measurement, and their order and payload sizes are part of the Plan.

Raises:

ValueError –

If a field is given that the kind does not use, a field the kind needs is missing, trajectory point IDs repeat, or the point boundaries decrease.

point_observation ¶

point_observation(point_id)

Return the single-point readout of the trajectory point point_id.

Pauli, probability and amplitude points map to the readout kinds of the same name, so their saved values keep those kinds' records and checks. A reduction point's readout is the single-point trajectory of that point, and its saved values are ReducedValues records.

Parameters:

point_id (str) –

ID of a point in positions.

Returns:

readout ( ObservationSpec ) –

The point's readout.

Raises:

ValueError –

If the trajectory has no such point.

point_observations ¶

point_observations()

Return the single-point readout of every point, by point ID, in one pass over the points.

Returns:

readouts ( dict[str, ObservationSpec] ) –

Each point's readout, as point_observation gives it.

point_readout_fields ¶

point_readout_fields(point)

Return the fields of one point's single-point readout, without building an ObservationSpec.

point_observation builds its readout from these fields, so a byte bound of the stored readout can be computed from the same fields without building it. It takes the point object itself, so no ID lookup is needed. Pauli, probability and amplitude points take their kind, labels, qubits, amplitude declaration and the unconditional population, and a Pauli point also its position. Their point ID, readout view and non-Pauli position stay associated only through the preparation record, the point ID, the boundary and the content hash of the trajectory. A reduction point's readout is the single-point trajectory of that entire point, so it copies the point's ID, declared position, reducer, parameters and readout view. Every other field keeps its default.

Parameters:

point (ObservationPoint) –

A point of a trajectory.

Returns:

fields ( dict ) –

Keyword arguments of ObservationSpec.

reject_unsupported_schedule ¶

reject_unsupported_schedule(backend)

Raise if backend cannot run this multi-point schedule, before any circuit is built or submitted.

A backend calls it to keep its supported single-point readouts and reject the multi-point schedules, readout views and reductions that it does not run, before building or submitting a circuit. The error names the backend and the feature.

Parameters:

backend (str) –

Name of the backend, used in the error message.

Raises:

ValueError –

If this readout is a trajectory.

unsupported_schedule ¶

unsupported_schedule()

Describe this readout's multi-point schedule, readout views and reductions, or return None.

Backends name this description when they reject a schedule they do not run. A single-point readout returns None.

Returns:

description ( str | None ) –

The description.

ReadoutDetails ¶

Bases: Record

The readout fields that a Method declares besides the readout kind and shots.

An experiment of a Program's MeasurementBatch holds it as readout, because the batch fixes the readout kind and the number of repetitions. ObservationSpec, the readout of a direct experiment, adds kind and shots to these fields. The one-endpoint readout (position, labels, qubits) is the one-point case of a trajectory. A populated positions belongs only to the trajectory kind, which leaves the one-endpoint fields empty, so a Plan never declares two competing schedules.

Attributes:

amplitudes (AmplitudeReadout | None) –

Default None. The amplitude output of an amplitude readout (AmplitudeReadout).
estimate (ObservableEstimateSpec | None) –

Default None. The weighted Pauli sum whose expectation a provider estimates (ObservableEstimateSpec).
position (Count | None) –

Default None, which means the end of the body. Number of bound logical operations before the readout point. Zero reads the initial state, and the body length reads the final state. The end is resolved before the circuit is prepared. Building the circuit keeps this boundary when it expands operations and, on a backend that runs readout views, inserts them there.
labels (tuple[Text, ...]) –

Default (). Pauli or host_scalars labels, in the order of the returned values.
qubits (tuple[Count, ...]) –

Default (). Measured or marginal qubit positions, least significant first.
population (Literal['unconditional', 'native_conditioned']) –

Default "unconditional". The declared conditioning of an exact readout, "unconditional" or "native_conditioned". The value "native_conditioned", accepted only for Pauli expectation and probability readouts, marks a preceding measurement or reset that can condition the simulator state from which the readout is computed. Every other readout kind, sampled counts included, uses "unconditional".
padding (Text) –

Default "no padding; all returned bit patterns belong to the declared registers". Meaning of any padding, and which returned coordinates belong to the system.
positions (tuple[ObservationPoint, ...]) –

Default (). The points (ObservationPoint) of a trajectory, in order. Each point names a boundary in the planned coherent body, its readout kind and its ordered labels or marginal qubits, and may name a readout view. The points share one preparation and measurement, and their order and payload sizes are part of the Plan.

ObservationPoint ¶

Bases: Record

One readout point of an exact trajectory: where the state is read and what is returned.

The positions of an ObservationSpec of kind "trajectory" hold the points in order. A point reads the state of the coherent circuit body at one boundary, optionally through a readout view (a basis change applied for the readout and then undone). Its readout kind is pauli_expectation with labels, probabilities with qubits, amplitudes with its AmplitudeReadout output declaration (the kind name alone does not determine its dimension, frame, masses or output bytes), or reduction with a registered reducer name and its parameters.

Attributes:

id (Text) –

Point ID, unique within its trajectory.
position (Count | None) –

Default None, which means the end of the body. Number of bound logical operations before the readout point. Zero reads the initial state, and the body length reads the final state. The end is resolved before the circuit is prepared. Building the circuit keeps this boundary when it expands operations and, on a backend that runs readout views, inserts them there.
kind (Literal['pauli_expectation', 'probabilities', 'amplitudes', 'reduction']) –

"pauli_expectation", "probabilities", "amplitudes" or "reduction".
labels (tuple[Text, ...]) –

Ordered Pauli labels for this point, with one character per logical qubit and qubit zero rightmost. Labels are distinct within a point. The same label at another point denotes another returned value.
qubits (tuple[Count, ...]) –

Ordered logical qubits of this point's probability marginal, least significant first in each returned outcome. A reversible view acts before the marginal is saved and is undone before the evolution continues.
amplitudes (AmplitudeReadout | None) –

The AmplitudeReadout declaration of an amplitude point.
reducer (Text | None) –

Registered reducer name of a reduction point (Reducer).
parameters (str) –

Reducer parameters as a JSON object in canonical text, with sorted keys and no spaces. A mapping is accepted and converted. Other kinds keep {}.
view (ReadoutView | None) –

Default None. The point's ReadoutView: the circuit definitions of its basis change and of the exact inverse, and the logical wires they act on. Its inverse restores, in exact arithmetic, the state from which the evolution continues. The preparation record counts every executed forward and inverse operation.

AmplitudeReadout ¶

Bases: Record

An amplitude readout: which qubits of a circuit's state form the output vector, and how it is scaled to physical units.

An ObservationSpec of kind "amplitudes" and an amplitude point of a trajectory carry it as amplitudes. The returned amplitudes are complex and keep their phase.

coordinates are least significant first. success is the algorithm's success event. The conditions and the original output length select the physical coordinates. No execution limit enters this scientific selection. recovery is a positive method scale, not an observed norm or a promise about approximation error. A physical-frame output requires that recovery.

Attributes:

construction_id (ContentID) –

Content hash of the SelectedConstruction whose circuit state is read.
source (Source) –

Source of the Method that declares the readout.
width (Count) –

Width of the circuit in qubits.
coordinates (tuple[Count, ...]) –

Circuit qubits that form the output coordinate index, least significant first.
success (tuple[tuple[Count, Count], ...]) –

Fixed (qubit, bit) pairs of the algorithm's success event, such as ancillas at zero.
conditions (tuple[tuple[Count, Count], ...]) –

Further fixed (qubit, bit) pairs that select the physical coordinates.
output (ArrayOutput) –

Requested vector output, its frame and its original dimension.
recovery (PhysicalScale | None) –

Positive composed scale that maps the selected encoded amplitudes to physical units. None is allowed only for a unit-frame output.
keep_masses (StrictBool) –

Default False. Whether the readout also returns the algorithm-success and physical-slice masses.

Raises:

ValueError –

If the coordinates and the fixed qubits do not list every circuit qubit exactly once, a fixed bit is not 0 or 1, the output is not a complex128 vector whose original dimension fits the coordinates, a physical-frame output has no recovery, or a recovery is zero or its evidence is not "composed_floating_point_recovery".

ObservableEstimateSpec ¶

Bases: Record

The finite real Pauli sum whose expectation a provider estimates, in its original physical units.

An ObservationSpec of kind "estimated_observable" carries it as estimate, and the provider's answer is an EstimateValue whose estimate_id is this record's content hash. labels and coefficients give the weighted operator, including identity terms. precision is a requested standard-error target in the same coefficient units, not a bound on physical error or provider cost.

Attributes:

observable_id (ContentID) –

Content hash that identifies the original physical observable.
labels (tuple[Text, ...]) –

Distinct Pauli labels of equal width over I, X, Y and Z, including identity contributions.
coefficients (tuple[Real, ...]) –

Finite real weights in the original observable units, in the order of labels.
precision (Real) –

Requested provider standard-error target in those units, not total physical error.

ReductionContext ¶

ReductionContext(prepared_id: str, probability_window: float | None, probability_window_exclusions: tuple[str, ...] | None, state_error: float | None = None, state_error_reason: str | None = None, modulo_phase_state_error: float | None = None)

What a reduction of a saved state knows about the preparation that produced the state.

A reducer registered with receives_context=True receives it as the keyword context when it runs. Its fields are read-only values of the preparation record (PreparedArtifact) that produced the saved state.

For outputs declared invariant under a common global phase, a saved-state reduction receives the backend's state-error estimate modulo that phase when its assumptions are satisfied. This estimate includes the finite multiplication and modulus error of the classical phase correction. For phase-sensitive outputs, state_error is unavailable and state_error_reason explains why. The separately supplied modulo_phase_state_error can still be used for projected masses, which are phase invariant even when other diagnostics of the same reducer depend on phase. If the backend estimate is unavailable, the projected mass checks instead use probability_window, already propagated through the classical phase correction, and keep the original probability_window_exclusions visible. This window is the acceptance tolerance for those mass checks and does not replace the missing state-error estimate.

The preparation record's state error (PreparedArtifact.state_error) bounds the computed state only up to one common global phase. It does not bound the exact prefix phase, the summation that accumulates the prefix phase, the subtraction that forms the correction angle, or an amplitude defined with its phase, and adding a classical term to it gives no finite estimate for such a quantity. A saved state used by a phase-sensitive and a phase-invariant reducer is corrected once, and both see the same array and the same classical error bound of the preparation record (PreparedArtifact.statevector_roundoff). The phase-invariant reducer therefore includes the error of the phase product, even though its own registration did not request the phase correction.

Attributes:

prepared_id (str) –

Content hash of the preparation record that produced the saved state.
probability_window (float | None) –

The preparation record's saved_state_probability_window, its probability window propagated through the classical correction of the saved state, or None when that correction was not assessed, which gives no finite budget for a mass check. It does not bound a classical contraction of the saved state, which has its own accumulated error.
probability_window_exclusions (tuple[str, ...] | None) –

The preparation record's probability_window_exclusions, the operations, readout path, simulator version or non-default compiler optimization level whose effect the window does not bound. Empty when the whole execution lies inside the window, None when not assessed.
state_error (float | None) –

The state error bound that matches the reducer's declared phase behavior. For a reducer registered phase_invariant it is modulo_phase_state_error. For any other reducer it is None, since a bound defined with the phase is unavailable. It is also None when an assumption of the backend estimate remains unavailable. A reducer uses its probability window when this value is unavailable, and the original exclusions stay available in probability_window_exclusions.
state_error_reason (str | None) –

Why state_error is None. For a reducer that is not registered phase invariant it is the reason a bound defined with the phase is unavailable, and otherwise the preparation record's backend or classical reason. None when state_error is available.
modulo_phase_state_error (float | None) –

The preparation record's saved_state_error after resolving the labels that the reducer declares, a distance modulo one common global phase that includes the error of the classical phase product, or None when an assumption of the backend estimate or the classical assessment is unavailable. A phase-sensitive reducer may use it only for outputs shown separately to be phase invariant, as the projected mass checks do.

registered_reducer ¶

registered_reducer(name)

Return the reducer registered under name, or None when there is none.

When name is not registered, each module of BUILTIN_REDUCER_MODULES is imported (an already imported module is not imported again, and a module registers its reducers once, at import), and READOUT_REDUCERS is read again.

Parameters:

name (str) –

The reducer's registered name.

Returns:

reducer ( Reducer | None ) –

The registered reducer, with its shape, work and execution functions.

Reducer ¶

Reducer(shape: Callable[[Mapping[str, Any]], tuple[ReducerOutput, ...]], work: Callable[[Mapping[str, Any], int], int] | None = None, execute: Callable[..., tuple] | None = None, phase_invariant: bool = False, receives_context: bool = False, state_error_resolutions: tuple[str, ...] = ())

A registered reduction, which turns a saved simulator state into output values at a trajectory point.

An ObservationPoint of kind "reduction" names it by reducer, and registered_reducer(name) returns this entry. The registry supplies the validated output shapes and dtypes, the work of one reduction and its execution. A reducer name without a registered shape fails when the point's output shape is resolved, before any backend work. A built-in reducer registers itself in READOUT_REDUCERS when its module is imported, and that module is listed in BUILTIN_REDUCER_MODULES so that registered_reducer resolves its name in a process that has not imported it. A user reducer is added to READOUT_REDUCERS directly, under a name that no built-in reducer uses.

The functions a reducer registers are:

shape(parameters): the output components, each with its dtype and shape. Before data collection, the Run sets aside an upper bound on the JSON bytes needed to store each component.
work(parameters, width): the classical work of one reduction of a saved state of width qubits, as a nonnegative integer in the unit that the calling Method's work allowance counts. admit_reductions requires the calling Method's remaining work allowance and rejects a schedule whose summed registered work exceeds it, before the circuits run. The allowance is specific to the calling Method.
execute(state, parameters, bindings): the reduction itself. It receives the read-only complex128 simulator state saved at its point (qubit zero least significant), the validated read-only parameter mapping and the experiment's immutable argument bindings, and returns one array per registered component with that component's dtype and shape (execute_reduction checks them). The saved outputs are stored with these bindings in the ObservationChunk of their point. A reducer registered with receives_context=True is also called with the keyword context, a read-only ReductionContext of the preparation record that produced the state, so that the reducer can check that record's probability window, exclusions and qualified state error while the data are collected, before its outputs are saved. The context's state_error is the modulo-phase budget for a reducer registered phase_invariant and unavailable, with its reason, for any other. modulo_phase_state_error carries the modulo-phase budget for both (ReductionContext).

Attributes:

shape (Callable[[Mapping[str, Any]], tuple[ReducerOutput, ...]]) –

Function of the validated parameter mapping that returns the output components as a nonempty tuple of ReducerOutput. It describes the saved output only. The memory of the reduction's own state or workspace is checked by the code that allocates it.
work (Callable[[Mapping[str, Any], int], int] | None) –

Registered work function, or None when no execution is registered.
execute (Callable[..., tuple] | None) –

Registered execution function, or None when no execution is registered. A reducer is executable when both are registered.
phase_invariant (bool) –

True when the reducer's outputs are unchanged when the saved state is multiplied by one common global phase, and False otherwise, the default. It is set at registration and read from the registry (registered_reducer(name).phase_invariant). It declares whether an intermediate reduction point of this reducer may be served without a record of the saved state's global phase at that point, and whether its context carries the modulo-phase budget as its state_error (ReductionContext).
receives_context (bool) –

True when execute takes the keyword context. False, the default, calls it with the three positional arguments only.
state_error_resolutions (tuple[str, ...]) –

Labels in the preparation record's probability_window_exclusions whose effects this reducer's own readout arithmetic bounds. The execution interface passes them to the saved_state_error method of the preparation record that produced the state when it builds the ReductionContext. The default resolves no labels.

ReducedValues ¶

Bases: Record

The saved values of one output component of a reduction point, flattened in C order.

The values of a reduction point's ObservationChunk hold one record per output component that its Reducer registers, in component order. A float64 component stores real, a complex128 component real and imaginary, and an int64 component integers. The component's dtype and shape are those its reducer registers (core.planning.reducer_outputs), which the ObservationChunk checks.

Attributes:

kind (Literal['reduced']) –

Fixed "reduced".
component (Count) –

Index of the output component.
real (tuple[Real, ...]) –

Default (). Values of a float64 component, or the real parts of a complex128 component.
imaginary (tuple[Real, ...]) –

Default (). Imaginary parts of a complex128 component.
integers (tuple[StrictInt, ...]) –

Default (). Values of an int64 component.

ObservationChunk ¶

Bases: Record

One recorded batch of outputs, or the outputs of one trajectory point, as saved with a Run or Result.

data.observations.chunks holds them, and a Method's analyze reads them, as Run your own circuit shows. The outputs can be sampled counts, an exact readout (probabilities, Pauli expectation values or amplitudes that a simulator computes without shot sampling, subject to numerical rounding), a provider's estimate of an expectation value, or the results of a classical routine. A chunk keeps their sufficient statistics, never one record per shot. Chunks of different attempts stay distinct even when their values are equal. Their identifiers record where the data came from and are not evidence that random measurements are independent.

Read probabilities and counts with histogram(), whose layout Histogram states, and build such a chunk with from_histogram. Counts are stored as JSON CountBin records. Every count, the exact total and the requested shots are at most 2**63 - 1, the int64 maximum of the count weights that the reader returns, and a chunk outside that range is rejected. A probability marginal stores its values in binary arrays. The chunk holds one ProbabilityArrays record with the array manifests and the summary values computed when the arrays were saved. The arrays live in the array store of the Run or Result that holds the chunk. A chunk from a Run, from load_run or load_result, or a revision or copy of such a chunk reads them from that store. A chunk rebuilt from JSON in any other way cannot read its arrays, and its histogram() raises an error that names the loader to use.

A trajectory stores one chunk per observation point. The chunk names its point and resolved boundary, so a saved value maps to its body, point and preparation record after reloading. A trajectory stores one full declaration in its preparation record and one row per point, with only that point's readout declaration and the content hash of the shared declaration on the row. Storage and validation are linear in the total size of the declarations and payloads, with no per-point copy or rescan of the full schedule. The chunk's observation is ObservationSpec.point_observation of the point, and trajectory_id is the content hash of the full declaration. Joining the chunk to its preparation record, in validate_unit_bound and when the Run records the chunk, checks both. Point chunks share the completion, preparation, shots and backend work of the execution that produced them. The chunks of one execution share its run, attempt and job, and differ in chunk. A missing point makes the quantity that depends on it incomplete. It never causes the shared prefix to be run again in analysis or loading.

Attributes:

schema_version (Literal[3]) –

Fixed 3. Version of the saved record format.
run_id (Text) –

Identifier of the Run that produced the data.
execution (Literal['quantum_circuit', 'host_kernel']) –

"quantum_circuit" or "host_kernel", the kind of computation that produced the data.
plan_id (ContentID) –

Content hash of the Plan.
realization_id (ContentID) –

Content hash of the experiment's concrete parameter values.
prepared_id (ContentID) –

Content hash of the preparation record of the circuit or classical computation that was run.
experiment (Text) –

Name of the experiment in the Plan.
setting (Text) –

The readout or batch setting.
bindings (tuple[Binding, ...]) –

The experiment's parameter values, in order.
quantum_layout (tuple[RegisterMap, ...]) –

Order of the quantum registers, which fixes how outcome coordinates are read.
classical_layout (tuple[RegisterMap, ...]) –

Order of the classical registers, which fixes how count labels are read.
attempt (Text) –

Identifier of the attempt that was set aside for the execution that produced the data.
job (Text) –

Identifier of the job that produced the data, not of a later reduction.
chunk (Text) –

Position of this part within that job.
observation (ObservationSpec) –

The readout against which the returned statistics are checked. For a trajectory point, it is that point's single-point readout.
population (Literal['unconditional', 'native_conditioned', 'unknown']) –

The recorded conditioning of an exact readout, "unconditional", "native_conditioned" or "unknown". For an exact readout, "unconditional" means that no measurement or reset precedes it. "native_conditioned", possible only for Pauli expectation and probability readouts, marks a preceding measurement or reset that can condition the simulator state from which the readout is computed. "unknown" means that the conditioning could not be established, for example after unresolved control flow. Every other readout kind, sampled counts included, and the results of every classical routine use "unconditional".
returned_shots (Count | None) –

Total of the returned counts, or None when no shot total is available.
trajectories (Count | None) –

Number of trajectories, or None when unavailable or not applicable.
values (tuple[Statistic, ...]) –

Sufficient statistics, each kept with its original label and its physical normalization. Probabilities have one ProbabilityArrays record, and counts one CountBin per stored outcome. Read both with histogram().
source (Source) –

The backend or classical code that produced the data (Source).
selected_kernel_id (ContentID | None) –

Content hash of the classical computation's declaration, or None for a circuit.
physical_scale (PhysicalScale | None) –

Positive factor that restores physical magnitude to this chunk's unit-normalized data, or None. Its meaning belongs to the Method. For LCHS and the QLS qsvt_inverse solver it is the norm of the output vector, and analysis multiplies the unit solution direction by it. For Expectation, Lanczos and QPE it is the norm of the supplied input state. Expectation's physical quadratic form uses it, and the eigenvalue Methods record it with the input, since an energy does not depend on the state's norm. QHD, FixedGCIM and ADAPT classical chunks carry None, because their scalars need no recovery, a QLS shortcut chunk carries None because the shortcut recovers no physical norm, and quantum circuit chunks other than amplitude readout carry None.
physical_scale_unavailable (Text | None) –

Why physical_scale is None, because the scale is unavailable or no recovery applies. Classical and amplitude chunks set exactly one of the two fields.
artifacts (tuple[ArtifactManifest, ...]) –

Manifests of the arrays saved from these outputs.
applications (tuple[KernelApplication, ...]) –

Records of the classical operator applications.
unavailable (tuple[UnavailableOutput, ...]) –

Named outputs that could not be produced.
point (Text | None) –

ID of the trajectory point whose values this chunk holds, or None for a readout without a point schedule.
boundary (Count | None) –

Resolved boundary of that point in the planned body, or None.
trajectory_id (ContentID | None) –

Content hash of the trajectory declaration that the point belongs to, held by the preparation record, or None.

acquisition_key ¶

acquisition_key

(run_id, attempt, job, chunk), which identifies the outputs that one chunk records.

A Run stores, deduplicates and joins observations under this key. Two chunks with equal values but different keys remain distinct records. The point chunks of one trajectory come from one execution, share its run, attempt and job, and differ only in chunk.

declares_readout_of ¶

declares_readout_of(receipt)

Return whether this chunk holds the readout that its preparation record declares.

A point chunk holds the single-point readout of its point in the preparation record's trajectory, whose content hash is its trajectory_id. Any other chunk holds the record's readout itself. The record's point lookup is indexed, so K point chunks join in O(K) lookups.

Parameters:

receipt (PreparedArtifact) –

The preparation record.

Returns:

declared ( bool ) –

Whether the readouts match.

from_histogram ¶

from_histogram(outcomes, /, **fields)

Build a probabilities or counts chunk from its outcomes.

Validation is that of every other construction path, including the count range 0 to 2**63 - 1. A probability chunk keeps its arrays in memory, with manifests that carry the digest of their bytes. Its stored encoding, dense or sparse, and its sorted order are those of every saved probability readout.

Parameters:

outcomes (Mapping | tuple) –

Either a mapping from bit-string key to weight, with keys spelled as the chunk stores them (rightmost character bit 0, no register separators), or a pair (indices, weights) in the layout of Histogram: 1-D indices for a width of at most 64 or (entries, words) packed indices for every width, integer counts or float64 probabilities. Empty arrays of shape (0,) or (0, words) describe an empty chunk whatever their dtype.
**fields (object, default: {} ) –

The other ObservationChunk fields except values. observation selects counts or probabilities. The width is the number of its qubits (probabilities) or of the bits of classical_layout (counts).

Raises:

TypeError –

When values is also supplied.
ValueError –

For another readout kind, indices outside the width or in another layout, weights of another type or length, or any check of the chunk itself.

histogram ¶

histogram()

Return the outcomes of this probabilities or counts chunk in the Histogram layout.

The chunk builds its Histogram on the first call and returns the same read-only object afterwards. The cached Histogram is not a field, so equality, content hashing and serialization never see it. A probability chunk rebuilt from stored JSON returns a Histogram whose width and entries come from its summaries. Its arrays are read through the array store of its Run or Result on the first access to the weights or indices, once per payload for the store's lifetime, with no recheck of the values or summaries.

Raises:

ValueError –

For any other readout kind, or for a probability chunk that has neither its arrays nor a store to read them from.

validate_unit_bound ¶

validate_unit_bound(receipt)

Check that exact probabilities, Pauli expectations and branch masses exceed one only within the roundoff window of the executed circuit.

The window follows the backend operation count of the preparation record, so this check joins the chunk to its own preparation record. Alone, the chunk accepts nonnegative probabilities and masses and finite expectations. Counts and classical scalars have no roundoff endpoint here.

The window is derived from the preparation record, so each place where a new chunk meets its record calls this method: the decoding of backend output and the validation of a standalone Result before it is saved. Reopening a Run or loading a Result reads chunks that passed one of them and does not call it again. A Method's Result validation may add its own checks, as QLS does for its masses (_quantum_readout.validate_saved_masses). Code that creates chunks outside these two places must call this method. Engineering constants defines the window in its exact_probability_window paragraph.

A trajectory point chunk also joins its record's trajectory declaration: the same trajectory_id, the declared point's single-point readout and its resolved boundary. A reduction point has no endpoint here, because classical contractions of saved states have their own accumulated error, which the record's probability and Pauli readout term does not bound. Amplitude-derived masses use the record's saved_state_probability_window, which includes the classical correction of the saved state, and are checked for nonnegativity only when that correction was not assessed.

Parameters:

receipt (PreparedArtifact) –

The chunk's preparation record.

Raises:

ValueError –

If the record is not this chunk's, a point chunk does not match its declared point or boundary, or a value exceeds its endpoint by more than the window.

Histogram ¶

Histogram(width, integers, weights)

Outcome indices and weights of one probabilities or counts chunk.

ObservationChunk.histogram() returns it. Code that reads observations can rely on the layout below. All arrays are read-only.

width: the readout width w, the number of observed qubits (probabilities) or of classical bits over the whole classical layout (counts).
entries: the number of stored entries, counting any stored zero weight, so it is not the number of nonzero weights.
weights: a 1-D array with one weight per entry, float64 for probabilities and int64 for counts.
indices(): for w <= 64, a 1-D uint64 array with one outcome index per entry. Bit 0 of an index is the first observed qubit (probabilities) or classical bit 0 (counts), which is the rightmost character of the chunk's bit-string key. For w > 64 it raises ValueError naming the width.
packed_indices(): for every w, a 2-D uint64 array of shape (entries, words) with words = max(1, ceil(w/64)). Word 0 holds the least significant 64 bits and the padding bits above w are zero.
index_list(): the outcome indices as Python integers, for every w.

Entries keep the order in which the chunk stores them, and nothing is sorted. A probability chunk stores a dense marginal by outcome position, every outcome including exact zeros, or a sparse marginal with strictly increasing indices of its nonzero values (ProbabilityArrays), so its entries are in increasing index order. A dense marginal's indices are formed when they are first requested. For a histogram obtained from a validated count chunk, every weight and the exact total are in [0, 2**63 - 1], and the total equals returned_shots and does not exceed the requested shots. Because the weights are nonnegative, an int64 sum of this single chunk's weights cannot overflow. Totals combined across measurements require an overflow-safe accumulation. An empty chunk gives indices() of shape (0,) and packed_indices() of shape (0, words).

Code that builds a Histogram directly must supply inputs that already follow this layout. The constructor converts the integers to packed words and checks neither the integers against the width nor the weights' dtype, shape, values or length. The order, range and total statements above come from the validation of an ObservationChunk, so they hold for the Histogram that ObservationChunk.histogram() returns and not automatically for one built directly.

Parameters:

width (int) –

The readout width w of the layout above.
integers (Sequence[int]) –

The full outcome integers, one per entry in stored order, not split into 64-bit words.
weights (ndarray) –

A 1-D NumPy array with one weight per entry, float64 for probabilities and int64 for counts. Its length sets entries. A weights array that is a view of another array is copied. An array that owns its data is kept without a copy and made read-only, so the caller can no longer write to it.

index_list ¶

index_list()

Return the outcome indices as Python integers, for every width.

indices ¶

indices()

Return the 1-D uint64 outcome indices, for a width of at most 64.

packed_indices ¶

packed_indices()

Return the (entries, words) uint64 outcome indices, word 0 least significant.

PreparedArtifact ¶

Bases: Record

The preparation record of one circuit or classical computation: what was built, for which target, and its roundoff bounds.

run.data.receipts and result.data.receipts hold one per preparation. It describes the prepared circuit and holds no executable bytes. snapshot names a circuit built in this process and is not a verified file digest. target and compiler are recorded when the circuit is prepared. The concrete parameter values (realization) survive failed attempts and the reopening of a saved Run, so recovering them needs no completed observation and no guess of a default point. Reading this record loads no circuit data. The fields below are read-only.

Attributes:

schema_version (Literal[9]) –

Fixed 9. Version of the saved record format.
execution (Literal['quantum_circuit', 'host_kernel']) –

"quantum_circuit" or "host_kernel", the kind of preparation.
plan_id (ContentID) –

Content hash of the Plan.
realization_id (ContentID) –

Content hash of realization.
realization (Realization) –

The experiment and its concrete parameter values, kept even before any result exists.
construction_id (ContentID) –

Content hash of the construction used for this preparation.
snapshot (Text) –

Name of the circuit built in this process, not a digest of its bytes.
target (Source) –

The backend target (Source) when the circuit was prepared.
compiler (Source) –

The compiler or preparation code (Source).
runtime (RuntimeOptions) –

The runtime seed and backend preparation options in effect.
observation (ObservationSpec) –

The readout (ObservationSpec).
quantum_layout (tuple[RegisterMap, ...]) –

Layout of the logical quantum registers.
classical_layout (tuple[RegisterMap, ...]) –

Layout of the logical classical registers.
native_basis (tuple[Text, ...]) –

The backend's gate names after preparation.
environment (tuple[Source, ...]) –

Versions of the packages used by the preparation (Source records).
preparation_time (Text) –

Time of the preparation.
construction_work_reserved (Count) –

Circuit construction work counted before execution, in work units.
logical (LogicalPreparationReceipt | None) –

Record of how the logical circuit was built, or None for a classical preparation.
native_operations (Count | None) –

Prepared operation count, or None when unavailable. For a coherent statevector readout on Aer, a trajectory included, it counts the backend evolution operations that execute, including every executed operation of a readout view (a basis change applied before a point's readout) and of its inverse. It counts no save instruction, because a save evaluates or copies the current state and adds no state error to the continuing state. It is not multiplied by the number of saved labels or points, and one whole-trajectory count gives a conservative window for every point. On Aer, for a body with control flow and for sampled counts, it counts every instruction of the prepared backend circuit. Other adapters state their own count.
host_preparation_work_reserved (Count) –

Setup work of the classical computation counted for this preparation.
selected_kernel_id (ContentID | None) –

Content hash of the classical computation's declaration, or None for a circuit.
transformation (Text) –

Description of how the planned circuit was turned into the backend's circuit.
population (Literal['unconditional', 'native_conditioned', 'unknown']) –

The recorded conditioning of an exact readout, in which the simulator computes probabilities, Pauli expectation values or amplitudes without shot sampling, subject to numerical rounding. The value is "unconditional", "native_conditioned" or "unknown". For an exact readout, "unconditional" means that no measurement or reset precedes it. "native_conditioned", possible only for Pauli expectation and probability readouts, marks a preceding measurement or reset that can condition the simulator state from which the readout is computed. "unknown" means that the conditioning could not be established, for example after unresolved control flow. Every other readout kind, sampled counts included, and every classical routine use "unconditional".
payload (PayloadRef | None) –

Where the backend's circuit bytes are saved, or None. It holds no bytes itself.
native_quantum_layout (tuple[RegisterMap, ...]) –

Layout of the compiled quantum registers.
native_classical_layout (tuple[RegisterMap, ...]) –

Layout of the compiled classical registers.
logical_to_native (tuple[Count, ...]) –

The compiled wire of each logical wire, in order.
backend_configuration_id (ContentID | None) –

Content hash of the backend configuration, or None for classical execution.
counts_sampling (CountsSampling | None) –

How the counts are sampled (CountsSampling), or None for other readouts.
provider_options_json (Text | None) –

The provider settings in effect, saved without credentials. For IBM Runtime it is the request of IBMRuntimeBackend.options_json with the defaults that preparation writes in, and every job of the preparation is sent with these settings, also after the Run is reopened.
probability_window_exclusions (tuple[Text, ...] | None) –

Labels of the backend operations, readout path, simulator version or non-default compiler optimization level whose effect the derivation of probability_window does not bound. An empty tuple means the whole execution lies inside it. None means the preparing backend did not assess it.
body_length (Count | None) –

Number of bound logical operations of the planned body, the largest trajectory boundary, recorded for a trajectory, and None otherwise.
boundaries (tuple[Count, ...]) –

Resolved boundary of each trajectory point in declaration order, with the end-position shorthand resolved before backend preparation, and empty for other readouts.
statevector_roundoff (tuple[Nonnegative, Nonnegative] | None) –

The bound (t, e) on the error of the classical phase correction of this execution's saved statevectors, the componentwise maxima over the record's saved states. It is included in the error of every user of those statevectors (saved_state_error and saved_state_probability_window). For a state z before correction and its saved value z_saved, the pair bounds their 2-norm distance modulo one global phase by t * ||z||_2 + e. Thus t is relative to the input norm and e is an absolute 2-norm allowance. (0.0, 0.0) denotes an assessed zero-error operation, including no product or multiplication by the represented factor (1.0, ±0.0) under the classical arithmetic model. None means the classical correction was not assessed.
native_depth (NativeDepth | None) –

The native two-qubit depth of the prepared circuit on the backend's target (NativeDepth), computed once at preparation and kept unchanged after the Run is reopened. None means the backend did not compute it. IBM Runtime records it for its compiled circuit, qualified only for counts that keep the provider's dynamical decoupling and twirling off (IBMRuntimeBackend.options_json) under qiskit-ibm-runtime 0.49.0. The other backends record None. A requested native-depth limit refuses a circuit before submission when its depth is not qualified, or when a package version in environment differs from the installed one (nwqlib.backends.inspection.check_native_depth_cap).

probability_window ¶

probability_window: float

The allowed absolute difference between one and the sum of the probabilities in one complete distribution from this execution's exact readout.

It is max(1e-12, (c*G + 2**(n+1) + 10)*u) for G backend operations, the circuit width n, the executing simulator's per-instruction constant c and u = 2**-53, as Engineering constants derives. A target without a derived constant of its own uses Aer's, the larger one. Classical preparations and unknown counts keep the fixed floor 1e-12.

saved_state_probability_window ¶

saved_state_probability_window

probability_window propagated through the classical correction of a saved state, or None.

omega_saved = omega + (2t + t**2)(1 + omega) + 2(1 + t)(1 + omega) e + e**2 with omega equal to this record's probability_window and (t, e) its statevector_roundoff. An unassessed correction gives None, not the uncorrected window, so it yields no finite allowance for the check of a total probability.

saved_state_error ¶

saved_state_error(resolved=())

Return (delta_saved, reason): state_error(resolved) after the classical correction of a saved state.

delta_saved = delta + t (1 + delta) + e with (t, e) the record's statevector_roundoff. Like state_error it is a distance modulo one common global phase, conditional on the backend's first-order model. It returns the unavailable reason of state_error unchanged when delta is unavailable, and an unavailable reason for the missing assumption when the classical correction was not assessed. Code that reads a saved statevector uses it. Probability and Pauli readouts that the backend saves directly keep state_error, since their buffers undergo no classical correction.

state_error ¶

state_error(resolved=())

Return (delta, None) for this execution's final-state budget, or (None, reason).

delta is native_state_error of the backend operation count with the target's derived per-instruction constant, a first-order bound on ||psi_hat - exp(i phi) psi||_2 against the unitary backend circuit. Here psi_hat is the computed state, psi is the ideal unit state of that circuit and phi is one common global phase. It describes distance modulo one common global phase. It does not bound the exact prefix phase, the summation that accumulates the prefix phase of a saved state, the subtraction forming its correction angle, or a phase-defined amplitude. The users of a saved statevector use saved_state_error. It exists only when the derivation covers the whole execution, that is, for a circuit on a target with a derived constant, a known operation count and assessed probability_window_exclusions that are all in resolved, the labels whose effect the caller's own readout bounds. Unlike probability_window, an unknown count or target gets no default constant and no floor. The budget enters the bound on differences of point probabilities, which QHD uses for the tie window of its most probable point. The Aer constant that probability_window takes for an unknown target has no derivation for that target. When the count is unknown, its 1e-12 floor sets the allowed absolute difference between one and the sum of the probabilities in one exact-readout distribution. That floor is a validation convention, not a derived state-error bound, so neither fallback supplies delta.

Save and restore a method's data¶

A Method whose Runs or Results are saved implements save_archive(plan, files) and load_archive(saved, files) and names its Result class in result_type. Both hooks receive an ArchiveFiles object, save_archive reads the bound blocks from plan.blocks, and When the archive hooks are required shows them for a small Method. Import write_blocks and read_blocks from nwqlib.blocks._archive, a protected module that is a supported hook for Method authors (supported protected extension hooks).

ArchiveFiles ¶

ArchiveFiles(path, max_bytes)

The folder of a saved Result or Run, as passed to a Method's save_archive and load_archive hooks.

A Method author writes and reads the Method's data through the files argument of those hooks, as Add a Method and Run your own circuit show, rather than through a serializer of its own. Its operations keep each input in its own representation and count the written bytes against the folder's limit. Files have readable names, are created new and are never overwritten. An array or circuit used by several parts is written once per save and read once per load. Arrays load as read-only NumPy memory maps and are neither normalized nor content-hashed. The headers of input arrays are checked against their representation, dimensions and declared encoding. These checks do not validate every value or restore the digest that the input had when it was first accepted. Keep the folder available while using the restored Plan. Circuits use Qiskit's public QPY format. The memory and CPU use of the SDKs is unknown.

Open the folder path, with a limit of max_bytes on the bytes written.

NWQLib opens the folder and passes it to the hooks, so Method code does not build one.

Parameters:

path (str | PathLike) –

The folder.
max_bytes (int | None) –

Positive limit on the bytes written, or None for a folder without a limit of its own.

Raises:

ValueError –

If max_bytes is neither a positive integer nor None.

read_plan ¶

read_plan(data, *, problem, method, output, reconstruction=None)

Rebuild a Plan from its JSON description and the Problem, Method and output already restored.

Parameters:

data (dict) –

The description returned by Plan.to_record().
problem (ProblemRecord) –

The restored Problem.
method (Method) –

The restored Method.
output (OutputRecord) –

The restored output.
reconstruction (object | None, default: None ) –

The Method's restored interpretation data, which replaces the saved one when given.

Returns:

plan ( Plan ) –

The Plan. A Method that binds circuit blocks binds them with plan._bind(...) before returning the Plan from load_archive.

write_problem ¶

write_problem(problem)

Save a Problem, writing each of its numerical inputs once, and return its description.

Symbolic expressions are saved as descriptions and never evaluated.

Parameters:

problem (ProblemRecord) –

The Problem.

Returns:

description ( dict ) –

JSON description that read_problem reads.

read_problem ¶

read_problem(data)

Rebuild a built-in Problem from its saved description, with its inputs restored.

The Problem class is chosen from a fixed table of the built-in kinds, so saved text never selects an arbitrary class.

Parameters:

data (dict) –

The description that write_problem returned.

Returns:

problem ( ProblemRecord ) –

The Problem.

write_output ¶

write_output(output)

Save an output's fields, and its observable in its own representation when it has one.

Parameters:

output (OutputRecord) –

The output.

Returns:

description ( dict ) –

JSON description that read_output reads.

read_output ¶

read_output(data)

Rebuild a built-in output from its saved description.

The output class is chosen from a fixed table of the built-in kinds, as in read_problem.

Parameters:

data (dict) –

The description that write_output returned.

Returns:

output ( OutputRecord ) –

The output.

write_state ¶

write_state(name, state)

Save a state input, its preparation and its circuit, and return its description.

The vector and its normalized direction are saved as given, without normalizing them again, so scale and phase survive exactly. When the two arrays have the same dtype, shape and bytes (a unit-norm vector is its own direction), one array is written and the direction names its file. The comparison is one pass over the entries.

Parameters:

name (str) –

Prefix of the file names.
state (StateInput) –

The state input.

Returns:

description ( dict ) –

JSON description that read_state reads.

read_state ¶

read_state(data)

Restore a state input after checking its payload layout against its manifest.

The expected array shape follows the representation. A vector of dimension D has shape (D,). A product state on n qubits has (n, 2) and an occupation string (n,), and both require D = 2**n. A complex128 normalized direction must exist exactly when the state is not an occupation string and its physical scale is nonzero. Payload bytes must equal the declared size. A direction that names the physical file is that one payload (write_state), read once. A supplied circuit must match the declared width and have no classical bits or parameters. Values are not rescanned, so a state is not normalized or re-ingested on load.

write_operator ¶

write_operator(name, operator)

Save an operator in its own representation, never a converted one, and return its description.

Dense, CSR, CSC, Pauli, ordered fermionic and periodic-stencil inputs keep their arrays or parameters, so saving never turns a sparse, Pauli or fermionic operator into a dense matrix. A declaration without data is saved as a declaration.

Parameters:

name (str) –

Prefix of the file names.
operator (OperatorInput) –

The operator.

Returns:

description ( dict ) –

JSON description that read_operator reads.

read_operator ¶

read_operator(data)

Restore an operator after checking every array header against its manifest.

Each representation has a fixed layout. Dense needs a (D, D) float64 or complex128 array. CSR/CSC needs one-dimensional values, signed 32 or 64-bit indices of the same length and D + 1 index pointers with indptr[0] == 0 and indptr[-1] equal to the value count. Pauli needs uint64 x and z masks of ceil(n/64) words per term and complex128 coefficients. Ordered fermionic terms need, for M strings on q modes with D = 2**q, M + 1 int64 offsets with offsets[0] == 0 and offsets[-1] equal to the entry count P, P int64 modes, P uint8 actions and M complex128 coefficients. A periodic stencil restores its parameters and checks its declared width. In every case the payload bytes must equal the declared size. Individual sparse indices and coefficient values are not scanned. The restored object wraps the memory-mapped arrays without copying them. A sparse matrix is built empty with the declared shape, and its three arrays are then set to the mapped ones, so SciPy does not check or convert the saved indices.

read_path ¶

read_path(name)

Register a file that the Method's saved data depends on, and return its path.

A load_archive hook that restores cached data must call it for every file it refers to, including files whose contents it reads only later. Registration reads the file's metadata only, so a missing file raises FileNotFoundError here, and it keeps the file from being removed as unused when the Run is reopened. A folder opened with a limit counts the file's size against it, and a folder opened without one (max_bytes=None) counts nothing.

Parameters:

name (str) –

The file name, without a directory part.

Returns:

path ( Path ) –

The file's path.

nwqlib.core.planning.Plan.blocks ¶

blocks

The in-memory circuit blocks that the Method bound to this Plan with _bind.

A Method's save_archive hook saves them, as Run your own circuit shows.

write_blocks ¶

write_blocks(blocks, files)

Return the saved form of a Method's selected blocks, for its save_archive hook.

Import it from nwqlib.blocks._archive, a supported module for Method authors despite its leading underscore. Call it in save_archive(plan, files) with the archive object files that the hook receives, and store the returned dict with the saved Plan. Each block is written once, base blocks before the blocks that transform them. Only the built-in preparation, Pauli SELECT and readout, reflection and transformed blocks can be saved. A signed Pauli SELECT or readout saves its operator and amplitude array only, because loading derives the coefficients from the operator, and blocks that share an operator or amplitude array write it once.

The selection limit of select_signed_pauli does not bound the whole archive or the live packed operator. Code that holds a whole archive in memory, for example to transfer it, needs its own allowance. This function takes no byte limit, and the archive's byte limits apply to each file it writes.

Parameters:

blocks (Iterable[SelectedBlock]) –

The blocks to save, usually the Plan's bound blocks.
files (ArchiveFiles) –

The archive object of the hook.

Returns:

saved ( dict ) –

The saved block graph, with its format, nodes and roots, for read_blocks.

read_blocks ¶

read_blocks(data, records, files)

Restore the blocks saved by write_blocks, for a Method's load_archive hook.

Import it from nwqlib.blocks._archive, a supported module for Method authors despite its leading underscore. A saved kind selects one constructor from a fixed table of built-in block kinds, so loading never imports or calls code named in the archive. A preparation is bound to its restored state input, and a transformed block is bound to its restored base. A signed Pauli SELECT or readout derives its coefficients from the restored operator with the expression selection uses, so alpha, the coefficients and the PREP amplitudes equal those before saving, and a SELECT and its readout share one restored operator.

Parameters:

data (dict) –

The saved block graph that write_blocks returned.
records (Sequence[SelectedDefinition]) –

The selected definitions that the saved root blocks refer to by position. The reference Method passes plan.construction.selections.
files (ArchiveFiles) –

The archive object of the hook.

Returns:

blocks ( tuple[SelectedBlock, ...] ) –

The restored blocks, in the saved order.

Raises:

ValueError –

If the saved format is not the current block format.

InputRef ¶

Bases: Record

A declaration of an input and of how it is accessed, without its data.

It names the input and its representation. It does not build an oracle or a circuit for the input. Eigenproblem.subspace takes one to name an explicitly defined subspace.

Attributes:

identity (Text) –

Required. Name of the input.
representation (Text) –

Required. How the input is represented, for example "circuit".
source (Source) –

Required. The Source of the input.
schema_version (Literal[2]) –

Fixed 2. Version of the saved record format.