pyqres.core

核心操作类

Operation

class pyqres.core.operation.Operation(reg_list=None, param_list=None, temp_reg_list=None, submodules=None, **kwargs)

基类：object

Base class for all quantum operations.

Two concrete subclasses: - Primitive: leaf node with known resource cost (T-count, etc.) - Composite: decomposes into sub-operations via program_list

__init__(reg_list=None, param_list=None, temp_reg_list=None, submodules=None, **kwargs)

static program_type()

declare_qfunction()

declare_program_list()

validate_registers()

control(controller)

control_by_all_ones(controller)

control_by_nonzero(controller)

control_by_bit(controller)

control_by_value(controller)

dagger()

is_self_conjugate()

Check if operation is self-conjugate (U† = U).

Self-conjugate operations don't change when dagger is applied. This affects T-count, T-depth, simulation, and operation unrolling.

返回类型:

bool

render_parameters()

render_registers()

render_submodules()

render_this(indent=0, dagger_ctx=False, controllers_ctx=None)

plain_render_this(indent=0, dagger_ctx=False, controllers_ctx=None)

t_count(dagger_ctx=False, controllers_ctx=None)

sum_t_count(t_count_list)

t_depth(current_t_depth, dagger_ctx=False, controllers_ctx=None)

merge_t_depth(current_t_depth, t_depth_list)

toffoli_count(dagger_ctx=False, controllers_ctx=None)

sum_toffoli_count(toffoli_count_list)

enter(dagger_ctx=False, controllers_ctx=None)

exit(dagger_ctx=False, controllers_ctx=None)

traverse(visitor, dagger_ctx=False, controllers_ctx=None)

traverse_children(visitor, dagger_ctx=False, controllers_ctx=None)

Primitive

class pyqres.core.operation.Primitive(reg_list=None, param_list=None, temp_reg_list=None, submodules=None, **kwargs)

基类：Operation

Leaf operation with known resource cost. Cannot be further decomposed.

static program_type()

traverse_children(visitor, dagger_ctx=False, controllers_ctx=None)

t_depth(current_t_depth, dagger_ctx=False, controllers_ctx=None)

Default T-depth implementation: adds t_count to all involved registers.

toffoli_count(dagger_ctx=False, controllers_ctx=None)

Default Toffoli-count: approximated as t_count / 7.

Composite

class pyqres.core.operation.Composite(reg_list=None, param_list=None, temp_reg_list=None, submodules=None, **kwargs)

基类：Operation

Operation that decomposes into sub-operations via program_list.

static program_type()

t_count(dagger_ctx=False, controllers_ctx=None)

t_depth(current_t_depth, dagger_ctx=False, controllers_ctx=None)

toffoli_count(dagger_ctx=False, controllers_ctx=None)

StandardComposite

class pyqres.core.operation.StandardComposite(reg_list=None, param_list=None, temp_reg_list=None, submodules=None, **kwargs)

基类：Composite

Composite with default summation: sum children's T-counts.

AbstractComposite

class pyqres.core.operation.AbstractComposite(reg_list=None, param_list=None, temp_reg_list=None, submodules=None, **kwargs)

基类：Composite

Composite with custom sum_t_count() aggregation.

sum_t_count(t_count_list)

注册表

OperationRegistry

class pyqres.core.registry.OperationRegistry

基类：object

Central registry for all Operation subclasses.

classmethod auto_register(node_cls)

classmethod register(name=None)

classmethod get_class(name)

classmethod has_class(name)

返回类型:

bool

classmethod remove_class(name)

classmethod all_names()

元数据

RegisterMetadata

class pyqres.core.metadata.RegisterMetadata

基类：object

Quantum register metadata manager.

__init__()

declare_register(name, size, reg_type='General')

declare_registers(regs)

undeclare_register(name)

undeclare_registers(regs)

split_register(reg, new_reg_declarations)

merge_register(reg, regs_to_merge)

register_metadata_stack: List[RegisterMetadata] = []

static get_register_metadata()

返回类型:

RegisterMetadata

static push_register_metadata()

返回类型:

RegisterMetadata

static pop_register_metadata()

static add_register(reg)

static add_registers(regs)

static remove_register(reg)

static remove_registers(regs)

static get_registers()

static get_register_types()

ProgramMetadata

class pyqres.core.metadata.ProgramMetadata

基类：object

Quantum program metadata manager.

__init__()

qfunctions: Dict[str, FunctionDeclaration]

declare_qfunction(name, reg_count, param_count=0, temp_reg_count=0, submodule_count=0)

declare_program_list(name, program_list)

quantikz(path=None)

访问者

TCounter

class pyqres.core.visitor.TCounter

基类：object

Visitor that computes total T-gate count via lowering.

__init__()

enter(node)

exit(node)

visit(node, dagger_ctx=False, controllers_ctx=None)

get_count()

get_result()

TDepthCounter

class pyqres.core.visitor.TDepthCounter

基类：object

Visitor that computes T-gate depth via lowering.

__init__()

enter(node)

exit(node)

visit(node, dagger_ctx=False, controllers_ctx=None)

get_depth()

get_result()

TreeRenderer

class pyqres.core.visitor.TreeRenderer(fold_modules=None)

基类：object

Visitor that renders an Operation tree as an indented tree structure.

Used by Operation.__repr__() to generate a hierarchical text representation of an operation and its children. Supports folding (hiding) of specific module subtrees.

Example output:

Toffoli: QRegs(q0[1], q1[1], q2[1])
  CNOT: QRegs(q0[1], q1[1])
  CNOT: QRegs(q1[1], q2[1])
  CNOT: QRegs(q0[1], q1[1])

text

Accumulated rendered text.

indent

Current indentation level (in spaces).

fold_modules

List of operation names to fold (hide their children).

folding

Whether currently inside a folded subtree.

hidden

Whether current node should be hidden.

示例

>>> from pyqres.primitives import Toffoli
>>> from pyqres.core.metadata import RegisterMetadata
>>> RegisterMetadata.push_register_metadata()
>>> RegisterMetadata.get_register_metadata().declare_register('q0', 1)
>>> RegisterMetadata.get_register_metadata().declare_register('q1', 1)
>>> RegisterMetadata.get_register_metadata().declare_register('q2', 1)
>>> t = Toffoli(['q0', 'q1', 'q2'])
>>> renderer = TreeRenderer()
>>> t.traverse(renderer)
>>> print(renderer.text)

__init__(fold_modules=None)

Initialize the renderer.

参数:

fold_modules -- List of operation names to fold. Children of these operations will not be rendered.

enter(node)

Called when entering a node during traversal.

Increases indent level and manages folding state.

参数:

node -- The Operation node being entered.

exit(node)

Called when exiting a node during traversal.

Decreases indent level and resets folding state when leaving a folded module.

参数:

node -- The Operation node being exited.

visit(node, dagger_ctx=False, controllers_ctx=None)

Visit a node and render its string representation.

Calls node.render_this() to get the formatted string for this node, then appends it to the accumulated text.

参数:

• node -- The Operation node to visit.

• dagger_ctx -- Whether the node is being traversed in dagger mode.

• controllers_ctx -- Current controller context from parent nodes.

PlainRenderer

class pyqres.core.visitor.PlainRenderer(fold_modules=None)

基类：object

Visitor that renders an Operation tree as plain text.

Similar to TreeRenderer but uses plain_render_this() which provides a simpler output format. Used by Operation.__str__().

Example output:

Toffoli: QRegs(q0[1], q1[1], q2[1])
  CNOT: QRegs(q0[1], q1[1])
  CNOT: QRegs(q1[1], q2[1])
  CNOT: QRegs(q0[1], q1[1])

text

Accumulated rendered text.

indent

Current indentation level (in spaces).

fold_modules

List of operation names to fold (hide their children).

folding

Whether currently inside a folded subtree.

hidden

Whether current node should be hidden.

__init__(fold_modules=None)

Initialize the renderer.

参数:

fold_modules -- List of operation names to fold. Children of these operations will not be rendered.

enter(node)

Called when entering a node during traversal.

Increases indent level and manages folding state.

参数:

node -- The Operation node being entered.

exit(node)

Called when exiting a node during traversal.

Decreases indent level and resets folding state when leaving a folded module.

参数:

node -- The Operation node being exited.

visit(node, dagger_ctx=False, controllers_ctx=None)

Visit a node and render its plain string representation.

Calls node.plain_render_this() to get the formatted string for this node, then appends it to the accumulated text.

参数:

• node -- The Operation node to visit.

• dagger_ctx -- Whether the node is being traversed in dagger mode.

• controllers_ctx -- Current controller context from parent nodes.

ToffoliCounter

class pyqres.core.visitor.ToffoliCounter

基类：object

Visitor that computes total Toffoli gate count via lowering.

__init__()

enter(node)

exit(node)

visit(node, dagger_ctx=False, controllers_ctx=None)

get_count()

get_result()

Lowering

LoweringEngine

class pyqres.core.lowering.LoweringEngine

基类：object

Recursively lowers an Operation tree to primitives and computes resource costs.

estimate(operation, estimator)

TCountEstimator

class pyqres.core.lowering.TCountEstimator

基类：ResourceEstimator

create_visitor()

Create a visitor that computes this resource during traversal.

property name

Human-readable name of this resource type.

TDepthEstimator

class pyqres.core.lowering.TDepthEstimator

基类：ResourceEstimator

create_visitor()

Create a visitor that computes this resource during traversal.

property name

Human-readable name of this resource type.

QECEstimator

class pyqres.core.lowering.QECEstimator

基类：ResourceEstimator

Estimator that lowers to QEC-compiler AbstractCircuit.

create_visitor()

Create a visitor that computes this resource during traversal.

property name

Human-readable name of this resource type.

pyqres.core.lowering.to_abstract_circuit(operation)

Lower a pyqres Operation tree to a QEC AbstractCircuit.

Requires qec-compiler to be installed.

QEC lowering internals

class pyqres.core.qec_lowering.QECLoweringVisitor

基类：object

Visitor that lowers an Operation tree to QEC AbstractCircuit gates.

__init__()

enter(node)

exit(node)

visit(node, dagger_ctx=False, controllers_ctx=None)

build_circuit(operation=None)

Build the final AbstractCircuit from accumulated gates.

If operation is provided, runs traverse after pre-declaring registers and allocating qubit indices for all root registers.

class pyqres.core.qec_lowering.UnsupportedQECPrimitive

基类：Exception

Raised when a primitive cannot be lowered to QEC-compiler gates.

模拟器

SimulatorVisitor

class pyqres.core.simulator.SimulatorVisitor(verbose=False)

基类：object

Visitor that executes operations on a pysparq sparse state.

__init__(verbose=False)

enter(node)

exit(node)

visit(node, dagger_ctx=False, controllers_ctx=None)

print_state(option=None, precision=None)

get_result()

PyQSparseOperationWrapper

class pyqres.core.simulator.PyQSparseOperationWrapper(op)

基类：object

Wrapper for pysparq operations with controller and dagger support.

__init__(op)

set_controller(controllers_ctx)

set_dagger(dagger_ctx)

工具函数

pyqres.core.utils.merge_controllers(controller1, controller2)

Merge controller2 into controller1, returning a new dict.

pyqres.core.utils.reg_sz(reg_name)

pyqres.core.utils.get_control_qubit_count(controllers)

pyqres.core.utils.mcx_t_count(ncontrols)

T-count for multi-controlled X gate.