Skip to content

Project Management API

The public interface used to create and manage a MicroGridsPy project. A project is a folder containing a formulation.json plus CSV/YAML input templates; these functions create, validate, and manipulate that folder.

The workflow distinguishes clearly between creating a project, validating its inputs, and running the optimization (documented under Optimization).

create_project

microgridspy.create_project(project_name, *, formulation=TYPICAL_YEAR, system_type='off_grid', allow_export=False, resources=('Resource_1',), conversions=None, scenarios=1, horizon_years=None, capacity_expansion=False, investment_steps_years=None, start_year_label=None, battery_label='Battery', generator_label='Generator', fuel_label='Fuel', csv_delimiter=',', csv_decimal='.', settings=None, overwrite=False)

Create a project folder, its formulation.json and input templates.

Parameters:

Name Type Description Default
project_name str

name of the project (sanitized to a filesystem-safe form).

 required
formulation str

"typical_year" or "multi_year".

 TYPICAL_YEAR
system_type str

"off_grid" or "on_grid".

 'off_grid'
allow_export bool

whether grid export is permitted (on-grid only).

 False
resources Sequence[str]

renewable resource labels, e.g. ["solar", "wind"]. Their count sets the number of renewable sources.

 ('Resource_1',)
conversions Sequence[str] | None

conversion-technology labels; defaults to ["Technology_1", ...] matching resources.

 None
scenarios int | Sequence[str]

number of stochastic scenarios, or an explicit list of labels. A single scenario disables the multi-scenario machinery.

 1
horizon_years int | None

planning horizon (multi-year formulation only).

 None
capacity_expansion bool

enable staged capacity expansion (multi-year only).

 False
investment_steps_years Sequence[int] | None

step durations, e.g. [5, 5, 5, 5].

 None
start_year_label str | None

header for the first year; defaults to "typical_year" for the typical-year formulation, "2026" for multi-year.

 None
battery_label str

battery component display name.

 'Battery'
generator_label str

generator component display name.

 'Generator'
fuel_label str

fuel display name.

 'Fuel'
csv_delimiter str

CSV field delimiter written into the templates.

 ','
csv_decimal str

CSV decimal separator written into the templates.

 '.'
settings TemplateSettings | None

a fully-built TemplateSettings for complete control; when given, the individual template arguments above are ignored.

 None
overwrite bool

overwrite existing input templates if the project exists.

 False

Returns:

Name Type Description
ProjectPaths ProjectPaths

the resolved paths of the created project.

Raises:

Type Description
FileExistsError

if the project already exists and overwrite is False.

validate_project

microgridspy.validate_project(project_name)

Pre-flight check that a project has the inputs needed to solve.

Verifies the project exists, its formulation.json is present and valid JSON, and the required input files are on disk - so problems surface before a long solve rather than midway through model building.

Parameters:

Name Type Description Default
project_name str

the project to check.

 required

Returns:

Name Type Description
ProjectPaths ProjectPaths

the project's paths, if valid.

Raises:

Type Description
InputValidationError

with a message describing the first problem found.

copy_project

microgridspy.copy_project(source, dest, *, overwrite=False)

Copy a project to a new name within the same workspace.

Parameters:

Name Type Description Default
source str

the existing project to copy from.

 required
dest str

the new project name.

 required
overwrite bool

replace dest if it already exists.

 False

Returns:

Name Type Description
ProjectPaths ProjectPaths

the paths of the new project.

Raises:

Type Description
FileNotFoundError

if source does not exist.
FileExistsError

if dest exists and overwrite is False.

rename_project

microgridspy.rename_project(source, dest, *, overwrite=False)

Rename a project (copy to the new name, then delete the old one).

Parameters:

Name Type Description Default
source str

the existing project name.

 required
dest str

the new project name.

 required
overwrite bool

replace dest if it already exists.

 False

Returns:

Name Type Description
ProjectPaths ProjectPaths

the paths of the renamed project.

delete_project

microgridspy.delete_project(project_name, *, missing_ok=False)

Delete a project folder and everything in it.

Parameters:

Name Type Description Default
project_name str

the project to delete.

 required
missing_ok bool

if True, return quietly when the project does not exist; otherwise raise FileNotFoundError.

 False

Raises:

Type Description
FileNotFoundError

if the project does not exist and missing_ok is False.

TemplateSettings

For full control over the generated input templates, build a TemplateSettings object and pass it to create_project(..., settings=...).

microgridspy.TemplateSettings dataclass

Full specification of the input templates written for a project.

An immutable bundle of every choice that shapes the generated formulation.json and the CSV/YAML input templates: the formulation and system type, scenario and year/investment-step structure, renewable/battery/generator/fuel labels and modelling options (battery loss and degradation models, generator efficiency model), and the CSV delimiter/decimal format.

Most users never build this directly — microgridspy.create_project() derives a sensible instance from its keyword arguments. Construct one explicitly and pass it as create_project(..., settings=...) only when you need full control over the generated templates.

Example projects

Two ready-to-run example projects are bundled with the package, so a project can be solved end-to-end immediately after pip install (no repository clone). See solve_example for the one-call quick start.

list_examples

microgridspy.list_examples()

Return the names of the example projects bundled with the package.

Returns:

Type Description
list[str]

Sorted list of example names usable with load_example().

load_example

microgridspy.load_example(name='demo_typical_year', dest=None, *, overwrite=False)

Copy a bundled example project into the active workspace.

The example's input files are copied into <workspace>/projects/<dest>/inputs so the project can then be solved like any other, e.g. with microgridspy.solve().

Parameters:

Name Type Description Default
name str

the example to load (see list_examples()).

 'demo_typical_year'
dest str | None

destination project name; defaults to name.

 None
overwrite bool

replace the destination project if it already exists.

 False

Returns:

Type Description
str

The destination project name.

Raises:

Type Description
ValueError

if name is not a bundled example.
FileExistsError

if the destination exists and overwrite is False.