MicroGridsPy - Mini-Grid Planning Optimization

MicroGridsPy is an open-source Python package for the techno-economic planning of mini-grid energy systems in remote and underserved areas. It is built on Linopy for mathematical optimization and ships with an optional Streamlit graphical interface.

You can use it two ways:

• As a Python library — call the optimization from your own scripts and notebooks (import microgridspy).
• As a guided app — define a project, generate input templates, audit data, solve, and explore results in a Streamlit workspace (microgridspy-gui).

The reference energy system can include:

• Renewable generation
• Battery storage
• Backup generators
• Optional grid connection
• Optional grid export

The app supports both simple and advanced studies, including:

• Typical-year and multi-year formulations
• Single-scenario and multi-scenario analyses
• Continuous and discrete sizing
• Optional carbon-cost internalization
• Renewable land constraints
• Capacity expansion over time

Each project is stored in its own folder with CSV, YAML, and JSON files, so studies remain reproducible, inspectable, and easy to revisit.

Installation

MicroGridsPy targets Python 3.10+. Install it with pip, adding the optional Streamlit GUI and the open-source HiGHS solver:

pip install "microgridspy[gui,highs]"

To work on the code, or before the package is available on PyPI, install from a clone instead:

git clone https://github.com/MicroGridsPy/MicroGridsPy.git
cd MicroGridsPy
pip install -e ".[gui,highs]"

Extras let you install only what you need:

For example, pip install microgridspy gives a lean library with no GUI, while pip install "microgridspy[gui,highs]" installs everything needed to run the app with the open-source solver.

Launch the app

microgridspy-gui

The app looks for a projects/ folder in the current directory (or in the folder set by the MICROGRIDSPY_WORKSPACE environment variable).

Using MicroGridsPy as a Python library

The package exposes a small, stable API:

import microgridspy as mgp

# create a new project and scaffold its input templates
mgp.create_project("my_site", formulation="typical_year", resources=["solar", "wind"])
# ...fill in projects/my_site/inputs (load demand, resource availability, *.yaml)...

mgp.validate_project("my_site")  # pre-flight input check
model = mgp.solve("my_site", solver="highs")  # build + solve
results = model.results()  # analysis-ready pandas tables
print(results.kpis)
mgp.export_results(results)  # write CSV/Excel to the project folder

Key entry points: solve, create_project, validate_project, load_results, export_results, list_projects, set_workspace, and the model classes TypicalYearModel / MultiYearModel. For runnable end-to-end scripts see examples/run_demo_typical_year.py (seconds to solve) and examples/run_demo_multi_year.py (an explicit 10-year horizon; expect ~20 minutes).

What The App Does

MicroGridsPy Planning combines project setup, input-template generation, data audit, optimization, and result interpretation in a single interface.

It is intended to support a complete workflow:

1. Define the structure of the planning problem.
2. Generate the input templates required by that problem.
3. Fill and validate the CSV and YAML inputs.
4. Solve the optimization model.
5. Inspect design, dispatch, cost, and reliability results.

This makes the tool useful both for early-stage feasibility studies and for more detailed long-term planning exercises.

Intended Workflow And User Experience

The application is organized as a sequence of Streamlit pages that progressively define, validate, solve, and interpret a planning problem.

1. Project Setup

The first page defines the global structure of the study:

• Off-grid or on-grid configuration
• Technologies included in the system
• Typical-year or multi-year formulation
• Deterministic or multi-scenario setup
• Economic and policy settings
• Optional modelling features such as carbon cost or discrete sizing

These choices determine the shape of the optimization problem and the set of input templates generated for the user.

2. Input Template Generation

Based on the selected configuration, the application creates structured templates tailored to the project:

• CSV files for time series
• YAML files for techno-economic parameters
• JSON settings for workflow and formulation choices

This helps keep user inputs consistent with the actual model dimensions and enabled technologies.

3. Data Audit And Visualization

Before optimization, the user can inspect and validate the generated inputs through:

• Dataset structure summaries
• Parameter overviews
• Optimization-constraint summaries
• Time-series visualizations
• Grid availability checks for on-grid systems

This step is useful for detecting mistakes before solving.

4. Optimization

The optimization page builds and solves the mathematical model using:

• HiGHS
• Gurobi

The model computes the least-cost system design and dispatch subject to the selected technical, economic, and policy constraints.

5. Results

The results page provides access to:

• Optimal capacities
• Dispatch plots
• Energy-balance views
• Cost breakdowns
• Emissions indicators
• Reliability metrics
• Scenario-dependent outputs

For multi-year studies, the app also supports year-by-year and investment-step interpretation.

Planning Modes

MicroGridsPy Planning supports two complementary formulations.

Typical-Year Planning

The typical-year formulation represents the system with a single representative year.

It is most appropriate when:

• Demand and resource conditions are assumed to be stationary
• Capacity expansion is not required
• A compact, computationally efficient model is preferred

The objective is based on expected equivalent annual cost, combining annualized investment costs and expected operating costs.

Multi-Year Planning

The multi-year formulation represents the system over an explicit planning horizon.

It is most appropriate when:

• Demand evolves over time
• Capacity expansion is relevant
• Degradation, replacement, and investment timing matter
• Long-term trade-offs need to be assessed explicitly

The objective is based on expected net present cost and includes the time value of money, operating costs, and remaining asset value where applicable.

Planning Modes Comparison

The two planning modes serve different purposes. The table below summarizes their main strengths and limitations.

Quick Guidance

• Choose Typical-Year when you need a simpler and faster model for screening alternatives or understanding the basic least-cost structure of the system.
• Choose Multi-Year when investment timing, degradation, grid arrival, evolving demand, or staged expansion materially affect the planning outcome.

Main Modeling Features

Depending on project setup, the application can represent:

• Off-grid and on-grid systems
• Optional grid export
• Renewable, battery, and generator investment
• Generator partial-load efficiency curves
• Scenario-weighted uncertainty
• Land-use limits for renewables
• Lost-load constraints and penalties
• Minimum renewable penetration targets
• Carbon-cost inclusion in the objective
• Continuous sizing or discrete unit-based sizing
• Capacity expansion over multiple investment stages

Input Structure

Each project is stored under its own folder and typically contains:

Core configuration

• formulation.json

Time-series inputs

• load_demand.csv
• resource_availability.csv
• grid_import_price.csv
• grid_export_price.csv
• grid_availability.csv

Technology inputs

• renewables.yaml
• battery.yaml
• generator.yaml
• generator_efficiency_curve.csv
• grid.yaml

The exact set of files depends on whether the project is typical-year or multi-year, off-grid or on-grid, and whether optional features such as export or partial-load modeling are enabled.

Solvers

Supported optimization solvers:

• HiGHS: open-source and recommended as the default option
• Gurobi: commercial solver, useful for harder MILP cases or larger studies

If you select HiGHS in the app, make sure the highspy package is installed (pip install "microgridspy[highs]").

Contacts

For questions, feedback, or collaboration:

• Alessandro Onori - alessandro.onori@polimi.it