Data center microgrid¶

Public API for PowerZooJax's current microgrid environment surface. At the moment, that surface is the single behind-the-meter DataCenterMicrogridEnv, which models a self-contained microgrid composed of a data-center load, battery, PV, and diesel generation.

This page documents that concrete environment API rather than the generic microgrid concept. For the physical interpretation and system-level description, see Physics / Microgrid.

`DataCenterMicrogridEnv`¶

from powerzoojax.envs import (
    DataCenterMicrogridEnv,
    DCMicrogridState,
    DCMicrogridParams,
    make_dcmicrogrid_params,
    make_dcmicrogrid_params_with_profiles,
)

Step contract¶

Action: 5-D Box [train_sched, ft_sched, cooling_norm, batt_norm, dg_norm]. batt_norm in [-1, 1] (positive = discharge); others in [0, 1].
Observation: 24-D, with workload, thermal, energy-asset, power-balance, battery-headroom, grid-price, and time channels (see Physics / Microgrid).
Reward: scalar r_energy + w_cost * r_cost + w_carbon * r_carbon. info["reward_vector"] = [r_energy, r_cost, r_carbon] exposes the unscaled components separately.
Constraint costs: costs = (cost_sla, cost_overtemp, cost_power_deficit), with info["cost_sum"] as the aggregate diagnostic.

Here train_sched and ft_sched are sequential GPU-budget fractions, not fixed GPU counts: training first consumes a fraction of the current headroom, then finetuning consumes a fraction of the remaining headroom. See Physics / Microgrid for the exact scheduling semantics.

`powerzoojax.envs.microgrid.dc_microgrid.DataCenterMicrogridEnv` ¶

Bases: Environment

Self-contained data-center microgrid environment (pure-JAX).

Combines DataCenter compute/thermal dynamics with a battery, PV, and diesel generator attached via the ResourceBundle protocol, with optional capped grid import.

Action: Box(5) — [train_sched, ft_sched, cooling_norm, batt_norm, dg_norm] Obs: Box(24) — see module docstring.

`reset(key, params)` ¶

`step(key, state, action, params)` ¶

`observation_space(params)` ¶

`action_space(params)` ¶

`powerzoojax.envs.microgrid.dc_microgrid.DCMicrogridState` ¶

Full state of the DataCenterMicrogridEnv.

Attributes:

Name	Type	Description
`dc`	`DataCenterState`	DataCenterState — task buffer, thermal, IT power.
`resource_states`	`tuple`	tuple of bundle states, one per attached ResourceBundle in `params.resources`. By convention the default factory builds them in the order `(BatteryBundleState, SolarBundleState, DieselBundleState)`.
`last_action`	`Array`	Last 5-D normalised action (history feature in obs).
`done`	`Array`	Episode termination flag.

`powerzoojax.envs.microgrid.dc_microgrid.DCMicrogridParams` ¶

Parameters for DataCenterMicrogridEnv.

Attributes:

Name	Type	Description
`dc`	`DataCenterParams`	DataCenterParams sub-config (IT + thermal + task generation).
`resources`	`tuple`	tuple of attached `ResourceBundle` instances. Default factory builds `(BatteryBundle, SolarBundle, DieselBundle)`. The env's `step()` dispatches actions to bundles in this order.
`battery_deg_cost_per_mwh`	`float`	Degradation cost [$/MWh of throughput]. Applied at the env-level reward layer (NOT inside BatteryBundle).
`w_cost`	`float`	Weight on r_cost in scalarized reward.
`w_carbon`	`float`	Weight on r_carbon in scalarized reward.
`grid_import_p_max_mw`	`float`	Maximum external grid import [MW].
`grid_price_ref_per_mwh`	`float`	Price scale used to normalize observation features [currency/MWh].
`grid_carbon_kg_per_kwh`	`float`	Grid-import carbon intensity.
`terminal_soc_target`	`float`	End-of-episode SOC inventory target.
`terminal_soc_penalty`	`float`	Quadratic terminal SOC inventory penalty.
`cpu_profile`	`Array`	Optional (T,) float32 ∈ [0,1] inference load fraction. None → DataCenterEnv's synthetic `_diurnal_factor()`.
`outdoor_temp_profile`	`Array`	Optional (T,) float32 [°C] outdoor temperature. None → DataCenterEnv's synthetic `_outdoor_temp()`.
`price_profile`	`Array`	Optional (T,) float32 grid-import price [currency/MWh]. None → price signal is zero.

Note

The solar_profile is now owned by the SolarBundle (see make_solar_bundle(profile=...)) — there is no env-level solar_profile field, eliminating a previous source-of-truth ambiguity.

`solar_profile` `property` ¶

Backward-compat: returns the (T,) PV CF profile.

The RenewableBundle stores profiles as (T, n_devices); for the single-device microgrid PV we squeeze along axis 1 so callers see the same shared (T,) shape they used in the SolarBundle / inline era.

`dg` `property` ¶

Backward-compat shim: returns a single-device DieselParams view.

powerzoojax.envs.microgrid.dc_microgrid.make_dcmicrogrid_params(n_gpus=1000, gpu_idle_w=55.0, gpu_active_w=580.0, p_base_mw=0.4, infer_gpu_peak=400, cop_ref=5.0, cop_decay=0.04, t_ref=20.0, c_thermal=500.0, ua_cooling=200.0, h_wall=5.0, t_set_min=18.0, t_set_max=27.0, t_initial=22.0, t_critical=35.0, p_aux_frac=0.05, train_arrival_interval=8, train_gpu_lo=50, train_gpu_hi=200, train_dur_lo=10, train_dur_hi=50, train_deadline_slack=2.0, train_gpu_eta=0.9, ft_arrival_interval=4, ft_gpu_lo=10, ft_gpu_hi=50, ft_dur_lo=5, ft_dur_hi=20, ft_deadline_slack=3.0, ft_gpu_eta=0.75, delta_t_hours=5.0 / 60.0, steps_per_day=288, max_steps=288, battery_capacity_mwh=2.0, battery_power_mw=0.5, battery_eta_charge=0.95, battery_eta_discharge=0.95, battery_soc_min=0.1, battery_soc_max=0.9, battery_soc_init=0.5, battery_deg_cost_per_mwh=5.0, pv_p_max_mw=0.4, solar_profile=None, grid_import_p_max_mw=0.0, grid_price_ref_per_mwh=150.0, grid_carbon_kg_per_kwh=0.18, terminal_soc_target=0.5, terminal_soc_penalty=0.0, price_profile=None, dg_p_max_mw=0.6, dg_fuel_cost_per_mwh=300.0, dg_emission_factor=0.8, dg_p_min_norm=0.0, w_cost=0.5, w_carbon=0.3, cpu_profile=None, outdoor_temp_profile=None) ¶

Build DCMicrogridParams with default (BatteryBundle, SolarBundle, DieselBundle).

All numeric defaults preserved from the previous in-line implementation; the change is structural — physics now lives in the dedicated bundle modules and is composed via the ResourceBundle protocol.

`powerzoojax.envs.microgrid.dc_microgrid.make_dcmicrogrid_params_with_profiles(source='google', episode_start_step=0, data_dir=None, manifest_dir=None, strict=False, require_real_data=False, **kwargs)` ¶

Build DCMicrogridParams with exogenous workload / solar / temp profiles.

Loads the DC workload profile (datacenter.cpu_util) from the specified data source via :mod:powerzoojax.data.dc_microgrid_profiles. Solar uses the committed GB generation-by-type real trace, normalised to a capacity factor. Grid-import price uses the committed GB MID market trace. Outdoor temperature remains a deterministic adapter because no weather manifest exists yet.

Parameters:

Name	Type	Description	Default
`source`	`str`	Workload source key — `"google"`, `"azure"`, or `"alibaba"`.	`'google'`
`episode_start_step`	`int`	Cyclic offset into the source profile.	`0`
`data_dir`	`Optional[str]`	Override for parquet directory.	`None`
`manifest_dir`	`Optional[str]`	Override for manifests directory.	`None`
`strict`	`bool`	Error handling for profile loading.	`False`
`require_real_data`	`bool`	If True, missing parquet data or parquet-engine imports raise instead of falling back to synthetic workload/solar.	`False`
`**kwargs`		Forwarded to :func:`make_dcmicrogrid_params`.	`{}`

Returns:

Type	Description
`DCMicrogridParams`	DCMicrogridParams with `cpu_profile`, `outdoor_temp_profile`
`DCMicrogridParams`	populated and the SolarBundle's `profile` set from the loader.

Diesel generator helpers¶

from powerzoojax.envs import (
    DieselParams,
    compute_dg_power,
    compute_dg_fuel_cost,
    compute_dg_emissions,
)

DieselParams carries p_dg_max_mw, fuel_cost_per_mwh, and emission_factor (kgCO2 / kWh). All three helpers are pure functions.

`powerzoojax.envs.microgrid.dc_microgrid.DieselParams` ¶

Static parameters for a single diesel generator.

Attributes:

Name	Type	Description
`p_dg_max_mw`	`float`	Nameplate capacity [MW].
`fuel_cost_per_mwh`	`float`	Variable fuel cost [$/MWh].
`emission_factor`	`float`	Carbon intensity [kgCO2 / kWh_e].

All fields are pytree_node=False — compile-time constants under JIT.

`powerzoojax.envs.microgrid.dc_microgrid.compute_dg_power(desired_norm, p_dg_max_mw)` ¶

Compute DG active power from normalised setpoint in [0, 1].

`powerzoojax.envs.microgrid.dc_microgrid.compute_dg_fuel_cost(p_dg_mw, dt_h, fuel_cost_per_mwh)` ¶

Fuel cost [$] for one time step.

`powerzoojax.envs.microgrid.dc_microgrid.compute_dg_emissions(p_dg_mw, dt_h, emission_factor)` ¶

CO2 emissions [kgCO2] for one time step.

MW × h = MWh; × 1e3 → kWh_e; × emission_factor[kg/kWh] → kgCO2.

Data center microgrid¶