API Reference¶

The API Reference is generated automatically from the MicroGridsPy Python package using mkdocstrings. It reads the package statically from src/ via Griffe, so signatures, parameters and return values stay synchronized with the source:

Python source + docstrings
          ↓
      mkdocstrings (Griffe)
          ↓
      API Reference

When signatures or behavior change, update the Python docstrings and rebuild the documentation — details should not be duplicated by hand in Markdown.

Import convention¶

import microgridspy as mgp

Everything documented here is re-exported at the top level of the microgridspy package.

API organization¶

The reference is split into logical groups:

Page	Public objects
Project Management	`create_project`, `validate_project`, `copy_project`, `rename_project`, `delete_project`, `TemplateSettings`
Models	`TypicalYearModel`, `MultiYearModel`, `InputValidationError`
Optimization	`solve`, `load_inputs`
Results	`load_results`, `export_results`, `TypicalYearResults`, `MultiYearResults`, input time-series helpers

Stability¶

TypicalYearModel, MultiYearModel and InputValidationError form the stable core. The results dataclasses (TypicalYearResults, MultiYearResults) are provisional — their tables may grow — until the 1.0 release.

Workspace helpers¶

Projects live in a workspace directory. These helpers manage it:

`microgridspy.set_workspace(path)` ¶

Set the workspace directory that contains the projects/ folder.

The choice is stored in the MICROGRIDSPY_WORKSPACE environment variable, so it applies to every subsequent path resolution in this process. This is the explicit alternative to relying on the current working directory.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	the workspace directory (its `projects/` sub-folder holds the individual projects). `~` is expanded and the path is resolved.	required

Returns:

Name	Type	Description
`Path`	`Path`	the resolved workspace directory.

`microgridspy.list_projects(base_dir=None)` ¶

List the project names available in the current workspace.

Parameters:

Name	Type	Description	Default
`base_dir`	`Path \| None`	optional explicit workspace; defaults to the resolution used by `get_projects_root()` (`MICROGRIDSPY_WORKSPACE` or cwd).	`None`

Returns:

Type	Description
`list[str]`	list[str]: sorted names of the sub-directories under `projects/`,
`list[str]`	or an empty list if that root does not exist yet.

`microgridspy.project_paths(project_name, base_dir=None)` ¶

Get the paths for a given project.

`microgridspy.project_exists(project_name, base_dir=None)` ¶

Ensure that a project with the given name exists.

Cross-links with methodology¶

The API Reference and the Methodology complement each other: the Methodology explains what is modelled mathematically, while the API Reference explains how the Python package exposes it. For example, the battery formulation corresponds to the battery inputs and results surfaced through the model classes.