Deploy documentation for 8b08664

0.5.0/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: c1cf84787be901b79a2e2e3aa240a192
+tags: 645f666f9bcd5a90fca523b33c5a78b7

0.5.0/_sources/api_reference.md.txt

@@ -0,0 +1,53 @@
+# API reference
+
+```{important}
+This reference is work in progress.
+```
+
+## `mesmo.api`
+
+```{eval-rst}
+.. automodule:: mesmo.api
+```
+
+## `mesmo.problems`
+
+```{eval-rst}
+.. automodule:: mesmo.problems
+```
+
+## `mesmo.electric_grid_models`
+
+```{eval-rst}
+.. automodule:: mesmo.electric_grid_models
+```
+
+## `mesmo.thermal_grid_models`
+
+```{eval-rst}
+.. automodule:: mesmo.thermal_grid_models
+```
+
+## `mesmo.der_models`
+
+```{eval-rst}
+.. automodule:: mesmo.der_models
+```
+
+## `mesmo.data_interface`
+
+```{eval-rst}
+.. automodule:: mesmo.data_interface
+```
+
+## `mesmo.utils`
+
+```{eval-rst}
+.. automodule:: mesmo.utils
+```
+
+## `mesmo.config`
+
+```{eval-rst}
+.. automodule:: mesmo.config
+```

0.5.0/_sources/change_log.md.txt

@@ -0,0 +1,78 @@
+# Change log
+
+Note that version numbering follows the [Semantic Versioning principle](https://semver.org/).
+
+## [0.5.0](https://github.com/mesmo-dev/mesmo/releases/tag/0.5.0)
+
+With this release, the Flexible Distribution Grid Demonstrator (FLEDGE) was renamed to Multi-Energy System Modeling and Optimization (MESMO).
+
+### New features
+
+- Added new optimization problem object (`utils.OptimizationProblem`) as main interface for defining optimization problems with functionality to 1) export the standard form for LP / QP, 2) directly interface Gurobi for better performance with large problems.
+- Overhead line types can now be defined in terms of conductor data and geometric arrangement (Arif Ahmed).
+- Added local-approximation variant for linear electric grid model.
+- Added linear model set for electric grid model, which enables defining separate linear models for each time step.
+- Added power flow solution set, to obtain power flow solutions more conveniently for multiple time steps.
+- Added pre-solve method for DER model set, to obtain baseline nominal power time series for flexible DERs.
+
+### Changes
+
+- Improved / simplified `define_optimization...()` methods for most use cases.
+- Revised `define_optimization...()` methods for new optimization problem object.
+- Switched from `multiprocess` to `ray` for parallel processing for performance reasons.
+- Revised documentation structure, overhauled the architecture documentation and added the configuration reference.
+
+## [v0.4.1](https://github.com/mesmo-dev/mesmo/releases/tag/v0.4.1)
+
+### Fixes
+
+- Updated `environment.yml`.
+- Updated version indicators.
+
+## [v0.4.0](https://github.com/mesmo-dev/mesmo/releases/tag/v0.4.0)
+
+### New features
+
+- Added problems module with definitions for nominal operation problem (simulation) and optimal operation problem (optimization).
+- Added high-level API for executing optimal & nominal operation problems.
+- Added various DER models.
+- Enabled most DERs for thermal grids (Verena Kleinschmidt).
+- Added ability to define electric grid model as single-phase-approximate.
+- Added Z-Bus power flow solution method (Arif Ahmed).
+- Added plots module (work-in-progress).
+- Added ability to set local configuration with `config.yml`.
+- Added ability to set base units for apparent power, voltage and thermal power for in scenario definition.
+
+### Changes
+
+- Moved implementation of optimization problems from Pyomo to CVXPY for performance improvements.
+- Reformulated optimization constraints to use normalized values for improved numerical performance.
+- Improved MESMO definition data format documentation.
+- Refactored DER model data definition format.
+- Refactored price data object.
+- Various fixes in linear electric grid model model and DLMP calculations.
+- Introduced various error messages for common issues.
+
+## [v0.3.0](https://github.com/mesmo-dev/mesmo/releases/tag/v0.3.0)
+
+### New features
+
+- Moved to Python as main implementation language.
+- Extended linear electric models with methods for defining optimization variables / constraints.
+- Added thermal grid model.
+- Added linear thermal grid model with methods for defining optimization variables / constraints.
+- Added DER models and integrated CoBMo for flexible building models.
+- Added methods for defining operation limits and obtaining DLMPs for electric and thermal grids.
+- Provided various example scripts for running optimal operation problems for DERs / electric grids / thermal grids / multi-energy grids.
+
+## [v0.2.0](https://github.com/mesmo-dev/mesmo/releases/tag/v0.2.0)
+
+### Auxiliary Release
+
+- Snapshot before moving to Python as main implementation language.
+
+## [v0.1.0](https://github.com/mesmo-dev/mesmo/releases/tag/v0.1.0)
+
+### Initial release
+
+- Initial set of modules with Julia as main implementation language.

0.5.0/_sources/configuration_reference.md.txt

@@ -0,0 +1,163 @@
+# Configuration reference
+
+```{important}
+This reference is work in progress.
+```
+
+The MESMO configuration is defined via `config.yml`. As an initial user, you likely do not need to modify the configuration.
+
+## Configuration workflow
+
+An empty `config.yml` is created during the first runtime of MESMO. To define the local configuration, simply insert and modify configuration parameters from the references below.
+
+<img src="assets/configuration_file_structure.png" alt="" class="invert"/>
+
+**Figure: Configuration file location.**
+
+MESMO distinguishes 1) local configuration in `config.yml` and 2) default configuration in `config_default.yml`. The local configuration takes precedence over the default configuration. That means, during initialization, `get_config()` first reads the default configuration from `config_default.yml` and then redefines any parameters that have been modified in `config.yml`.
+
+<img src="assets/configuration_workflow.png" alt="" class="invert"/>
+
+**Figure: Configuration initialization workflow.**
+
+The following sections serve as a reference for configuration parameters. Please note that key / value pairs are defined in a nested structure for each configuration type. This nested structure needs to be replicated for key / value pairs in `config.yml`.
+
+```{important}
+Please only modify `config.yml`, but do not make changes to `config_default.yml`.
+```
+
+## Path configuration
+
+### Default values
+
+```yaml
+paths:
+  data: ./data
+  database: ./data/database.sqlite
+  results: ./results
+  additional_data: []
+  ignore_data_folders: []
+  cobmo_additional_data: []
+```
+
+### Configuration keys
+
+- `data`: Defines the main data directory, i.e. the location of the CSV input files which are imported by {func}`mesmo.data_interface.recreate_database()`. Can be given as absolute path or relative path to `./`¹. Defaults to the data directory that is included with the MESMO repository. If you want to include additional data from other directories, please see `additional_data` below.
+- `database`: Defines the file path for the internal SQLITE database. Can be given as absolute path or relative path to `./`¹. This file will be created by {func}`mesmo.data_interface.recreate_database()`, if it does not exist.
+- `results`: Defines the main results directory, i.e. the directory where results outputs are stored. This parameter is used as base path in {func}`mesmo.utils.get_results_path()`. Defaults to the results directory in the MESMO repository.
+- `additional_data`: Defines list of supplementary data directories, which are imported in addition to the main data directory by {func}`mesmo.data_interface.recreate_database()`. Should be defined as list of absolute or relative paths to `./`¹.
+- `ignore_data_folders`: Defines a list of directory names that are excluded during import by {func}`mesmo.data_interface.recreate_database()`. Should be defined as list of folder names to exclude, but does accept full paths.
+- `cobmo_additional_data`: Defines list of supplementary data directories for the `cobmo` submodule, similar to `additional_data` above.
+
+¹ In the path parameters, `./` denotes the MESMO repository base directory as reference for relative path definitions.
+
+### Using additional data directories
+
+As an example, additional data from folders `supplementary_data` and `project_data` adjacent to the MESMO repository base directory can be defined with the following configuration snippet:
+
+```yaml
+paths:
+  additional_data: [
+    ./../supplementary_data,
+    ./../project_data
+  ]
+```
+
+## Optimization solver configuration
+
+### Default values
+
+```yaml
+optimization:
+  solver_name: gurobi
+  solver_interface: direct
+  show_solver_output: true
+  time_limit:
+```
+
+### Configuration keys
+
+- `solver_name`: Defines the optimization solver. Choices are 'gurobi' or any valid solver name [for CVXPY](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver). Solver name should be defined in lower caps.
+- `solver_interface`: Defines the interface for sending the optimization problem to the solver. Choices are 'direct' or 'cvxpy'. If 'direct', MESMO will use a direct solver interface, which is currently only implemented for Gurobi. If no direct solver interface is available for the selected solver, MESMO will automatically fall back to CVXPY. If 'cvxpy', MESMO will always use CVXPY without checking for a direct solver interface. If not defined, will use 'direct'.
+- `time_limit`: Solver time limit in seconds. If not defined, the value is set to infinite. Currently only implemented for Gurobi and CPLEX.
+- `show_solver_output`: Choices are 'true' or 'false'. If 'true', activate verbose solver output. If 'false', silence any solver outputs.
+
+### Setting CPLEX as optimization solver
+
+As an example, [CPLEX](https://www.ibm.com/analytics/cplex-optimizer) can be defined as the optimization solver with the following configuration snippet:
+
+```yaml
+optimization:
+  solver_name: cplex
+  solver_interface: cvxpy
+```
+
+Note that CPLEX is interfaced through CVXPY, because there is currently no direct interface implemented in MESMO. This requires CPLEX to be installed [as per CVXPY instructions](https://www.cvxpy.org/install/index.html#install-with-cplex-support).
+
+## Multiprocessing configuration
+
+MESMO enables multiprocessing, i.e. parallel processing, of subtasks that are enabled for parallelization via {func}`mesmo.utils.starmap()`. This can be useful when running very large scenarios, but requires additional computational overhead for starting up and maintaining a pool of parallel workers. Therefore, this feature is disabled by default and not recommended when running small test cases.
+
+### Default values
+
+```yaml
+multiprocessing:
+  run_parallel: false
+  cpu_share: 1.0
+```
+
+### Configuration keys
+
+- `run_parallel`: Enables / disables multiprocessing. Disabled by default and not recommended when running small scenarios.
+- `cpu_share`: Defines the share of CPU cores to be used for parallel processing. Can be used to limit the system loading, e.g. on shared workstations.
+
+## Logging and tests configuration
+
+### Default values
+
+```yaml
+logs:
+  level: info
+  format: '%(asctime)s | %(levelname)s | %(message)s'
+tests:
+  scenario_name: singapore_6node
+```
+
+### Configuration keys
+
+- `level`: Defines the logging level for the [Python logging facility](https://docs.python.org/3/howto/logging.html). Choices: `debug`, `info`, `warn`. All log messages at or above the selected log level are printed, in the following order `debug` < `info` < `warn`.
+- `format`: Defines the format of the log message output. See [here](https://docs.python.org/3/library/logging.html#formatter-objects) and [here](https://docs.python.org/3/library/logging.html#logrecord-attributes) for additional information on how to define the format string.
+- `scenario_name`: Defines the scenario which is used when running automated testing scripts in the `tests` directory and some of the example scripts in the `examples` directory.
+
+## Plot configuration
+
+### Default values
+
+```yaml
+plots:
+  matplotlib_style: seaborn-colorblind
+  matplotlib_colormap: viridis_r
+  matplotlib_font_family: ['Arial', 'Helvetica']
+  matplotlib_figure_size: [7.0, 4.0]
+  plotly_font_family: Arial
+  plotly_font_size: 15
+  plotly_figure_width: 1000
+  plotly_figure_height: 500
+  file_format: png
+  add_basemap: false
+  show_basemap_attribution:
+```
+
+### Configuration keys
+
+- `matplotlib_style`: Defines the style template for matplotlib plots.
+- `matplotlib_colormap`: Defines the colormap for matplotlib plots.
+- `matplotlib_font_family`: Defines the fonts for matplotlib plots.
+- `matplotlib_figure_size`: Defines the figure size for matplotlib plots in inch.
+- `plotly_font_family`: Defines the font for plotly plots.
+- `plotly_font_size`: Defines the font size for plotly plots.
+- `plotly_figure_width`: Defines the figure width for plotly plots in pixels.
+- `plotly_figure_height`: Defines the figure height for plotly plots in pixels.
+- `file_format`: Defines the file format for matplotlib / plotly plots.
+- `add_basemap`: If True, add basemap layer to static grid plots for orientation. Requires installation of `contextily`.
+- `show_basemap_attribution`: If True, show copyright notice for basemap.

0.5.0/_sources/contributing.md.txt

@@ -0,0 +1,71 @@
+# Contributing
+
+If you are keen to contribute to this project, please follow these guidelines:
+
+- Before making any change, please first discuss via issue or email with the owners of this repository.
+- Development is based on Python 3.8.
+- Git branches follow the [GitFlow principle](https://nvie.com/posts/a-successful-git-branching-model/).
+- Release versioning follows the [Semantic Versioning principle](https://semver.org/).
+
+## Git branches
+
+Based on the [GitFlow principle](https://nvie.com/posts/a-successful-git-branching-model/) there are the following branches:
+
+1. `master` - Contains stable release versions of the repository. Only admins should send pull requests / commits to `master` when 1) fixing a critical bug or 2) publishing a new release.
+2. `develop` - This branch is intended as the main branch for development or improvement of features. Anyone can send pull requests to `develop`.
+3. `feature/xxx` - This branch is dedicated to developing feature `xxx`. The idea is to keep development or improvement works separate from the main `develop` branch. Once the work is finished, a pull request is created for feature `xxx` to be merged back into the `develop` branch.
+
+## Release versioning
+
+Every time the `master` branch changes, a new version number is defined according to the [Semantic Versioning principle](https://semver.org/):
+
+1. New releases cause a changing version number in the first digit for major changes and in the second digit for minor changes (e.g. from 0.1.13 -> 0.2.0).
+2. Bugfixes cause a changing version number in the third digit (eg. from 0.1.12 -> 0.1.13)
+
+## Style guide
+
+- Follow the [PEP 8 Style Guide](https://www.python.org/dev/peps/pep-0008/) and check [this PEP8 Explainer](https://realpython.com/python-pep8/).
+- Variable / function / object / class / module names:
+    - Names are verbose and avoid abbreviations.
+    - Variable / function / object names are in lowercase and underscore_case (all letters are lowercase and all words are separated by underscores).
+    - Variable / object names start with a lowercase letter.
+    - Class / module names start with an uppercase letter and are in CamelCase (all letters are lowercase except for the first letter of new words).
+- Paths:
+    - Use relative paths.
+    - Use `os.join.path("x", "y")` instead of `"x/y"`.
+- Docstrings / comments:
+    - Docstrings should at minimum contain a short description of the function / class / module.
+    - Docstrings and comments should only contain full sentences which conclude with a full stop (dot).
+    - Docstrings follow [Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
+- Exceptions / errors / warnings / debug info:
+    - Use proper logging tools instead of `print("Error: ...")`.
+    - Use [logging](https://docs.python.org/3.6/library/logging.html) like `logger.error("...")` or `logger.warning("...")` or `logger.debug("...")`.
+- Line length:
+    - Line lengths should not exceed 120 characters.
+- Line breaks:
+    - Use brackets to contain content spanning multiple lines.
+    - Do not use the `\` symbol for line breaks.
+- Quotes / strings:
+    - Use single quotes `'...'` for parameters, indexes, pathes and use double quotes `"..."` for content, messages and docstrings.
+- Results / output files:
+    - Store results / output files only in the `results` directory.
+    - The results path should be obtained with `mesmo.utils.get_results_path()`
+    - The content of the `results` directory should remain local, i.e., it should be ignored by Git and should not appear in any commits to the repository.
+
+## Release checklist
+
+Before pushing a new commit / release to the `master` branch, please go through the following steps:
+
+1. Run tests locally and ensure that all tests complete successfully.
+2. Ensure that change log entry has been added for this version in `docs/change_log.md`.
+3. Ensure that version numbers and year numbers have been updated everywhere:
+    - `setup.py` (at `version=`)
+    - `docs/change_log.md`
+    - `docs/conf.py` (at `copyright =`)
+    - `CITATION.bib`
+    - `LICENSE`
+4. After pushing a new commit / release, create a tag and publish a new release on Github: <https://github.com/mesmo-dev/mesmo/releases>
+5. After publishing a new release, edit the latest Zenodo entry: <https://doi.org/10.5281/zenodo.3562875>
+    - Set title to "MESMO - Multi-Energy System Modeling and Optimization".
+    - Set correct author names.
+    - Set license to "MIT License".