[Feat] Numerous extensions and enhancements with examples

.gitignore

@@ -13,3 +13,6 @@ docs/api/
 
 data/offline/
 data/online/
+.claude/
+examples/offline/data/offline/
+examples/offline/outputs

README.md

@@ -64,28 +64,30 @@ from openg2g.grid.config import TapPosition
 # 1. Set up a trace-based datacenter
 models = (
     InferenceModelSpec(
-        model_label="Llama-3.1-8B", num_replicas=720, gpus_per_replica=1,
-        initial_batch_size=128, itl_deadline_s=0.08,
+        model_label="Llama-3.1-8B", gpus_per_replica=1,
+        itl_deadline_s=0.08, feasible_batch_sizes=(8, 16, 32, 64, 128, 256, 512),
     ),
     InferenceModelSpec(
-        model_label="Llama-3.1-70B", num_replicas=180, gpus_per_replica=4,
-        initial_batch_size=128, itl_deadline_s=0.10,
+        model_label="Llama-3.1-70B", gpus_per_replica=4,
+        itl_deadline_s=0.10, feasible_batch_sizes=(8, 16, 32, 64, 128, 256, 512),
     ),
 )
+replica_counts = {"Llama-3.1-8B": 720, "Llama-3.1-70B": 180}
 data_dir = Path("data/offline")
 inference_data = InferenceData.load(data_dir, models, duration_s=3600, dt_s=0.1)
 dc_config = DatacenterConfig()
 dc = OfflineDatacenter(
     dc_config,
-    OfflineWorkload(inference_data=inference_data),
+    OfflineWorkload(inference_data=inference_data, replica_counts=replica_counts),
     dt_s=Fraction(1, 10),
+    total_gpu_capacity=1440,
 )
 
 # 2. Set up the grid
 TAP_STEP = 0.00625
 grid = OpenDSSGrid(
     dss_case_dir="examples/ieee13",
-    dss_master_file="IEEE13Nodeckt.dss",
+    dss_master_file="IEEE13Bus.dss",
     dc_bus="671",
     dc_bus_kv=4.16,
     power_factor=dc_config.power_factor,
@@ -109,22 +111,22 @@ See [`examples/`](examples/) for complete simulation scripts (offline trace-repl
 
 ## Running Example Simulations
 
-A single `--config` flag drives both data generation and simulation. The first run downloads benchmark data from the [ML.ENERGY Benchmark v3 dataset](https://huggingface.co/datasets/ml-energy/benchmark-v3) (gated -- [request access](https://huggingface.co/datasets/ml-energy/benchmark-v3) first) and generates simulation artifacts. Subsequent runs load from cache.
+The first run downloads benchmark data from the [ML.ENERGY Benchmark v3 dataset](https://huggingface.co/datasets/ml-energy/benchmark-v3) (gated -- [request access](https://huggingface.co/datasets/ml-energy/benchmark-v3) first) and generates simulation artifacts. Subsequent runs load from cache.
 
 ```bash
 export HF_TOKEN=hf_xxxxxxxxxxx  # needed for first run only
 
 # Baseline: fixed taps
-python examples/offline/run_baseline.py --config examples/offline/config.json --mode no-tap
+python examples/offline/run_baseline.py --system ieee13 --mode no-tap
 
 # Baseline: scheduled tap changes
-python examples/offline/run_baseline.py --config examples/offline/config.json --mode tap-change
+python examples/offline/run_baseline.py --system ieee13 --mode tap-change
 
 # OFO closed-loop control
-python examples/offline/run_ofo.py --config examples/offline/config.json
+python examples/offline/run_ofo.py --system ieee13
 ```
 
-`--config` is the only required argument. Model specs, data sources, and paths are all in the config file. Generated data is cached in `data/offline/{hash}/`.
+`--system` selects the IEEE test feeder (ieee13, ieee34, or ieee123). Model specs and data sources are in `config.json`; all other experiment parameters are defined inline in each script. Generated data is cached in `data/offline/{hash}/`.
 
 ## Documentation
 

_zensical.toml

@@ -34,6 +34,16 @@ nav = [
     { "Data Pipeline" = "guide/data-pipeline.md" },
     { "Building Simulators" = "guide/building-simulators.md" },
   ]},
+  { "Examples" = [
+    { "GPU Flexibility for Voltage Regulation" = "examples/gpu-flexibility.md" },
+    { "Voltage Regulation Strategies" = "examples/voltage-regulation-strategies.md" },
+    { "Controller Parameter Sensitivity" = "examples/controller-parameter-sensitivity.md" },
+    { "Grid Topology and DER Effects" = "examples/grid-topology-effects.md" },
+    { "Datacenter Sizing and Hosting Capacity" = "examples/hosting-capacity.md" },
+    { "Datacenter Location Planning" = "examples/dc-location-planning.md" },
+    { "Multi-Datacenter Coordination" = "examples/multi-dc-coordination.md" },
+    { "Joint PV + DC Siting and Sizing" = "examples/pv-dc-siting.md" },
+  ]},
   { "API Reference" = "auto-generated by scripts/docs.sh and scripts/gen_api_docs.py" },
 ]