hal.hal

HardwareAwareLayout

HardwareAwareLayout(
    name,
    directory_path,
    parity_check_matrix=None,
    tanner_graph=None,
    settings=None,
    path_to_tiers=None,
    path_to_layers=None,
)

Place and route a Tanner graph onto tiered hardware grids.

Uses a tiered planarity-based placement followed by grid routing.

Attributes:

• name (str) –

  Identifier for the mapping instance.

• path_to_directory (Path) –

  Directory where artifacts for this run are saved.

• settings (Settings) –

  Configuration controlling placement, routing and benchmarking.

• verbose (bool) –

  Whether to print detailed progress information.

• routed (bool) –

  True after higher-tier routing has completed; False otherwise.

• perf_metrics (dict[str, float]) –

  Timing metrics populated by the time_it decorator (e.g. place_time).

• parity_check_matrix (ndarray | None) –

  Parity-check matrix used to generate the Tanner graph if provided.

• G_tanner (Graph | None) –

  Tanner graph representation of the code.

• tiers (list[Tier] | None) –

  Per-tier graphs and grids after placement; updated after routing.

• grid_size (int | None) –

  Square grid dimension used when toric_code is not provided.

• grid_size_x (int | None) –

  Grid width (rectangular case or derived from settings when square).

• grid_size_y (int | None) –

  Grid height (rectangular case or derived from settings when square).

• margin_size (float | None) –

  Margin in grid cells (square grid case) used for rasterization.

• grid_spacing (ndarray | None) –

  Spacing used to map continuous positions onto the grid (square case).

• node_expansion_val (int | None) –

  Reserved expansion radius around each node on the grid.

Initialize a HardwareAwareLayout instance.

Either a parity check matrix or a Tanner graph must be provided.

Parameters:

• name (str) –

  Human-friendly mapping identifier used in filenames.

• directory_path (str) –

  Output directory where a timestamped run folder will be created.

• parity_check_matrix (ndarray | None, default: None ) –

  Full parity-check matrix; if provided, a Tanner graph is generated.

• tanner_graph (Graph | None, default: None ) –

  Pre-constructed Tanner graph to use directly instead of parity_check_matrix.

• settings (Settings | None, default: None ) –

  Settings instance; if None, defaults are used and printed.

• path_to_tiers (list[str] | None, default: None ) –

  Paths to previously saved tier artifacts (graphs/grids/metrics) to load.

• path_to_layers (list[str] | None, default: None ) –

  Backwards compatible alias for path_to_tiers.

Raises:

• ValueError –

  If neither parity_check_matrix nor tanner_graph is provided.

complexity property

complexity

Calculate the hardware complexity of the mapping.

The complexity is defined as the product of the number of tiers, the number of nodes, and the number of edges in the Tanner graph.

Returns:

• float –

  The calculated hardware complexity.

num_tiers property

num_tiers

Return the number of tiers.

benchmark

benchmark(
    bad=None, baseline=None, weights=None, clip_high=False
)

Baseline -> score == 1 Bad point -> score == 2 Worse -> score > 2 (because we do NOT cap above 'bad')

Parameters:

• bad (dict, default: None ) –

  Threshold where each metric is "equally bad".

• baseline (dict, default: None ) –

  Reference point that should evaluate to 1. Defaults: 1, 1, 0, 0

• weights (dict or None, default: None ) –

  Metric weights. None ⇒ all 1.

• clip_high (bool, default: False ) –

  If True, r_m is clamped to 1 (old behaviour).

benchmark_sweep

benchmark_sweep(sweep_params, num_processes=None)

Run a parallelized sweep over selected settings and aggregate results.

Each entry in sweep_params maps a Settings attribute name to a list of values to try. List entries can be: - a raw value (used both as the label and the value), - None (labelled as "Automatic"), or - a tuple (label, value) to decouple filenames/labels from actual values.

Parameters:

• sweep_params (dict[str, list]) –

  Mapping from Settings attribute name to a list of candidate values.

• num_processes (int | None, default: None ) –

  Cap on worker processes; defaults to os.cpu_count().

Returns:

• DataFrame –

  Concatenated benchmark DataFrame across all successful configurations, with extra columns for the sweep labels.

display

display(save=False, path=None, tiers=None)

Display an interactive graph of the mapping for selected tiers.

display_gif

display_gif(tier_ind, save=False, path=None, fps=1, step=1)

Create an animated GIF of the routing process for a specific tier.

display_grids

display_grids(
    save=False, grid_inds=None, path=None, dpi=None
)

Display and optionally save grid images for each tier.

Delegates to hal.utils.visualization_utils.display_grids.

display_line_plot

display_line_plot()

Plot nodes and routed edges as static line plots for each tier.

from_database classmethod

from_database(directory_path)

Create an instance from a mapping database directory.

Parameters:

• directory_path (str) –

  Directory containing mapping data previously saved by save.

Returns:

• HardwareAwareLayout –

  A new instance loaded from disk.

place

place(
    layout=None,
    mps_edge_order=None,
    grid_size=None,
    margin=None,
    node_expansion_val=None,
    orthogonalize_layout=True,
    custom_pos=None,
    toric_code=None,
)

Compute node placements and generate tiered graphs with corresponding grids.

The method: 1. Determines node positions using the specified layout. 2. Orders edges and partitions them into tiers. 3. Normalizes node positions. 4. Creates grid and expanded grid representations for each tier.

Parameters:

• layout (str | None, default: None ) –

  Layout algorithm ('community', 'spring', 'kamada_kawai', 'grid', etc.).

• mps_edge_order (str | None, default: None ) –

  Ordering used while extracting a maximum planar subgraph (e.g. 'length_asc').

• grid_size (int | None, default: None ) –

  Square grid dimension used when not placing a toric code.

• margin (float | None, default: None ) –

  Margin ratio used during rasterization (square grid case).

• node_expansion_val (int | None, default: None ) –

  Expansion radius (in cells) reserved around each node.

• orthogonalize_layout (bool, default: True ) –

  If True, derive an orthogonalized base layer before tiering.

• custom_pos (dict | None, default: None ) –

  Optional user-provided positions for nodes; bypasses layout.

• toric_code (dict | None, default: None ) –

  Enable rectangular placement tailored for toric-code style layouts.

Returns:

• None –

route

route(
    max_bump_transitions_per_coupler=None,
    max_coupler_length=None,
    max_tsvs_per_coupler=None,
    routing_edge_order=None,
    edge_expansion_val=None,
)

Route edges across the tiers.

The method first routes the base tier using a straightline connection, then attempts to route remaining edges. If conflicts arise (or an edge is repeatedly attempted), the edge is moved to a new tier.

Parameters:

• max_bump_transitions_per_coupler (int | None, default: None ) –

  Maximum allowed face switches per routed edge before promotion.

• max_coupler_length (int | None, default: None ) –

  Maximum allowed coupler length per routed edge before promotion.

• max_tsvs_per_coupler (int | None, default: None ) –

  Maximum allowed TSVs per coupler; if exceeded, routing stops.

• routing_edge_order (str | None, default: None ) –

  Ordering method for selecting edges to route.

• edge_expansion_val (int | None, default: None ) –

  Grid-cell expansion used to mark routed traces.

Returns:

• None –

save

save(path=None)

Save all artifacts (graphs, grids, metrics, settings) to disk.

Parameters:

• path (str | None, default: None ) –

  Directory root for saving. Defaults to the instance directory.

_run_single_config

_run_single_config(args)

Worker function to process a single combination of settings.

time_it

time_it(func)

Decorator to measure and store the execution time of a method.