Visualization

Interactive HTML

pyqres.visualization can write standalone HTML files for an already constructed operation object. The files contain inline CSS and JavaScript, so they can be opened directly in a browser without running a local server.

The call-tree view renders every operation node as expandable details elements and shows registers, parameters, controllers, dagger state, and submodules.

The circuit view renders a register-level timeline. The sidebar lets you switch between call-tree and circuit views, choose a maximum expansion depth, and select specific composite module instances to expand. Depth 0 keeps the root module collapsed, depth 1 expands one module level, and each larger value expands one more level. Changing these controls redraws the circuit in the browser.

Generated views

Call tree HTML is intended for checking operation structure before lowering:

• composite and primitive node names

• register and temporary-register usage

• parameter values

• controller and dagger contexts after propagation

• generated submodules

Circuit HTML is a register-level view. It is deliberately higher level than a gate-by-gate QEC circuit: a composite can stay collapsed as one module block or be expanded in the browser. This is useful for QDA and block-encoding inspection, where expanding every primitive immediately makes the drawing too large.

Expansion semantics

The circuit sidebar has two expansion controls:

• Expansion depth expands composite modules by tree depth. 0 means the root remains a single module, 1 expands the root one level, and larger values expand deeper nested composites.

• Module overrides lists composite module instances. Checking one forces that module to expand even if the global depth would keep it collapsed.

Register sizes are inferred from RegisterMetadata, temporary-register declarations, and structural register operations such as SplitRegister and AddRegister. Dynamically created registers such as _overflow and _other should therefore show their qubit counts when enough structural information is present in the operation tree.

from pyqres.core.metadata import RegisterMetadata
from pyqres.algorithms.block_encoding import BlockEncodingTridiagonal
from pyqres.visualization import write_call_tree_html, write_circuit_html

rm = RegisterMetadata.get_register_metadata()
rm.declare_register("main", 2, "UnsignedInteger")
rm.declare_register("anc_UA", 4, "UnsignedInteger")

op = BlockEncodingTridiagonal(
    main_reg="main",
    anc_UA="anc_UA",
    alpha=0.5,
    beta=0.3,
)

write_call_tree_html(op, "block_encoding_tree.html")
write_circuit_html(op, "block_encoding_circuit.html")

There is also a small QDA-Tridiagonal example:

python examples/qda_tridiagonal_visualization.py

It writes:

• visualizations/qda_tridiagonal_tree.html

• visualizations/qda_tridiagonal_circuit.html

Public API

• operation_to_tree_data(operation) returns the JSON-serializable tree model used by both HTML renderers. This is useful for tests or custom downstream visualization tools.

• render_call_tree_html(operation, title=None) and render_circuit_html(operation, title=None) return HTML text without writing a file.

• write_call_tree_html(operation, path, title=None) and write_circuit_html(operation, path, title=None) write the standalone HTML file and return the output Path.

API

pyqres.visualization.operation_to_tree_data(operation)

Return a JSON-serializable operation tree model.

返回类型:

dict

pyqres.visualization.render_call_tree_html(operation, title=None)

Render an expandable operation call tree as a standalone HTML page.

返回类型:

str

pyqres.visualization.render_circuit_html(operation, title=None)

Render an interactive register-level circuit as standalone HTML.

返回类型:

str

pyqres.visualization.write_call_tree_html(operation, path, title=None)

Write an expandable operation call tree HTML file.

返回类型:

Path

pyqres.visualization.write_circuit_html(operation, path, title=None)

Write an interactive register-level circuit HTML file.

返回类型:

Path

Quantikz 线路图

Quantum-Resource-Estimator 支持使用 Quantikz LaTeX 包生成量子线路图。

生成线路图

from pyqres.core.metadata import RegisterMetadata
from pyqres.primitives import X
from pyqres.quantikz import QuantikzVisitor

rm = RegisterMetadata.get_register_metadata()
rm.declare_register("ctrl", 1)
rm.declare_register("q", 1)

op = X(["q"], [0]).control_by_all_ones("ctrl")

visitor = QuantikzVisitor()
op.traverse(visitor)
latex = visitor.to_latex()

Quantikz 输出是 register-level 线路图。它会展开 pyqres Operation 树， 继承 controller context，并按照 dagger traversal 逆序渲染子操作。若需要直接 构造 timeline，也可以使用 QuantumCircuit、OpCode 和 LatexGenerator。

依赖

• LaTeX 系统（需安装 pdflatex）

• quantikz2 LaTeX 包