qre Package

Packages

application
interop
models

Modules

instruction_ids
property_keys

Classes

Application	An application defines a class of quantum computation problems along with a method to generate traces for specific problem instances. We distinguish between application and trace parameters. The application parameters define which particular instance of the application we want to consider. The trace parameters define how to generate a trace. They change the specific way in which we solve the problem, but not the problem itself. For example, in quantum cryptanalysis, the application parameters could define the key size for an RSA prime product, while the trace parameters define which algorithm to use to break the cryptography, as well as parameters therein.
Architecture	Abstract base class for quantum hardware architectures.
Block
Constraint
ConstraintBound
Encoding
EstimationResult
EstimationTable	A table of quantum resource estimation results. Extends `list[EstimationTableEntry]` and provides configurable columns for displaying estimation data. By default the table includes qubits, runtime (displayed as a `pandas.Timedelta`), and error columns. Additional columns can be added or inserted with `add_column` and `insert_column`. Initialize an empty estimation table with default columns.
EstimationTableColumn	Definition of a single column in an `EstimationTable`.
EstimationTableEntry	A single row in an `EstimationTable`. Each entry represents one Pareto-optimal estimation result for a particular combination of application trace and architecture ISA.
FactoryResult
ISA
ISAContext	Context passed through enumeration, holding shared state. Initialize the ISA context for the given architecture.
ISAQuery	Abstract base class for all nodes in the ISA enumeration tree. Enumeration nodes define the structure of the search space for ISAs starting from architectures and modified by ISA transforms such as error correction schemes. They can be composed using operators like `+` (sum) and `*` (product) to build complex enumeration strategies.
ISARefNode	A reference to a bound ISA in the enumeration context. This node looks up the binding from the context and yields the bound ISA.
ISARequirements
ISATransform	Abstract base class for transformations between ISAs (e.g., QEC schemes). An ISA transform defines a mapping from a required input ISA (e.g., architecture constraints) to a provided output ISA (logical instructions). It supports enumeration of configuration parameters.
InstructionFrontier
InstructionSource
LatticeSurgery	Lattice surgery trace transform. Converts a trace into a form suitable for lattice-surgery-based resource estimation.
PSSPC	Pauli-based computation trace transform (PSSPC). Converts rotation gates and optionally CCX gates into T-state-based operations suitable for lattice surgery resource estimation.
Trace
TraceQuery	A query that enumerates transformed traces from an application. A trace query chains a sequence of trace transforms, each with optional keyword arguments to override their default parameter domains.
TraceTransform	Abstract base class for trace transformations.

Functions

block_linear_function

block_linear_function(block_size, slope, offset=None)

Parameters

Name	Description
block_size Required
slope Required
offset	Default value: None

constant_function

constant_function(value)

Parameters

Name	Description
value Required

constraint

Create an instruction constraint.

constraint(id: int, encoding: Encoding = Encoding.PHYSICAL, *, arity: int | None = 1, error_rate: ConstraintBound | None = None, **kwargs: bool) -> Constraint

Parameters

Name	Description
id Required	int The instruction ID.
encoding	Encoding The instruction encoding. PHYSICAL (0) or LOGICAL (1). Default value: 0
arity Required	<xref:Optional>[int] The instruction arity. If None, instruction is assumed to have variable arity. Default is 1.
error_rate Required	<xref:Optional>[<xref:ConstraintBound>] The constraint on the error rate.
**kwargs Required	bool Required properties that matching instructions must have. Valid property names: distance. Set to True to require the property.

Keyword-Only Parameters

Name	Description
arity	Default value: 1
error_rate	Default value: None

Returns

Type	Description
Constraint	The instruction constraint.

Exceptions

Type	Description
ValueError	If an unknown property name is provided in kwargs.

estimate

Estimate the resource requirements for a given application instance and architecture.

The application instance might return multiple traces. Each of the traces is transformed by the trace query, which applies several trace transforms in sequence. Each transform may return multiple traces. Similarly, the architecture's ISA is transformed by the ISA query, which applies several ISA transforms in sequence, each of which may return multiple ISAs. The estimation is performed for each combination of transformed trace and ISA. The results are collected into an EstimationTable and returned.

The collection only contains the results that are optimal with respect to the total number of qubits and the total runtime.

Note

The pruning strategy used when use_graph is set to True (default)

filters ISA instructions by comparing their per-instruction space, time,

and error independently. However, the total qubit count of a result

depends on the interaction between factory space and runtime:

factory_qubits = copies × factory_space where copies are determined

by count.div_ceil(runtime / factory_time). Because of this, an ISA

instruction that is dominated on per-instruction metrics can still

contribute to a globally Pareto-optimal result (e.g., a factory with

higher time may need fewer copies, leading to fewer total qubits). As a

consequence, use_graph=True may miss some results that

use_graph=False would find. Use use_graph=False when completeness of

the Pareto frontier is required.

estimate(application: Application, architecture: Architecture, isa_query: ISAQuery, trace_query: TraceQuery | None = None, *, max_error: float = 1.0, post_process: bool = False, use_graph: bool = True, name: str | None = None) -> EstimationTable

Parameters

Name	Description
application Required	Application The quantum application to be estimated.
architecture Required	Architecture The target quantum architecture.
isa_query Required	ISAQuery The ISA query to enumerate ISAs from the architecture.
trace_query	TraceQuery The trace query to enumerate traces from the application. Default value: None
max_error Required	float The maximum allowed error for the estimation results.
post_process Required	bool If True, use the Python-threaded estimation path (intended for future post-processing logic). If False (default), use the Rust parallel estimation path.
use_graph Required	bool If True (default), use the Rust estimation path that builds a graph of ISAs and prunes suboptimal ISAs during estimation. If False, use the Rust estimation path that does not perform any pruning and simply enumerates all ISAs for each trace.
name Required	<xref:Optional>[str] An optional name for the estimation. If given, this will be added as a first column to the results table for all entries.

Keyword-Only Parameters

Name	Description
max_error	Default value: 1.0
post_process	Default value: False
use_graph	Default value: True
name	Default value: None

Returns

Type	Description
EstimationTable	A table containing the optimal estimation results.

generic_function

generic_function(func)

Parameters

Name	Description
func Required

instruction_name

instruction_name(id)

Parameters

Name	Description
id Required

linear_function

linear_function(slope)

Parameters

Name	Description
slope Required

plot_estimates

Plot estimation results displaying qubits vs runtime.

Creates a log-log scatter plot where the x-axis shows the total runtime and the y-axis shows the total number of physical qubits.

data may be a single EstimationTable or an iterable of tables. When multiple tables are provided, each is plotted as a separate series. If a table has a EstimationTable.name (set via the name parameter of estimate), it is used as the legend label for that series.

When runtime_unit is None (the default), the x-axis uses human-readable time-unit tick labels spanning nanoseconds to centuries. When a unit string is given (e.g. "hours"), all runtimes are scaled to that unit and the x-axis label includes the unit while the ticks are plain numbers.

Supported runtime_unit values: "ns", "µs" (or "us"), "ms", "s", "min", "hours", "days", "weeks", "months", "years".

plot_estimates(data: EstimationTable | Iterable[EstimationTable], *, runtime_unit: str | None = None, figsize: tuple[float, float] = (15, 8), scatter_args: dict[str, Any] = {'marker': 'x'})

Parameters

Name	Description
data Required	A single EstimationTable or an iterable of EstimationTable objects to plot.
runtime_unit Required	Optional time unit to scale the x-axis to.
figsize Required	Figure dimensions in inches as `(width, height)`.
scatter_args Required	Additional keyword arguments to pass to `matplotlib.axes.Axes.scatter` when plotting the points.

Keyword-Only Parameters

Name	Description
runtime_unit	Default value: None
figsize	Default value: (15, 8)
scatter_args	Default value: {'marker': 'x'}

Returns

Type	Description
<xref:matplotlib.figure.Figure>	The figure containing the plot.

Exceptions

Type	Description
ImportError	If matplotlib is not installed.
ValueError	If all tables are empty or runtime_unit is not recognised.

property_name

property_name(id)

Parameters

Name	Description
id Required

property_name_to_key

property_name_to_key(name)

Parameters

Name	Description
name Required