diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 56e5910..0000000 --- a/.travis.yml +++ /dev/null @@ -1,14 +0,0 @@ -language: python -python: - - "3.9" -install: - - pip install -r requirements.txt - - pip install pytest - - pip install pytest-cov - - pip install codecov - - pip install --no-cache-dir -e . -script: - - pytest --cov=./tsam - -after_success: - - codecov \ No newline at end of file diff --git a/README.md b/README.md index 0577b50..9bf87d2 100644 --- a/README.md +++ b/README.md @@ -60,11 +60,12 @@ Initialize an aggregation object and define the length of a single period, the n aggregation = tsam.TimeSeriesAggregation(raw, noTypicalPeriods = 8, hoursPerPeriod = 24, - rescaleClusterPeriods = False, segmentation = True, + noSegments = 8, representationMethod = "distributionAndMinMaxRepresentation", distributionPeriodWise = False - clusterMethod = 'hierarchical') + clusterMethod = 'hierarchical' + ) ``` Run the aggregation to typical periods diff --git a/docs/Makefile b/docs/Makefile index 99156b8..8b324be 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,12 +1,12 @@ # Minimal makefile for Sphinx documentation # -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = tsam -SOURCEDIR = source -BUILDDIR = build +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = ./source +BUILDDIR = ./build # Put it first so that "make" without argument is like "make help". help: @@ -14,7 +14,12 @@ help: .PHONY: help Makefile +# Build, watch and serve docs with live reload +livehtml: + sphinx-autobuild -b html --host 0.0.0.0 --port 7000 -c $(SOURCEDIR) $(SOURCEDIR) $(BUILDDIR)/html + + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png new file mode 100644 index 0000000..b7ab2e0 Binary files /dev/null and b/docs/source/_static/logo.png differ diff --git a/docs/source/_static/tsam-logo.png b/docs/source/_static/tsam-logo.png new file mode 100644 index 0000000..c8712f7 Binary files /dev/null and b/docs/source/_static/tsam-logo.png differ diff --git a/docs/source/aboutUsDoc.rst b/docs/source/aboutUsDoc.rst deleted file mode 100644 index 2843c75..0000000 --- a/docs/source/aboutUsDoc.rst +++ /dev/null @@ -1,33 +0,0 @@ -######## -About Us -######## - -.. image:: https://www.fz-juelich.de/iek/iek-3/DE/_Documents/Pictures/IEK-3Team_2019-02-04.jpg?__blob=poster - :target: https://www.fz-juelich.de/iek/iek-3/EN/Home/home_node.html - :alt: Abteilung TSA - :align: center - -We are the `Institute of Energy and Climate Research: Techno-Economic Energy 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. - -**Contributions and Users** - -Within the BMWi funded project `METIS `_ we develop together with the RWTH-Aachen -`(Prof. Aaron Praktiknjo) `_, -the EDOM Team at FAU `(PD Lars Schewe) `_ and the -`Jülich Supercomputing Centre (JSC) `_ energy system models -on both, global and national scales, and new methods for effectively solving them. - -.. image:: http://www.metis-platform.net/metis-platform/DE/_Documents/Pictures/projectTeamAtKickOffMeeting_640x338.jpg?__blob=normal - :target: http://www.metis-platform.net - :alt: METIS Team - :align: center - -Dr. Martin Robinius is teaching a `course `_ -at TU Berlin in which he is introducing tsam to students. \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index a9b50a1..3208b3b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -69,7 +69,7 @@ # General information about the project. project = "tsam" -copyright = "2016-2022, tsam Developer Team" +copyright = "2016-2023, tsam Developer Team" author = "Leander Kotzur, Maximilian Hoffmann" # The version info for the project you're documenting, acts as replacement for @@ -77,16 +77,16 @@ # built documents. # # The short X.Y version. -version = "2.0.1" +version = "2.3.0" # The full version, including alpha/beta/rc tags. -release = "2.0.1" +release = "2.3.0" # 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 +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -105,14 +105,29 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_rtd_theme" +html_theme = "sphinx_book_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 = {} +html_theme_options = { + "repository_url": "https://github.com/FZJ-IEK3-VSA/tsam", + "use_repository_button": True, + "show_navbar_depth": 1, +} + + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = "tsam Documentation" +# A shorter title for the navigation bar. Default is the same as html_title. +html_short_title = "tsam" + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = "_static/tsam-logo.png" # 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, @@ -180,7 +195,3 @@ "Miscellaneous", ), ] - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"https://docs.python.org/": None} diff --git a/docs/source/durationRepresentationDoc.rst b/docs/source/durationRepresentationDoc.rst index 24d8d7f..acb364b 100644 --- a/docs/source/durationRepresentationDoc.rst +++ b/docs/source/durationRepresentationDoc.rst @@ -1,5 +1,5 @@ ######################################### -The Duration Representation Functionality +Duration Representation Functionality ######################################### .. |br| raw:: html diff --git a/docs/source/exactKmedoidsDoc.rst b/docs/source/exactKmedoidsDoc.rst index b35152b..9d13fb0 100644 --- a/docs/source/exactKmedoidsDoc.rst +++ b/docs/source/exactKmedoidsDoc.rst @@ -1,5 +1,5 @@ ################################# -The Exact k-Medoids Functionality +Exact k-Medoids Functionality ################################# .. |br| raw:: html diff --git a/docs/source/furtherReadingDoc.rst b/docs/source/furtherReadingDoc.rst index 58c7ecc..90a1756 100644 --- a/docs/source/furtherReadingDoc.rst +++ b/docs/source/furtherReadingDoc.rst @@ -23,4 +23,6 @@ The publications about time series aggregation for energy system optimization mo * | Kannengießer et al. (2019): | `Reducing Computational Load for Mixed Integer Linear Programming: An Example for a District and an Island Energy System `_ * | Hoffmann et al. (2020): - | `A Review on Time Series Aggregation Methods for Energy System Models `_ \ No newline at end of file + | `A Review on Time Series Aggregation Methods for Energy System Models `_ +* | Hoffmann et al. (2022): + | `The Pareto-Optimal Temporal Aggregation of Energy System Models ` diff --git a/docs/source/gettingStartedDoc.rst b/docs/source/gettingStartedDoc.rst index 7edde2f..92c1571 100644 --- a/docs/source/gettingStartedDoc.rst +++ b/docs/source/gettingStartedDoc.rst @@ -1,39 +1,85 @@ -.. _getting_started: +.. _start: -############### +******** Getting started -############### +******** -In the following, instructions for installing and using the tsam package on Windows are given. The installation -instructions for installing and using tsam on Linux/macOS systems are however quite similar and can be, hopefully -easily, derived from the instructions below. +**Basic Workflow** -**tsam installation** +A small example how tsam can be used is decribed as follows -Install via pip by typing +.. code-block:: python -.. code-block:: bash + import pandas as pd + import tsam.timeseriesaggregation as tsam - pip install tsam +Read in the time series data set with pandas -into the command prompt. Alternatively, download or clone a local copy of the repository to your computer +.. code-block:: python -.. code-block:: bash + raw = pd.read_csv('testdata.csv', index_col = 0) - git clone https://github.com/FZJ-IEK3-VSA/tsam.git +Initialize an aggregation object and define the number of typical periods, the length of a single period, the aggregation method -and install tsam in the folder where the setup.py is located with +.. code-block:: python -.. code-block:: bash + aggregation = tsam.TimeSeriesAggregation(raw, + noTypicalPeriods = 8, + hoursPerPeriod = 24, + segmentation = True, + noSegments = 8, + representationMethod = "distributionAndMinMaxRepresentation", + distributionPeriodWise = False + clusterMethod = 'hierarchical' + ) - pip install -e . +Run the aggregation to typical periods -or install directly via python as +.. code-block:: python -.. code-block:: bash + typPeriods = aggregation.createTypicalPeriods() - python setup.py install +Store the results as .csv file -**Installation of an optimization solver** +.. code-block:: python -Some clustering algorithms implemented in tsam are based on Mixed-Integer Linear Programming. Accordingy, an appropriate solver for using these functionalities is required that can be accessed by `Pyomo `_. In theory many solvers can be used (e.g. `GUROBI `_ or `cbc `_). For the installation of GUROBI, follow the instructions on the solver's website. For installation of cbc, move the downloaded folder to a desired location. Then, manually append the Environment Variable *Path* with the absolute path leading to the folder in which the glpsol.exe is located (c.f. w32/w64 folder, depending on operating system type). + typPeriods.to_csv('typperiods.csv') + + +**Hypertuned aggregation** + +In case you do not know, which number of segments or typical periods to choose, you should make first a run with the HyperTunedAggregations class. It will find the best combination of typical periods and segments for the aggregation by minimizing the error between the original and the aggregated time series. The following example shows how to use it. + + +Either create or provide a TimeSeriesAggregation object and use it as base case to get tuned by the HyperTunedAggregations class. + +.. code-block:: python + + tune_aggregation = tune.HyperTunedAggregations( + tsam.TimeSeriesAggregation( + raw, + hoursPerPeriod=24, + clusterMethod="hierarchical", + representationMethod="distributionRepresentation", + rescaleClusterPeriods=False, + segmentation=True, + ) + ) + +Afterwards, define the aggregation level you want to reach. The following examples shows how to reduce the original time series to 5% of the original data set. + +.. code-block:: python + + segments, periods, RMSE = tune_aggregation.identifyOptimalSegmentPeriodCombination( + dataReduction=0.05 + ) + + +Since, it is quite time consuming, I would recommend to just run it once at the beginning for your time series set, save the resulting segment and period number, and use it as fix values for the original TimeSeriesAggregation object in production. + +The scientific documentation of the methodology can be found here: +`The Pareto-Optimal Temporal Aggregation of Energy System Models `_ + +**Additional Examples** + +More detailed examples can be found on the `GitHub page of tsam `_. \ No newline at end of file diff --git a/docs/source/hypertunedaggregationDoc.rst b/docs/source/hypertunedaggregationDoc.rst new file mode 100644 index 0000000..d14302c --- /dev/null +++ b/docs/source/hypertunedaggregationDoc.rst @@ -0,0 +1,20 @@ +###################### +Hypertuning segment and period selection +###################### + +.. |br| raw:: html + +
+ +Descriptions of the basic functions are given below. + +**Function descriptions:** + +.. automodule:: hyperparametertuning + :member-order: bysource + + .. autoclass:: HyperTunedAggregations + :members: + :member-order: bysource + + .. automethod:: __init__ diff --git a/docs/source/index.rst b/docs/source/index.rst index 24faf80..51e40ab 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,13 +2,13 @@ sphinx-quickstart on Sat Nov 10 21:04:19 2018. -.. image:: http://www.fz-juelich.de/SharedDocs/Bilder/IBG/IBG-3/DE/Plant-soil-atmosphere%20exchange%20processes/INPLAMINT%20(BONARES)/Bild3.jpg?__blob=poster - :target: http://www.fz-juelich.de/iek/iek-3/EN/Forschung/_Process-and-System-Analysis/_node.html +.. image:: https://www.fz-juelich.de/static/media/Logo.2ceb35fc.svg + :target: https://www.fz-juelich.de/en/iek/iek-3 :width: 230px :alt: Forschungszentrum Juelich Logo :align: right -Welcome to tsam's documentation! +Introduction ================================ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -16,34 +16,29 @@ tsam - time series aggregation module ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ tsam is a python package which uses different machine learning algorithms for the aggregation of typical periods. It is applicable -for all type of time series, either weather data, load data or both simultaneously. The module is able to significantly reduce input -time series for energy system models, and therefore the model's complexity and computational time. +for all type of time series, either weather data, price data, behavioral data, electrical load data or all together. The module is able to significantly reduce input +time series for mathmatical models, and therefore the model's complexity and computational time. -To use tsam, jump to the :ref:`Section Getting Started`. +To use tsam, first :ref:`install tsam` and then :ref:`start aggregating time series `. -The concept of tsam is that scientists, programmers and anyone who is interested all around the world can use tsam to aggregate their -time series whatever they might be used for. Therefore, tsam is open-source available on `GitHub `_ -and **open for collaboration**. -The authors of both, the program and the publications, **kindly request you to cite their work** listed in the -:ref:`Further Reading Section ` if tsam is used in a scientific context. +tsam is open-source available on `GitHub `_ +and open for collaboration, help requests etc. +In case you use tsam in a scientific publication, we kindly request you to cite one of our publications listed in the +:ref:`Further Reading Section `. .. toctree:: :maxdepth: 1 :caption: Contents: self + installationDoc gettingStartedDoc - usersGuideDoc + structureOfTsamDoc mathematicalBackgroundDoc newsDoc integratedSoftwareDoc legalNoticeDoc - aboutUsDoc furtherReadingDoc -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/source/installationDoc.rst b/docs/source/installationDoc.rst new file mode 100644 index 0000000..e3efe47 --- /dev/null +++ b/docs/source/installationDoc.rst @@ -0,0 +1,38 @@ +.. _installation: + +############### +Installation +############### + +In the following, instructions for installing and using the tsam package are given. + +**tsam installation** + +Install via pip by typing + +.. code-block:: bash + + pip install tsam + +into the command prompt. Alternatively, download or clone a local copy of the repository to your computer + +.. code-block:: bash + + git clone https://github.com/FZJ-IEK3-VSA/tsam.git + +and install tsam in the folder where the setup.py is located with + +.. code-block:: bash + + pip install -e . + +or install directly via python as + +.. code-block:: bash + + python setup.py install + +**Installation of an optimization solver** + + +Some clustering algorithms implemented in tsam are based on Mixed-Integer Linear Programming. Accordingy, an appropriate solver for using these functionalities is required that can be accessed by `Pyomo `_. The `HiGHS `_ solver is set as default and installed via `highspy` but can be replaced by any other solver that is supported by Pyomo. diff --git a/docs/source/kmaxoidsDoc.rst b/docs/source/kmaxoidsDoc.rst index 63ac324..f543a19 100644 --- a/docs/source/kmaxoidsDoc.rst +++ b/docs/source/kmaxoidsDoc.rst @@ -1,5 +1,5 @@ ########################### -The k-Maxoids Functionality +k-Maxoids Functionality ########################### .. |br| raw:: html diff --git a/docs/source/newsDoc.rst b/docs/source/newsDoc.rst index e6e8f09..2e6bacd 100644 --- a/docs/source/newsDoc.rst +++ b/docs/source/newsDoc.rst @@ -2,6 +2,12 @@ tsam's Change Log ################# +********************* +This is outdated. Please refer to the releases on `GitHub `_ for the most recent changes. +********************* + + + ********************* Release version 2.0.1 ********************* diff --git a/docs/source/periodAggregationDoc.rst b/docs/source/periodAggregationDoc.rst index 7efb71c..d831e3e 100644 --- a/docs/source/periodAggregationDoc.rst +++ b/docs/source/periodAggregationDoc.rst @@ -1,5 +1,5 @@ ############################# -The Aggregation Functionality +Aggregation function ############################# .. |br| raw:: html diff --git a/docs/source/representationsDoc.rst b/docs/source/representationsDoc.rst index 4eedd8c..5ef83e7 100644 --- a/docs/source/representationsDoc.rst +++ b/docs/source/representationsDoc.rst @@ -1,5 +1,5 @@ ################################ -The Representation Functionality +Representation function ################################ .. |br| raw:: html diff --git a/docs/source/segmentationDoc.rst b/docs/source/segmentationDoc.rst index 9637a40..c0d4489 100644 --- a/docs/source/segmentationDoc.rst +++ b/docs/source/segmentationDoc.rst @@ -1,5 +1,5 @@ ############################## -The Segmentation Functionality +Segmentation Functionality ############################## .. |br| raw:: html diff --git a/docs/source/structureOfTsamDoc.rst b/docs/source/structureOfTsamDoc.rst index 2fbf571..2e9cb03 100644 --- a/docs/source/structureOfTsamDoc.rst +++ b/docs/source/structureOfTsamDoc.rst @@ -12,16 +12,17 @@ clustering of adjacent time steps called segmentation. **Submodule with the basic functionalities** .. toctree:: - :maxdepth: 2 + :maxdepth: 1 timeseriesaggregationDoc + hypertunedaggregationDoc periodAggregationDoc representationsDoc -**Submodules including exact k-medoids and segmentation** +**Sub functions such as k-medoids and segmentation** .. toctree:: - :maxdepth: 2 + :maxdepth: 1 exactKmedoidsDoc kmaxoidsDoc diff --git a/docs/source/timeseriesaggregationDoc.rst b/docs/source/timeseriesaggregationDoc.rst index 2ac3312..86ffabe 100644 --- a/docs/source/timeseriesaggregationDoc.rst +++ b/docs/source/timeseriesaggregationDoc.rst @@ -1,5 +1,5 @@ ###################### -The Main Class of tsam +Time Series Aggregation Class ###################### .. |br| raw:: html diff --git a/docs/source/tutorialDoc.rst b/docs/source/tutorialDoc.rst deleted file mode 100644 index 527e4a7..0000000 --- a/docs/source/tutorialDoc.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _tutorial: - -******** -Tutorial -******** - -**Basic Workflow** - -A small example how tsam can be used is decribed as follows - -.. code-block:: python - :linenos: - :lineno-start: 1 - - import pandas as pd - import tsam.timeseriesaggregation as tsam - -Read in the time series data set with pandas - -.. code-block:: python - :linenos: - :lineno-start: 3 - - raw = pd.read_csv('testdata.csv', index_col = 0) - -Initialize an aggregation object and define the number of typical periods, the length of a single period and the aggregation method - -.. code-block:: python - :linenos: - :lineno-start: 4 - - aggregation = tsam.TimeSeriesAggregation(raw, - noTypicalPeriods = 8, - hoursPerPeriod = 24, - clusterMethod = 'hierarchical') - -Run the aggregation to typical periods - -.. code-block:: python - :linenos: - :lineno-start: 8 - - typPeriods = aggregation.createTypicalPeriods() - -Store the results as .csv file - -.. code-block:: python - :linenos: - :lineno-start: 9 - - typPeriods.to_csv('typperiods.csv') - -**Additional Examples** - -More detailed examples can be found on the `GitHub page of tsam `_. \ No newline at end of file diff --git a/docs/source/usersGuideDoc.rst b/docs/source/usersGuideDoc.rst deleted file mode 100644 index 19d327d..0000000 --- a/docs/source/usersGuideDoc.rst +++ /dev/null @@ -1,13 +0,0 @@ -########### -User Guide -########### - -The user guide provides a quick start example in the :ref:`Tutorial Section ` and the modules of the package are presented with all their -input and output options in the :ref:`Structure Section `. - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - tutorialDoc - structureOfTsamDoc \ No newline at end of file diff --git a/requirements_dev.txt b/requirements_dev.txt new file mode 100644 index 0000000..e9ed61a --- /dev/null +++ b/requirements_dev.txt @@ -0,0 +1,9 @@ +-r requirements.txt + +# Testing +pytest +sphinx + +# Documentation +sphinx-autobuild +sphinx_book_theme \ No newline at end of file diff --git a/setup.py b/setup.py index c91abbb..9a43b29 100644 --- a/setup.py +++ b/setup.py @@ -8,7 +8,7 @@ setuptools.setup( name="tsam", - version="2.2.2", + version="2.3.0", author="Leander Kotzur, Maximilian Hoffmann", author_email="leander.kotzur@googlemail.com, max.hoffmann@fz-juelich.de", description="Time series aggregation module (tsam) to create typical periods",