Skip to content

Data Reference

The Data Reference documents the information required to define a MicroGridsPy case study. Every project is a folder of plain files — CSV, YAML, and JSON — so studies stay reproducible, inspectable, and easy to revisit.

create_project(...) generates these files as templates; you then populate them with case-study data and run validate_project(...) before solving. Which files are required depends on the formulation and on flags in formulation.json (e.g. on_grid, allow_export).

Two kinds of data documentation

This page is the user-facing reference — what files and data do I need to run MicroGridsPy? For the developer-facing description of the canonical internal xarray dataset passed between the loading and formulation layers, see the Internal Data Contract.

Legend for the Required column: yes = always required · conditional = required when the listed condition holds · derived = generated by the backend, not edited by hand · no = reference only.

Input files

File Format Required Condition Edited by user Purpose
formulation.json JSON yes always no formulation mode, scenarios, grid flags, global constraints
load_demand.csv CSV yes always yes hourly electrical demand → load balance and unmet-load
resource_availability.csv CSV yes always yes hourly renewable availability by resource
renewables.yaml YAML yes always yes renewable sizing, annuity, land and subsidy parameters
battery.yaml YAML yes always yes storage sizing and operation
generator.yaml YAML yes always yes backup generation, fuel cost and fuel emissions
grid.yaml YAML conditional on_grid=true yes grid limits, emissions, renewable share, outage simulation
grid_import_price.csv CSV conditional on_grid=true yes hourly import tariff → grid import cost
grid_export_price.csv CSV conditional on_grid=true and allow_export=true yes hourly export tariff → export revenue
grid_availability.csv CSV derived on_grid=true no hourly availability after outage simulation
battery_efficiency_curve.csv CSV conditional loss_model = convex_loss_epigraph yes advanced convex battery loss formulation
ambient_temperature.csv CSV conditional degradation_model.cycle_fade_enabled=true yes hourly ambient temperature → semi-empirical \(\alpha(T)\)/\(\beta(T)\) degradation
generator_efficiency_curve.csv CSV conditional efficiency_model = efficiency_curve yes partial-load generator efficiency curve
README_inputs.md Markdown no always no human-readable summary of generated inputs

In addition to the typical-year files (with an extra year axis), the multi-year formulation carries cohort/investment-step dimensions and, when degradation is enabled, an ambient-temperature series driving the semi-empirical \(\alpha(T)\)/\(\beta(T)\) coefficients.

File Format Required Condition Dimensional meaning
formulation.json JSON yes always project-level scalars and lists (horizon, scenarios, steps)
load_demand.csv CSV yes always period × scenario × year
resource_availability.csv CSV yes always period × scenario × year × resource
renewables.yaml YAML yes always resource + investment step
battery.yaml YAML yes always investment step + shared battery technical data
generator.yaml YAML yes always investment step + yearly/scenario fuel prices
grid.yaml YAML conditional on_grid=true scenario-level parameters + connection timing
grid_import_price.csv CSV conditional on_grid=true period × scenario × year
grid_export_price.csv CSV conditional on_grid=true and allow_export=true period × scenario × year
grid_availability.csv CSV derived on_grid=true period × scenario × year
battery_efficiency_curve.csv CSV conditional loss_model = convex_loss_epigraph curve points
ambient_temperature.csv CSV conditional degradation_model.cycle_fade_enabled=true period × scenario × year
generator_efficiency_curve.csv CSV conditional efficiency_model = efficiency_curve curve points
README_inputs.md Markdown no always reference only

Time-series file contract

Time-series CSVs use a small header block to label value axes, followed by 8760 hourly rows (one representative year). The meta/hour column must run from 0 to 8759.

File Header rows Meta column Value axes Units Length Required when
load_demand.csv 2 meta/hour scenario × typical_year kWh/hour 8760 always
resource_availability.csv 3 meta/hour scenario × typical_year × resource capacity factor [–] 8760 always
grid_import_price.csv 2 meta/hour scenario × typical_year currency/kWh 8760 on_grid=true
grid_export_price.csv 2 meta/hour scenario × typical_year currency/kWh 8760 on_grid=true and export enabled
grid_availability.csv 2 meta/hour scenario × typical_year 0/1 8760 derived
ambient_temperature.csv 2 meta/hour scenario × typical_year °C 8760 battery cycle-fade degradation
generator_efficiency_curve.csv 1 – Relative Power Output [-], Efficiency [-] dimensionless variable generator curve mode
battery_efficiency_curve.csv 1 – relative_power_pu, charge_efficiency, discharge_efficiency dimensionless variable battery convex-loss mode

Notes: scenario headers must match formulation.json; resource labels must match the resource fields in renewables.yaml; the last relative-power point of a generator curve must be 1.0; battery full-load multipliers should be 1.0.

File Header rows Meta column Value axes Units Length Required when
load_demand.csv 2 meta/hour scenario × year kWh/hour 8760 always
resource_availability.csv 3 ('meta','hour','') scenario × year × resource capacity factor [–] 8760 always
grid_import_price.csv 2 meta/hour scenario × year currency/kWh 8760 on_grid=true
grid_export_price.csv 2 meta/hour scenario × year currency/kWh 8760 on_grid=true and export enabled
grid_availability.csv 2 meta/hour scenario × year 0/1 8760 derived
ambient_temperature.csv 2 meta/hour scenario × year °C 8760 battery cycle-fade degradation
generator_efficiency_curve.csv 1 – Relative Power Output [-], Efficiency [-] dimensionless variable generator curve mode
battery_efficiency_curve.csv 1 – relative_power_pu, charge_efficiency, discharge_efficiency dimensionless variable battery convex-loss mode

Notes: all scenario–year combinations must exist; resource_availability values are expected near [0,1]; relative_power_pu must be strictly increasing on (0,1] and end at 1.0.

Machine-readable tables

The tables above are maintained as CSV files under docs/tables/: typical_year_input_reference.csv, typical_year_timeseries_reference.csv, multi_year_input_reference.csv, and multi_year_timeseries_reference.csv. They can be consumed programmatically while this page presents the same information for humans.