APIs

match(
    r::ZXCalculus.ZX.AbstractRule,
    _::ZXCalculus.ZX.AbstractZXDiagram{T, P}
) -> Array{ZXCalculus.ZX.Match{_A}, 1} where _A

Find all vertices in ZX-diagram zxd that match the pattern of rule r.

Returns a vector of Match objects containing the matched vertex sets.

replace!(
    r::ZXCalculus.ZX.AbstractRule,
    zxd::ZXCalculus.ZX.AbstractZXDiagram
) -> ZXCalculus.ZX.AbstractZXDiagram

Match and replace with the rule r.

Returns the modified ZX-diagram.

ne(zxd; count_mul = false)

Returns the number of edges of a ZX-diagram. If count_mul, it will return the sum of multiplicities of all multiple edges. Otherwise, it will return the number of multiple edges.

neighbors(zxd, v; count_mul = false)

Returns a vector of vertices connected to v. If count_mul, there will be multiple copy for each vertex. Otherwise, each vertex will only appear once.

nv(zxd)

Returns the number of vertices (spiders) of a ZX-diagram.

add_power!(
    _::ZXCalculus.ZX.AbstractZXDiagram,
    n
) -> ZXCalculus.ZX.ZXDiagram

Add n to the power of √2 in the global scalar.

add_global_phase!(
    _::ZXCalculus.ZX.AbstractZXDiagram,
    p
) -> ZXCalculus.ZX.ZXDiagram

Add phase p to the global phase of the ZX-diagram.

add_spider!(
    _::ZXCalculus.ZX.AbstractZXDiagram,
    stype,
    args...
) -> Any

Add a new spider with spider type st and phase p to the ZX-diagram.

Returns the vertex identifier of the newly added spider.

add_spider!(zxd, spider_type, phase = 0, connect = [])

Add a new spider which is of the type spider_type with phase phase and connected to the vertices connect.

ancilla_extraction(
    zxg::Union{ZXCalculus.ZX.ZXCircuit, ZXCalculus.ZX.ZXGraph}
) -> ZXCalculus.ZX.ZXCircuit{Int64, ZXCalculus.Utils.Phase}

Extract a quantum circuit from a general ZX-graph even without a gflow.

This function can handle ZX-graphs that don't have a generalised flow (gflow), and will introduce post-selection operators as needed.

Returns a ZXCircuit representing the extracted circuit.

base_zx_graph(
    _::ZXCalculus.ZX.AbstractZXCircuit
) -> ZXCalculus.ZX.ZXGraph

Get the underlying ZXGraph of the circuit.

biadjacency(zxg, F, N)

Return the biadjacency matrix of zxg from vertices in F to vertices in N.

check_rule(
    r::ZXCalculus.ZX.AbstractRule,
    _::ZXCalculus.ZX.AbstractZXDiagram{T, P},
    _::Array{T, 1}
) -> Bool

Check whether the vertices vs in ZX-diagram zxd still match the rule r.

This is used to verify that a previously matched pattern is still valid before rewriting, as the diagram may have changed since the match was found.

Returns true if the vertices still match the rule pattern, false otherwise.

circuit_extraction(
    zxg::Union{ZXCalculus.ZX.ZXCircuit{T, P}, ZXCalculus.ZX.ZXGraph{T, P}}
) -> YaoHIR.Chain

Extract a quantum circuit from a graph-like ZX-diagram.

This is the main circuit extraction algorithm that converts a ZX-diagram in graph-like form into an equivalent quantum circuit.

Returns a ZXDiagram representing the extracted circuit.

clifford_simplification(
    circ::ZXCalculus.ZX.ZXDiagram
) -> ZXCalculus.ZX.ZXCircuit{T, P} where {T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}

Simplify zxd with the Clifford simplification algorithms in arXiv:1902.03178.

This applies a sequence of local complementation and pivot rules to simplify the ZX-diagram while preserving Clifford structure.

Returns the simplified ZX-diagram.

column_loc(
    _::ZXCalculus.ZX.AbstractZXCircuit,
    v
) -> Union{Nothing, Rational{Int64}}

Get the column (time/depth) location of spider v in the circuit layout.

Returns a rational number representing the position along the circuit, or nothing if not in layout.

column_loc(
    layout::ZXCalculus.ZX.ZXLayout{T},
    v
) -> Union{Nothing, Rational{Int64}}

Return the column number corresponding to the spider v, or nothing if not in layout.

concat!(
    circ1::ZXCalculus.ZX.ZXCircuit{T, P},
    circ2::ZXCalculus.ZX.ZXCircuit{T, P}
) -> ZXCalculus.ZX.ZXCircuit

Concatenate two ZX-circuits, where the second circuit is appended after the first.

The circuits must have the same number of qubits. The outputs of the first circuit are connected to the inputs of the second circuit.

Returns the modified first circuit.

concat!(
    zxd_1::ZXCalculus.ZX.ZXDiagram{T, P},
    zxd_2::ZXCalculus.ZX.ZXDiagram{T, P}
) -> ZXCalculus.ZX.ZXDiagram

Appends two diagrams, where the second diagram is inverted

convert_to_zx_circuit(
    root::YaoHIR.BlockIR
) -> ZXCalculus.ZX.ZXCircuit{Int64, ZXCalculus.Utils.Phase}

Convert a BlockIR to a ZXCircuit.

This is the main conversion function from YaoHIR's BlockIR representation to ZXCalculus. It translates each gate operation in the BlockIR to the corresponding ZX-diagram representation in a ZXCircuit.

Arguments

• root::YaoHIR.BlockIR: The BlockIR representation to convert

Returns

• ZXCircuit: The circuit representation in ZX-calculus form

Examples

using YaoHIR, ZXCalculus

# Create a BlockIR from a quantum circuit
bir = BlockIR(...)

# Convert to ZXCircuit (two equivalent ways)
zxc = convert_to_zx_circuit(bir)
zxc = ZXCircuit(bir)  # Constructor syntax

# Convert back to YaoHIR Chain
chain = convert_to_chain(zxc)

See also: ZXCircuit, convert_to_chain

convert_to_zxd(
    root::YaoHIR.BlockIR
) -> ZXCalculus.ZX.ZXDiagram{Int64, ZXCalculus.Utils.Phase}

Convert a BlockIR to a ZXDiagram.

Returns a ZXDiagram for backward compatibility.

dagger(
    circ::ZXCalculus.ZX.ZXCircuit{T, P}
) -> ZXCalculus.ZX.ZXCircuit{_A, _B} where {_B, _A}

Compute the dagger (adjoint) of a ZX-circuit.

This swaps inputs and outputs and negates all phases. The dagger operation corresponds to the adjoint of the quantum operation represented by the circuit.

Returns a new ZX-circuit representing the adjoint operation.

dagger(
    zxd::ZXCalculus.ZX.ZXDiagram{T, P}
) -> ZXCalculus.ZX.ZXDiagram

Dagger of a ZXDiagram by swapping input and outputs and negating the values of the phases

edge_type(
    _::ZXCalculus.ZX.AbstractZXDiagram,
    v1,
    v2
) -> ZXCalculus.ZX.EdgeType.EType

Return the edge type between vertices v1 and v2 in the ZX-diagram.

find_inputs(zxg::ZXGraph)

Find all spiders with type SpiderType.In in the graph. This is a search utility and does not guarantee circuit structure or ordering.

find_outputs(zxg::ZXGraph)

Find all spiders with type SpiderType.Out in the graph. This is a search utility and does not guarantee circuit structure or ordering.

gaussian_elimination(M[, steps])

Return result and steps of Gaussian elimination of matrix M. Here we assume that the elements of M is in binary field F_2 = {0,1}.

generate_layout!(
    _::ZXCalculus.ZX.AbstractZXCircuit
) -> ZXCalculus.ZX.ZXLayout

Generate or update the layout for the circuit.

This computes the spatial positioning (qubit and column locations) of all spiders for visualization and analysis purposes.

Returns a ZXLayout object containing the layout information.

get_input_idx(zwd::ZXDiagram{T,P}, q::T) where {T,P}

Get spider index of input qubit q. Returns -1 if non-existant

get_inputs(
    _::ZXCalculus.ZX.AbstractZXCircuit
) -> Vector{T} where T<:Integer

Get the ordered input spider vertices of the circuit.

Returns a vector of vertex identifiers in qubit order.

get_inputs(zxd)

Returns a vector of input ids.

get_output_idx(zxd::ZXDiagram{T,P}, q::T) where {T,P}

Get spider index of output qubit q. Returns -1 is non-existant

get_outputs(
    _::ZXCalculus.ZX.AbstractZXCircuit
) -> Vector{T} where T<:Integer

Get the ordered output spider vertices of the circuit.

Returns a vector of vertex identifiers in qubit order.

get_outputs(zxd)

Returns a vector of output ids.

import_edges!(
    circ1::ZXCalculus.ZX.ZXCircuit{T, P},
    circ2::ZXCalculus.ZX.ZXCircuit{T, P},
    v2tov1::Dict{T, T}
)

Import edges of circ2 to circ1, modifying circ1.

import_edges!(
    d1::ZXCalculus.ZX.ZXDiagram{T, P},
    d2::ZXCalculus.ZX.ZXDiagram{T, P},
    v2tov1::Dict{T, T}
)

Import edges of d2 to d1, modify d1

import_non_in_out!(
    circ1::ZXCalculus.ZX.ZXCircuit{T, P},
    circ2::ZXCalculus.ZX.ZXCircuit{T, P},
    v2tov1::Dict{T, T}
)

Add non-input and non-output spiders of circ2 to circ1, modifying circ1.

Records the mapping of vertex indices from circ2 to circ1.

import_non_in_out!(
    d1::ZXCalculus.ZX.ZXDiagram{T, P},
    d2::ZXCalculus.ZX.ZXDiagram{T, P},
    v2tov1::Dict{T, T}
)

Add non input and output spiders of d2 to d1, modify d1. Record the mapping of vertex indices.

insert_spider!(
    _::ZXCalculus.ZX.AbstractZXDiagram,
    v1,
    v2,
    stype,
    args...
) -> Vector{K} where K<:Integer

Insert a new spider on the edge between vertices v1 and v2.

Returns the vertex identifier of the newly inserted spider.

insert_spider!(zxd, v1, v2, spider_type, phase = 0)

Insert a spider of the type spider_type with phase = phase, between two vertices v1 and v2. It will insert multiple times if the edge between v1 and v2 is a multiple edge. Also it will remove the original edge between v1 and v2.

is_hadamard(
    zxg::ZXCalculus.ZX.AbstractZXDiagram,
    v1,
    v2
) -> Bool

Return true if the edge between vertices v1 and v2 is a Hadamard edge in the ZX-diagram.

is_interior(zxg::ZXGraph, v)

Return true if v is a interior spider of zxg.

nin(zxd::ZXCalculus.ZX.AbstractZXDiagram) -> Any

Get the number of input spiders in the circuit.

nout(zxd::ZXCalculus.ZX.AbstractZXDiagram) -> Any

Get the number of output spiders in the circuit.

nqubits(_::ZXCalculus.ZX.AbstractZXCircuit) -> Int64

Get the number of qubits in the circuit.

Returns an integer representing the qubit count.

nqubits(zxd)

Returns the qubit number of a ZX-diagram.

phase(
    _::ZXCalculus.ZX.AbstractZXDiagram,
    v
) -> ZXCalculus.Utils.AbstractPhase

Get the phase of spider v in the ZX-diagram.

Returns a phase value (typically AbstractPhase).

phase(zxd, v)

Returns the phase of a spider. If the spider is not a Z or X spider, then return 0.

phase_teleportation(
    cir::ZXCalculus.ZX.ZXDiagram
) -> ZXCalculus.ZX.ZXDiagram

Reduce T-count of zxd with the phase teleportation algorithms in arXiv:1903.10477.

This optimization technique reduces the number of non-Clifford (T) gates in the circuit by teleporting phases through the diagram.

Returns a ZX-diagram with reduced T-count.

phases(
    _::ZXCalculus.ZX.AbstractZXDiagram
) -> Dict{T, P} where {T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}

Get all spider phases in the ZX-diagram.

Returns a dictionary mapping vertex identifiers to their phases.

plot(zxd::ZXCalculus.ZX.AbstractZXDiagram; kwargs...)

Plot the ZX-diagram.

push_gate!(
    _::ZXCalculus.ZX.AbstractZXCircuit,
    args...
) -> ZXCalculus.ZX.ZXCircuit{T, P} where {T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}

Add a gate to the end of the circuit.

push_gate!(
    _::ZXCalculus.ZX.ZXCircuit{T, P},
    gate::Val{G},
    args...
) -> ZXCalculus.ZX.ZXCircuit

Add a gate to the end of the circuit.

Arguments

• circ: The circuit to modify
• gate: Gate type as Val (e.g., Val(:H), Val(:CNOT))
• locs: Qubit locations where the gate is applied
• phase: Optional phase parameter for phase gates (:Z, :X)

Supported gates

• Single-qubit: :Z, :X, :H
• Two-qubit: :CNOT, :CZ, :SWAP

push_gate!(zxd, ::Val{M}, locs...[, phase]; autoconvert=true)

Push an M gate to the end of qubit loc where M can be :Z, :X, :H, :SWAP, :CNOT and :CZ. If M is :Z or :X, phase will be available and it will push a rotation M gate with angle phase * π. If autoconvert is false, the input phase should be a rational numbers.

pushfirst_gate!(
    _::ZXCalculus.ZX.AbstractZXCircuit,
    args...
) -> ZXCalculus.ZX.ZXCircuit{T, P} where {T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}

Add a gate to the beginning of the circuit.

pushfirst_gate!(
    _::ZXCalculus.ZX.ZXCircuit{T, P},
    gate::Val{G},
    args...
) -> ZXCalculus.ZX.ZXCircuit

Add a gate to the beginning of the circuit.

Arguments

• circ: The circuit to modify
• gate: Gate type as Val (e.g., Val(:H), Val(:CNOT))
• locs: Qubit locations where the gate is applied
• phase: Optional phase parameter for phase gates (:Z, :X)

Supported gates

• Single-qubit: :Z, :X, :H
• Two-qubit: :CNOT, :CZ, :SWAP

pushfirst_gate!(zxd, ::Val{M}, loc[, phase])

Push an M gate to the beginning of qubit loc where M can be :Z, :X, :H, :SWAP, :CNOT and :CZ. If M is :Z or :X, phase will be available and it will push a rotation M gate with angle phase * π.

qubit_loc(
    _::ZXCalculus.ZX.AbstractZXCircuit,
    v
) -> Union{Nothing, Rational{Int64}}

Get the qubit (row) location of spider v in the circuit layout.

Returns an integer representing the qubit wire index (1 to nqubits), or nothing if not in layout.

qubit_loc(
    layout::ZXCalculus.ZX.ZXLayout{T},
    v
) -> Union{Nothing, Rational{Int64}}

Return the qubit number corresponding to the spider v, or nothing if not in layout.

rem_spider!(zxd::ZXCalculus.ZX.AbstractZXDiagram, v) -> Bool

Remove spider v from the ZX-diagram.

rem_spider!(zxd, v)

Remove a spider indexed by v.

rem_spiders!(_::ZXCalculus.ZX.AbstractZXDiagram, vs) -> Bool

Remove multiple spiders vs from the ZX-diagram.

rem_spiders!(zxd, vs)

Remove spiders indexed by vs.

rewrite!(
    r::ZXCalculus.ZX.AbstractRule,
    zxd::ZXCalculus.ZX.AbstractZXDiagram{T, P},
    matches::Array{ZXCalculus.ZX.Match{T}, 1}
) -> ZXCalculus.ZX.AbstractZXDiagram{T, P} where {T, P}

Rewrite a ZX-diagram zxd with rule r for all vertices in matches.

The matches parameter can be a vector of Match objects or a single Match instance.

Returns the modified ZX-diagram.

rewrite!(
    r::ZXCalculus.ZX.AbstractRule,
    _::ZXCalculus.ZX.AbstractZXDiagram{T, P},
    _::Array{T, 1}
) -> ZXCalculus.ZX.ZXGraph

Rewrite a ZX-diagram zxd with rule r for the specific vertices vs.

This is the core rewriting function that must be implemented for each rule.

Returns the modified ZX-diagram.

round_phases!(_::ZXCalculus.ZX.AbstractZXDiagram)

Round all phases in the ZX-diagram to the range [0, 2π).

round_phases!(zxd)

Round phases between [0, 2π).

scalar(
    _::ZXCalculus.ZX.AbstractZXDiagram
) -> ZXCalculus.Utils.Scalar{P} where P<:ZXCalculus.Utils.AbstractPhase

Get the global scalar of the ZX-diagram.

Returns a Scalar object containing the phase and power of √2.

scalar(zxd)

Returns the scalar of zxd.

set_column!(
    layout::ZXCalculus.ZX.ZXLayout{T},
    v,
    col
) -> ZXCalculus.ZX.ZXLayout{T} where T

Set the column number of the spider v to col.

set_edge_type!(
    _::ZXCalculus.ZX.AbstractZXDiagram,
    v1,
    v2,
    etype
) -> Bool

Set the edge type between vertices v1 and v2 in the ZX-diagram.

set_loc!(
    layout::ZXCalculus.ZX.ZXLayout{T},
    v,
    q,
    col
) -> ZXCalculus.ZX.ZXLayout{T} where T

Set both the qubit and column location of the spider v.

set_phase!(_::ZXCalculus.ZX.AbstractZXDiagram, v, p) -> Bool

Set the phase of spider v to p in the ZX-diagram.

set_phase!(zxd, v, p)

Set the phase of v in zxd to p.

set_qubit!(
    layout::ZXCalculus.ZX.ZXLayout{T},
    v,
    q
) -> ZXCalculus.ZX.ZXLayout{T} where T

Set the qubit number of the spider v to q.

set_spider_type!(
    _::ZXCalculus.ZX.AbstractZXDiagram,
    v,
    st
) -> Bool

Set the spider type of vertex v to st in the ZX-diagram.

simplify!(
    r::ZXCalculus.ZX.AbstractRule,
    zxd::ZXCalculus.ZX.AbstractZXDiagram
) -> ZXCalculus.ZX.AbstractZXDiagram

Simplify zxd with the rule r.

Repeatedly applies the rule until no more matches are found or MAX_ITERATION is reached.

Returns the simplified ZX-diagram.

spider_sequence(
    _::ZXCalculus.ZX.AbstractZXCircuit
) -> Vector{Any}

Get the ordered sequence of spiders for each qubit.

Returns a vector of vectors, where each inner vector contains the spider vertices on a particular qubit wire, ordered by their column position.

spider_type(
    _::ZXCalculus.ZX.AbstractZXDiagram,
    v
) -> ZXCalculus.ZX.SpiderType.SType

Get the type of spider v in the ZX-diagram.

Returns a SpiderType.SType value (Z, X, H, In, or Out).

spider_type(zxd, v)

Returns the spider type of a spider.

spider_types(
    _::ZXCalculus.ZX.AbstractZXDiagram
) -> Dict{T, ZXCalculus.ZX.SpiderType.SType} where T<:Integer

Get all spider types in the ZX-diagram.

Returns a dictionary mapping vertex identifiers to their spider types.

spiders(
    _::ZXCalculus.ZX.AbstractZXDiagram
) -> Vector{K} where K<:Integer

Get all spider vertices in the ZX-diagram.

Returns a vector of vertex identifiers.

stype_to_val(st)::Union{SpiderType,nothing}

Converts SpiderType into Val

tcount(_::ZXCalculus.ZX.AbstractZXDiagram) -> Any

Count the number of non-Clifford phases (T-gates) in the ZX-diagram.

Returns an integer count.

tcount(zxd)

Returns the T-count of a ZX-diagram.

update_frontier!(zxg, frontier, qubit_map, cir)

Update frontier. This is an important step in the circuit extraction algorithm. For more detail, please check the paper arXiv:1902.03178.

verify_equality(
    circ_1::ZXCalculus.ZX.ZXCircuit,
    circ_2::ZXCalculus.ZX.ZXCircuit
) -> Bool

Check the equivalence of two different ZX-circuits.

This function concatenates the first circuit with the dagger of the second, then performs full reduction. If the result contains only bare wires, the circuits are equivalent.

Returns true if the circuits are equivalent, false otherwise.

verify_equality(
    zxd_1::ZXCalculus.ZX.ZXDiagram,
    zxd_2::ZXCalculus.ZX.ZXDiagram
) -> Bool

Check the equivalence of two different ZX-diagrams.

This function concatenates the first diagram with the dagger of the second, then performs full reduction. If the result contains only bare wires, the diagrams are equivalent.

Returns true if the diagrams are equivalent, false otherwise.

abstract type AbstractZXCircuit{T<:Integer, P<:ZXCalculus.Utils.AbstractPhase} <: ZXCalculus.ZX.AbstractZXDiagram{T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}

Abstract type for ZX-diagrams with circuit structure.

This type represents ZX-diagrams that have explicit quantum circuit semantics, including ordered inputs, outputs, and layout information for visualization.

Interface Requirements

Concrete subtypes must implement both:

1. The AbstractZXDiagram interfaces (graphinterface, calculusinterface)

2. The circuit-specific interfaces defined here:

   • circuit_interface.jl: Circuit structure and gate operations
   • layout_interface.jl: Layout information for visualization

Use Interfaces.test to verify implementations.

See also

• AbstractZXDiagram: Base abstract type for all ZX-diagrams
• ZXCircuit: Main implementation with ZXGraph composition
• ZXGraph: Pure graph representation without circuit assumptions

abstract type AbstractZXDiagram{T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}

Abstract type for ZX-diagrams, representing graph-like quantum circuit diagrams.

This type defines the base interface for all ZX-diagram representations, providing graph operations and spider (vertex) manipulation methods.

Interface Requirements

Concrete subtypes must implement the following interfaces:

• graph_interface.jl: Graph operations (Graphs.jl compatibility)
• calculus_interface.jl: Spider and scalar operations (ZX-calculus)

Use Interfaces.test to verify implementations.

See also: AbstractZXCircuit, ZXGraph, ZXCircuit

GEStep

A struct for representing steps in the Gaussian elimination.

struct IdentityRemovalRule <: ZXCalculus.ZX.AbstractRule

Removes identity spiders connected to two spiders or a Pauli spider connected to one Z-spider via a Hadamard edge.

struct LocalCompRule <: ZXCalculus.ZX.AbstractRule

Remove a Z-spider with Clifford phase by local complementary. Requirements:

• The spider must be interior (not connected to inputs/outputs)
• The spider must have Clifford phase (±pi/2)
• All edges connected to the spider must be hadamard edges.

struct Match{T<:Integer}

A struct for saving matched vertices from rule matching.

Fields

• vertices::Vector{T} where T<:Integer: Vector of vertex identifiers that match a rule pattern

struct Pivot1Rule <: ZXCalculus.ZX.AbstractRule

Remove two adjacent Pauli Z spiders by pivoting. Some requirements:

• Both spiders must be interior (not connected to inputs/outputs)
• Both spiders must have Pauli phases (0 or pi)
• The two spiders must be connected by an hadamard edge.

struct Pivot2Rule <: ZXCalculus.ZX.AbstractRule

The pivoting rule that convert an internal non-Clifford u Z-spider connected to an internal Pauli Z-spider v into a phase gadget. Requirements:

• The internal non-Clifford spider must have at least two neighbors (not a part of the phase gadget).
• The internal Pauli spider must be connected to the internal non-Clifford spider via a Hadamard edge.

struct Pivot3Rule <: ZXCalculus.ZX.AbstractRule

The pivoting rule that convert a boundary non-Clifford u Z-spider connected to an internal Pauli Z-spider v into a phase gadget. Requirements:

- The boundary non-Clifford spider must have at least two neighbors (otherwise should be extracted directly).
- The internal Pauli spider must be connected to the boundary non-Clifford spider via a Hadamard edge.

struct PivotBoundaryRule <: ZXCalculus.ZX.AbstractRule

Applying pivoting rule when an internal Pauli Z-spider u is connected to a Z-spider v on the boundary via a Hadamard edge.

struct PivotGadgetRule <: ZXCalculus.ZX.AbstractRule

• This rule should be only used in circuit extraction.
• This rule will do pivoting on u, v but preserve u, v.
• And the scalars are not considered in this rule.
• gadget_u is the non-Clifford spider

Rule{L}

The struct for identifying different rules.

Rule for ZXDiagrams:

• FusionRule(): fusion rule (also available as Rule{:f}())
• XToZRule(): hadamard rule (also available as Rule{:h}())
• Identity1Rule(): identity rule 1 (also available as Rule{:i1}())
• HBoxRule(): identity rule 2 (also available as Rule{:i2}())
• PiRule(): π rule (also available as Rule{:pi}())
• CopyRule(): copy rule (also available as Rule{:c}())
• BialgebraRule(): bialgebra rule (also available as Rule{:b}())
• ScalarRule(): scalar rule (also available as Rule{:scalar}())

Rule for ZXGraphs:

• LocalCompRule(): local complementary rule (also available as Rule{:lc}())
• Pivot1Rule(): pivoting rule (also available as Rule{:p1}())
• PivotBoundaryRule(): rule for removing Pauli spiders adjacent to boundary spiders (also available as Rule{:pab}())
• Pivot2Rule(): pivot rule 2 (also available as Rule{:p2}())
• Pivot3Rule(): pivot rule 3 (also available as Rule{:p3}())
• IdentityRemovalRule(): identity removal rule (also available as Rule{:id}())
• GadgetFusionRule(): gadget fusion rule (also available as Rule{:gf}())
• PivotGadgetRule(): pivot gadget rule (also available as Rule{:pivot}())
• ScalarRule(): scalar rule (also available as Rule{:scalar}())

struct ZXCircuit{T, P} <: ZXCalculus.ZX.AbstractZXCircuit{T, P}

This is the type for representing ZX-circuits with explicit circuit structure.

ZXCircuit separates the graph representation (ZXGraph) from circuit semantics (ordered inputs/outputs and layout). This design enables efficient graph-based simplification while maintaining circuit structure for extraction and visualization.

Fields

• zx_graph::ZXCalculus.ZX.ZXGraph{T, P} where {T, P}: The underlying ZXGraph representation

• inputs::Vector: Ordered input spider vertices

• outputs::Vector: Ordered output spider vertices

• layout::ZXCalculus.ZX.ZXLayout{T} where T: Layout information for visualization

• phase_ids::Dict{T, Tuple{T, Int64}} where T: Maps vertex id to its master id and scalar multiplier for phase tracking

• master::Union{Nothing, ZXCalculus.ZX.ZXCircuit{T, P}} where {T, P}: Reference to master circuit for phase tracking (optional)

ZXCircuit(
    nbits::Integer
) -> ZXCalculus.ZX.ZXCircuit{T, ZXCalculus.Utils.Phase} where T<:Integer

Construct an empty ZX-circuit with nbits qubits.

Each qubit is represented by a pair of In/Out spiders connected by a simple edge. This creates a minimal circuit structure ready for gate insertion.

Example

julia> circ = ZXCircuit(3)
ZXCircuit with 3 inputs and 3 outputs...

struct ZXDiagram{T<:Integer, P<:ZXCalculus.Utils.AbstractPhase} <: ZXCalculus.ZX.AbstractZXCircuit{T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}

This is the type for representing ZX-diagrams.

Fields

• mg::Multigraph: The underlying multigraph structure

• st::Dict{T, ZXCalculus.ZX.SpiderType.SType} where T<:Integer: Spider types indexed by vertex

• ps::Dict{T, P} where {T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}: Phases of spiders indexed by vertex

• layout::ZXCalculus.ZX.ZXLayout: Layout information for visualization

• phase_ids::Dict{T, Tuple{T, Int64}} where T<:Integer: Maps vertex id to its master id and scalar multiplier

• scalar::ZXCalculus.Utils.Scalar{P} where P<:ZXCalculus.Utils.AbstractPhase: Global scalar factor

• inputs::Vector{T} where T<:Integer: Ordered input spider vertices

• outputs::Vector{T} where T<:Integer: Ordered output spider vertices

ZXDiagram(nbits)

Construct a ZXDiagram of a empty circuit with qubit number nbit

julia> zxd = ZXDiagram(3)
ZX-diagram with 6 vertices and 3 multiple edges:
(S_1{input} <-1-> S_2{output})
(S_3{input} <-1-> S_4{output})
(S_5{input} <-1-> S_6{output})

ZXDiagram(mg::Multigraph{T}, st::Dict{T, SpiderType.SType}, ps::Dict{T, P},
    layout::ZXLayout{T} = ZXLayout{T}(),
    phase_ids::Dict{T,Tuple{T, Int}} = Dict{T,Tuple{T,Int}}()) where {T, P}
ZXDiagram(mg::Multigraph{T}, st::Vector{SpiderType.SType}, ps::Vector{P},
    layout::ZXLayout{T} = ZXLayout{T}()) where {T, P}

Construct a ZXDiagram with all information.

struct ZXGraph{T<:Integer, P<:ZXCalculus.Utils.AbstractPhase} <: ZXCalculus.ZX.AbstractZXDiagram{T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}

This is the type for representing the graph-like ZX-diagrams.

A pure graph representation without circuit structure assumptions. Spiders of type In/Out can exist but are treated as searchable vertices, not as ordered inputs/outputs.

Fields

• mg::Multigraph: The underlying multigraph structure

• ps::Dict{T, P} where {T<:Integer, P<:ZXCalculus.Utils.AbstractPhase}: Phases of spiders indexed by vertex

• st::Dict{T, ZXCalculus.ZX.SpiderType.SType} where T<:Integer: Spider types indexed by vertex

• et::Dict{Tuple{T, T}, ZXCalculus.ZX.EdgeType.EType} where T<:Integer: Edge types indexed by sorted vertex pairs

• scalar::ZXCalculus.Utils.Scalar{P} where P<:ZXCalculus.Utils.AbstractPhase: Global scalar factor

struct ZXLayout{T<:Integer}

A struct for the layout information of ZX-circuits.

Fields

• nbits::Int64: Number of qubits in the circuit

• spider_q::Dict{T, Rational{Int64}} where T<:Integer: Mapping from spider vertices to qubit locations

• spider_col::Dict{T, Rational{Int64}} where T<:Integer: Mapping from spider vertices to column positions

match(r, zxwd)

Returns all matched vertices, which will be store in sturct Match, for rule r in a ZXW-diagram zxwd.

Rule that implements both f and s1 rule.

ne(zxwd; count_mul = false)

Returns the number of edges of a ZXW-diagram. If count_mul, it will return the sum of multiplicities of all multiple edges. Otherwise, it will return the number of multiple edges.

neighbors(zxwd, v; count_mul = false)

Returns a vector of vertices connected to v. If count_mul, there will be multiple copy for each vertex. Otherwise, each vertex will only appear once.

nv(zxwd)

Returns the number of vertices (spiders) of a ZXW-diagram.

push_gate!(zxwd, ::Val{M}, locs...[, phase]; autoconvert=true)

Push an M gate to the end of qubit loc where M can be :Z, :X, :H, :SWAP, :CNOT and :CZ. If M is :Z or :X, phase will be available and it will push a rotation M gate with angle phase * π. If autoconvert is false, the input phase should be a rational numbers.

pushfirst_gate!(zxwd, ::Val{M}, loc[, phase])

Push an M gate to the beginning of qubit loc where M can be :Z, :X, :H, :SWAP, :CNOT and :CZ. If M is :Z or :X, phase will be available and it will push a rotation M gate with angle phase * π.

rem_spider!(zxwd, v)

Remove a spider indexed by v.

rem_spiders!(zxwd, vs)

Remove spiders indexed by vs.

rewrite!(r, zxd, matches)

Rewrite a ZX-diagram zxd with rule r for all vertices in matches. matches can be a vector of Match or just an instance of Match.

Add input and outputs to diagram

add_spider!(zxwd, spider, connect = [])

Add a new spider spider with appropriate parameter connected to the vertices connect.

Concatenate two ZXWDiagrams, modify d1.

Remove outputs of d1 and inputs of d2. Then add edges between to vertices that was conntecting to outputs of d1 and inputs of d2. Assuming you don't concatenate two empty circuit ZXWDiagram

Convert ZXWDiagram that represents unitary U to U^†

Construct ZXW Diagram for representing the expectation value circuit

get_inputs(zxwd)

Returns a vector of input ids.

get_outputs(zxwd)

Returns a vector of output ids.

Import edges of d2 to d1, modify d1

Add non input and output spiders of d2 to d1, modify d1. Record the mapping of vertex indices.

insert_spider!(zxwd, v1, v2, spider)

Insert a spider spider with appropriate parameter, between two vertices v1 and v2. It will insert multiple times if the edge between v1 and v2 is a multiple edge. Also it will remove the original edge between v1 and v2.

Insert W triangle on a vector of vertices

Prepare spider at loc for integration.

Perform the simplified step of zeroing out phase of spider and readying it for integration

1. If target spider is X spider, turn it to Z by adding H to all its legs
2. Pull out the Phase of the spider
3. zero out the phase
4. change the current spider back to its original type if necessary,

will generate one extra H spider.

Integrate two pairs of +/- parameter. Theorem 23 of https://arxiv.org/abs/2201.13250

nout(zxwd)

Returns the number of outputs of a ZXW-diagram

nqubits(zxwd)

Returns the qubit number of a ZXW-diagram.

parameter(zxwd, v)

Returns the parameter of a spider. If the spider is not a Z or X spider, then return 0.

print_spider(io, zxwd, v)

Print a spider to io.

round_phases!(zxwd)

Round phases between [0, 2π).

set_phase!(zxwd, v, p)

Set the phase of v in zxwd to p. If v is not a Z or X spider, then do nothing. If v is not in zxwd, then return false to indicate failure.

spider_type(zxwd, v)

Returns the spider type of a spider if it exists.

Stacking two ZXWDiagrams in place. Modify d1.

Performs tensor product of two ZXWDiagrams. The result is a ZXWDiagram with d1 on lower qubit indices. Assuming number of inputs and outputs of are the same for both d1 and d2.

Replace symbols in ZXW Diagram with specific values

Finds vertices of Spider that contains the parameter θ or -θ

Graphs.add_edge!(zwd::ZWDiagram, he, mul)

Add mul of edges that connects vertices with already connected with edgex.

rem_edge!(zwd::ZWDiagram, x)

Remove Edge with indices x.

ne(zwd)

Returns the number of edges of a ZW-diagram.

neighbors(zwd, v)

Returns a vector of vertices connected to v.

nv(zwd)

Returns the number of vertices (spiders) of a ZW-diagram.

add_spider!(zwd, spider, connect = [])

Add a new spider spider with appropriate parameter connected to the half edges connect.

Had to make halfedge class 1 citizen because there will be ambiguity Consider A to B and there are multiple edges to A and from A to B

get_input_idx(zwd::ZXWDiagram{T,P}, q::T) where {T,P}

Get spider index of input qubit q.

get_inputs(zwd)

Returns a vector of input ids.

get_output_idx(zwd::ZWDiagram{T,P}, q::T) where {T,P}

Get spider index of output qubit q.

get_outputs(zwd)

Returns a vector of output ids.

insert_spider!(zwd, he1, spider)

Insert a spider spider with appropriate parameter on the half-edge prior to he1. v1 <- he1 - v2 becomes v1 <- he1 - v2 <- henew - vnew

nout(zwd)

Returns the number of outputs of a ZW-diagram

nqubits(zwd)

Returns the qubit number of a ZW-diagram.

parameter(zwd, v)

Returns the parameter of a spider. If the spider is not a monoZ or binZ spider, then return 0.

print_spider(io, zwd, v)

Print a spider to io.

round_phases!(zwd)

Round phases between [0, 2π).

set_phase!(zwd, v, p)

Set the phase of v in zwd to p. If v is not a monoZ or binZ spider, then do nothing. If v is not in zwd, then return false to indicate failure.

spider_type(zwd, v)

Returns the spider type of a spider if it exists.

spiders(zwd::ZWDiagram)

Returns a vector of spider idxs.

ZWDiagram(nbits::T, ::Type{P}) where {T<:Integer}

Create a ZW-diagram with nbits input and output qubits.

Scalar is parameterized to be P.

continued_fraction(ϕ, n::Int) -> Rational

Obtain s and r from ϕ that satisfies |s//r - ϕ| ≦ 1/2r²

Parameter

The Algebraic Data Type for representing parameter related to spider. PiUnit(x) represents the the phase of a number exp(im*x*π). Factor(x) represents a number x.

Parameter Constructors for Parameter type.

Phase

The type supports manipulating phases as expressions. Phase(x) represents the number x⋅π.

Scalar

A struct for recording the scalars when we rewrite ZX-diagrams.

add_facet_to_boarder!(pmg::PlanarMultigraph{T}, h::T, g::T) where {T<:Integer}

Creates a facet with edge connecting the destination of h and g.

h and g needs to be in ccw order

Reference

• CGAL

add_vertex_and_facet_to_boarder!(
pmg::PlanarMultigraph{T},
h::T,
g::T,

) where {T<:Integer}

TBW

Reference

• CGAl

create_edge!(pmg::PlanarMultigraph{T}, vs::T, vd::T) where {T<:Integer}

Create an a pair of halfedge from vs to vd, add to PlanarMultigraph pmg. Facet information is not updated yet but set to default value of 0. Vertex to halfedge is updated and set to the two newly added half edges.

create_face!(pmg::PlanarMultigraph{T}) where {T<:Integer}

create_vertex!(g::PlanarMultigraph{T}; mul::Int = 1) where {T<:Integer}

Create vertices.

Create mul of vertices and record them in PlanarMultigraph g's v_max field.

erase_facet!(pmg::PlanarMultigraph{T}, h::T)

Erase the facet incident on h.

Reference

• CGAL Library

gc_vertex!(pmg::PlanarMultigraph{T}, vs::Vector{T}) where {T<:Integer}

Garbage collect vertices that's no longer connected to any edge.

is_boundary(g::PlanarMultigraph{T}, he_id::T) where {T}

If the half edge is on the boundary of entire manifold

join_facet!(pmg::PlanarMultigraph{T}, h::T) where {T}

Join two facets incident to h and it's twin into one.

The facet incident to h's twin is removed.

join_vertex!(pmg::PlanarMultigraph{T}, h::T) where {T<:Integer}

Join two vertices connected by a HalfEdge into one.

Provides the removal of an edge.

make_hole!(pmg::PlanarMultigraph{T}, h::T) where {T<:Integer}

Convert the facet incident to a half edge into a hole.

Makes all the half edges in the facet a boundary halfedge.

Reference

• CGAL

n_conn_comp(g::PlanarMultigraph)

Return the number of connected components.

new_edge(src::T, dst::T) where {T<:Integer}

Create a half edge and its twin

out_half_edge(g::PlanarMultigraph{T}, v::T)

Get the one out half edge of a vertex

prev(g::PlanarMultigraph{T}, he_id::T) where {T<:Integer}

Provides Previous Half Edge of a facet. HDS is bidi

split_edge!(pmg::PlanarMultigraph{T}, h::T) where {T<:Integer}

Split an edge into two consecutive ones. 1->2->3 becomes 1->4->2->3

split_facet!(pmg::PlanarMultigraph{T}, h::T, g::T) where {T<:Integer}

Split a facet incident to h and g into two facets.

Precondition

1. h and g are in the same facet
2. h and g are not the same half edge
3. Cannot be used to split the faces incident to the multiedge.

split_vertex!(g::PlanarMultigraph{T}, he1::T, he2::T) where {T<:Integer}

Split a vertex into 2 vertices.

Connect the two vertices with a new pair of half edges. he1 and he2 are half edges that marks the start and end of half edges that remain on v1.

After splitting, h points to the newly added vertex

Reference

• CGAL

surrounding_half_edge(g::PlanarMultigraph{T}, f::T)

Get the one surrounding half edge of a face

trace_face(g::PlanarMultigraph{T}, f::T; safe_trace = false) where {T}

Return the half edges of a face.

If safe_trace is true, then the half edges are returned in scrambled order. Otherwise, the returned half edges are in counter clockwise order but is not guaranteed to be consitent with he2f.

σ(g::PlanarMultigraph{T}, he_id::T) where {T}

Get prevatsource

σ_inv(pmg::PlanarMultigraph{T}, h::T) where {T}

Get nextatsource, clockwise

ϕ(g::PlanarMultigraph{T}, he_id::T) where {T}

Get twin half edge id

HalfEdge{T<:Integer}(src ,dst)

Datatype to represent a Half Edge

Reference

• Brönnimann, Hervé [Designing and Implementing a General Purpose Halfedge Data Structure]

(https://doi.org/10.1007/3-540-44688-5_5)

• CGAL Library HalfEdge Data Structure

PlanarMultigraph{T<:Integer}

Implements a planar multigraph with a maximal HDS Structure.

Features

1. Stores Forward Half Edge pointer in facet
2. Vertex linked
3. Face Linked

References:

Our implementation is based heavily on the CGAL Library. A good introduction on the HDS Structure and the Polyhedron3 Object which gives the boundary representation of a 2-manifold can be found in this paper.

TODO: Proof of Completeness for Euler Operations with Preconditions In the

CGAL Library, the Euler Operations are implemented with preconditions. It was pointed out that Euler Operations are closed for orientable 2-manifolds in paper where the detailed proof is in book. It was further pointed out in paper that Euler Operations are complete in Theorem 4.4.

The question remains whether the completeness remains for the preconditions attached. One way of proving is to show that for the Euler Operations used in Theorem 4.4, we could always construct them out of the Euler Operations in CGAL Library with preconditions?