localuf.decoders.uf

Classes

BaseCluster(uf, root[, no_boundaries])

Abstract base class for the cluster in UF.

UF(code[, dynamic, inclination])

The original, algorithmic UF decoder.
class localuf.decoders.uf.UF(code, dynamic=False, inclination='default')[source]

Bases: BaseUF

The original, algorithmic UF decoder.

Extends BaseUF. Incompatible with the frugal decoding scheme.

Additional instance constants:

  • _FORESTER decides whether to maintain a static or dynamic forest.

  • _INCLINATION a class that decides which boundary the root should be on

    when there is a percolating cluster i.e. one that spans opposite boundaries. Has the update_boundary method.

Additional instance attributes:

  • parents maps each node in the decoding graph to its parent node.

  • clusters maps each root node to the cluster of that root node.

    Initially, EVERY node its own cluster; then, only grow active clusters.

  • active_clusters the set of clusters

    with odd defect count and no boundary node.

  • forest the spanning forest after syndrome validation as a list of pairs (edge, node)

    where node is the further endpoint from the root of the tree in the forest.

  • digraph a NetworkX digraph of forest.

Parameters:

  • code (Code)

  • dynamic (bool)

  • inclination (Literal['default', 'west'])

reset(no_boundaries=False)[source]

Factory reset.

Parameters:

no_boundaries – whether to treat all boundary nodes as detectors too.

load(syndrome)[source]

Load a new syndrome.

Parameters:

syndrome (set[tuple[int, ...]])

decode(syndrome, draw=False, fig_width=None)[source]

Additional inputs over Decoder.decode():

  • fig_width figure width.

Parameters:

  • syndrome (set[tuple[int, ...]])

  • fig_width (float | None)

complementary_gap(noise_level=None, draw=False, fig_width=None, fig_height=None, **kwargs_for_networkx_draw)[source]

Calculate the complementary gap after decoding.

Assumes self.decode() has already been called. If self.CODE.MERGED_EQUIVALENT_BOUNDARY_NODES is False, raises a ValueError.

Parameters:

  • noise_level (None | float) – a probability representing the noise strength. This is needed to define nonuniform edge weights of the decoding graph in the circuit-level noise model. If None, all edges are assumed to have weight 1.

  • draw – whether to draw the original and complementary corrections.

  • fig_width (float | None) – figure width.

  • fig_height (float | None) – figure height.

  • kwargs_for_networkx_draw – passed to networkx.draw().

Returns:

weight_2 - weight_1 the complementary gap.

Side effects:

  • self ends up in the final state after computing the complementary correction.

  • All clusters are blind to boundary nodes

    so will stop growing only once they have an odd defect count.

unclustered_node_fraction()[source]

Compute the Unclustered Node Fraction DCS.

Return fraction:

The fraction of nodes that are not in a cluster.

validate(syndrome, log_history=False)[source]

Grow all active clusters until they are inactive.

Parameters:

syndrome (set[tuple[int, ...]])

static_merge(cu, cv)[source]

Merge clusters cu and cv along edge uv for static UF.

Parameters:

  • cu (_Cluster)

  • cv (_Cluster)

dynamic_merge(cu, cv, e)[source]

Merge clusters cu and cv along edge uv for dynamic UF.

Parameters:

  • cu (_Cluster)

  • cv (_Cluster)

  • e (tuple[tuple[int, ...], tuple[int, ...]])

peel()[source]

Peel the validated erasure.

draw_growth(**kwargs)[source]

Draw growth of edges using matplotlib.

Parameters:

  • growth – A dictionary where each key an edge index; value, its growth value.

  • syndrome – The set of defects.

  • highlighted_edges – The set of edges to be highlighted in drawing.

  • x_offset – The ratio of out-of-screen to along-screen distance.

  • with_labels – Whether to show node labels.

  • labels – A dictionary where each key a node index; value, its label as a string.

  • width – Line width of edges.

  • arrows – Whether to draw arrows on edges used by pointers. For Macar, Actis, Snowflake decoders only.

  • kwargs_for_networkx_draw – Passed to networkx.draw(). E.g. linewidths line width of node symbol border.

property digraph

Return a NetworkX digraph representing the spanning forest after syndrome validation.

Note: Requires calling peel() first.

draw_forest(x_offset=0.2, node_size=50, width=2.0, edge_color='g', boundary_color='#9cdaed', defect_color='#Ff6666', nondefect_color='#Bef4be', show_boundary_defects=True, **kwargs_for_networkx_draw)[source]

Draw spanning forest.

kwargs_for_networkx_draw passed to networkx.draw().

Note: Not as informative as draw_peel().

draw_peel(x_offset=0.2, node_size=50, width=2.0, correction_color='k', boundary_color='#9cdaed', defect_color='#Ff6666', nondefect_color='#Bef4be', show_boundary_defects=True, **kwargs_for_networkx_draw)[source]

Draw forest and correction from peeling.

kwargs_for_networkx_draw passed to networkx.draw().

Note: Requires calling peel() first.

draw_decode(fig_width=None, fig_height=None, **kwargs_for_networkx_draw)[source]

Draw all stages of decoding.

Parameters:

  • kwargs_for_networkx_draw – keyword arguments passed to NetworkX.draw e.g. margins=(0.1, 0.1).

  • fig_width (float | None)

  • fig_height (float | None)

class localuf.decoders.uf.BaseCluster(uf, root, no_boundaries=False)[source]

Bases: ABC

Abstract base class for the cluster in UF.

Mathematically, a cluster is a connected subgraph of the decoding graph.

Attributes:

  • root the representative of the cluster.

  • size the number of nodes in the cluster.

  • odd a Boolean to say if the number of defects in the cluster is odd.

  • boundary the node in the cluster that is the surface boundary if it exists; else, None.

    If cluster.boundary not None, cluster will never be active in future. If syndrome validation not dynamic, boundary may not be unique!

Parameters:

  • uf (UF)

  • root (tuple[int, ...])