tm-based sizing

Author: networmix

examples/small_test_baseline.yml

@@ -66,6 +66,17 @@ build:
   capacity_allocation:
     enabled: false
 
+  tm_sizing:
+    enabled: true
+    matrix_name: baseline_traffic_matrix
+    quantum_gbps: 3200.0
+    headroom: 1.3
+    alpha_dc_to_pop: 1.2
+    beta_intra_pop: 0.8
+    flow_placement: EQUAL_BALANCED
+    edge_select: ALL_MIN_COST
+    respect_min_base_capacity: true
+
 components:
   assignments:
     core:

examples/small_test_clos.yml

@@ -67,6 +67,17 @@ build:
   capacity_allocation:
     enabled: false
 
+  tm_sizing:
+    enabled: true
+    matrix_name: baseline_traffic_matrix
+    quantum_gbps: 3200.0
+    headroom: 1.3
+    alpha_dc_to_pop: 1.2
+    beta_intra_pop: 0.8
+    flow_placement: EQUAL_BALANCED
+    edge_select: ALL_MIN_COST
+    respect_min_base_capacity: true
+
 components:
   assignments:
     core:

topogen/config.py

@@ -187,6 +187,9 @@ class BuildConfig:
     capacity_allocation: "BuildCapacityAllocationConfig" = field(  # type: ignore[name-defined]
         default_factory=lambda: BuildCapacityAllocationConfig()
     )
+    tm_sizing: "BuildTmSizingConfig" = field(  # type: ignore[name-defined]
+        default_factory=lambda: BuildTmSizingConfig()
+    )
 
 
 @dataclass
@@ -205,6 +208,40 @@ class BuildCapacityAllocationConfig:
     enabled: bool = False
 
 
+@dataclass
+class BuildTmSizingConfig:
+    """Traffic-matrix-based capacity sizing configuration.
+
+    When enabled, capacities are sized from an early traffic matrix and ECMP
+    routing on the site-level graph before DSL expansion. This stage computes
+    per-corridor loads from DC-to-DC demands, applies headroom, and quantizes
+    to discrete capacity increments. Local DC-to-PoP and PoP-to-PoP base
+    capacities are then derived from metro egress.
+
+    Attributes:
+        enabled: Enable TM-based sizing stage.
+        matrix_name: Traffic matrix name to use. Defaults to ``traffic.matrix_name``.
+        quantum_gbps: Capacity quantum Q in Gb/s for rounding up.
+        headroom: Headroom multiplier h applied to corridor loads before quantizing.
+        alpha_dc_to_pop: Fraction for DC→PoP base capacity relative to PoP egress.
+        beta_intra_pop: Fraction for intra-metro PoP↔PoP base capacity relative to
+            the minimum of the two PoP egress values.
+        flow_placement: Flow splitting policy. One of {"EQUAL_BALANCED", "PROPORTIONAL"}.
+        edge_select: Path selection policy. One of {"ALL_MIN_COST", "ALL_MIN_COST_WITH_CAP_REMAINING"}.
+        respect_min_base_capacity: If True, do not size below configured base capacities.
+    """
+
+    enabled: bool = False
+    matrix_name: str | None = None
+    quantum_gbps: float = 3200.0
+    headroom: float = 1.3
+    alpha_dc_to_pop: float = 1.2
+    beta_intra_pop: float = 0.8
+    flow_placement: str = "EQUAL_BALANCED"
+    edge_select: str = "ALL_MIN_COST"
+    respect_min_base_capacity: bool = True
+
+
 @dataclass
 class ComponentAssignment:
     """Component assignment configuration for a network role.
@@ -580,6 +617,7 @@ def _from_dict(cls, config_dict: dict[str, Any]) -> TopologyConfig:
         build_defaults_dict = build_dict.get("build_defaults", {})
         build_overrides_list = build_dict.get("build_overrides", [])
         capacity_alloc_dict = build_dict.get("capacity_allocation", {})
+        tm_sizing_dict = build_dict.get("tm_sizing", {})
 
         if not isinstance(build_defaults_dict, dict):
             raise ValueError("'build_defaults' must be a dictionary")
@@ -589,6 +627,10 @@ def _from_dict(cls, config_dict: dict[str, Any]) -> TopologyConfig:
             capacity_alloc_dict = {}
         if not isinstance(capacity_alloc_dict, dict):
             raise ValueError("'capacity_allocation' must be a dictionary if provided")
+        if tm_sizing_dict is None:
+            tm_sizing_dict = {}
+        if not isinstance(tm_sizing_dict, dict):
+            raise ValueError("'tm_sizing' must be a dictionary if provided")
 
         # Parse link parameter configurations
         intra_metro_link_dict = build_defaults_dict.get("intra_metro_link", {})
@@ -655,6 +697,41 @@ def _from_dict(cls, config_dict: dict[str, Any]) -> TopologyConfig:
             enabled=bool(capacity_alloc_dict.get("enabled", False))
         )
 
+        # TM-based sizing configuration
+        _allowed_tm_keys = {
+            "enabled",
+            "matrix_name",
+            "quantum_gbps",
+            "headroom",
+            "alpha_dc_to_pop",
+            "beta_intra_pop",
+            "flow_placement",
+            "edge_select",
+            "respect_min_base_capacity",
+        }
+        _tm_extra = set(tm_sizing_dict.keys()) - _allowed_tm_keys
+        if _tm_extra:
+            raise ValueError(
+                f"Unknown keys in 'build.tm_sizing': {sorted(_tm_extra)}. Allowed keys: {sorted(_allowed_tm_keys)}"
+            )
+        tm_sizing = BuildTmSizingConfig(
+            enabled=bool(tm_sizing_dict.get("enabled", False)),
+            matrix_name=(
+                str(tm_sizing_dict.get("matrix_name"))
+                if tm_sizing_dict.get("matrix_name") is not None
+                else None
+            ),
+            quantum_gbps=float(tm_sizing_dict.get("quantum_gbps", 3200.0)),
+            headroom=float(tm_sizing_dict.get("headroom", 1.3)),
+            alpha_dc_to_pop=float(tm_sizing_dict.get("alpha_dc_to_pop", 1.2)),
+            beta_intra_pop=float(tm_sizing_dict.get("beta_intra_pop", 0.8)),
+            flow_placement=str(tm_sizing_dict.get("flow_placement", "EQUAL_BALANCED")),
+            edge_select=str(tm_sizing_dict.get("edge_select", "ALL_MIN_COST")),
+            respect_min_base_capacity=bool(
+                tm_sizing_dict.get("respect_min_base_capacity", True)
+            ),
+        )
+
         # Normalize list of overrides into slug->override mapping.
         # Schema per entry: { metros: [str, ...], <override_fields> }
         allowed_override_keys = {
@@ -703,6 +780,7 @@ def _from_dict(cls, config_dict: dict[str, Any]) -> TopologyConfig:
             build_defaults=build_defaults,
             build_overrides=normalized_overrides,
             capacity_allocation=capacity_allocation,
+            tm_sizing=tm_sizing,
         )
 
         # Handle optional components configuration (assignments only)

topogen/scenario/assembly.py

@@ -13,6 +13,7 @@
 from .graph_pipeline import (
     assign_per_link_capacity,
     build_site_graph,
+    tm_based_size_capacities,
     to_network_sections,
 )
 from .libraries import _build_blueprints_section, _build_components_section
@@ -59,7 +60,23 @@ def build_scenario(graph: "nx.Graph", config: "TopologyConfig") -> str:
     # New graph-based pipeline builds the authoritative site graph first
     logger.info("Building site-level MultiGraph")
     G = build_site_graph(metros, metro_settings, graph, config)
-    logger.info("Assigning capacities from defaults split by adjacency")
+    # Optional TM-based sizing before per-link capacity split
+    try:
+        tm_based_size_capacities(G, metros, metro_settings, config)
+    except Exception:
+        # Fail fast with clear error; no silent fallback
+        raise
+    # Log clearly which capacity path is in effect
+    try:
+        tm_enabled = bool(
+            getattr(getattr(config.build, "tm_sizing", object()), "enabled", False)
+        )
+    except Exception:
+        tm_enabled = False
+    if tm_enabled:
+        logger.info("Assigning per-link capacities after TM-based sizing")
+    else:
+        logger.info("Assigning per-link capacities from configured base capacities")
     assign_per_link_capacity(G, config)
 
     # Determine used blueprints directly from the site graph (source of truth)