microgridspy 0.4.0__tar.gz

microgridspy-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: ci
+
+on:
+  push:
+    branches: ["master", "main"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0            # tags needed for hatch-vcs to derive the version
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (with dev + open-source solver)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,highs]"
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+      - name: Test (with coverage)
+        run: |
+          coverage run -m pytest -q
+          coverage report

microgridspy-0.4.0/.github/workflows/draft-pdf.yml

@@ -0,0 +1,30 @@
+name: draft-pdf
+
+# Compiles the JOSS paper to a PDF on changes, so the draft can be previewed.
+# The compiled PDF is uploaded as a build artifact (it is not committed).
+on:
+  push:
+    paths:
+      - "paper/**"
+      - ".github/workflows/draft-pdf.yml"
+  workflow_dispatch:
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          paper-path: paper/paper.md
+
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          path: paper/paper.pdf

microgridspy-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0            # full history + tags for hatch-vcs
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write               # OIDC: Trusted Publishing, no API token stored
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

microgridspy-0.4.0/.gitignore

@@ -0,0 +1,41 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build / packaging artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Test / lint caches
+.pytest_cache/
+.cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Docs build output
+docs/_build/
+site/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Editors / IDE
+.history/
+.vscode/
+.idea/
+
+# OS cruft
+.DS_Store
+Thumbs.db
+
+# The local workspace. `projects/` is created at runtime by create_project()/the GUI
+# and holds whatever the user is working on, so none of it belongs in the repository.
+# The two demo projects ship inside the package (src/microgridspy/examples/), and the
+# Kalobeyei case studies are published as a separate archive - see docs/examples/.
+projects/

microgridspy-0.4.0/.mailmap

@@ -0,0 +1,39 @@
+# Canonical contributor identities.
+#
+# Git records whatever name/email was configured on the machine that made each
+# commit, so one person can appear several times. This file maps those variants
+# onto a single canonical identity; `git shortlog`, `git log` and most analysis
+# tools honour it. No history is rewritten - only the display is corrected.
+#
+# Syntax:  Canonical Name <canonical@email> Recorded Name <recorded@email>
+# Canonical names/emails follow AUTHORS where the person is listed there.
+
+# --- Universite de Liege: original authors ---
+Sergio Balderrama <slbalderrama@doct.ulg.ac.be> Sergio Balderrama <sergiob44_47@hotmail.com>
+Sergio Balderrama <slbalderrama@doct.ulg.ac.be> Sergio Balderra <sergiob44_47@hotmail.com>
+Sergio Balderrama <slbalderrama@doct.ulg.ac.be> Slbalderrama <sergiob44_47@hotmail.com>
+Sergio Balderrama <slbalderrama@doct.ulg.ac.be> slbalderrama <sergiob44_47@hotmail.com>
+Sylvain Quoilin <squoilin@uliege.be> Sylvain Quoilin <squoilin@ulg.ac.be>
+Sylvain Quoilin <squoilin@uliege.be> Sylvain Quoilin <sylvain.quoilin@ec.europa.eu>
+
+# --- Politecnico di Milano ---
+Alessandro Onori <alessandro.onori@polimi.it> AleOnori98 <onorialessandro1998@gmail.com>
+Alessandro Onori <alessandro.onori@polimi.it> AleOnori98 <63561931+AleOnori98@users.noreply.github.com>
+Alessandro Onori <alessandro.onori@polimi.it> Alessandro Onori <63561931+AleOnori98@users.noreply.github.com>
+Nicolò Stevanato <nicolo.stevanato@polimi.it> Nicolò Stevanato <nicolo.stevanato@mail.polimi.it>
+Gianluca Pellecchia <gianluca.pellecchia@polimi.it> Gianluca Pellecchia <gianluca.pellecchia@mail.polimi.it>
+Gianluca Pellecchia <gianluca.pellecchia@polimi.it> gianlucapellecchia <gianluca.pellecchia@mail.polimi.it>
+Lorenzo Rinaldi <lorenzo.rinaldi@polimi.it> LorenzoRinaldi <lorenzo.rinaldi1@gmail.com>
+Lorenzo Rinaldi <lorenzo.rinaldi@polimi.it> LorenzoRinaldi <43796440+LorenzoRinaldi@users.noreply.github.com>
+Giulia Guidicini <giulia.guidicini@polimi.it> Giulia Guidicini <43995656+gguidicini@users.noreply.github.com>
+Ivan Sangiorgio <ivan.sangiorgio@polimi.it> Ivan Sangiorgio <73618037+ivansangiorgio@users.noreply.github.com>
+
+# --- TU Delft ---
+Francesco Lombardi <f.lombardi@tudelft.nl> Francesco Lombardi <francesco.lombardi@polimi.it>
+Francesco Lombardi <f.lombardi@tudelft.nl> Francesco Lombardi <f.lombardi@outlook.com>
+Francesco Lombardi <f.lombardi@tudelft.nl> FLomb <francesco.lombardi@polimi.it>
+Francesco Lombardi <f.lombardi@tudelft.nl> FLomb <f.lombardi@outlook.com>
+
+# --- Display-name normalisation only (canonical email not confirmed) ---
+Giacomo Crevani <giacomo.crevani@mail.polimi.it> GiacomoCrevani <giacomo.crevani@mail.polimi.it>
+Costanza Summaria <83756734+costisum@users.noreply.github.com> costanzasummaria <83756734+costisum@users.noreply.github.com>

microgridspy-0.4.0/.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs build configuration.
+# RTD is the build/host layer only: it installs the tools, runs the Zensical
+# build, and publishes the result. Zensical is the site generator; mkdocstrings
+# produces the API reference. See https://docs.readthedocs.io/en/stable/config-file/
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  commands:
+    # Zensical (site generator) + mkdocstrings Python handler (API extraction).
+    # mkdocstrings reads the package statically from src/ (paths=["src"] in
+    # zensical.toml), so MicroGridsPy itself need not be installed.
+    - pip install zensical mkdocstrings-python
+    # Build the static site into ./site, then hand it to Read the Docs.
+    - zensical build
+    - mkdir -p "$READTHEDOCS_OUTPUT/html"
+    - cp -r site/. "$READTHEDOCS_OUTPUT/html/"

microgridspy-0.4.0/AUTHORS

@@ -0,0 +1,68 @@
+# Authors
+
+MicroGridsPy is an open-source mini-grid sizing and dispatch model originally developed by
+Sergio Balderrama and Sylvain Quoilin at the Université de Liège. It was subsequently extended 
+through research projects and publications involving the SESAM group at Politecnico di Milano and other collaborators.
+
+The current version is a **major redevelopment** of the original model: it has been restructured 
+as an installable Python package based on Linopy, with a stable API and fully integrated GUI, and includes new consistent economic, 
+battery degradation, inverter sizing, expanded stochastic optimisation and multi-year capacity-expansion features.
+
+## Main developer and maintainer
+
+- Alessandro Onori, Politecnico di Milano
+  <alessandro.onori@polimi.it> — ORCID: 0009-0009-1195-2078
+
+## Current contributors and Scientific advisory
+
+- Nicolò Stevanato, Politecnico di Milano
+  <nicolo.stevanato@polimi.it> — ORCID: 0000-0002-3419-0389
+- Riccardo Mereu, Politecnico di Milano
+  <riccardo.mereu@polimi.it> — ORCID: 0000-0003-0544-595X
+- Emanuela Colombo, Politecnico di Milano
+  <emanuela.colombo@polimi.it> — ORCID: 0000-0002-9747-5699
+
+## Past contributors
+
+The following contributors worked on **earlier versions** of MicroGridsPy, **up to the 2023 release line**:
+
+- Francesco Lombardi, TU Delft
+  — El Espino (2019), PowerTech (2019), MYCE (2020)
+- Giulia Guidicini, Politecnico di Milano
+  — MYCE (2020)
+- Lorenzo Rinaldi, Politecnico di Milano
+  — MYCE (2020)
+- Gianluca Pellecchia, Politecnico di Milano
+  — Third-generation minigrids (2023)
+- Ivan Sangiorgio, Politecnico di Milano
+  — Third-generation minigrids (2023)
+
+The original MicroGridsPy framework and **first open-source release (2019)** were developed at the Université de Liège:
+
+- Sergio Balderrama, Université de Liège
+- Sylvain Quoilin, Université de Liège
+
+## Development history
+
+Key publications documenting the development of the model include:
+
+- **El Espino (2019)** — S. Balderrama, F. Lombardi, F. Riva, W. Canedo, E. Colombo,
+  S. Quoilin. "A two-stage linear programming optimization framework for isolated hybrid
+  microgrids in a rural context: the case study of the 'El Espino' community." *Energy* 188
+  (2019) 116073. https://doi.org/10.1016/j.energy.2019.116073
+- **PowerTech (2019)** — N. Stevanato, F. Lombardi, E. Colombo, S. Balderrama, S. Quoilin.
+  "Two-stage stochastic sizing of a rural micro-grid based on stochastic load generation."
+  *2019 IEEE Milan PowerTech*, pp. 1–6. https://doi.org/10.1109/PTC.2019.8810571
+- **MYCE (2020)** — N. Stevanato, F. Lombardi, G. Guidicini, L. Rinaldi, S. L. Balderrama,
+  M. Pavičević, S. Quoilin, E. Colombo. "Long-term sizing of rural microgrids: accounting
+  for load evolution through multi-step investment plan and stochastic optimization."
+  *Energy for Sustainable Development* 58 (2020) 16–29.
+  https://doi.org/10.1016/j.esd.2020.07.002
+- **Third-generation minigrids (2023)** — N. Stevanato, G. Pellecchia, I. Sangiorgio,
+  D. Shendrikova, C. A. Soares, R. Mereu, E. Colombo. "Planning third generation minigrids:
+  multi-objective optimization and brownfield investment approaches in modelling
+  village-scale on-grid and off-grid energy systems." *Renewable and Sustainable Energy
+  Transition* 3 (2023) 100053. https://doi.org/10.1016/j.rset.2023.100053
+- **Financing schemes, ECOS (2023)** — G. Crevani, C. Soares, E. Colombo. "Modelling
+  financing schemes for energy system planning: a mini-grid case study." *Proceedings of
+  ECOS 2023*, pp. 1958–1969.

microgridspy-0.4.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-09-25
+
+### Fixed
+- **Multi-year battery energy balance closes at the end of the horizon.** `soc_balance`
+  linked `soc[t] -> soc[t+1]` only up to the second-to-last period, and `soc_year_link_*`
+  only carried state *between* years, so the state implied after the final period of the
+  final year was unbounded: the battery could discharge energy it had never stored in that
+  last step. New `soc_terminal_upper` / `soc_terminal_lower` constraints apply the same
+  bounds to that state. The typical-year formulation was never affected — its `soc_cyclic`
+  constraint already closed the loop.
+  The leak only bound when the battery would otherwise be empty at the horizon end, so
+  long hourly runs are unlikely to change: on `demo_multi_year` the final-hour discharge
+  (18.9 kWh) was already covered by stored energy (664.2 kWh). Short or reduced-resolution
+  horizons could be affected materially.
+
+### Changed
+- **BREAKING — the two formulations are now named `typical_year` and `multi_year`
+  everywhere**: in `formulation.json`, in `create_project(formulation=...)`, in the CLI
+  `--formulation` choices and in the model class names. Previously the same two concepts
+  were spelled three ways (`steady_state`/`dynamic` in data and the API, `typical_year`/
+  `multi_year` in module names and docs, `SteadyStateModel`/`MultiYearModel` in code).
+  Projects created by earlier releases must set `core_formulation` to the new name; the
+  old spellings now raise `InputValidationError` instead of being translated.
+- **BREAKING — `SteadyStateModel` was removed.** Use `TypicalYearModel`.
+- **One exception type.** `InputValidationError` was defined separately in 20 modules, so
+  `except microgridspy.InputValidationError` did not catch errors raised by most of the
+  package. It now lives in `microgridspy.errors` and every layer raises that one class.
+- **One capital-recovery factor.** `_crf` was implemented five times, with three different
+  zero-rate tolerances and three different answers for a non-positive lifetime, so the
+  annuity used in the objective could differ from the annuity shown in the results. It now
+  lives in `microgridspy.finance.crf`. For a non-positive lifetime it returns `nan`
+  (previously `0.0`, `nan` or `inf` depending on which copy ran).
+
+### Removed
+- Dead code: `export/csv_reader.py`, `export/manifest.py`, `export/yaml_reader.py`,
+  `app/typical_year_file_results_page.py` and 17 unreferenced functions.
+- The `error_cls` parameter threaded through the IO and coercion helpers, which existed
+  only to select between the duplicate exception classes.
+- The duplicated session state on the Optimization page: a solved run was stored four ways
+  (`gp_sets`/`gp_data`/`gp_vars`, the results bundle and the two typed results objects).
+  Only the bundle and the typed results remain.
+- `pre-commit` from the `dev` extra — the project has no pre-commit configuration.
+
+## [0.2.0] - 2026-08-24
+
+### Added
+- Project management: `delete_project`, `copy_project`, `rename_project`.
+- `load_inputs()` — assemble a project's input dataset without solving.
+- `list_input_timeseries()` and `plot_input_timeseries()` — input time-series
+  plots returned as matplotlib figures.
+- `to_excel()` method on `TypicalYearResults` / `MultiYearResults`.
+- `microgridspy` command-line interface (`list` / `create` / `validate` / `solve`).
+
+### Changed
+- Removed outdated files (broken `requirements.txt`, `environment_nobuilds.yml`,
+  documentation PDFs); README rewritten for `pip install` and the Python API.
+- Home page: the PDF previews were replaced with a documentation-link placeholder.
+- The `formulation.json` builder is shared between the GUI and the library.
+- Whole codebase formatted and linted with ruff.
+- Added a package-level test suite (`tests/test_public_api.py`); `ruff check`,
+  `ruff format --check`, and `pytest` all pass.
+
+### Fixed
+- `results_summary()` now reads the objective from `model.objective.value`, so the
+  headline objective value is populated instead of `None`.
+- Restored 3 multi-year inverter tests whose fixture was missing the
+  `year_inv_step` mapping.
+
+## [0.1.0] - 2026-08-24
+
+First pip-installable release.
+
+### Added
+- `pyproject.toml` (Hatchling + hatch-vcs): git-tag-driven versioning, the
+  `microgridspy-gui` console entry point, and optional extras `gui`, `highs`,
+  `gurobi`, `dev`.
+- `src/` layout; the package is importable as `microgridspy`.
+- Public API:
+  - `SteadyStateModel`, `MultiYearModel` with `solve_single_objective()`,
+    `results()` and `results_summary()`.
+  - `solve()`, `load_results()`, `export_results()` convenience functions.
+  - `create_project()`, `validate_project()` for headless project scaffolding.
+  - `set_workspace()`, `list_projects()`, `project_paths()`, `project_exists()`.
+  - `TypicalYearResults`, `MultiYearResults`, `InputValidationError`.
+- `MICROGRIDSPY_WORKSPACE` environment variable to locate the projects folder.
+
+### Changed
+- Renamed the importable package from `core` to `microgridspy`.
+- Moved the Streamlit GUI into the `microgridspy.app` subpackage; installing the
+  core no longer requires Streamlit (it is gated behind the `gui` extra).
+- The GUI's project-creation writes `formulation.json` via the shared
+  `microgridspy.io.project_setup.build_formulation_payload`, so the app and the
+  library stay in lock-step.
+
+### Fixed
+- Optimal HiGHS solves were reported as "no feasible solution" because the
+  result gate grepped the solver log for a Gurobi-specific marker. Detection now
+  uses the in-memory linopy solution, so HiGHS and Gurobi both work.
+
+[Unreleased]: https://github.com/MicroGridsPy/MicroGridsPy/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/MicroGridsPy/MicroGridsPy/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/MicroGridsPy/MicroGridsPy/releases/tag/v0.1.0

microgridspy-0.4.0/CITATION.cff

@@ -0,0 +1,107 @@
+# Citation metadata for MicroGridsPy.
+#
+# Author order follows AUTHORS: the maintainer of the current redevelopment first,
+# then current contributors and scientific advisory, then contributors to earlier
+# versions, then the original authors of the model at the Universite de Liege.
+#
+# When the JOSS paper is published, add a `preferred-citation:` block here pointing
+# to it; GitHub and citation tools will then offer the paper instead of the software.
+cff-version: 1.2.0
+message: "If you use MicroGridsPy in your research, please cite it as below."
+title: "MicroGridsPy: bottom-up optimization of mini-grids for rural electrification"
+abstract: >-
+  MicroGridsPy is an open-source Python package for the techno-economic planning of
+  mini-grid energy systems in remote and underserved areas. It sizes and dispatches
+  renewable generation, battery storage, backup generators and optional grid connection
+  by linear and mixed-integer optimization, supporting typical-year and multi-year
+  capacity-expansion formulations, single- and multi-scenario studies, and both
+  continuous and discrete sizing. It is built on Linopy and ships with a command-line
+  interface, a documented Python API and an optional Streamlit graphical interface.
+type: software
+version: "0.4.0"
+date-released: "2026-09-25"
+license: EUPL-1.2
+repository-code: "https://github.com/MicroGridsPy/MicroGridsPy"
+url: "https://microgridspy-package-docs.readthedocs.io/"
+keywords:
+  - energy
+  - mini-grid
+  - rural electrification
+  - energy access
+  - optimization
+  - linopy
+  - capacity expansion
+authors:
+  # Main developer and maintainer of the current version.
+  - family-names: Onori
+    given-names: Alessandro
+    affiliation: "Politecnico di Milano"
+    email: alessandro.onori@polimi.it
+    orcid: "https://orcid.org/0009-0009-1195-2078"
+  # Current contributors and scientific advisory.
+  - family-names: Stevanato
+    given-names: "Nicolo"
+    affiliation: "Politecnico di Milano"
+    email: nicolo.stevanato@polimi.it
+    orcid: "https://orcid.org/0000-0002-3419-0389"
+  - family-names: Colombo
+    given-names: Emanuela
+    affiliation: "Politecnico di Milano"
+    email: emanuela.colombo@polimi.it
+    orcid: "https://orcid.org/0000-0002-9747-5699"
+  - family-names: Mereu
+    given-names: Riccardo
+    affiliation: "Politecnico di Milano"
+    email: riccardo.mereu@polimi.it
+    orcid: "https://orcid.org/0000-0003-0544-595X"
+  # Contributors to earlier versions.
+  - family-names: Lombardi
+    given-names: Francesco
+    affiliation: "Delft University of Technology"
+    email: f.lombardi@tudelft.nl
+  - family-names: Guidicini
+    given-names: Giulia
+    affiliation: "Politecnico di Milano"
+    email: giulia.guidicini@polimi.it
+  - family-names: Rinaldi
+    given-names: Lorenzo
+    affiliation: "Politecnico di Milano"
+    email: lorenzo.rinaldi@polimi.it
+  - family-names: Pellecchia
+    given-names: Gianluca
+    affiliation: "Politecnico di Milano"
+    email: gianluca.pellecchia@polimi.it
+  - family-names: Sangiorgio
+    given-names: Ivan
+    affiliation: "Politecnico di Milano"
+    email: ivan.sangiorgio@polimi.it
+  # Original authors of the model (Universite de Liege, first release 2019).
+  - family-names: Balderrama
+    given-names: Sergio
+    affiliation: "Universidad Mayor de San Simon / Universite de Liege"
+    email: slbalderrama@doct.ulg.ac.be
+    orcid: "https://orcid.org/0000-0003-0656-3544"
+  - family-names: Quoilin
+    given-names: Sylvain
+    affiliation: "KU Leuven"
+    email: squoilin@uliege.be
+    orcid: "https://orcid.org/0000-0002-2064-209X"
+references:
+  - type: dataset
+    title: "Kalobeyei case-study dataset for MicroGridsPy: seven mini-grid planning scenarios"
+    doi: 10.5281/zenodo.22958510
+    notes: "Inputs, results and solver logs for the seven scenarios documented in the Examples section."
+    authors:
+      - family-names: Onori
+        given-names: Alessandro
+  - type: software
+    title: "MicroGridsPy-Pyomo: archived Pyomo implementation of the MicroGridsPy mini-grid planning model"
+    doi: 10.5281/zenodo.22900498
+    version: "2.1"
+    year: 2026
+    notes: "The archived Pyomo implementation superseded by this package."
+    authors:
+      - family-names: Balderrama
+        given-names: Sergio
+      - family-names: Quoilin
+        given-names: Sylvain

microgridspy-0.4.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**alessandro.onori@polimi.it**.
+<!-- TODO: replace with a dedicated conduct-reporting address if the project adopts one. -->
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla coc]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

microgridspy-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to MicroGridsPy
+
+Thanks for your interest in improving MicroGridsPy! Contributions of all kinds are
+welcome — bug reports, feature requests, documentation, and code. For
+documentation-specific conventions, see
+[`docs/developers/contributing.md`](docs/developers/contributing.md).
+
+## Reporting issues
+
+Please open an issue on the
+[issue tracker](https://github.com/MicroGridsPy/MicroGridsPy/issues) and include, where
+relevant: what you expected, what happened, a minimal example (or project inputs) that
+reproduces the problem, your OS, Python version, and MicroGridsPy version
+(`python -c "import microgridspy; print(microgridspy.__version__)"`).
+
+## Development setup
+
+```bash
+git clone https://github.com/MicroGridsPy/MicroGridsPy.git
+cd MicroGridsPy
+pip install -e ".[highs,dev]"
+```
+
+## Before opening a pull request
+
+- Keep changes focused and describe the motivation in the PR.
+- Run the linters and tests locally:
+
+  ```bash
+  ruff check .
+  ruff format --check .
+  pytest
+  ```
+
+- Update [`CHANGELOG.md`](CHANGELOG.md) when behavior changes.
+- Add or update tests for new behavior, and update the docs when relevant
+  (keep API details in docstrings — the API reference is generated from them).
+- If you build the docs, verify they build cleanly (`zensical build`).
+
+## Code style
+
+The project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting
+(configured in `pyproject.toml`).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's
+[EUPL-1.2 license](LICENSE).