Initial commit of public branch of the SecMOD framework

.gitignore

+.vscode
+.vscode/tags
+SecMOD.egg-info
+secmod/__pycache__
+doc/source/_build
+tests/downloads
+docs/_build/
+logs
\ No newline at end of file

.gitlab-ci.yml

+pages:
+  stage: deploy
+  tags: 
+  - anaconda
+  - sphinx
+  - sphinx-rtd-theme
+  - windows
+  variables:
+    GIT_SUBMODULE_STRATEGY: recursive
+  before_script:
+  - git submodule sync --recursive
+  - git submodule update --init --recursive --remote
+  script:
+  - C:\Anaconda3\shell\condabin\conda-hook.ps1
+  - conda activate
+  - python setup.py install_egg_info
+  - pip install --user -e .
+  - $dir = Get-Location
+  - $pubdir = ($dir.ToString() + "\public")
+  - $docsdir = ($dir.ToString() + "\docs")
+  - Rename-Item -Path "SecMOD" -NewName "SecMODTemp"
+  - Rename-Item -Path "SecMODTemp" -NewName "secmod"
+  - New-Item -ItemType Directory -Force -Path "WD"
+  - cd "WD"
+  - python -m secmod.setup
+  - sphinx-build -b html $docsdir $pubdir
+  artifacts:
+    paths:
+    - public
+  only:
+  - master

.gitmodules

+

CONTRIBUTING.md

+# Contributing
+
+You are interested in contributing to SecMOD? We appreciate any contributions!
+
+## Reporting issues
+
+Please note that the issue tracker is not for questions. Please use other platforms, such as Stack Overflow
+instead. Make sure to tag your question with SecMOD tag.
+
+If possible, before submitting an issue report, try to verify that the issue
+hasen't already been fixed and is not a duplicate.
+
+## Submitting code
+
+If you contribute code to SecMOD, you agree to license your code under the MIT.
+
+The new code should follow PEP8 coding style (except the line length limit,
+which is 90) and adhere to the style of the surrounding code.
+
+You should preferably use atomic (very small) commits for your changes. Read more
+about why and how [here](https://www.freshconsulting.com/atomic-commits/).
+
+You must follow some simple formatting rules for your commit messages, which can
+be found [here](https://chris.beams.io/posts/git-commit/)
+
+

LICENSE.txt

+Copyright © 2022 Christiane Reinert (a), Lars Schellhas (a), Jacob Mannhardt (a), David Yang Shu (b), Andreas Kämper (b), Nils Baumgärtner (a), Sarah Deutz (a), and André Bardow (b,c).
+(a) Institute of Technical Thermodynamics, RWTH Aachen University, Aachen, Germany.
+(b) Energy & Process Systems Engineering, Department of Mechanical and Process Engi-
+neering, ETH Zurich, Zürich, Switzerland.
+(c) Institute of Energy and Climate Research – Energy Systems Engineering (IEK-10),
+Forschungszentrum Jülich, Jülich, Germany.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

MANIFEST.in

+# Include the README
+include *.md
+
+# Include the license file
+include LICENSE.txt
+
+# Include the data files
+recursive-include data *

README.md

+# SecMOD - A framework for multi-energy system optimization and life-cycle assessment 
+The SecMOD framework is a flexible framework for the optimization and life-cycle assessment of linear multi-sector systems. 
+
+## Referencing
+
+If you use our software or any part of it, please cite:
+
+Reinert, C.; Schellhas, L.; Mannhardt, J.; Shu, D.; Kämper, A.; Baumgärtner, N.; Deutz, S., and Bardow, A. (2022): "SecMOD: An open-source modular framework
+combining multi-sector system optimization and life-cycle assessment". Frontiers in Energy Research. DOI: 10.3389/fenrg.2022.884525.
+
+## License
+This project is licensed under the MIT license, for more information please refer to the license file.
+
+## Documentation and Support 
+**Please find the full documentation of the SecMOD framework [here](https://ltt.pages.git-ce.rwth-aachen.de/opt/secmod/secmod/).**
+
+If you need help with Git, please refer to the git documentation [here](https://git-scm.com/docs).
+
+[![pipeline status](https://git-ce.rwth-aachen.de/ltt/secmod/secmod/badges/master/pipeline.svg)](https://git-ce.rwth-aachen.de/ltt/secmod/secmod/commits/master)
+ <a href="https://git-ce.rwth-aachen.de/ltt/opt/secmod/secmod/-/commits/master"><img alt="pipeline status" src="https://git-ce.rwth-aachen.de/ltt/opt/secmod/secmod/badges/master/pipeline.svg" /></a> 
+
+## Installation
+A brief instruction to install SecMOD can also be found below:
+Clone a copy of the whole repository to your computer:
+```
+git clone git@git-ce.rwth-aachen.de:ltt/secmod/secmod.git
+```
+
+Open a terminal with a python enviroment (e.g. Anaconda promt) and install the secmod package with:
+```shell
+pip install --user -e '<Path\to\cloned\repository>'
+``` 
+The path should point to the directory where secmod is saved (repository folder).
+Make sure that the setup.py file is located in your repository folder. You can use this installation for several projects in multiple working directories.
+
+For further installation instruction please go [here](https://ltt.pages.git-ce.rwth-aachen.de/opt/secmod/secmod/usage/installation.html). The code was tested with Python 3.7.5. 
+## First Steps
+
+Create a working directory for the optimization framework. Next, cd to that directory and enter
+```shell
+python -m secmod.setup
+```
+in the terminal. This sets up the right folder structure. 
+Start the optimization with double clicking the start.bat file, where you can choose your enviroment or 
+alternatively use 
+
+```shell
+python -m secmod
+```
+to start. 
+
+
+
 

docs/conf.py

+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'SecMOD'
+copyright = '2022, Institute of Technical Thermodynamics, RWTH Aachen University'
+author = 'Institute of Technical Thermodynamics, RWTH Aachen University'
+
+# The short X.Y version
+version = '2.0'
+# The full version, including alpha/beta/rc tags
+release = ''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.todo',
+]
+
+# Add private methods to autodoc
+autodoc_default_options = {
+    'members': None,
+    'member-order': 'bysource',
+    'private-members': None,
+    'undoc-members': None
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'SecMODdoc'
+todo_include_todos = True
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'SecMOD.tex', 'SecMOD Documentation',
+     'Institute of Technical Thermodynamics, RWTH Aachen University', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'secmod', 'SecMOD Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'SecMOD', 'SecMOD Documentation',
+     author, 'SecMOD', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------

docs/index.rst

+.. SecMOD documentation master file, created by
+   sphinx-quickstart on Thu Apr 25 15:42:33 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to SecMOD's documentation!
+==================================
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents
+
+    usage/quickstart
+    usage/installation
+    usage/data
+    usage/developer_reference
+    usage/packages
+    usage/troubleshooting
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/usage/data.rst

+==============
+Data in SecMOD
+==============
+Plese refer to our publication for a detailled description of required data:
+Reinert, C.; Schellhas, L.; Mannhardt, J.; Shu, D.; Kämper, A.; Baumgärtner, N.; Deutz, S., and Bardow, A. (2022): "SecMOD: An open-source modular framework
+combining multi-sector system optimization and life-cycle assessment". Frontiers in Energy Research. DOI: 10.3389/fenrg.2022.884525 .
+
+Input data
+==================================
+Input data is used to model a given multi-sector system with the desired spatial, technical and temporal resolution. Input data can be added manually in the sampledata folder or in some cases be obtained automatically from open webpages, such as the open power system database by the scripts in sampledata/00-EXTERNAL.
+
+.. image:: ../img/secmod_scheme.svg
+
+Units in SecMOD
+==================================
+SecMOD employs unitizing to automatically convert units. All units used in the model must be defined in the sample data file.
+
+Output data and evaluation
+==================================
+The objective of the optimization is to determine an optimal design and operation of the multi-sector system according to the given objective and constraints. 
+The output data of the optimization is saved in the working directory in `01-MODEL-RESULTS/InvestmentModel_year.pickle`. 
+Usually, the evaluation will start automatically. To start the evaluation without the optimization, type::
+
+    python -m secmod.evaluation
+
+This will open a graphical user interface (GUI). 
+In the user interface, the capacity, product flows, and impacts can be shown for all products in different plot types. Clicking on a capacity will open a second layer to investigate the construction years. Further, all raw results are shown as a table next to the plot.
+The data can be exported in several formats including tikz, png, xlsx and pdf.
+
+

docs/usage/developer_reference.rst

+===================
+Developer reference
+===================
+
+
+secmod.classes module
+=====================
+
+.. automodule:: secmod.classes
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+secmod.data\_preprocessing module
+=================================
+
+.. automodule:: secmod.data_preprocessing
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+secmod.data\_processing module
+==============================
+
+.. automodule:: secmod.data_processing
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+secmod.evaluation module
+========================
+
+.. automodule:: secmod.evaluation
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+secmod.helpers module
+=====================
+
+.. automodule:: secmod.helpers
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+secmod.optimization module
+==========================
+
+.. automodule:: secmod.optimization
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+secmod.setup module
+===================
+
+.. automodule:: secmod.setup
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+===============
+
+.. automodule:: secmod
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/usage/installation.rst

+============
+Installation
+============
+
+The installation of SecMOD is easily done.
+If you want to edit its source code, you need to
+follow :ref:`editable-installation`.
+If you just want to use the published package,
+follow :ref:`package-installation`.
+
+
+.. _editable-installation:
+
+Editable Installation
+=====================
+
+To edit the source code and therefore contribute to the development of SecMOD,
+you need to clone the `repository <https://git.rwth-aachen.de/ltt/secmod/secmod>`_
+to your local machine **recursively**. Using SSH as authentication to the git server
+the following command needs to be used::
+
+    git clone --recurse-submodules -j8 git@git-ce.rwth-aachen.de:ltt/opt/secmod/secmod.git 01-SecMOD
+
+.. NOTE:: If you don´t know yet how to clone a repository have a
+    look `here <https://git.rwth-aachen.de/help/#new-to-git-and-gitlab>`_.
+    Make sure that you have Python already installed on your PC.
+
+After the clone process is completed, open a python terminal e.g. in your 
+IDE (Visual Studio Code, Spyder, ...) or the Anaconda prompt.
+Afterwards you can install SecMOD in form of your local repository by using the
+following install command::
+
+    pip install --user -e PATH
+
+.. NOTE:: The PATH at the end of the command stands for the directory
+    of your local repository. You can either use an absolute path or
+    a path relative to the currently active directory of the terminal.
+
+Your local repository should now be installed, if no errors occurred during the process.
+You can now proceed to the :doc:`quickstart <quickstart>` guide to complete your setup. 
+
+.. _package-installation:
+
+Package Installation
+====================
+
+.. error:: SecMOD is not yet packaged and therefore not available through PyPI.
+    Use the :ref:`editable-installation` instead.
+
+    See `Issue 13 <https://git.rwth-aachen.de/ltt/secmod/secmod/issues/13>`_
+    for further information about the packaged distribution of SecMOD.
+
+If you don´t need to edit the source code of the SecMOD package,
+but just want to use the modules, you can install the package directly
+from PyPi using the following command::
+
+    pip install secmod
+
+SecMOD should now be installed, if no errors occurred during the process.
+You can now proceed to the :doc:`quickstart <quickstart>` guide to complete your setup. 

docs/usage/packages.rst

+====================
+Packages in SecMOD
+====================
+
+.. csv-table::
+    :widths: auto
+    :header: Package name, Usage, Link
+
+    Pyomo, Optimization, https://www.pyomo.org/
+    Numpy, Scientific Computing, https://numpy.org/
+    Pandas, Scientific Computing, https://pandas.pydata.org/
+    Scipy, Scientific Computing, https://www.scipy.org/
+    datapackage, Datamanagement, https://frictionlessdata.io/docs/using-data-packages-in-python/
+    geopy, Geocoordinates/distances, https://github.com/geopy/geopy
+    pint, Unit-Handling, https://pint.readthedocs.io/en/latest/
+    pathlib, , https://docs.python.org/3/library/pathlib.html
+    requests, Network, https://3.python-requests.org/
+    clint, Terminal-Visualation, https://github.com/kennethreitz/clint
+    tikzplotlib, Visualization, https://github.com/nschloe/tikzplotlib
+    sympy, , https://www.sympy.org/en/index.html
+    tsam, Scientific Computing, https://github.com/FZJ-IEK3-VSA/tsam
+    pandastable, Visualization, https://pandastable.readthedocs.io/en/latest/description.html

docs/usage/quickstart.rst

+==========
+Quickstart
+==========
+
+In order to improve the distributability of SecMOD the package code is
+separated from the handled input data. This allows to use a single installation
+of SecMOD for several projects or scenarios in multiple working directories.
+
+To get started with SecMOD, the following two steps must be completed:
+
+1. :doc:`Installation of SecMOD <installation>`
+2. :ref:`Set up a working directory <setupWD>`
+
+For the first step follow the instructions for the :doc:`installation of SecMOD <installation>`.
+Afterwards return to :ref:`Step 2 <setupWD>` to set up your first working directory.
+
+.. _setupWD:
+
+Set up a working directory
+==========================
+
+Create a new directory where you want. Note that this directory will contain all
+input and results data and can become large in size, depending on the size of your
+examined model.
+
+1. Open a terminal with an activated Python environment (e.g. Anaconda prompt)!
+2. Navigate to your newly created directory in the terminal (e.g. "cd D:/WorkingDirectory")!
+3. Run the command "python -m secmod.setup" in the terminal!
+
+SecMOD will now create the necessary folders for the input data and furthermore copy the
+sample data provided in the SecMOD repository.
+Afterwards all necessary data to run SecMOD is available in the working directory. Furthermore,
+a file called "start.bat" is created at the top level of your working directory.
+This file allows you to start SecMOD with a simple double click. Depending on your Python
+installation, you might need to edit the file (right click > edit) according to the instructions.
+
+If you encounter problems during the automatic setup, please refer to :doc:`Troubleshooting <troubleshooting>`.

docs/usage/troubleshooting.rst

+===============
+Troubleshooting
+===============
+
+SecMOD is programmed to handle most things internally, if possible.
+If you still encounter an error, SecMOD mostly provides you with an error message
+which should help to resolve the issue. 

sampledata/00-EXTERNAL/README.md

+# README - 00-EXTERNAL
+
+This directory contains a data package "external_data_packages", which has links
+to the sources of some useful external data: the open power system data (OPSD) platform. In our current work, we included their data on existing conventional and renewable power plants in Germany. Please refer to the folder "external data packages" for the script we used.
+
+Please note that in some cases, updates on the script might be necessary if the data format on the OPSD platform changes.
+
+Furthermore all external data packages are downloaded to this directory. The downloaded
+data packages should not be modified, since the modifications will be overwritten,
+if an update of the external data packages is available from the source.