Skip to content

Typical-Year Tutorial

This tutorial runs a complete typical-year study from project creation to results, using the open-source HiGHS solver. It assumes MicroGridsPy is installed with the highs extra — see Installation.

1. Create the project

import microgridspy as mgp

paths = mgp.create_project(
    "tutorial_typical",
    formulation="typical_year",
    system_type="off_grid",
    resources=["solar"],  # one renewable source labelled "solar"
    scenarios=1,  # deterministic (single scenario)
)
print(paths)  # where the input templates were written

This writes formulation.json and input templates into the project folder. The renewable source count follows the length of resources.

2. Populate the inputs

Edit the generated files with your case-study data (see the Data Reference for formats and units):

  • load_demand.csv — 8760 hourly demand values (kWh/hour).
  • resource_availability.csv — hourly capacity factor for solar (values in [0,1]).
  • renewables.yaml — PV CAPEX, FOM, lifetime, WACC, efficiency, unit size.
  • battery.yaml — energy CAPEX, efficiencies, DoD, charge/discharge times, lifetime.
  • generator.yaml — diesel capacity, nominal efficiency, fuel LHV, fuel cost, emissions.

You can inspect an input series before solving:

fig_hourly, fig_daily = mgp.plot_input_timeseries("tutorial_typical", "load_demand")

3. Validate

mgp.validate_project("tutorial_typical")  # raises InputValidationError if incomplete

4. Solve

model = mgp.solve("tutorial_typical", solver="highs")

5. Inspect capacity and cost results

results = model.results()

print(results.kpis)  # LCOE, renewable share, total cost, ...
print(results.design_summary)  # installed capacity by technology
print(results.dispatch.head())  # hourly dispatch time series

6. Export

mgp.export_results(results)  # CSV/Excel into the project's results/ folder

What the model solved

Under the hood, the typical-year formulation minimized the expected equivalent annual cost (EAC) — annualized investment cost plus expected annual operating cost — subject to the hourly energy balance, the renewable production limit, and the battery and generator constraints. Because there is a single representative year, intertemporal discounting does not affect the sizing decision.

Next steps

  • Add a second scenario (scenarios=2) to make it stochastic.
  • Enable a weak-grid connection with system_type="on_grid".
  • Move to the Multi-Year Tutorial for phased capacity expansion.