[API] Reorg core component constructors

Author: jaywonchung

README.md

@@ -52,23 +52,27 @@ For a full walkthrough including data setup, see the [Getting Started guide](htt
 from fractions import Fraction
 
 from openg2g.coordinator import Coordinator
-from openg2g.datacenter.config import DatacenterConfig, WorkloadConfig
-from openg2g.datacenter.offline import OfflineDatacenter, PowerTraceStore
+from openg2g.datacenter.config import DatacenterConfig
+from openg2g.datacenter.offline import (
+    OfflineDatacenter, OfflineInferenceData, OfflineWorkload, PowerTraceStore,
+)
 from openg2g.grid.opendss import OpenDSSGrid
 from openg2g.controller.noop import NoopController
 from openg2g.models.spec import LLMInferenceModelSpec, LLMInferenceWorkload
 from openg2g.types import TapPosition
 
 # 1. Set up a trace-based datacenter
-workload = WorkloadConfig(
-    inference=LLMInferenceWorkload(models=(
-        LLMInferenceModelSpec("Llama-3.1-8B", num_replicas=720, gpus_per_replica=1, initial_batch_size=128),
-        LLMInferenceModelSpec("Llama-3.1-70B", num_replicas=180, gpus_per_replica=4, initial_batch_size=128),
-    )),
-)
+models = LLMInferenceWorkload(models=(
+    LLMInferenceModelSpec("Llama-3.1-8B", num_replicas=720, gpus_per_replica=1, initial_batch_size=128),
+    LLMInferenceModelSpec("Llama-3.1-70B", num_replicas=180, gpus_per_replica=4, initial_batch_size=128),
+))
 store = PowerTraceStore.load("data/generated/traces_summary.csv")
 templates = store.build_templates(duration_s=3600, dt_s=Fraction(1, 10))
-dc = OfflineDatacenter(DatacenterConfig(), workload, template_store=templates, dt_s=Fraction(1, 10))
+dc = OfflineDatacenter(
+    DatacenterConfig(),
+    OfflineWorkload(inference_data=OfflineInferenceData(models, power_templates=templates)),
+    dt_s=Fraction(1, 10),
+)
 
 # 2. Set up the grid
 TAP_STEP = 0.00625
@@ -94,11 +98,7 @@ coord = Coordinator(
 log = coord.run()
 ```
 
-See [`examples/`](examples/) for complete simulation scripts:
-
-- `run_baseline.py --mode no-tap`: fixed taps, no OFO
-- `run_baseline.py --mode tap-change`: scheduled tap changes, no OFO
-- `run_ofo.py`: OFO closed-loop batch size control
+See [`examples/`](examples/) for complete simulation scripts (offline trace-replay and online hardware-in-the-loop variants).
 
 ## Running Example Simulations
 
@@ -127,20 +127,23 @@ python data/offline/generate_training_trace.py \
 # Baseline: fixed taps
 python examples/offline/run_baseline.py --mode no-tap \
   --data-dir data/generated \
-  --training-trace data/generated/synthetic_training_trace.csv
+  --training-trace data/generated/synthetic_training_trace.csv \
+  --ieee-case-dir examples/ieee13
 
 # Baseline: scheduled tap changes
 python examples/offline/run_baseline.py --mode tap-change \
   --data-dir data/generated \
-  --training-trace data/generated/synthetic_training_trace.csv
+  --training-trace data/generated/synthetic_training_trace.csv \
+  --ieee-case-dir examples/ieee13
 
 # OFO closed-loop control
 python examples/offline/run_ofo.py \
   --data-dir data/generated \
-  --training-trace data/generated/synthetic_training_trace.csv
+  --training-trace data/generated/synthetic_training_trace.csv \
+  --ieee-case-dir examples/ieee13
 ```
 
-`--data-dir` and `--training-trace` are required for all simulation drivers.
+`--data-dir`, `--training-trace`, and `--ieee-case-dir` are required for all offline simulation drivers.
 
 ## Documentation
 

data/offline/generate_training_trace.py

@@ -1,8 +1,7 @@
 """Generate a synthetic GPU training-like power trace.
 
-Extracted from baseline_wo_control.py. Produces a CSV with columns
-``t_s`` and ``power_W`` that can be used as a training overlay in
-the simulation.
+Produces a CSV with columns ``t_s`` and ``power_W`` that can be used as a
+training overlay in the simulation.
 """
 
 from __future__ import annotations

docs/getting-started/quickstart.md

@@ -48,15 +48,18 @@ These three runs correspond to the evaluation cases in the [GPU-to-Grid paper](h
 ```bash
 python examples/offline/run_baseline.py --mode no-tap \
   --data-dir data/generated \
-  --training-trace data/generated/synthetic_training_trace.csv
+  --training-trace data/generated/synthetic_training_trace.csv \
+  --ieee-case-dir examples/ieee13
 
 python examples/offline/run_baseline.py --mode tap-change \
   --data-dir data/generated \
-  --training-trace data/generated/synthetic_training_trace.csv
+  --training-trace data/generated/synthetic_training_trace.csv \
+  --ieee-case-dir examples/ieee13
 
 python examples/offline/run_ofo.py \
   --data-dir data/generated \
-  --training-trace data/generated/synthetic_training_trace.csv
+  --training-trace data/generated/synthetic_training_trace.csv \
+  --ieee-case-dir examples/ieee13
 ```
 
 Outputs (plots and logs) are saved to `outputs/baseline_no-tap/`, `outputs/baseline_tap-change/`, and `outputs/ofo/`.

docs/guide/architecture.md

@@ -152,12 +152,12 @@ __init__() ──> reset() ──> start() ──> step() / apply_control() ─
 This is mainly to allow reuse component objects across multiple [`Coordinator.run()`][openg2g.coordinator.Coordinator.run] calls with different configurations without having to re-instantiate all of them all the time:
 
 ```python
-grid = OpenDSSGrid(...)               # stores config only
-ctrl = OFOBatchSizeController(...)        # stores fits + tuning
-for config in datacenter_configs:
-    dc = OfflineDatacenter(**config)  # builds power templates
+grid = OpenDSSGrid(...)                    # stores config only
+ctrl = OFOBatchSizeController(...)         # stores fits + tuning
+for workload in workloads:
+    dc = OfflineDatacenter(dc_config, workload, dt_s=dt)  # builds power templates
     coord = Coordinator(dc, grid, [ctrl], total_duration_s=3600, dc_bus="671")
-    log = coord.run()                 # reset -> start -> loop -> stop
+    log = coord.run()                      # reset -> start -> loop -> stop
 ```
 
 

docs/guide/building-simulators.md

@@ -26,43 +26,46 @@ The sections below show how to set up each component.
 ### Datacenter
 
 The [`OfflineDatacenter`][openg2g.datacenter.offline.OfflineDatacenter] replays GPU power traces built from the [data pipeline](data-pipeline.md).
-Load traces from the generated manifest, build templates for the simulation config, then create the datacenter with a [`DatacenterConfig`][openg2g.datacenter.config.DatacenterConfig] and [`WorkloadConfig`][openg2g.datacenter.config.WorkloadConfig]:
+Load traces from the generated manifest, build templates for the simulation config, then create the datacenter with a [`DatacenterConfig`][openg2g.datacenter.config.DatacenterConfig] and [`OfflineWorkload`][openg2g.datacenter.offline.OfflineWorkload]:
 
 ```python
 from fractions import Fraction
 
-from openg2g.datacenter.config import DatacenterConfig, WorkloadConfig
-from openg2g.datacenter.offline import OfflineDatacenter, PowerTraceStore
+from openg2g.datacenter.config import DatacenterConfig, PowerAugmentationConfig, ServerRamp, TrainingRun
+from openg2g.datacenter.offline import OfflineDatacenter, OfflineInferenceData, OfflineWorkload, PowerTraceStore
 from openg2g.datacenter.training_overlay import TrainingTrace
 from openg2g.models.spec import LLMInferenceModelSpec, LLMInferenceWorkload
-from openg2g.types import ServerRamp, TrainingRun
 
 store = PowerTraceStore.load("data/generated/traces_summary.csv")
 templates = store.build_templates(duration_s=3600.0, dt_s=Fraction(1, 10))
 
 training_trace = TrainingTrace.load("data/generated/synthetic_training_trace.csv")
 
-workload = WorkloadConfig(
-    inference=LLMInferenceWorkload(models=(
-        LLMInferenceModelSpec(
-            model_label="Llama-3.1-8B", num_replicas=720, gpus_per_replica=1, initial_batch_size=128,
-        ),
-        LLMInferenceModelSpec(
-            model_label="Llama-3.1-70B", num_replicas=180, gpus_per_replica=4, initial_batch_size=128,
-        ),
-    )),
+workload = OfflineWorkload(
+    inference_data=OfflineInferenceData(
+        LLMInferenceWorkload(models=(
+            LLMInferenceModelSpec(
+                model_label="Llama-3.1-8B", num_replicas=720, gpus_per_replica=1, initial_batch_size=128,
+            ),
+            LLMInferenceModelSpec(
+                model_label="Llama-3.1-70B", num_replicas=180, gpus_per_replica=4, initial_batch_size=128,
+            ),
+        )),
+        power_templates=templates,
+    ),
     server_ramps=ServerRamp(t_start=2500.0, t_end=3000.0, target=0.2),
     training=TrainingRun(t_start=1000.0, t_end=2000.0, n_gpus=2400, trace=training_trace),
 )
 
 dc = OfflineDatacenter(
-    datacenter=DatacenterConfig(gpus_per_server=8, base_kw_per_phase=500.0),
-    workload=workload,
-    template_store=templates,
+    DatacenterConfig(gpus_per_server=8, base_kw_per_phase=500.0),
+    workload,
     dt_s=Fraction(1, 10),
     seed=0,
-    amplitude_scale_range=(0.98, 1.02),
-    noise_fraction=0.005,
+    power_augmentation=PowerAugmentationConfig(
+        amplitude_scale_range=(0.98, 1.02),
+        noise_fraction=0.005,
+    ),
 )
 ```
 

docs/guide/data-pipeline.md

@@ -130,11 +130,13 @@ At simulation time, the generated artifacts are consumed by two components:
 ```bash
 python examples/offline/run_baseline.py --mode no-tap \
   --data-dir data/generated \
-  --training-trace data/generated/synthetic_training_trace.csv
+  --training-trace data/generated/synthetic_training_trace.csv \
+  --ieee-case-dir examples/ieee13
 
 python examples/offline/run_ofo.py \
   --data-dir data/generated \
-  --training-trace data/generated/synthetic_training_trace.csv
+  --training-trace data/generated/synthetic_training_trace.csv \
+  --ieee-case-dir examples/ieee13
 ```
 
-`--data-dir` and `--training-trace` are required for all simulation drivers.
+`--data-dir`, `--training-trace`, and `--ieee-case-dir` are required for all offline simulation drivers.

examples/offline/plotting.py

@@ -1,8 +1,7 @@
 """Plotting functions and data-loading helpers for openg2g simulation results.
 
-Faithfully ports the matplotlib code from ``baseline_wo_control.py`` and
-``final_ofo_test.py`` (the G2G paper reference scripts), adapted to read data
-from the library's ``SimulationLog`` and ``LLMDatacenterState`` objects.
+Reproduces the figures from the G2G paper, reading data from the library's
+``SimulationLog`` and ``LLMDatacenterState`` objects.
 
 This module lives outside the ``openg2g`` library on purpose: the library
 exports simulation state and metrics, while all matplotlib-dependent
@@ -32,8 +31,7 @@
 Figure = matplotlib.figure.Figure
 
 # ── Bus color map (IEEE 13-bus, tab20-based) ─────────────────────────
-# Deterministic colors from baseline_wo_control.py so all voltage plots
-# use consistent bus coloring.
+# Deterministic colors so all voltage plots use consistent bus coloring.
 
 BUS_COLOR_MAP: dict[str, Any] = {
     "611": (0.1216, 0.4667, 0.7059, 1.0),
@@ -121,7 +119,6 @@ def _bus_sort_key(b: str) -> tuple[int, str]:
 
 # ══════════════════════════════════════════════════════════════════════
 # Paper Fig. 5: 2-panel, 3-phase power (MW) + per-model average ITL
-# (ported from baseline_wo_control.py  plot_power_latency_subfigs_compact)
 # ══════════════════════════════════════════════════════════════════════
 
 
@@ -237,7 +234,6 @@ def plot_power_and_itl_2panel(
 
 # ══════════════════════════════════════════════════════════════════════
 # Paper Fig. 6 / Fig. 7: Per-phase all-bus voltages with bus colormap
-# (ported from both baseline_wo_control.py and final_ofo_test.py)
 # ══════════════════════════════════════════════════════════════════════
 
 
@@ -415,7 +411,6 @@ def plot_allbus_voltages_per_phase(
 
 # ══════════════════════════════════════════════════════════════════════
 # Paper Fig. 8: 4-panel, batch, power/replica, ITL, throughput (OFO)
-# (ported from final_ofo_test.py  plot_model_timeseries_4panel_compact)
 # ══════════════════════════════════════════════════════════════════════
 
 
@@ -610,7 +605,7 @@ def _apply_overlays(ax: Axes) -> None:
 
 
 # ══════════════════════════════════════════════════════════════════════
-# Standalone plots (nice-to-have, ported from final_ofo_test.py)
+# Standalone plots
 # ══════════════════════════════════════════════════════════════════════
 
 
@@ -943,28 +938,3 @@ def _draw_schedule_lines(ax: Axes) -> None:
         fig.savefig(save_path, bbox_inches="tight")
         plt.close(fig)
     return fig
-
-
-# ══════════════════════════════════════════════════════════════════════
-# Shared data-loading helpers
-# ══════════════════════════════════════════════════════════════════════
-
-
-def load_itl_fits_from_csv(csv_path: Path | str) -> dict[str, dict[int, Any]]:
-    """Load ITL mixture fits from a CSV.
-
-    Returns:
-        {model_label: {batch_size: ITLMixtureModel}}.
-    """
-    import pandas as pd
-    from mlenergy_data.modeling import ITLMixtureModel
-
-    df = pd.read_csv(csv_path)
-    result: dict[str, dict[int, Any]] = {}
-    for row in df.to_dict(orient="records"):
-        model = str(row["model_label"]).strip()
-        batch = int(row["max_num_seqs"])
-        result.setdefault(model, {})[batch] = ITLMixtureModel.from_dict(row)
-    if not result:
-        raise ValueError(f"No ITL mixture rows loaded from {csv_path}")
-    return result