localuf.decoders.luf.main

Classes for local Union–Find decoder.

Classes

ActisNode(nodes, index)	Node for LUF w/o direct access to blind global controller.
ActisNodes(luf[, optimal])	Collection of all LUF nodes, where controller only sees node whose ID is 0.
Controller(luf)	Global controller for LUF.
ControllerFriendship(node)	Friendship w/ controller.
Friendship(node)	The type of connection for communicating stage, {busy, active}_signal information.
LUF(code[, visible, _optimal])	The graph used by local UF decoder.
MacarNode(nodes, index)	Node for LUF which directly accesses global controller.
MacarNodes(luf)	Collection of all LUF nodes, where controller directly connects to each node.
NodeFriendship(node)	Friendship w/ neighboring nodes.
Nodes(luf)	Collection of all LUF nodes.
OptimalWaiter(nodes)	Optimal waiter for ActisNodes.
UnoptimalWaiter(nodes)	Unoptimal waiter for ActisNodes.
Waiter(nodes)	Base class for WAITER attribute of ActisNodes instance.

class localuf.decoders.luf.main.LUF(code, visible=True, _optimal=True)

Bases: BaseUF

The graph used by local UF decoder.

Extends _BaseUF.

Class attributes:

• DEFAULT_X_OFFSET default x_offset.

  Slightly larger than constants.DEFAULT_X_OFFSET as the drawer for this class shows more information at each node.

Instance attributes (1–5 constant):

• CONTROLLER a global controller object.

• NODES a Nodes object.

• VISIBLE whether controller has direct connection w/ each node or only node w/ ID 0

  i.e. strictly local iff VISIBLE is False. Only computed if syndrome not yet an attribute.

• _DIGRAPH_MAKER maker of NetworkX digraph.

• _DECODE_DRAWER provides draw_decode.

• _FIG_WIDTH figure width used by drawer.

• correction only exists after calling decode().

• _pointer_digraph a NetworkX digraph representing the fully grown edges used by pointers,

  the set of its edges as directed edges, the set of its edges as undirected edges.

In drawings of this graph:

• active nodes are square-shaped

• inactive nodes are circular

• CID is shown as a label

• nodes with anyons are outlined in black

• pointers are shown by arrows on edges

• edges so far added to the correction are in red

• the top-left node also shows the controller stage (PS stands for presyncing etc.)

Parameters:

code (Surface)

DEFAULT_X_OFFSET = 0.3

property CONTROLLER

property NODES

property VISIBLE

decode(syndrome, draw=False, log_history=False, **kwargs_for_draw_decode)

Additional inputs over those of Decoder.decode():

• log_history whether to populate history attribute.

• kwargs_for_draw_decode passed to self.draw_decode().

Returns tSV:

Number of timesteps to validate syndrome.

Returns tBP:

Number of timesteps to burn and peel.

If log_history is True then tSV + tBP = len(self.history).

Parameters:

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

validate(syndrome, draw=False, log_history=False, **kwargs_for_draw_decode)

Validate syndrome.

Parameters:

• syndrome (set[tuple[int, ...]]) – the set of defects.

• draw – whether to draw.

• log_history – whether to populate history attribute.

• kwargs_for_draw_decode – passed to self.draw_decode().

Returns:

tSV # timesteps to validate syndrome. Equals len(self.history) if log_history is True.

peel(log_history)

Burn & peel after syndrome validation.

log_history whether to populate history attribute.

Returns:

tBP # timesteps to burn and peel.

Parameters:

log_history (bool)

property syndrome

Syndrome computed from self.NODES.

reset()

Factory reset.

draw_growth(highlighted_edges=None, highlighted_edge_color='k', unhighlighted_edge_color='#b6b6b6', x_offset=0.3, with_labels=True, labels=None, show_global=True, node_size=300, linewidths=2.0, anyon_color='k', active_shape='s', width=2.0, arrows=None, boundary_color='#9cdaed', defect_color='#Ff6666', nondefect_color='#Bef4be', show_boundary_defects=True, defect_label_color='k', **kwargs_for_networkx_draw)

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 (set[tuple[tuple[int, ...], tuple[int, ...]]] | None) – 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 (dict[tuple[int, ...], str] | None) – A dictionary where each key a node index; value, its label as a string.

• width – Line width of edges.

• arrows (bool | None) – 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.

draw_decode(**kwargs_for_networkx_draw)

Draw all stages of decoding.

Parameters:

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

class localuf.decoders.luf.main.Controller(luf)

Bases: object

Global controller for LUF.

Instance attributes (1 constant):

• LUF the LUF object which has this controller.

• stage the global stage.

Parameters:

luf (LUF)

property LUF

reset()

Factory reset.

advance()

Advance 1 timestep.

Output: growth_changed which is True if any growths have changed (happens after growth and burning stages, and peeling steps); else, False.

Side effect: Update stage.

class localuf.decoders.luf.main.Nodes(luf)

Bases: ABC

Collection of all LUF nodes.

Instance attributes (1–2 constant):

• LUF the LUF object which has these nodes.

• dc a dictionary where each

  key an index tuple; value, the node object at that index.

• syndrome the set of defects.

• busy is False iff we are sure all nodes are ready for next stage.

• valid is True iff we are sure no node is active after presyncing stage

  i.e. syndrome has been validated.

• _global_label the label of global information used by drawer.

Parameters:

luf (LUF)

dc: dict[tuple[int, ...], _Node]

property LUF

load(syndrome)

Load syndrome onto nodes collection.

Parameters:

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

property syndrome

Compute syndrome from nodes in dc.

reset()

Factory reset.

advance()

Advance 1 timestep.

update_unphysicals()

After each merging or syncing step, set attribute := next_attribute for all nodes.

update_access()

Update access for all nodes.

Call after growth has changed.

labels(show_global=True)

Return the labels dictionary for the drawer.

show_global whether to prepend the global label to the top-left node label.

Returns:

result a dictionary where each key a node index as a tuple; value, the label for the node at that index.

class localuf.decoders.luf.main.MacarNodes(luf)

Bases: Nodes

Collection of all LUF nodes, where controller directly connects to each node.

Extends Nodes.

Parameters:

luf (LUF)

property dc

property busy

property valid

class localuf.decoders.luf.main.ActisNodes(luf, optimal=True)

Bases: Nodes

Collection of all LUF nodes, where controller only sees node whose ID is 0.

Extends Nodes.

Additional instance attributes (1–2 constant):

• SPAN distance from controller to furthest node (boundary node w/ highest ID).

• WAITER object which decides how long controller must wait until

  it is sure no more info is being relayed (towards it).

• countdown tracker used by WAITER.

• busy_signal whether collection receives a busy signal in current timestep.

• active_signal whether collection has received an active signal during the current syncing stage.

• next_{busy, active}_signal the provisional {busy, active}_signal for the next timestep.

• {busy, active}_signal have string representations via [attribute]_signal_symbol property.

Notes: This decoder starts in the GROWING stage. Alternatively, could start in the SYNCING stage and in load(), call self.update_valid() instead of self.valid = False. This would be beneficial if noise level low enough.

Parameters:

luf (LUF)

property dc

property SPAN

property WAITER

property busy_signal_symbol

property active_signal_symbol

reset()

Factory reset.

load(syndrome)

Load syndrome onto nodes collection.

update_valid()

Update valid attribute. Call after finish SYNCING stage.

advance()

Advance 1 timestep.

update_unphysicals()

After each merging or syncing step, set attribute := next_attribute for all nodes.

class localuf.decoders.luf.main.Waiter(nodes)

Bases: ABC

Base class for WAITER attribute of ActisNodes instance.

Instance attributes:

• NODES the ActisNodes object the waiter belongs to.

• RECEIVING_START the value the waiter sets countdown to

  if it receives a busy signal during the receiving window.

Parameters:

nodes (ActisNodes)

RECEIVING_START: int

property NODES

abstract property received_busy_signal: bool

Whether to set countdown to RECEIVING_START.

advance()

Advance 1 timestep.

Countdown start for controller stage:

• GROWING or PRESYNCING is span as it takes span timesteps

  (span-1 .. -1 .. 0) for information to go from controller to furthest node.

• MERGING is span+1 as it takes span timesteps

  (span .. -1 .. 1) for information to go from furthest node to controller [and furthest node (which is a boundary) can be busy].

• SYNCING is span as it takes span-1 timesteps

  (span-1 .. -1 .. 1) for information to go from furthest detector to controller (furthest boundary node never busy nor active).

class localuf.decoders.luf.main.OptimalWaiter(nodes)

Bases: Waiter

Optimal waiter for ActisNodes.

Extends Waiter.

Additional class constants:

• RECEIVING_WINDOW the countdown values

  during which the waiter considers busy signals.

Parameters:

nodes (ActisNodes)

RECEIVING_WINDOW = {1, 2}

RECEIVING_START: int = 2

property received_busy_signal

Whether to set countdown to RECEIVING_START.

class localuf.decoders.luf.main.UnoptimalWaiter(nodes)

Bases: Waiter

Unoptimal waiter for ActisNodes.

Extends Waiter.

Receiving window is the entire countdown i.e. always.

Parameters:

nodes (ActisNodes)

property received_busy_signal

Whether to set countdown to RECEIVING_START.

class localuf.decoders.luf.main.MacarNode(nodes, index)

Bases: _Node

Node for LUF which directly accesses global controller.

Extends _Node.

Parameters:

• nodes (Nodes)

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

advance()

Advance 1 timestep.

class localuf.decoders.luf.main.ActisNode(nodes, index)

Bases: _Node

Node for LUF w/o direct access to blind global controller.

Extends _Node.

Additional instance attributes (1–2 constant):

• SPAN the countdown start of the node.

• FRIENDSHIP the type of connection the node has for communicating

  stage and signal information.

• countdown tracks how long node must wait until staging is done

  i.e. when all nodes have same stage, when stage in {GROWING, PRESYNCING}.

• stage node stage.

• busy_signal if in the current timestep the node either

  is busy or receives a busy signal from another node.

• active_signal if in the current timestep the node either

  has stage as presyncing and becomes active, or receives an active signal from another node.

• next_{stage, {busy, active}_signal} the provisional {stage, {busy, active}_signal} for the next timestep.

• stage, {busy, active}_signal have string representations via [attribute]_symbol property.

Parameters:

• nodes (ActisNodes)

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

property NODES

property SPAN

property FRIENDSHIP

property stage_symbol

property busy_signal_symbol

property active_signal_symbol

reset()

Factory reset.

advance()

Advance 1 timestep.

advance_definite(stage)

Advance when stage in {'growing', 'presyncing'}.

Parameters:

stage (str)

advance_indefinite(stage)

Advance when stage in {'merging', 'syncing'}.

Parameters:

stage (str)

presyncing()

Initialise for syncing stage i.e. update after merge stage.

If node the root of an active cluster, set active, active_signal to True; else, set both to False.

update_unphysicals_for_actis()

next_{stage, {busy, active}_signal} -> stage, {busy, active}_signal.

get_label()

Return node information for drawer.

class localuf.decoders.luf.main.Friendship(node)

Bases: ABC

The type of connection for communicating stage, {busy, active}_signal information.

Instance attributes (1 constant):

• NODE the node which has this friendship.

Parameters:

node (ActisNode)

property NODE

abstractmethod update_stage()

Update stage depending on neighbors and return whether stage changed.

Return type:

bool

update_stage_helper(relayee)

Update stage based on stage of component relayee.

Parameters:

relayee (Controller | ActisNode)

abstractmethod relay_signals()

Relay {busy, active}_signal toward controller.

Return type:

None

class localuf.decoders.luf.main.ControllerFriendship(node)

Bases: Friendship

Friendship w/ controller.

Extends Friendship. Only node whose ID is 0 has this friendship. Note this node never busy.

Parameters:

node (ActisNode)

update_stage()

Update stage depending on neighbors and return whether stage changed.

relay_signals()

Relay {busy, active}_signal toward controller.

class localuf.decoders.luf.main.NodeFriendship(node)

Bases: Friendship

Friendship w/ neighboring nodes.

Extends Friendship.

Additional instance attributes (1 constant):

• RELAYEE the neighboring node that busy_signal is sent to.

  Equals the neighbor in the direction toward node of ID 0.

Parameters:

node (ActisNode)

property RELAYEE: tuple[int, ...]

update_stage()

Update stage depending on neighbors and return whether stage changed.

relay_signals()

Relay {busy, active}_signal toward controller.