microgridspy 0.4.0__py3-none-any.whl

microgridspy/__init__.py

@@ -0,0 +1,102 @@
+"""MicroGridsPy: bottom-up optimization tool for planning mini-grids.
+
+Public API:
+
+```python
+import microgridspy as mgp
+
+# one-liner: solve and get analysis-ready tables
+results = mgp.solve("demo_typical_year", solver="highs").results()
+results.kpis                      # pandas DataFrame
+mgp.export_results(results)       # write CSV/Excel to the project folder
+
+# or drive the models directly
+from microgridspy import TypicalYearModel
+model = TypicalYearModel("demo_typical_year")
+model.solve_single_objective(solver="highs")
+summary = model.results_summary()
+```
+
+The two formulations are named ``typical_year`` and ``multi_year`` everywhere —
+in ``formulation.json``, in ``create_project(formulation=...)`` and in the model
+class names.
+
+The Streamlit GUI lives in `microgridspy.app` and is installed only with
+the ``[gui]`` extra; importing this package never imports Streamlit.
+
+Stability: ``TypicalYearModel``, ``MultiYearModel`` and ``InputValidationError``
+are the stable core. The results dataclasses are provisional (their tables may
+grow) until the 1.0 release.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+# --- Convenience API --------------------------------------------------------
+from microgridspy.api import (
+    export_results,
+    list_input_timeseries,
+    load_inputs,
+    load_results,
+    plot_input_timeseries,
+    solve,
+    solve_example,
+)
+
+# --- Workspace helpers ------------------------------------------------------
+from microgridspy.errors import InputValidationError
+from microgridspy.export.multi_year_results import MultiYearResults
+
+# --- Structured results (provisional) ---------------------------------------
+from microgridspy.export.typical_year_results import TypicalYearResults
+from microgridspy.io.examples import list_examples, load_example
+
+# --- Project scaffolding & management ---------------------------------------
+from microgridspy.io.project_setup import (
+    copy_project,
+    create_project,
+    delete_project,
+    rename_project,
+    validate_project,
+)
+from microgridspy.io.templates import TemplateSettings
+from microgridspy.io.utils import list_projects, project_exists, project_paths, set_workspace
+from microgridspy.multi_year_model.model import MultiYearModel
+
+# --- Models (stable core) ---------------------------------------------------
+from microgridspy.typical_year_model.model import TypicalYearModel
+
+__all__ = [
+    "TypicalYearModel",
+    "MultiYearModel",
+    "solve",
+    "solve_example",
+    "list_examples",
+    "load_example",
+    "load_results",
+    "export_results",
+    "load_inputs",
+    "list_input_timeseries",
+    "plot_input_timeseries",
+    "create_project",
+    "validate_project",
+    "delete_project",
+    "copy_project",
+    "rename_project",
+    "TemplateSettings",
+    "TypicalYearResults",
+    "MultiYearResults",
+    "set_workspace",
+    "list_projects",
+    "project_paths",
+    "project_exists",
+    "InputValidationError",
+    "__version__",
+]
+
+try:
+    __version__ = _version("microgridspy")
+except PackageNotFoundError:  # not installed (e.g. running from a source checkout)
+    __version__ = "0.0.0+unknown"

microgridspy/api.py

@@ -0,0 +1,248 @@
+"""High-level convenience API for MicroGridsPy.
+
+These are thin wrappers over the model, export, and IO layers that give library
+users a short path from a project name to solved, analysis-ready results:
+
+```python
+import microgridspy as mgp
+
+results = mgp.solve("demo_typical_year", solver="highs").results()
+results.kpis                      # pandas DataFrame
+mgp.export_results(results)       # write CSV/Excel to the project folder
+```
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import xarray as xr
+
+from microgridspy.errors import InputValidationError
+from microgridspy.export.multi_year_results import MultiYearResults
+from microgridspy.export.typical_year_results import TypicalYearResults
+from microgridspy.io.formulation import MULTI_YEAR, TYPICAL_YEAR, VALID_FORMULATIONS
+from microgridspy.multi_year_model.model import MultiYearModel
+from microgridspy.typical_year_model.model import TypicalYearModel
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+AnyModel = TypicalYearModel | MultiYearModel
+AnyResults = TypicalYearResults | MultiYearResults
+
+
+def _detect_formulation(project_name: str) -> str:
+    """Read ``core_formulation`` from a project's ``formulation.json``."""
+    from microgridspy.io.utils import project_paths
+
+    fpath = project_paths(project_name).formulation_json
+    if not fpath.exists():
+        raise InputValidationError(
+            f"Cannot detect formulation: {fpath} not found. "
+            f"Pass formulation='{TYPICAL_YEAR}' or '{MULTI_YEAR}' explicitly."
+        )
+    try:
+        raw = json.loads(fpath.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise InputValidationError(f"Cannot parse {fpath}: {exc}") from exc
+    return str(raw.get("core_formulation", TYPICAL_YEAR))
+
+
+def _model_for(project_name: str, formulation: str) -> AnyModel:
+    if formulation == TYPICAL_YEAR:
+        return TypicalYearModel(project_name)
+    if formulation == MULTI_YEAR:
+        return MultiYearModel(project_name)
+    raise InputValidationError(
+        f"Unknown formulation {formulation!r}. Expected one of {', '.join(VALID_FORMULATIONS)}."
+    )
+
+
+def solve(
+    project_name: str,
+    *,
+    formulation: str | None = None,
+    solver: str = "highs",
+    **solver_kwargs: Any,
+) -> AnyModel:
+    """Build and solve a project, returning the solved model.
+
+    Args:
+        project_name: the project folder in the active workspace.
+        formulation: ``"typical_year"`` or ``"multi_year"``; if ``None`` it is read
+            from the project's ``formulation.json``.
+        solver: ``"highs"`` (open source) or ``"gurobi"`` (licensed).
+        **solver_kwargs: forwarded to
+            `TypicalYearModel.solve_single_objective()` (e.g. ``solver_params``,
+            ``problem_fn``, ``log_file_path``).
+
+    Returns:
+        The solved model instance, ready for `results()` /
+        `results_summary()`.
+    """
+    if formulation is None:
+        formulation = _detect_formulation(project_name)
+    model = _model_for(project_name, formulation)
+    model.solve_single_objective(solver=solver, **solver_kwargs)
+    return model
+
+
+def solve_example(
+    name: str = "demo_typical_year",
+    *,
+    solver: str = "highs",
+    dest: str | None = None,
+    overwrite: bool = True,
+    **solver_kwargs: Any,
+) -> AnyModel:
+    """Load a bundled example project and solve it, end-to-end.
+
+    A one-call quick start that works straight after ``pip install`` (no repository
+    clone needed): it copies the example into the active workspace and solves it.
+
+    Args:
+        name: the bundled example to run (see
+            `microgridspy.list_examples()`); ``"demo_typical_year"`` or
+            ``"demo_multi_year"``.
+        solver: ``"highs"`` (open source) or ``"gurobi"`` (licensed).
+        dest: destination project name; defaults to ``name``.
+        overwrite: replace the destination project if it already exists (default
+            True, so the example is re-runnable).
+        **solver_kwargs: forwarded to the model's ``solve_single_objective``.
+
+    Returns:
+        The solved model instance, ready for `results()` / `results_summary()`.
+    """
+    from microgridspy.io.examples import load_example
+
+    project = load_example(name, dest=dest, overwrite=overwrite)
+    return solve(project, solver=solver, **solver_kwargs)
+
+
+def load_results(
+    project_name: str,
+    *,
+    formulation: str | None = None,
+) -> AnyResults | None:
+    """Load a previously saved run's results from the project's ``results/`` folder.
+
+    Args:
+        project_name: the project to read.
+        formulation: ``"typical_year"`` or ``"multi_year"``; auto-detected from
+            ``formulation.json`` when ``None``.
+
+    Returns:
+        The structured results object, or ``None`` if no saved run exists.
+    """
+    from microgridspy.export.results_page_helpers import (
+        load_multi_year_results_from_files,
+        load_typical_year_results_from_files,
+    )
+
+    if formulation is None:
+        formulation = _detect_formulation(project_name)
+    if formulation == MULTI_YEAR:
+        return load_multi_year_results_from_files(project_name)
+    return load_typical_year_results_from_files(project_name)
+
+
+def export_results(results: AnyResults, out_dir: Path | None = None) -> dict[str, str]:
+    """Write a results object to CSV/Excel files.
+
+    Args:
+        results: a `TypicalYearResults` or `MultiYearResults`.
+        out_dir: destination directory; when ``None``, writes to the project's
+            ``results/`` folder.
+
+    Returns:
+        Mapping of output name to the written file path.
+    """
+    if isinstance(results, MultiYearResults):
+        from microgridspy.export.multi_year_results import export_multi_year_results_package
+
+        return export_multi_year_results_package(results=results, out_dir=out_dir)
+    if isinstance(results, TypicalYearResults):
+        from microgridspy.export.typical_year_results import export_typical_year_results_package
+
+        return export_typical_year_results_package(results=results, out_dir=out_dir)
+    raise TypeError(
+        f"export_results expects TypicalYearResults or MultiYearResults, got {type(results).__name__}"
+    )
+
+
+def load_inputs(project_name: str, *, formulation: str | None = None) -> xr.Dataset:
+    """Assemble and return a project's input dataset, without solving.
+
+    Builds the sets and data layers (the same inputs a model would use), so you
+    can inspect the assembled xarray Dataset directly.
+
+    Args:
+        project_name: the project to read.
+        formulation: ``"typical_year"`` or ``"multi_year"``; auto-detected when None.
+
+    Returns:
+        xr.Dataset: the assembled input dataset.
+    """
+    if formulation is None:
+        formulation = _detect_formulation(project_name)
+    model = _model_for(project_name, formulation)
+    model._initialize_data()  # builds sets + data, no optimization model
+    return model.data
+
+
+def list_input_timeseries(project_name: str, *, formulation: str | None = None) -> list[str]:
+    """List the time-series input variables available to plot for a project."""
+    from microgridspy.visualization.input_plots import list_timeseries_options
+
+    ds = load_inputs(project_name, formulation=formulation)
+    return [opt.variable for opt in list_timeseries_options(ds)]
+
+
+def plot_input_timeseries(
+    project_name: str,
+    variable: str | None = None,
+    *,
+    formulation: str | None = None,
+    scenario: str | None = None,
+    year: str | int | None = None,
+    **selectors: Any,
+) -> tuple[Figure, Figure]:
+    """Plot an input time series as ``(hourly, daily)`` matplotlib figures.
+
+    Args:
+        project_name: the project to read.
+        variable: the time-series variable to plot; defaults to the first
+            available (see `list_input_timeseries()`).
+        formulation: auto-detected when None.
+        scenario: optional scenario selector when the variable has that dimension.
+        year: optional year selector when the variable has that dimension.
+        **selectors: further dimension selectors (e.g. ``resource="solar"``).
+
+    Returns:
+        tuple[matplotlib.figure.Figure, matplotlib.figure.Figure]: hourly and
+        average-daily figures.
+    """
+    from microgridspy.visualization.input_plots import (
+        build_timeseries_figures,
+        list_timeseries_options,
+        slice_timeseries,
+    )
+
+    ds = load_inputs(project_name, formulation=formulation)
+    names = [opt.variable for opt in list_timeseries_options(ds)]
+    if not names:
+        raise InputValidationError(f"No plottable time-series inputs found for '{project_name}'.")
+    if variable is None:
+        variable = names[0]
+    elif variable not in names:
+        raise InputValidationError(
+            f"'{variable}' is not a plottable time series for '{project_name}'. Available: {names}"
+        )
+    da = slice_timeseries(
+        ds, variable=variable, scenario=scenario, year=year, selectors=selectors or None
+    )
+    label = variable.replace("_", " ")
+    return build_timeseries_figures(da, title_prefix=label, y_label=label)

microgridspy/app/Home.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import streamlit as st
+
+st.set_page_config(
+    page_title="MicroGridsPy - Planning",
+    layout="wide",
+)
+
+
+ASSETS_DIR = Path(__file__).resolve().parent / "assets"
+REPOSITORY_URL = "https://github.com/AleOnori98/microgridspy-planning"
+RAMP_URL = "https://github.com/AleOnori98/RAMP-Streamlit"
+PVGIS_URL = "https://github.com/AleOnori98/PVGIS-Streamlit-App"
+LV_TOPOLOGY_URL = "https://github.com/AleOnori98/LV-Distribution-Topology-Streamlit"
+# Official documentation site (Read the Docs).
+DOCS_URL = "https://microgridspy-package-docs.readthedocs.io/en/latest/"
+
+ECOSYSTEM_TOOL_ROWS = (
+    (
+        {
+            "title": "RAMP Demand Model",
+            "description": "Bottom-up stochastic demand assessment for appliances, households, and community load evolution.",
+            "image_name": "ramp_tool_card.png",
+            "badge": "Upstream input layer",
+            "repo_url": RAMP_URL,
+        },
+        {
+            "title": "PVGIS Resource Assessment",
+            "description": "Solar and wind resource estimation used to build planning-ready renewable input profiles.",
+            "image_name": "pvgis_tool_card.png",
+            "badge": "Upstream input layer",
+            "repo_url": PVGIS_URL,
+        },
+    ),
+    (
+        {
+            "title": "LV Distribution Topology Tool",
+            "description": "Distribution network layout, pole placement, and topology design for the physical electrification layer.",
+            "image_name": "distribution_tool_card.jpeg",
+            "badge": "Network design layer",
+            "repo_url": LV_TOPOLOGY_URL,
+        },
+        {
+            "title": "Dispatch Simulation Module",
+            "description": "Detailed operational analysis starting from a predefined system design, useful for operational realism and control studies.",
+            "image_name": "simulation_tool_card.png",
+            "badge": "Operational analysis layer",
+        },
+    ),
+)
+
+APP_PAGE_LINKS = (
+    ("pages/0_Project_Setup.py", "1. Project Setup"),
+    ("pages/1_Data_Audit_and_Visualization.py", "2. Data Audit and Visualization"),
+    ("pages/2_Optimization.py", "3. Optimization"),
+    ("pages/3_Results.py", "4. Results"),
+)
+
+REPOSITORY_REFERENCES = (
+    "`README.md`: overall project scope and workflow",
+    "`docs/data-reference/data-contract.md`: canonical dataset contract",
+    "`projects/`: your project folders and input templates (created here at runtime)",
+)
+
+USEFUL_LINKS = (("Official documentation", DOCS_URL),)
+
+
+def _asset(name: str) -> str:
+    return str(ASSETS_DIR / name)
+
+
+def _inject_css() -> None:
+    st.markdown(
+        """
+        <style>
+        :root {
+            --mgpy-ink: #153243;
+            --mgpy-muted: #5b6b73;
+            --mgpy-accent: #1f7a8c;
+            --mgpy-gold: #f4b942;
+            --mgpy-surface: #f7fbfc;
+            --mgpy-border: rgba(21, 50, 67, 0.10);
+        }
+        .featured-card {
+            display: block;
+            height: 0.01rem;
+            margin: 0;
+            padding: 0;
+            opacity: 0;
+        }
+        div[data-testid="stVerticalBlockBorderWrapper"]:has(.featured-card) {
+            border: 2px solid rgba(47, 128, 237, 0.95) !important;
+            box-shadow: 0 8px 24px rgba(47, 128, 237, 0.10);
+            background: linear-gradient(180deg, #ffffff 0%, #f7fbff 100%);
+        }
+        .featured-kicker {
+            display: inline-block;
+            padding: 0.25rem 0.6rem;
+            border-radius: 999px;
+            background: rgba(47, 128, 237, 0.12);
+            color: #2f80ed;
+            font-size: 0.82rem;
+            font-weight: 700;
+            letter-spacing: 0.04em;
+            margin-bottom: 0.4rem;
+        }
+        div[data-testid="stButton"]:has(button[kind="primary"]) button {
+            background: linear-gradient(135deg, #2f80ed 0%, #1f7a8c 100%);
+            border: 1px solid #2f80ed;
+            color: white;
+            font-weight: 700;
+        }
+        </style>
+        """,
+        unsafe_allow_html=True,
+    )
+
+
+def _render_featured_planning_card() -> None:
+    with st.container(border=True):
+        st.markdown('<div class="featured-card"></div>', unsafe_allow_html=True)
+        col_image, col_body = st.columns([1.15, 1.45], gap="large")
+        with col_image:
+            st.image(_asset("planning_tool_card.png"), width="stretch")
+        with col_body:
+            st.markdown(
+                '<div class="featured-kicker">Core planning engine</div>', unsafe_allow_html=True
+            )
+            st.markdown("### MicroGridsPy Planning")
+            st.write(
+                "Techno-economic optimization of mini-grid systems under deterministic or stochastic assumptions. "
+                "Use it to size renewables, batteries, generators, and grid interaction with either a representative typical year "
+                "or a multi-year dynamic formulation with capacity expansion."
+            )
+            st.markdown(f"[GitHub repository]({REPOSITORY_URL})")
+            if st.button("Open Project Setup", type="primary", key="open_project_setup"):
+                st.switch_page("pages/0_Project_Setup.py")
+
+
+def _tool_card(
+    *,
+    title: str,
+    description: str,
+    image_name: str,
+    badge: str,
+    repo_url: str | None = None,
+) -> None:
+    with st.container(border=True):
+        st.image(_asset(image_name), width="stretch")
+        st.caption(badge)
+        st.markdown(f"**{title}**")
+        st.write(description)
+        if repo_url:
+            st.markdown(f"[GitHub repository]({repo_url})")
+
+
+def _render_markdown_bullets(title: str, items: tuple[str, ...]) -> None:
+    bullet_lines = "\n".join(f"- {item}" for item in items)
+    st.markdown(f"**{title}**\n\n{bullet_lines}")
+
+
+def _render_ecosystem() -> None:
+    st.title("Welcome to MicroGridsPy!")
+    st.markdown(
+        "**MicroGridsPy Planning** is the techno-economic optimization layer of the MicroGridsPy ecosystem."
+    )
+    st.markdown(
+        "It supports off-grid and weak-grid mini-grid design, combining renewable generation, batteries, generators, "
+        "optional grid interaction, stochastic scenarios, and both typical-year and multi-year capacity-expansion formulations. "
+        "The broader ecosystem connects resource assessment, demand modelling, distribution design, planning, and detailed operational analysis into one coherent workflow."
+    )
+
+    _render_featured_planning_card()
+    st.subheader("Ecosystem tools")
+    for tool_row in ECOSYSTEM_TOOL_ROWS:
+        columns = st.columns(len(tool_row), gap="large")
+        for column, tool in zip(columns, tool_row):
+            with column:
+                _tool_card(**tool)
+
+
+def _render_resources() -> None:
+    st.subheader("Resources and Navigation")
+    st.write(
+        "Use this application as the planning workspace inside the broader ecosystem. "
+        "The links below help you start a new project and locate the main reference material already available in this repository."
+    )
+    st.write("")
+
+    c1, c2 = st.columns([1, 3.0], gap="large")
+    with c1:
+        st.markdown("**Start here in this app**")
+        for page_path, label in APP_PAGE_LINKS:
+            st.page_link(page_path, label=label)
+
+    with c2:
+        _render_markdown_bullets("Repository references", REPOSITORY_REFERENCES)
+
+    st.write("")
+    st.markdown("**At a glance**")
+    info_cols = st.columns(3, gap="medium")
+    with info_cols[0]:
+        st.info(
+            "Planning modes: Typical-year for compact investment studies, multi-year for dynamic expansion and long-horizon planning."
+        )
+    with info_cols[1]:
+        st.info(
+            "Backend: Python + Streamlit frontend, Linopy optimization backend, CSV/YAML/JSON project workflow."
+        )
+    with info_cols[2]:
+        st.info(
+            "Use together: Resource, demand, planning, network, and dispatch modules can be combined at increasing levels of detail."
+        )
+
+    st.write("")
+    st.markdown("**Documentation**")
+    st.info(f"Full documentation is available at [{DOCS_URL}]({DOCS_URL}).")
+
+
+def _render_footer() -> None:
+    st.subheader("Contacts")
+    st.markdown("**Active Developer**")
+    st.markdown(
+        """
+        **Alessandro Onori** , alessandro.onori@polimi.it
+        *Core Linopy optimization model, modeling advancements, and Streamlit UI development*
+        """
+    )
+
+    st.markdown("**Technical Advisors**")
+    st.markdown(
+        """
+        - Nicolò Stevanato, nicolo.stevanato@polimi.it, Politecnico di Milano
+        - Riccardo Mereu, riccardo.mereu@polimi.it, Politecnico di Milano
+        - Emanuela Colombo, emanuela.colombo@polimi.it, Politecnico di Milano
+        """
+    )
+
+    st.subheader("License")
+    st.markdown(
+        "Open-source research codebase. Refer to the repository materials for the current licensing terms."
+    )
+
+
+def render_home_page() -> None:
+    _inject_css()
+    _render_ecosystem()
+    _render_resources()
+    st.divider()
+    _render_footer()
+
+
+render_home_page()

microgridspy/app/__init__.py

@@ -0,0 +1,7 @@
+"""MicroGridsPy Streamlit GUI.
+
+This subpackage contains the optional graphical interface. Its extra
+dependency (streamlit) is installed only via the ``[gui]`` extra:
+``pip install "microgridspy[gui]"``. Importing the library core
+(``import microgridspy``) never imports anything from here.
+"""

microgridspy/app/launcher.py

@@ -0,0 +1,31 @@
+"""Console entry point: ``microgridspy-gui`` launches the Streamlit app from anywhere.
+
+Registered in ``pyproject.toml`` under ``[project.scripts]`` as
+``microgridspy-gui = "microgridspy.app.launcher:main"``. It locates the
+packaged ``Home.py`` via `importlib.resources`, so it works regardless of
+where the package was installed or which directory the user runs it from.
+"""
+
+from __future__ import annotations
+
+import sys
+from importlib import resources
+
+
+def main() -> None:
+    try:
+        from streamlit.web import cli as stcli  # streamlit is only needed for the GUI
+    except ModuleNotFoundError as exc:  # pragma: no cover - trivial guard
+        raise SystemExit(
+            "The MicroGridsPy GUI requires the optional 'gui' extra.\n"
+            'Install it with:  pip install "microgridspy[gui]"'
+        ) from exc
+
+    # Locate the packaged Home.py regardless of install location.
+    with resources.as_file(resources.files("microgridspy.app") / "Home.py") as home:
+        sys.argv = ["streamlit", "run", str(home)]
+        sys.exit(stcli.main())
+
+
+if __name__ == "__main__":
+    main()