Merge branch 'release/0.5.0'

.coveragerc

@@ -0,0 +1,6 @@
+[report]
+include =
+    mesmo/*
+    examples/*
+omit =
+    examples/development/*

.github/workflows/documentation.yml

@@ -1,11 +1,12 @@
 name: Documentation
-
 on: [push]
 
 jobs:
   build-documentation:
-
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}  # Required for conda commands.
 
     steps:
     - name: Checkout repository
@@ -14,9 +15,9 @@ jobs:
       run: |
         git fetch --prune --unshallow
     - name: Set up Python
-      uses: s-weigand/setup-conda@v1
+      uses: conda-incubator/setup-miniconda@v2
       with:
-        python-version: 3.7
+        python-version: 3.8
     - name: Install dependencies
       run: |
         conda install sphinx
@@ -25,10 +26,13 @@ jobs:
       run: |
         sphinx-multiversion docs docs/_build/html
         cp docs/assets/gh-pages_index.html docs/_build/html/index.html
-        find docs/_build/html -type f -name "*.html" -exec sed -i 's/<li><p>\(.*\)<\/p>\(.*\)/<li>\1\2/g' {} +
     - name: Deploy documentation HTML to Github Pages
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: docs/_build/html/
         keep_files: false
+        force_orphan: true
+        full_commit_message: Deploy documentation for ${{ github.sha }}
+        user_name: GitHub Actions
+        user_email: github-actions[bot]@users.noreply.github.com

.github/workflows/maintenance.yml

@@ -0,0 +1,80 @@
+name: Maintenance
+on:
+  workflow_run:
+    workflows: ["Python tests"]
+    branches: [develop]
+    types:
+      - completed
+
+jobs:
+  get-environment:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      max-parallel: 8
+      matrix:
+        os: [
+          windows-latest,
+          macos-latest,
+          ubuntu-latest
+        ]
+    defaults:
+      run:
+        shell: bash -l {0}  # Required for conda commands.
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+    - name: Checkout submodules
+      run: |
+        auth_header="$(git config --local --get http.https://github.com/.extraheader)"
+        git submodule sync --recursive
+        git -c "http.extraheader=$auth_header" -c protocol.version=2 submodule update --init --force --recursive --depth=1
+    - name: Set up Python
+      uses: conda-incubator/setup-miniconda@v2
+    - name: Install dependencies
+      run: |
+        conda create -n mesmo -c conda-forge python=3.8 contextily cvxpy numpy pandas scipy
+        conda activate mesmo
+        pip install -v -e .
+    - name: Get new environment-${{ matrix.os }}.yml
+      run: |
+        rm environment-*
+        conda env export -n mesmo --no-builds | grep -v "^prefix: " > environment-${{ matrix.os }}.yml
+    - name: Store environment-${{ matrix.os }}.yml
+      uses: actions/upload-artifact@v2
+      with:
+        name: environment-${{ matrix.os }}.yml
+        path: environment-${{ matrix.os }}.yml
+
+  run-maintenance:
+    needs: get-environment
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+    - name: Remove old environment files
+      run: |
+        rm environment-*
+    - name: Get cached environment-windows-latest.yml
+      uses: actions/download-artifact@v2
+      with:
+        name: environment-windows-latest.yml
+    - name: Get cached environment-macos-latest.yml
+      uses: actions/download-artifact@v2
+      with:
+        name: environment-macos-latest.yml
+    - name: Get cached environment-ubuntu-latest.yml
+      uses: actions/download-artifact@v2
+      with:
+        name: environment-ubuntu-latest.yml
+    - name: Commit changes
+      uses: stefanzweifel/git-auto-commit-action@v4
+      with:
+        commit_message: Automated maintenance for ${{ github.sha }}
+        commit_user_name: GitHub Actions
+        commit_user_email: github-actions[bot]@users.noreply.github.com

.github/workflows/pythontests.yml

@@ -1,20 +1,22 @@
 name: Python tests
-
 on: [push]
 
 jobs:
   run-tests:
-
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       max-parallel: 8
       matrix:
         os: [
           windows-latest,
-          # macos-latest,
+          macos-latest,
           ubuntu-latest
         ]
-        python-version: [3.7]
+        python-version: [3.7, 3.8]
+    defaults:
+      run:
+        shell: bash -l {0}  # Required for conda commands.
 
     steps:
     - name: Checkout repository
@@ -25,21 +27,32 @@ jobs:
         auth_header="$(git config --local --get http.https://github.com/.extraheader)"
         git submodule sync --recursive
         git -c "http.extraheader=$auth_header" -c protocol.version=2 submodule update --init --force --recursive --depth=1
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: s-weigand/setup-conda@v1
-      with:
-        python-version: ${{ matrix.python-version }}
+    - name: Set up Python
+      uses: conda-incubator/setup-miniconda@v2
     - name: Install dependencies
       run: |
+        conda create -n mesmo -c conda-forge python=${{ matrix.python-version }} contextily cvxpy numpy pandas scipy
+        conda activate mesmo
         pip install -v -e .
     - name: Lint with flake8
       run: |
+        conda activate mesmo
         pip install flake8
         # Stop the build if there are Python syntax errors or undefined names.
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # Exit-zero treats all errors as warnings. Line lengths should not exceed 120 characters.
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=120 --statistics
-    - name: Test with pytest
+    - name: Run tests
       run: |
-        pip install pytest
-        pytest tests
+        conda activate mesmo
+        pip install pytest pytest-cov pytest-subtests
+        pytest tests --cov=./ --cov-report=xml
+    - name: Report coverage to Codecov
+      if: always()
+      uses: codecov/codecov-action@v2
+      with:
+        fail_ci_if_error: true
+    - name: Report coverage to Codacy
+      if: always()
+      uses: codacy/codacy-coverage-reporter-action@v1
+      with:
+        project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+        coverage-reports: coverage.xml

.gitignore

@@ -13,8 +13,6 @@
 
 .pytest_cache
 
-cache/
-
 *.sqlite
 
 *.sqlite-journal

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "cobmo"]
 	path = cobmo
-	url = https://github.com/TUMCREATE-ESTL/cobmo
+	url = https://github.com/mesmo-dev/cobmo

CITATION.bib

@@ -0,0 +1,8 @@
+@misc{mesmo,
+author = {Sebastian Troitzsch and Verena Kleinschmidt and Tom Schelo and Arif Ahmed},
+title = {{MESMO - Multi-Energy System Modeling and Optimization}},
+year = 2021,
+howpublished = {Version 0.5.0, Zenodo},
+doi = {10.5281/zenodo.3523568},
+url = {https://doi.org/10.5281/zenodo.3523568}
+}

README.md

@@ -1,60 +1,72 @@
-# FLEDGE - Flexible Distribution Grid Demonstrator
+![](docs/assets/mesmo_logo.png)
 
-[![DOI](https://zenodo.org/badge/201130660.svg)](https://zenodo.org/badge/latestdoi/201130660)
+[![](https://zenodo.org/badge/201130660.svg)](https://zenodo.org/badge/latestdoi/201130660)
+[![](https://img.shields.io/github/release-date/mesmo-dev/mesmo?label=last%20release)](https://github.com/mesmo-dev/mesmo/releases)
+[![](https://img.shields.io/github/last-commit/mesmo-dev/mesmo?label=last%20commit%20%28develop%29)](https://github.com/mesmo-dev/mesmo/commits/develop)
+[![](https://img.shields.io/github/workflow/status/mesmo-dev/mesmo/Python%20tests/develop?label=tests%20%28develop%29)](https://github.com/mesmo-dev/mesmo/actions/workflows/pythontests.yml?query=branch%3Adevelop)
 
-The Flexible Distribution Grid Demonstrator (FLEDGE) is a software tool for optimal operation problems of electric and thermal distribution grids along with distributed energy resources (DERs), such as flexible building loads, electric vehicle (EV) chargers, distributed generators (DGs) and energy storage systems (ESS). To this end, it implements 1) electric grid models, 2) thermal grid models, 3) DER models, and 4) optimal operation problems.
+> Work in progress: The repository is under active development and interfaces may change without notice. Please use [GitHub issues](https://github.com/mesmo-dev/mesmo/issues) for raising problems, questions, comments and feedback.
 
-## Work in progress
+# What is MESMO?
 
-Please note that the repository is under active development and the interface may change without notice. Create an [issue](https://github.com/TUMCREATE-ESTL/fledge/issues) if you have ideas / comments / criticism that may help to make the tool more useful.
+MESMO stand for "Multi-Energy System Modeling and Optimization" and is an open-source Python tool for the modeling, simulation and optimization of multi-scale electric and thermal distribution systems along with distributed energy resources (DERs), such as flexible building loads, electric vehicle (EV) chargers, distributed generators (DGs) and energy storage systems (ESS).
 
 ## Features
 
-- Electric grid models:
-    - Obtain nodal / branch admittance and incidence matrices¹.
-    - Obtain steady state power flow solution for nodal voltage / branch flows / losses via fixed-point algorithm / [OpenDSS](https://github.com/dss-extensions/OpenDSSDirect.py)¹.
-    - Obtain sensitivity matrices of global linear approximate grid model¹.
-    - ¹Fully enabled for unbalanced / multiphase grid configuration.
-- Thermal grid models:
-    - Obtain nodal / branch incidence matrices.
-    - Obtain thermal power flow solution for nodal head / branch flows / pumping losses.
-    - Obtain sensitivity matrices of global linear approximate grid model.
-- Distributed energy resource (DER) models:
-    - Time series models for fixed loads.
-    - Time series models for EV charging.
-    - Linear models for flexible building loads.
-- Optimal operation problems:
-    - Obtain numerical optimization problem for combined optimal operation for electric / thermal grids with DERs.
-    - Obtain electric / thermal optimal power flow solution.
-    - Obtain distribution locational marginal prices (DLMPs) for the electric / thermal grids.
+MESMO implements 1) non-linear models for simulation-based analysis and 2) convex models for optimization-based analysis of electric grids, thermal grids and DERs. Through high-level interfaces, MESMO enables modeling operation problems for both traditional scenario-based simulation as well as optimization-based decision support. An emphasis of MESMO is on the modeling of multi-energy systems, i.e. the coupling of multi-commodity and multi-scale energy systems.
+
+1. **Electric grid modeling**
+    - Simulation: Non-linear modeling of steady-state nodal voltage / branch flows / losses, for multi-phase / unbalanced AC networks.
+    - Optimization: Linear approximate modeling via global or local approximation, for multi-phase / unbalanced AC networks.
+2. **Thermal grid modeling**
+    - Simulation: Non-linear modeling of steady-state nodal pressure head / branch flow / pump losses, for radial district heating / cooling systems.
+    - Optimization: Linear approximate modeling via global or local approximation, for radial district heating / cooling systems.
+3. **Distributed energy resource (DER) modeling**
+    - Simulation & optimization: Time series models for non-dispatchable / fixed DERs.
+    - Optimization: Linear state-space models for dispatchable / flexible DERs.
+    - Currently implemented DER models: Conventional fixed loads, generic flexible loads, flexible thermal building loads, non-dispatchable generators, controllable electric / thermal generators, electric / thermal energy storage systems, combined heat-and-power plants.
+4. **Solution interfaces**
+    - Simulation: Solution of non-linear power flow problems for electric / thermal grids.
+    - Optimization: Solution of convex optimization problems for electric / thermal grids and DERs, through third-party numerical optimization solvers.
+    - Generic optimization problem interface: Supports defining custom constraints and objective terms to augment the built-in models. Enables retrieving duals / DLMPs for the study of decentralized / distributed control architectures for energy systems.
+    - High-level problem interfaces: Nominal operation problem for simulation-based studies; Optimal operation problem for optimization-based studies.
 
 ## Documentation
 
-The preliminary documentation is located at [tumcreate-estl.github.io/fledge](https://tumcreate-estl.github.io/fledge).
+The documentation is located at [mesmo-dev.github.io/mesmo](https://mesmo-dev.github.io/mesmo).
 
 ## Installation
 
-1. Check requirements:
-    - Python 3.7
-    - [Gurobi Optimizer](http://www.gurobi.com/)
-2. Clone or download repository. Ensure that the `cobmo` submodule directory is loaded as well.
-3. In your Python environment, run:
-    1. `pip install -v -e path_to_repository`
+MESMO has not yet been deployed to Python `pip` / `conda` package indexes, but can be installed in a local development environment as follows:
 
-Please also read [docs/getting_started.md](./docs/getting_started.md).
+1. Check requirements:
+    - Python distribution¹: [Anaconda](https://www.anaconda.com/distribution/) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) or [Miniforge](https://github.com/conda-forge/miniforge).
+    - Optimization solver²: [Gurobi](http://www.gurobi.com/) or [CVXPY-supported solver](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver).
+2. Clone or download the repository. Ensure that the `cobmo` submodule directory is loaded as well.
+3. In `conda`-enabled shell (e.g. Anaconda Prompt), run:
+    - `cd path_to_mesmo_repository`
+    - `conda create -n mesmo -c conda-forge python=3.8 contextily cvxpy numpy pandas scipy`
+    - `conda activate mesmo`
+    - `pip install -v -e .`
+    - On Intel CPUs³: `conda install -c conda-forge "libblas=*=*mkl"`
+
+For notes ¹/²/³ and alternative installation guide, see [docs/installation.md](docs/installation.md).
 
 ## Contributing
 
 If you are keen to contribute to this project, please see [docs/contributing.md](./docs/contributing.md).
 
 ## Publications
 
-Information on citing FLEDGE and a list of related publications is available at [docs/publications.md](docs/publications.md).
+Information on citing MESMO and a list of related publications is available at [docs/publications.md](docs/publications.md).
 
 ## Acknowledgements
 
+- MESMO is developed in collaboration between [TUMCREATE](https://www.tum-create.edu.sg/), the [Institute for High Performance Computing, A*STAR](https://www.a-star.edu.sg/ihpc) and the [Chair of Renewable and Sustainable Energy Systems, TUM](https://www.ei.tum.de/en/ens/).
+- Sebastian Troitzsch implemented the initial version of MESMO and maintains this repository.
+- Sarmad Hanif and Kai Zhang developed the underlying electric grid modeling, fixed-point power flow solution and electric grid approximation methodologies.
+- Arif Ahmed implemented the implicit Z-bus power flow solution method & overhead line type definitions.
+- Mischa Grussmann developed the thermal grid modeling and approximation methodologies.
+- Verena Kleinschmidt implemented several multi-energy DER models, such as the heating plant and CHP plant models. 
+- Sebastian Troitzsch and Tom Schelo implemented the optimization problem class.
 - This work was financially supported by the Singapore National Research Foundation under its Campus for Research Excellence And Technological Enterprise (CREATE) programme.
-- Sebastian Troitzsch implemented the initial version of FLEDGE and maintains this repository.
-- Sarmad Hanif and Kai Zhang developed the underlying electric grid modelling, fixed-point power flow solution and electric grid approximation methodologies.
-- Arif Ahmed implemented the implicit Z-bus power flow solution method.
-- Mischa Grussmann developed the thermal grid modelling and approximation methodologies.

data/der_models.csv

@@ -1,15 +1,16 @@
-der_type,der_model_name,definition_type,definition_name,power_per_unit_minimum,power_per_unit_maximum,power_factor_minimum,power_factor_maximum,energy_storage_capacity_per_unit,charging_efficiency,self_discharge_rate,marginal_cost,heat_pump_efficiency,thermal_efficiency,electric_efficiency
-fixed_load,mixed_commercial_residential,schedule_per_unit,mixed_commercial_residential,,,,,,,,,,,
-fixed_load,residential_landed,schedule_per_unit,residential_landed,,,,,,,,,,,
-flexible_load,mixed_commercial_residential,schedule_per_unit,mixed_commercial_residential,0.6,1.4,,,6,,,,,,
-flexible_load,residential_landed,schedule_per_unit,residential_landed,0.6,1.4,,,6,,,,,,
-fixed_generator,photovoltaic_generic,schedule_per_unit,photovoltaic_generic,,,,,,,,,,,
-fixed_generator,solarthermal_generic,schedule_per_unit,solarthermal_generic,,,,,,,,,,,
-flexible_generator,photovoltaic_generic,schedule_per_unit,photovoltaic_generic,0,1,,,,,,0.1,,,
-flexible_generator,solarthermal_generic,schedule_per_unit,solarthermal_generic,0,1,,,,,,0.1,,,
-fixed_ev_charger,fixed_ev_charger_generic,schedule_per_unit,fixed_ev_charger_generic,,,,,,,,,,,
-cooling_plant,cooling_plant_singapore,cooling_plant,cooling_plant_singapore,,,,,,,,,,,
-heat_pump,heat_pump_generic,schedule_per_unit,heat_pump_generic,0,1,,,6,,,1,1.2,,
-flexible_chp,flexible_chp_generic,schedule_per_unit,flexible_chp_generic,0,1,,,6,,,1,,0.55,0.37
-storage,battery_storage_generic,,,0,1,,,12,0.99,0.01,,,,
-storage,thermal_storage_generic,,,0.5,1,,,6,0.99,0.01,,,,
+der_type,der_model_name,definition_type,definition_name,power_per_unit_minimum,power_per_unit_maximum,power_factor_minimum,power_factor_maximum,energy_storage_capacity_per_unit,charging_efficiency,self_discharge_rate,marginal_cost,thermal_efficiency,electric_efficiency
+fixed_load,singapore_base_load,schedule_per_unit,singapore_base_load,,,,,,,,,,
+fixed_load,mixed_commercial_residential,schedule_per_unit,mixed_commercial_residential,,,,,,,,,,
+fixed_load,residential_landed,schedule_per_unit,residential_landed,,,,,,,,,,
+flexible_load,mixed_commercial_residential,schedule_per_unit,mixed_commercial_residential,0.6,1.4,,,6,,,,,
+flexible_load,residential_landed,schedule_per_unit,residential_landed,0.6,1.4,,,6,,,,,
+fixed_generator,photovoltaic_generic,schedule_per_unit,photovoltaic_generic,,,,,,,,,,
+fixed_generator,solarthermal_generic,schedule_per_unit,solarthermal_generic,,,,,,,,,,
+flexible_generator,photovoltaic_generic,schedule_per_unit,photovoltaic_generic,0,1,,,,,,0.1,,
+flexible_generator,solarthermal_generic,schedule_per_unit,solarthermal_generic,0,1,,,,,,0.1,,
+fixed_ev_charger,fixed_ev_charger_generic,schedule_per_unit,fixed_ev_charger_generic,,,,,,,,,,
+cooling_plant,cooling_plant_singapore,cooling_plant,cooling_plant_singapore,,,,,,,,,,
+heating_plant,heating_plant_generic,schedule_per_unit,heating_plant_generic,0,1,,,6,,,1,1.2,
+flexible_chp,flexible_chp_generic,schedule_per_unit,flexible_chp_generic,0,1,,,6,,,1,0.55,0.37
+storage,battery_storage_generic,,,0,1,,,12,0.99,0.01,,,
+storage,thermal_storage_generic,,,0.5,1,,,6,0.99,0.01,,,