mixle.experimental.typed_runtime.topology module

Measured topology and typed structured-shard placement.

class ClusterTopology(devices, links)

Bases: object

Directed measured network over topology-aware compute devices.

Parameters:

• devices (tuple[TopologyDevice, ...])

• links (tuple[LinkProfile, ...])

property islands: tuple[str, ...]

Sorted failure/network islands.

devices_in(island)

Devices in one island, ordered by id.

Parameters:

island (str)

Return type:

tuple[TopologyDevice, …]

resources(island=None)

Adapt topology devices to the stable placement planner’s resource type.

Parameters:

island (str | None)

Return type:

Resources

best_island()

Island with the largest declared aggregate throughput.

Return type:

str

transfer(source, target, nbytes)

Shortest transfer-time route under current link profiles.

Parameters:

• source (str)

• target (str)

• nbytes (int)

Return type:

TransferEstimate

as_dict()

Return a JSON-compatible topology receipt.

Return type:

dict[str, Any]

class LinkProfile(source, target, latency_seconds, bandwidth_bytes_per_second, contention_multiplier=1.0, sample_count=0, provenance='declared')

Bases: object

Directed link startup latency and sustained bandwidth.

Parameters:

• source (str)

• target (str)

• latency_seconds (float)

• bandwidth_bytes_per_second (float)

• contention_multiplier (float)

• sample_count (int)

• provenance (str)

transfer_seconds(nbytes)

Estimated one-way time including startup and measured contention.

Parameters:

nbytes (int)

Return type:

float

as_dict()

Return a JSON-compatible link profile.

Return type:

dict[str, Any]

class NodePlacement(node_id, scope, primary_island, replica_islands, shards, rationale)

Bases: object

Placement and cross-island replication policy for one typed node.

Parameters:

• node_id (str)

• scope (PlacementScope)

• primary_island (str)

• replica_islands (tuple[str, ...])

• shards (tuple[StructuredShard, ...])

• rationale (str)

as_dict()

Return a JSON-compatible node placement.

Return type:

dict[str, Any]

class PlacementScope(*values)

Bases: StrEnum

Communication scope permitted for one typed node.

class StructuredPlacementPlan(primary_island, placements, graph_fingerprint, topology_fingerprint)

Bases: object

Typed placement over one calibrated cluster topology.

Parameters:

• primary_island (str)

• placements (tuple[NodePlacement, ...])

• graph_fingerprint (str)

• topology_fingerprint (str)

placement(node_id)

Return placement metadata for one node.

Parameters:

node_id (str)

Return type:

NodePlacement

as_dict()

Return a JSON-compatible plan.

Return type:

dict[str, Any]

class StructuredShard(shard_id, node_id, island, device_id, axis, start, stop, reduction, exact, required_memory_bytes)

Bases: object

One contiguous typed model-axis cut.

Parameters:

• shard_id (str)

• node_id (str)

• island (str)

• device_id (str)

• axis (str)

• start (int)

• stop (int)

• reduction (str)

• exact (bool)

• required_memory_bytes (int)

as_dict()

Return a JSON-compatible shard placement.

Return type:

dict[str, Any]

class TopologyDevice(device_id, host, island, provider, region, spec, storage_region=None)

Bases: object

A compute device with failure, network, provider, and storage locality.

Parameters:

• device_id (str)

• host (str)

• island (str)

• provider (str)

• region (str)

• spec (DeviceSpec)

• storage_region (str | None)

as_dict()

Return a JSON-compatible device declaration.

Return type:

dict[str, Any]

class TransferEstimate(source, target, nbytes, seconds, path)

Bases: object

Best measured route and transfer time between two devices.

Parameters:

• source (str)

• target (str)

• nbytes (int)

• seconds (float)

• path (tuple[str, ...])

class TransferSample(source, target, bytes_transferred, elapsed_seconds)

Bases: object

One observed point-to-point transfer.

Parameters:

• source (str)

• target (str)

• bytes_transferred (int)

• elapsed_seconds (float)

calibrate_links(samples)

Fit time = latency + bytes / bandwidth independently per direction.

Parameters:

samples (tuple[TransferSample, ...])

Return type:

tuple[LinkProfile, …]

plan_structured_placement(graph, topology, *, n_data=None)

Place exact structured cuts inside one island and proposals across islands.

Parameters:

• graph (UpdateGraph)

• topology (ClusterTopology)

• n_data (int | None)

Return type:

StructuredPlacementPlan