openg2g 0.0.1.post1

A GPU-to-Grid simulation library for datacenter-grid cooperation.

OpenG2G

A modular Python library for simulating datacenter-grid interaction, with a focus on LLM workloads.

OpenG2G provides the building blocks for studying how datacenter-level controls (e.g., LLM workload batch size) affect distribution-level voltages. It ships with an implementation of Online Feedback Optimization (OFO) for joint voltage regulation and latency management, alongside a trace-replay datacenter backend and an OpenDSS-based grid simulator.

Key Features

• Multi-rate simulation: datacenter, grid, and controller components run at independent rates, coordinated by a shared clock.
• Pluggable architecture: swap datacenter backends (trace-based or live GPU) and controllers (OFO, tap scheduling, or your own) via simple abstract interfaces.
• OpenDSS integration: power flow analysis on standard IEEE test feeders with tap scheduling (TapPosition/TapSchedule API) and voltage monitoring.
• Online Feedback Optimization: primal-dual batch size control balancing voltage regulation, inference latency, and throughput.
• Live GPU support: OnlineDatacenter backend reads real-time GPU power via Zeus for hardware-in-the-loop experiments.

Installation

Requires Python 3.10+.

pip install openg2g

For grid simulation with OpenDSS:

pip install "openg2g[opendss]"

Development

git clone https://github.com/gpu2grid/openg2g.git
cd openg2g
uv sync

Quick Start

from fractions import Fraction

from openg2g.coordinator import Coordinator
from openg2g.datacenter.offline import OfflineDatacenter, PowerTraceStore
from openg2g.grid.opendss import OpenDSSGrid
from openg2g.controller.noop import NoopController
from openg2g.models.spec import LLMInferenceModelSpec
from openg2g.types import TapPosition

# 1. Set up a trace-based datacenter
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")
store.build_templates(duration_s=3600, timestep_s=Fraction(1, 10))
dc = OfflineDatacenter(trace_store=store, models=models, timestep_s=Fraction(1, 10))

# 2. Set up the grid
TAP_STEP = 0.00625
grid = OpenDSSGrid(
    dss_case_dir="examples/ieee13",
    dss_master_file="IEEE13Nodeckt.dss",
    dc_bus="671",
    dc_bus_kv=4.16,
    power_factor=0.95,
    dt_s=Fraction(1, 10),
    initial_tap_position=TapPosition(a=1.0 + 14 * TAP_STEP, b=1.0 + 6 * TAP_STEP, c=1.0 + 15 * TAP_STEP),
    connection_type="wye",
)

# 3. Run the simulation
coord = Coordinator(
    datacenter=dc,
    grid=grid,
    controllers=[NoopController()],
    total_duration_s=3600,
    dc_bus="671",
)
log = coord.run()

See examples/ for complete simulation scripts:

• run_baseline.py --mode no-tap -- fixed taps, no OFO ("No control, no tap")
• run_baseline.py --mode tap-change -- scheduled tap changes, no OFO ("Tap change only")
• run_ofo.py -- OFO closed-loop batch size control

Running Example Simulations

1. Build simulation data from benchmarks

The build script uses the mlenergy-data toolkit to download and process GPU benchmark data from the ML.ENERGY Benchmark v3 dataset (gated -- request access first). It produces the trace CSVs, latency fit parameters, and logistic fit parameters that the simulation consumes. Model selection is controlled by a JSON config file (data/offline/models.json).

Generated artifacts go into data/generated/ (gitignored). Source files (data/offline/*.py, data/offline/models.json) are versioned.

uv run python data/offline/build_mlenergy_data.py \
  --config data/offline/models.json \
  --out-dir data/generated

2. Generate a synthetic training power trace

uv run python data/offline/generate_training_trace.py \
  --out-csv data/generated/synthetic_training_trace.csv --seed 2

3. Run simulations

# Baseline: fixed taps
uv run python examples/offline/run_baseline.py --mode no-tap \
  --data-dir data/generated \
  --training-trace data/generated/synthetic_training_trace.csv

# Baseline: scheduled tap changes
uv run python examples/offline/run_baseline.py --mode tap-change \
  --data-dir data/generated \
  --training-trace data/generated/synthetic_training_trace.csv

# OFO closed-loop control
uv run python examples/offline/run_ofo.py \
  --data-dir data/generated \
  --training-trace data/generated/synthetic_training_trace.csv

--data-dir and --training-trace are required for all simulation drivers.

Documentation

Full documentation is available at https://gpu2grid.io/openg2g, including:

• Installation and setup guide
• Running simulations
• Implementing custom components
• Architecture reference

Citation

If you use OpenG2G in your research, please cite:

@article{gpu2grid-arxiv26,
  title   = {{GPU-to-Grid}: Voltage Regulation via {GPU} Utilization Control},
  author  = {Zhirui Liang and Jae-Won Chung and Mosharaf Chowdhury and Jiasi Chen and Vladimir Dvorkin},
  year    = {2026},
  journal = {arXiv preprint arXiv:2602.05116},
}