openg2g 0.1.0

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  # or: pip install -e . --group dev

Quick Start

For a full walkthrough including data setup, see the Getting Started guide. The snippet below illustrates the core API:

from fractions import Fraction
from pathlib import Path

from openg2g.coordinator import Coordinator
from openg2g.datacenter.config import DatacenterConfig, InferenceModelSpec
from openg2g.datacenter.offline import OfflineDatacenter, OfflineWorkload
from openg2g.datacenter.workloads.inference import InferenceData
from openg2g.grid.opendss import OpenDSSGrid
from openg2g.controller.noop import NoopController
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,
    ),
    InferenceModelSpec(
        model_label="Llama-3.1-70B", num_replicas=180, gpus_per_replica=4,
        initial_batch_size=128, itl_deadline_s=0.10,
    ),
)
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),
    dt_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=dc_config.power_factor,
    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 (offline trace-replay and online hardware-in-the-loop variants).

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 (gated -- request access first) and generates simulation artifacts. Subsequent runs load from cache.

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

# Baseline: scheduled tap changes
python examples/offline/run_baseline.py --config examples/offline/config.json --mode tap-change

# OFO closed-loop control
python examples/offline/run_ofo.py --config examples/offline/config.json

--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}/.

Documentation

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

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

Contact

Jae-Won Chung [e-mail]

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},
}