hal.settings

Settings dataclass

Settings(
    grid_size=500,
    grid_size_x=None,
    grid_size_y=None,
    custom_positions=None,
    layout="community",
    mps_edge_order="crossings_asc",
    place_margin=0.02,
    node_expansion_val=1,
    toric_code=None,
    max_bump_transitions_per_coupler=10,
    max_tsvs_per_coupler=None,
    max_coupler_length=1000,
    route_edge_order="length_asc",
    edge_expansion_val=1,
    save=True,
    verbose=False,
    baseline_defaults=(
        lambda: {
            "num_tiers": 1.0,
            "avg_coupler_length": 1.0,
            "max_avg_face_switches": 0.0,
            "avg_tsvs_per_edge": 0.0,
        }
    )(),
    bad_defaults=(
        lambda: {
            "num_tiers": 5.0,
            "avg_coupler_length": 10.0,
            "max_avg_face_switches": 4.0,
            "avg_tsvs_per_edge": 3.0,
        }
    )(),
)

Configuration for placement, routing, and benchmarking.

Attributes:

• grid_size (int) –

  Base grid dimension used when square grids are employed.

• grid_size_x (int | None) –

  Grid width override; defaults to grid_size when unset.

• grid_size_y (int | None) –

  Grid height override; defaults to grid_size when unset.

• custom_positions (dict[int, tuple[int, int]] | None) –

  Explicit node positions; if set, bypasses layout for placement.

• layout (str) –

  Placement layout algorithm identifier (e.g. 'community', 'spring').

• mps_edge_order (str) –

  Edge selection order for maximal planar subgraph extraction.

• place_margin (float) –

  Margin ratio used during rasterization in placement.

• node_expansion_val (int) –

  Expansion radius around each node for local wiring clearance.

• toric_code (dict | None) –

  If set, enables rectangular placement tailored to toric codes.

• max_bump_transitions_per_coupler (int | None) –

  Limit on face-switch events along any single routed edge.

• max_tsvs_per_coupler (int | None) –

  Maximum TSVs permitted per coupler before routing aborts.

• max_coupler_length (int | None) –

  Upper bound on relative coupler length (normalized to the shortest).

• route_edge_order (str) –

  Edge ordering used when routing (e.g. 'length_asc').

• edge_expansion_val (int) –

  Expansion radius (in cells) to reserve around routed traces.

• save (bool) –

  Whether to save intermediate and final artifacts.

• verbose (bool) –

  Emit detailed logs during place/route/benchmark.

• baseline_defaults (dict) –

  Baseline metric thresholds where score equals 1.

• bad_defaults (dict) –

  "Bad" metric thresholds where score equals 2.

bad_defaults class-attribute instance-attribute

bad_defaults = field(
    default_factory=lambda: {
        "num_tiers": 5.0,
        "avg_coupler_length": 10.0,
        "max_avg_face_switches": 4.0,
        "avg_tsvs_per_edge": 3.0,
    }
)

Bad threshold values for benchmark scoring (score = 2).

baseline_defaults class-attribute instance-attribute

baseline_defaults = field(
    default_factory=lambda: {
        "num_tiers": 1.0,
        "avg_coupler_length": 1.0,
        "max_avg_face_switches": 0.0,
        "avg_tsvs_per_edge": 0.0,
    }
)

Baseline values for benchmark scoring (score = 1).

custom_positions class-attribute instance-attribute

custom_positions = None

Explicit map p0: V → ℤ² that overrides automatic placement for vertices.

edge_expansion_val class-attribute instance-attribute

edge_expansion_val = 1

Safety margin (in grid cells) around every routed trace.

grid_size class-attribute instance-attribute

grid_size = 500

Grid size determining overall device area, aspect ratio, and layout granularity.

grid_size_x class-attribute instance-attribute

grid_size_x = None

Override grid width. If None, uses grid_size.

grid_size_y class-attribute instance-attribute

grid_size_y = None

Override grid height. If None, uses grid_size.

layout class-attribute instance-attribute

layout = 'community'

Layout algorithm for placement: 'kamada_kawai', 'community', 'planar', etc.

max_bump_transitions_per_coupler class-attribute instance-attribute

max_bump_transitions_per_coupler = 10

Maximum bump transitions per connection. When violated, edge pops to next tier.

max_coupler_length class-attribute instance-attribute

max_coupler_length = 1000

Maximum connection length between nodes in units of smallest connection length between nodes. When violated, pops to next tier.

max_tsvs_per_coupler class-attribute instance-attribute

max_tsvs_per_coupler = None

Maximum through-silicon vias per connection. When violated, routing fails.

mps_edge_order class-attribute instance-attribute

mps_edge_order = 'crossings_asc'

Edge ordering for MPS placement: 'length_desc', 'crossings_asc', etc.

node_expansion_val class-attribute instance-attribute

node_expansion_val = 1

Radius added around each node before routing; reserves area for local wiring.

place_margin class-attribute instance-attribute

place_margin = 0.02

Margin ratio for grid normalization during placement.

route_edge_order class-attribute instance-attribute

route_edge_order = 'length_asc'

Edge ordering for routing: 'crossings_asc', 'length_desc', etc.

save class-attribute instance-attribute

save = True

Whether to save intermediate results.

toric_code class-attribute instance-attribute

toric_code = None

Whether code being layed out is a toric code or not.

verbose class-attribute instance-attribute

verbose = False

Enable verbose output during placement and routing.

__post_init__

__post_init__()

Set derived values after initialization and validate benchmark dictionaries.

__repr__

__repr__()

Return a detailed representation for debugging.

__str__

__str__()

Return a user-friendly string representation.

load_from_json classmethod

load_from_json(filepath)

Loads settings from a JSON file.

This class method reads a JSON file, and creates a new instance of the Settings class from its contents.

Args: filepath: The path (as a string or Path object) to the input JSON file.

Returns: A new instance of the Settings class.

operation_summary

operation_summary(operation)

Return a summary of settings relevant to a specific operation.

Args: operation: One of 'place', 'route', or 'benchmark'

Returns: Formatted string showing relevant settings for the operation

save_to_json

save_to_json(filepath)

Saves the current settings to a JSON file.

This method converts the dataclass instance into a dictionary and writes it to the specified file path in a human-readable format.

Args: filepath: The path (as a string or Path object) to the output JSON file.

show_overrides

show_overrides(**kwargs)

Show which settings are being overridden by method parameters.

Args: **kwargs: Method parameters that might override settings

Returns: Formatted string showing what's being overridden

summary

summary()

Return a concise summary of key settings.