Skip to content

Results API

How optimization outputs are loaded, exported, and inspected. The structured results objects hold analysis-ready pandas DataFrames (capacity, costs, dispatch, KPIs). For guidance on interpreting these outputs, see the User Guide Results page.

load_results

microgridspy.load_results(project_name, *, formulation=None)

Load a previously saved run's results from the project's results/ folder.

Parameters:

Name Type Description Default
project_name str

the project to read.

 required
formulation str | None

"typical_year" or "multi_year"; auto-detected from formulation.json when None.

 None

Returns:

Type Description
AnyResults | None

The structured results object, or None if no saved run exists.

export_results

microgridspy.export_results(results, out_dir=None)

Write a results object to CSV/Excel files.

Parameters:

Name Type Description Default
results AnyResults

a TypicalYearResults or MultiYearResults.

 required
out_dir Path | None

destination directory; when None, writes to the project's results/ folder.

 None

Returns:

Type Description
dict[str, str]

Mapping of output name to the written file path.

TypicalYearResults

The structured results object returned by the typical-year formulation (TypicalYearModel.results()).

microgridspy.TypicalYearResults dataclass

Structured, analysis-ready results of a solved typical-year model.

Returned by TypicalYearModel.results() (and microgridspy.load_results()). Its fields are pandas DataFrames covering the main result families — headline kpis, design_summary (installed capacity), dispatch and energy_balance time series, the cost breakdown (upfront, annuities, expected_fixed_om, expected_cost_components), emissions, and per-technology / inverter design tables — plus the underlying solved data (an xarray.Dataset) and run metadata. Write them to disk with microgridspy.export_results() or to_excel.

Stability: provisional until the 1.0 release (the set of tables may grow).

MultiYearResults

The structured results object returned by the multi-year formulation.

microgridspy.MultiYearResults dataclass

Structured, analysis-ready results of a solved multi-year model.

Returned by MultiYearModel.results() (and microgridspy.load_results()). Analogous to TypicalYearResults, but with quantities resolved over the planning horizon: pandas DataFrames for headline KPIs, per-year installed capacity, staged design by investment step, dispatch and energy balances, discounted cash flows and cost components, and emissions — plus the underlying solved data/sets (xarray.Dataset). Write them to disk with microgridspy.export_results().

Stability: provisional until the 1.0 release (the set of tables may grow).

Input time-series inspection

Helpers to list and plot a project's input time series without solving.

microgridspy.list_input_timeseries(project_name, *, formulation=None)

List the time-series input variables available to plot for a project.

microgridspy.plot_input_timeseries(project_name, variable=None, *, formulation=None, scenario=None, year=None, **selectors)

Plot an input time series as (hourly, daily) matplotlib figures.

Parameters:

Name Type Description Default
project_name str

the project to read.

 required
variable str | None

the time-series variable to plot; defaults to the first available (see list_input_timeseries()).

 None
formulation str | None

auto-detected when None.

 None
scenario str | None

optional scenario selector when the variable has that dimension.

 None
year str | int | None

optional year selector when the variable has that dimension.

 None
**selectors Any

further dimension selectors (e.g. resource="solar").

 {}

Returns:

Type Description
Figure

tuple[matplotlib.figure.Figure, matplotlib.figure.Figure]: hourly and
Figure

average-daily figures.