diff --git a/README.md b/README.md index a0ad77fc..63a8067e 100644 --- a/README.md +++ b/README.md @@ -8,19 +8,21 @@ [![PyPI - License](https://img.shields.io/pypi/l/FINE)](https://github.com/FZJ-IEK3-VSA/FINE/blob/master/LICENSE.txt) [![codecov](https://codecov.io/gh/FZJ-IEK3-VSA/FINE/branch/master/graph/badge.svg)](https://codecov.io/gh/FZJ-IEK3-VSA/FINE) -Forschungszentrum Juelich Logo +Forschungszentrum Juelich Logo -The ETHOS.FINE python package provides a framework for modeling, optimizing and assessing energy systems. With the provided framework, systems with multiple regions, commodities, time steps and investment periods can be modeled. Target of the optimization is the minimization of the systems net present value while considering technical and environmental constraints. Besides using the full temporal resolution, an interconnected typical period storage formulation can be applied, that reduces the complexity and computational time of the model. +The ETHOS.FINE python package provides a framework for modeling, optimizing and assessing energy systems. With the provided framework, systems with multiple regions, commodities, time steps and investment periods can be modeled. Target of the optimization is the minimization of the systems net present value (NPV) while considering technical and environmental constraints. If only one investment period is considered, the net present value is equal to the total annual costs (TAC). Besides using the full temporal resolution, an interconnected typical period storage formulation can be applied, that reduces the complexity and computational time of the model. This Readme provides information on the installation of the package. For further information have a look at the [documentation](https://vsa-fine.readthedocs.io/en/latest/). -ETHOS.FINE is used for the modelling of a diverse group of optimization problems within the [Energy Transformation PatHway Optimization Suite (ETHOS) at IEK-3](https://www.fz-juelich.de/de/iek/iek-3/leistungen/model-services). +ETHOS.FINE is used for the modelling of a diverse group of optimization problems within the [Energy Transformation PatHway Optimization Suite (ETHOS) at ICE-2](https://www.fz-juelich.de/de/ice/ice-2/leistungen/model-services). If you want to use ETHOS.FINE in a published work, please [**kindly cite following publication**](https://www.sciencedirect.com/science/article/pii/S036054421830879X) which gives a description of the first stages of the framework. The python package which provides the time series aggregation module and its corresponding literature can be found [here](https://github.com/FZJ-IEK3-VSA/tsam). -## Installation from conda-forge +## Installation +There are several options for the installation of ETHOS.FINE. You can install it via PyPI or from conda-forge. +For detailed information, have a look at the [installation documentation](https://vsa-fine.readthedocs.io/en/latest/installationDoc.html). -If you would like to run ETHOS.FINE for your analysis we recommend to install it directly from conda-forge into a new Python environment with +If you would like to use ETHOS.FINE for your analysis, we recommend to install it directly from conda-forge into a new Python environment with ```bash mamba create --name fine --channel conda-forge fine @@ -28,52 +30,9 @@ mamba create --name fine --channel conda-forge fine **Note on Mamba vs.Conda:** `mamba` commands can be substitued with `conda`. We highly recommend using [(Micro-)Mamba](https://mamba.readthedocs.io/en/latest/) instead of Conda. The recommended way to use Mamba on your system is to install the [Miniforge distribution](https://github.com/conda-forge/miniforge#miniforge3). They offer installers for Windows, Linux and OS X. In principle, Conda and Mamba are interchangeable. The commands and concepts are the same. The distributions differ in the methodology for determining dependencies when installing Python packages. Mamba relies on a more modern methodology, which (with the same result) leads to very significant time savings during the installation of ETHOS.FINE. Switching to Mamba usually does not lead to any problems, as it is virtually identical to Conda in terms of operation. -**Note on the solver:** The mamba/conda installation comes with [GLPK](https://www.gnu.org/software/glpk/) [(installation for Windows)](https://sourceforge.net/projects/winglpk/files/latest/download) as Mixed Integer Linear Programming (MILP) solver. If you want to solve large problems it is highly recommended to install [GUROBI](http://www.gurobi.com/). See ["Installation of an optimization solver"](#installation-of-an-optimization-solver) for more information. +**Note on the solver:** +The functionality of ETHOS.FINE depends on the following C libraries that need to be installed on your system. If you do not know how to install those, consider installing from conda-forge. The mamba/conda installation comes with [GLPK](https://www.gnu.org/software/glpk/) [(installation for Windows)](https://sourceforge.net/projects/winglpk/files/latest/download) as Mixed Integer Linear Programming (MILP) solver. If you want to solve large problems it is highly recommended to install [GUROBI](http://www.gurobi.com/). See ["Installation of an optimization solver"](https://vsa-fine.readthedocs.io/en/latest/installationDoc.html#installation-of-an-optimization-solver) in the documentation for more information. -## Installation from pipy - -The functionality of ETHOS.FINE depends on the following C libraries that need to be installed on your system. If you do not know how to install those, consider installing from conda-forge. - -- [GLPK](https://www.gnu.org/software/glpk/) -- [GDAL](https://gdal.org/index.html) - -Create a virtual environment in the ETHOS.FINE folder and activate it - -```bash -python -m venv .venv -source .venv/bin/activate -``` - -Install ETHOS.FINE with - -```bash -python -m pip install fine -``` - -### Installation of an optimization solver - -ETHOS.FINE requires an MILP solver which can be accessed using [PYOMO](https://pyomo.readthedocs.io/en/stable/index.html). It searches for the following solvers in this order: - -#### [GUROBI](http://www.gurobi.com/) - -This solver is recommended due to better performance but requires license (free academic version available). It is set as the default solver. - -The installation requires the following three components: - -- Gurobi Optimizer - - In order to [download](https://www.gurobi.com/downloads/gurobi-optimizer-eula/) the software you need to create an account and obtain a license. -- Gurobi license - - The license needs to be installed according to the instructions in the registration process. -- Gurobi python api - - The python api can be installed according to [this instruction](https://support.gurobi.com/hc/en-us/articles/360044290292-How-do-I-install-Gurobi-for-Python-). - -#### [GLPK](https://sourceforge.net/projects/winglpk/files/latest/download) - -This solver is installed with the ETHOS.FINE environment. A complete installation instruction for Windows can be found [here](http://winglpk.sourceforge.net/). - -#### [CBC](https://projects.coin-or.org/Cbc) - -Installation procedure can be found [here](https://projects.coin-or.org/Cbc). ## Examples @@ -104,36 +63,11 @@ A number of [examples](https://github.com/FZJ-IEK3-VSA/FINE/tree/develop/example - [11_Partload](https://github.com/FZJ-IEK3-VSA/FINE/tree/develop/examples/11_Partload) - In this application, a hydrogen system is modeled and optimized considering partload behavior of the electrolyzer. -## Notes for developers - -### Editable install from conda-forge - -It is recommended to create a clean environment with conda to use ETHOS.FINE because it requires many dependencies. - -```bash -mamba env create --name fine --file requirements_dev.yml -mamba activate fine -``` - -Install ETHOS.FINE as editable install and without checking the dependencies from pypi with - -```bash -python -m pip install --no-deps --editable . -``` - -### Editable install from pypi - -If you do not want to use conda-forge consider the steps in section [Installation from pipy](#Installation-from-pipy) and install ETHOS.FINE as editable install and with developer dependencies with - -```bash -python -m pip install --editable .[develop] -``` - ## License MIT License -Copyright (C) 2016-2024 FZJ-IEK-3 +Copyright (C) 2016-2024 FZJ-ICE-2 Active Developers: Theresa Groß, Kevin Knosala, Noah Pflugradt, Johannes Behrens, Julian Belina, Arne Burdack, Toni Busch, Philipp Dunkel, David Franzmann, Patrick Freitag, Thomas Grube, Heidi Heinrichs, Maximilian Hoffmann, Jason Hu, Shitab Ishmam, Sebastian Kebrich, Felix Kullmann, Jochen Linßen, Rachel Maier, Shruthi Patil, Jan Priesmann, Julian Schönau, Maximilian Stargardt, Lovindu Wijesinghe, Christoph Winkler, Detlef Stolten @@ -145,9 +79,9 @@ If not, see https://opensource.org/licenses/MIT ## About Us -Institute image IEK-3 +Institute image ICE-2 -We are the Institute of Energy and Climate Research - Techno-economic Systems Analysis (IEK-3) belonging to the Forschungszentrum Jülich. Our interdisciplinary department's research is focusing on energy-related process and systems analyses. Data searches and system simulations are used to determine energy and mass balances, as well as to evaluate performance, emissions and costs of energy systems. The results are used for performing comparative assessment studies between the various systems. Our current priorities include the development of energy strategies, in accordance with the German Federal Government’s greenhouse gas reduction targets, by designing new infrastructures for sustainable and secure energy supply chains and by conducting cost analysis studies for integrating new technologies into future energy market frameworks. +We are the Institute of Climate and Energy Systems (ICE) - Jülich Systems Analysis belonging to the Forschungszentrum Jülich. Our interdisciplinary department's research is focusing on energy-related process and systems analyses. Data searches and system simulations are used to determine energy and mass balances, as well as to evaluate performance, emissions and costs of energy systems. The results are used for performing comparative assessment studies between the various systems. Our current priorities include the development of energy strategies, in accordance with the German Federal Government’s greenhouse gas reduction targets, by designing new infrastructures for sustainable and secure energy supply chains and by conducting cost analysis studies for integrating new technologies into future energy market frameworks. ## Contributions and Support Every contributions are welcome: diff --git a/docs/source/conf.py b/docs/source/conf.py index 2cc16a3b..44a62818 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -46,6 +46,7 @@ "sphinx.ext.viewcode", "sphinx.ext.githubpages", "myst_parser", + "sphinx.ext.autosectionlabel" ] inheritance_graph_attrs = dict( @@ -70,7 +71,7 @@ # General information about the project. project = "fine" -copyright = "2016-2023, FINE Developer Team" +copyright = "2016-2024, FINE Developer Team" author = "FINE Developer Team" # The version info for the project you're documenting, acts as replacement for diff --git a/docs/source/index.rst b/docs/source/index.rst index 8cf0f72e..b4125392 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,6 +10,7 @@ Home purposeAndVisionDoc + installationDoc usersGuideDoc newsDoc integratedSoftwareDoc diff --git a/docs/source/installationDoc.rst b/docs/source/installationDoc.rst new file mode 100644 index 00000000..d404db64 --- /dev/null +++ b/docs/source/installationDoc.rst @@ -0,0 +1,102 @@ +############ +Installation +############ + +There are several options for the installation of ETHOS.FINE. You can install it via PyPI or from conda-forge. +The provided framework enables you to create an optimization program based on your model constraints. +The optmizitation program is built by using `PYOMO `_. +To solve the program, ETHOS.FINE requires an MILP solver which can be accessed using `PYOMO `_. + +In the following, you find information on + +* how to install the package from conda-forge (:ref:`Installation from conda-forge`) +* how to install the package from PyPI (:ref:`Installation from PyPI`) +* how to install a solver (:ref:`Installation of an optimization solver`) + +Installation from conda-forge +***************************** + +If you would like to run ETHOS.FINE for your analysis we recommend to install it directly from conda-forge into a new Python environment with + +.. code-block:: bash + + mamba create --name fine --channel conda-forge fine + + +**Note on Mamba vs.Conda:** `mamba` commands can be substitued with `conda`. We highly recommend using `(Micro-)Mamba `_ instead of Conda. The recommended way to use Mamba on your system is to install the `Miniforge distribution `_ . They offer installers for Windows, Linux and OS X. In principle, Conda and Mamba are interchangeable. The commands and concepts are the same. The distributions differ in the methodology for determining dependencies when installing Python packages. Mamba relies on a more modern methodology, which (with the same result) leads to very significant time savings during the installation of ETHOS.FINE. Switching to Mamba usually does not lead to any problems, as it is virtually identical to Conda in terms of operation. + +**Note on the solver:** The mamba/conda installation comes with `GLPK `_ as Mixed Integer Linear Programming (MILP) solver. If you want to solve large problems it is highly recommended to install `GUROBI `_ . See :ref:`Installation of an optimization solver` for more information. + +To install an editable version of the code, it is recommended to create a clean environment, e.g., with conda to use ETHOS.FINE because it requires many dependencies. + +.. code-block:: bash + + mamba env create --name fine --file requirements_dev.yml + mamba activate fine + + +Install ETHOS.FINE as editable install and without checking the dependencies from PyPI with + +.. code-block:: bash + + python -m pip install --no-deps --editable . + + +Installation from PyPI +********************** + +The functionality of ETHOS.FINE depends on the following C libraries that need to be installed on your system. If you do not know how to install those, consider installing from conda-forge. + +- `GLPK `_ +- `GDAL `_ + +It is recommended to create a virtual environment. To do so, you can create a virtual environment with venv in the ETHOS.FINE folder + +.. code-block:: bash + + python -m venv .venv + +Find more information on creating virtual environments with venv `here `_ . + +Install ETHOS.FINE with + +.. code-block:: bash + + python -m pip install fine + +To install an editable version of the code, install ETHOS.FINE with + +.. code-block:: bash + + python -m pip install --editable .[develop] + +Installation of an optimization solver +************************************** + +ETHOS.FINE requires an MILP solver which can be accessed using `PYOMO `_. It searches for the following solvers in this order: + +GUROBI +====== + +The solver `GUROBI `_ is recommended due to better performance but requires license (free academic version available). It is set as the default solver. + +The installation requires the following three components: + +- Gurobi Optimizer + - In order to `download `_ the software you need to create an account and obtain a license. +- Gurobi license + - The license needs to be installed according to the instructions in the registration process. +- Gurobi python api + - The python api can be installed according to `this instruction `_ . + +GLPK +==== + +The solver `GLPK `_ is installed with the ETHOS.FINE environment. A complete installation instruction for Windows can be found `here `_ . + +CBC +=== + +Installation procedure for the solver `CBC `_ can be found `here `_ . + + diff --git a/docs/source/tutorialDoc.rst b/docs/source/tutorialDoc.rst index 3d9ed10e..0145c50f 100644 --- a/docs/source/tutorialDoc.rst +++ b/docs/source/tutorialDoc.rst @@ -2,30 +2,30 @@ Tutorial ******** -The repository of ETHOS.FINE provides a certain amount of different `examples ` to get to know to the package. +The repository of ETHOS.FINE provides a certain amount of different `examples `_ to get to know to the package. The examples are sorted by their complexity and should provide a good overview on the scope of the package. -* `00_Tutorial ` +* `00_Tutorial `_ * In this application, an energy supply system, consisting of two regions, is modeled and optimized. Recommended as starting point to get to know to ETHOS.FINE. -* `01_1node_Energy_System_Workflow ` +* `01_1node_Energy_System_Workflow `_ * In this application, a single region energy system is modeled and optimized. The system includes only a few technologies. -* `02_EnergyLand ` +* `02_EnergyLand `_ * In this application, a single region energy system is modeled and optimized. Compared to the previous examples, this example includes a lot more technologies considered in the system. -* `03_Multi-regional_Energy_System_Workflow ` +* `03_Multi-regional_Energy_System_Workflow `_ * In this application, an energy supply system, consisting of eight regions, is modeled and optimized. The example shows how to model multi-regional energy systems. The example also includes a notebook to get to know the optional performance summary. The summary shows how the optimization performed. -* `04_Model_Run_from_Excel ` +* `04_Model_Run_from_Excel `_ * ETHOS.FINE can also be run by excel. This example shows how to read and run a model using excel files. -* `05_District_Optimization ` +* `05_District_Optimization `_ * In this application, a small district is modeled and optimized. This example also includes binary decision variables. -* `06_Water_Supply_System ` +* `06_Water_Supply_System `_ * The application cases of ETHOS.FINE are not limited. This application shows how to model the water supply system. -* `07_NetCDF_to_save_and_set_up_model_instance ` +* `07_NetCDF_to_save_and_set_up_model_instance `_ * This example shows how to save the input and optimized results of an energy system Model instance to netCDF files to allow reproducibility. -* `08_Spatial_and_technology_aggregation ` +* `08_Spatial_and_technology_aggregation `_ * These two examples show how to reduce the model complexity. Model regions can be aggregated to reduce the number of regions (spatial aggregation). Input parameters are automatically adapted. Furthermore, technologies can be aggregated to reduce complexity, e.g. reducing the number of different PV components (technology aggregation). Input parameters are automatically adapted. -* `9_Stochastic_Optimization ` +* `9_Stochastic_Optimization `_ * In this application, a stochastic optimization is performed. It is possible to perform the optimization of an energy system model with different input parameter sets to receive a more robust solution. -* `10_PerfectForesight ` +* `10_PerfectForesight `_ * In this application, a transformation pathway of an energy system is modeled and optimized showing how to handle several investment periods with time-dependent assumptions for costs and operation. -* `11_Partload ` +* `11_Partload `_ * In this application, a hydrogen system is modeled and optimized considering partload behavior of the electrolyzer. \ No newline at end of file