debug for traffic matrix

Author: networmix

examples/small_test_baseline.yml

@@ -91,7 +91,7 @@ traffic:
   enabled: true
   model: gravity
   gbps_per_mw: 250.0
-  mw_per_dc_region: 50.0
+  mw_per_dc_region: 500.0
   priority_ratios:
     0: 1
   matrix_name: baseline_traffic_matrix
@@ -103,7 +103,7 @@ traffic:
     distance_metric: euclidean_km
     emission: explicit_pairs
     jitter_stddev: 0.0
-    rounding_gbps: 0.0
+    rounding_gbps: 100.0
 
 data_sources:
   uac_polygons: "data/tl_2020_us_uac20.zip"

examples/small_test_clos.yml

@@ -92,7 +92,7 @@ traffic:
   enabled: true
   model: gravity
   gbps_per_mw: 250.0
-  mw_per_dc_region: 50.0
+  mw_per_dc_region: 500.0
   priority_ratios:
     0: 1
   matrix_name: baseline_traffic_matrix
@@ -104,7 +104,7 @@ traffic:
     distance_metric: euclidean_km
     emission: explicit_pairs
     jitter_stddev: 0.0
-    rounding_gbps: 0.0
+    rounding_gbps: 100.0
 
 data_sources:
   uac_polygons: "data/tl_2020_us_uac20.zip"

topogen/cli.py

@@ -83,6 +83,18 @@ def build_command(args: argparse.Namespace) -> None:
             prefix = getattr(config_obj, "_source_path", config_path)
             output_path = Path.cwd() / f"{Path(prefix).stem}_scenario.yml"
 
+        # Attach optional debug directory to config for downstream use
+        if getattr(args, "debug_dir", None):
+            try:
+                debug_dir = Path(args.debug_dir)
+                debug_dir.mkdir(parents=True, exist_ok=True)
+                config_obj._debug_dir = debug_dir
+                # Provide a stable stem to downstream exporters
+                config_obj._source_stem = Path(config_path).stem
+            except Exception:
+                # Non-fatal: continue without debug directory
+                pass
+
         # Run the pipeline with timing
         with Timer("Topology generation pipeline"):
             scenario_yaml = _run_pipeline(
@@ -349,6 +361,14 @@ def main() -> None:
         action="store_true",
         help="Print generated YAML to stdout for debugging",
     )
+    build_parser.add_argument(
+        "--debug-dir",
+        default=None,
+        help=(
+            "Optional directory to write debug artifacts (e.g., traffic matrix "
+            "internals as JSON) when -v is enabled"
+        ),
+    )
 
     build_parser.set_defaults(func=build_command)
 

topogen/config.py

@@ -312,7 +312,11 @@ class TrafficGravityConfig:
         emission: One of {"explicit_pairs", "macro_pairwise"} for output format.
         max_partners_per_dc: If set, keeps top-K partners per DC by weight.
         jitter_stddev: Lognormal sigma for multiplicative noise (0 disables jitter).
-        rounding_gbps: If > 0, round per-pair demands to this step size and conserve totals.
+        rounding_gbps: If > 0, quantize undirected per-pair totals to this step size.
+        rounding_policy: Quantization policy for undirected totals. One of
+            {"nearest", "ceil", "floor"}. "nearest" minimizes absolute error,
+            "ceil" guarantees non-negative inflation (sum >= exact total), and
+            "floor" guarantees non-positive inflation (sum <= exact total).
         mw_per_dc_region_overrides: Optional overrides by metro name or full DC path
             (e.g., "metro3/dc2"). Overrides apply after defaults.
     """
@@ -326,6 +330,7 @@ class TrafficGravityConfig:
     max_partners_per_dc: int | None = None
     jitter_stddev: float = 0.0
     rounding_gbps: float = 0.0
+    rounding_policy: str = "nearest"
     mw_per_dc_region_overrides: dict[str, float] = field(default_factory=dict)
 
 
@@ -456,6 +461,9 @@ class TopologyConfig:
     # Visualization behavior; default False keeps previous straight-line rendering
     _use_real_corridor_geometry: bool = False
     _source_path: Path | None = None
+    # Optional instrumentation fields for debugging/export
+    _debug_dir: Path | None = None
+    _source_stem: str | None = None
 
     @classmethod
     def from_yaml(cls, config_path: Path) -> TopologyConfig: