localuf.decoders.snowflake.main

Classes

EdgeContact(edge)	Contact with edge immediately below.
FloorContact(edge)	Contact for edges in commit region.
Friendship(node)	The type of connection for communicating defect, active, cid, pointer information.
NodeEdgeMixin()	Mixin class for _Node and _Edge.
NodeFriendship(node)	Friendship with node immediately below.
NothingFriendship(node)	Friendship with nothing immediately below.
Snowflake(code[, merger, schedule, ...])	Snowflake decoder based on UF.
TopSheetFriendship(node)	Friendship for nodes in top sheet of viewing window.

class localuf.decoders.snowflake.main.Snowflake(code, merger='fast', schedule='2:1', unrooter='full', _neighbor_order=None, _include_timelike_lowest_edges=True)

Bases: BaseUF

Snowflake decoder based on UF.

Extends BaseUF. Incompatible with code capacity noise model. Compatible only with frugal scheme.

Does not use:

• _growth attribute.

• erasure attribute.

Parameters:

• code (Code)

• merger (Literal['fast', 'slow'])

• schedule (Literal['2:1', '1:1'])

• unrooter (Literal['full', 'simple'])

• _neighbor_order (Iterable[Literal['C', 'N', 'W', 'E', 'S', 'D', 'U', 'SD', 'NU', 'EU', 'WD', 'SEU', 'NWD']] | None)

• _include_timelike_lowest_edges (bool)

BW_DEFAULT_NODE_SIZE = 360

The default node size for black-and-white drawing.

floor_history: list[str]

A list of bitstrings representing the correction output from the bottom layer at each drop. The order of the bits is given by self._LOWEST_EDGES.

confidence_score_history: defaultdict[str, list[float]]

A map from DCS to a list of DCS values after each growth stage.

property NODES

A map from node coordinates to node objects.

property EDGES

A map from coordinate pairs to edge objects.

property syndrome

property verbose_syndrome

property growth

A map from each edge in the decoding graph to an integer representing its growth value.

property correction

index_to_id(index)

Return ID of node at index (j, t) or (i, j, t).

Parameters:

index (tuple[int, ...])

init_history()

Initialize history and floor_history attributes.

id_below(id_)

Return ID of node below node with ID id_.

Answer valid only for nodes not on bottom layer of viewing window. In implementation this function would be stored in each node.

Parameters:

id_ (int)

reset()

Factory reset.

decode(syndrome, log_history=False, log_floor_history=False, confidence_scores=(), noise_level_for_priors=None, time_only='merging', defects_possible=True)

Perform a decoding cycle i.e. a growth round.

Parameters:

• syndrome (set[tuple[int, ...]]) – The syndrome in the new region discovered by the window raise i.e. all defects in syndrome have the time coordinate self.CODE.SCHEME.WINDOW_HEIGHT-1.

• log_history (Literal[False, 'fine', 'coarse']) – Whether to populate history attribute; ‘fine’ logs each timestep; ‘coarse’, only the final timestep of the growth round.

• log_floor_history (bool) – Whether to populate floor_history attribute.

• confidence_scores (Iterable[Literal['throughput', 'swim_distance', 'unclustered_edge_fraction', 'min_defect_height']]) – An iterable of DCS names to record after the decoding cycle. Supported values are ‘throughput’, ‘swim_distance’, ‘unclustered_edge_fraction’, ‘min_defect_height’.

• noise_level_for_priors (None | float) – Noise level to use when computing some DCSs.

• time_only (Literal['all', 'merging', 'unrooting']) – Whether runtime includes a timestep for each drop, each grow, and each merging step (‘all’); each merging step only (‘merging’); or each unrooting step only (‘unrooting’).

• defects_possible (bool) – Whether to expect there may be defects in the viewing window in the current or any future timestep. If False, the decoder will perform only ‘drop’, and will skip ‘grow’ and ‘merge’ stages. This is useful at the end of the memory experiment after the final syndrome data has come in.

Return runtime:

Number of timesteps to complete decoding cycle. Equals the increase in len(self.history) if log_history == 'fine' and time_only == 'all'.

min_defect_height()

Calculate the minimum defect height DCS in the current decoding window.

drop(syndrome)

Make all nodes perform a drop i.e. raise window by a layer.

Parameters:

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

merge(whole, log_history, time_only='merging')

Make all nodes perform merging until none are busy.

Emergent effect: merge touching clusters, push defects to roots.

Parameters:

• whole (bool) – whether to perform MERGING_WHOLE or MERGING_HALF stage.

• log_history (Literal[False, 'fine', 'coarse']) – as in decode inputs.

• time_only (Literal['all', 'merging', 'unrooting']) – as in decode inputs.

Return runtime:

Number of timesteps to complete growth round.

draw_growth(highlighted_edges=None, highlighted_edge_color='k', unhighlighted_edge_color='#b6b6b6', x_offset=0.25, with_labels=True, labels=None, show_global=True, show_2_1_schedule_variables=None, node_size=None, linewidths=None, active_shape='s', width=None, arrows=None, show_boundary_defects=True, black_and_white=False, bw_unhighlighted_width=1.0, bw_unrooted_color='#c6cbd3', **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 (float | None) – 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.

• show_2_1_schedule_variables (None | bool)

• node_size (int | None)

• linewidths (float | None)

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).

generate_output(syndromes, output_to_csv_file=None, draw=False, margins=(0.2, 0.2), style='interactive', **kwargs_for_draw_decode)

Generate output in the form of bitstrings.

Parameters:

• syndromes (list[str] | list[set[tuple[int, ...]]]) –

  the input of Snowflake. This can either be a list of sets of coordinates (each set representing a syndrome; each coordinate specifying a defect), or a list of syndrome vectors (strings of ‘0’s and ‘1’s). The vertical (i.e. time) coordinate of each defect must be self.CODE.SCHEME.WINDOW_HEIGHT-1.

  For syndrome vectors, the ordering of the nodes is: - repetition code: west to east. - surface code: west to east along each row, then from south to north.

• output_to_csv_file (str | None) – the CSV file path to save the data in e.g. ‘snowflake_data.csv’. Defaults to None, meaning no CSV file is saved.

• draw (Literal[False, 'fine', 'coarse']) – whether to skip drawing the decoding process, draw it finely or draw it coarsely.

• margins – margins for the drawing.

• style (Literal['interactive', 'horizontal', 'vertical']) – how different drawing frames are laid out. Can be ‘interactive’, ‘horizontal’, or ‘vertical’.

• kwargs_for_draw_decode – additional keyword arguments for decoder.draw_decode().

Returns:

The output of Snowflake. This is a list of strings, each representing the edges in the bottom layer that are flipped just before each drop. The ordering of the edges is given by self._LOWEST_EDGES. INCONSISTENCY: for the repetition code, the purely timelike edges in the last layer are excluded from self._LOWEST_EDGES; the spacelike edges are ordered from west to east.

Side effects:

• If output_to_csv_file is not None, the input and output of Snowflake

  are saved in a CSV file at path output_to_csv_file.

• If draw is True, the decoding process is drawn.

class localuf.decoders.snowflake.main.NodeEdgeMixin

Bases: ABC

Mixin class for _Node and _Edge.

Instance attributes:

• SNOWFLAKE the decoder the node or edge belongs to.

property SNOWFLAKE

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

Bases: ABC

The type of connection for communicating defect, active, cid, pointer information.

Instance attributes (1 constant):

• NODE the node which has this friendship.

Parameters:

node (_Node)

property NODE

drop()

Drop information to node immediately below.

find_broken_pointers()

Start unrooting if in bottom sheet of viewing window and point downward.

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

Bases: Friendship

Friendship with node immediately below.

Extends Friendship.

Instance attributes (1 constant):

• DROPEE the node immediately below.

Parameters:

node (_Node)

property DROPEE

drop()

Drop information to node immediately below.

class localuf.decoders.snowflake.main.TopSheetFriendship(node)

Bases: NodeFriendship

Friendship for nodes in top sheet of viewing window.

Extends NodeFriendship. After a drop, these nodes must reset next_active and next_defect.

Parameters:

node (_Node)

drop()

Drop information to node immediately below.

class localuf.decoders.snowflake.main.NothingFriendship(node)

Bases: Friendship

Friendship with nothing immediately below.

Extends Friendship. Only nodes whose time index is 0 have this friendship.

Parameters:

node (_Node)

find_broken_pointers()

Start unrooting if in bottom sheet of viewing window and point downward.

class localuf.decoders.snowflake.main.EdgeContact(edge)

Bases: _Contact

Contact with edge immediately below.

Extends _Contact.

Instance attributes (1 constant):

• DROPEE the edge immediately below.

Parameters:

edge (_Edge)

property DROPEE

drop()

Drop information to edge or floor immediately below.

class localuf.decoders.snowflake.main.FloorContact(edge)

Bases: _Contact

Contact for edges in commit region.

Extends _Contact. Only edges in the bottom sheet of the viewing window have this contact.

Parameters:

edge (_Edge)

drop()

Drop information to edge or floor immediately below.