Merge branch 'dev' into features/docs-validation-heatpump-chiller

README.rst

@@ -20,7 +20,7 @@ oemof.solph. Currently, most of the functions collected here are intended to be
 together with oemof.solph. However, in some instances they may be useful independently
 of oemof.solph.
 
-oemof.thermal is rather new and under active development. Contributions are welcome.
+oemof.thermal is under active development. Contributions are welcome.
 
 Quickstart
 ==========
@@ -48,9 +48,8 @@ Find the documentation at `<https://oemof-thermal.readthedocs.io>`_.
 Contributing
 ============
 
-Everybody is welcome to contribute to the development of oemof.thermal. The `developer
-guidelines of oemof <https://oemof.readthedocs.io/en/stable/developing_oemof.html>`_
-are in most parts equally applicable to oemof.thermal.
+Everybody is welcome to contribute to the development of oemof.thermal. Find here the `developer
+guidelines of oemof <https://oemof.readthedocs.io/en/latest/developing_oemof.html>`_.
 
 License
 =======

VERSION

@@ -1 +1 @@
-__version__ = "0.0.3dev"
+__version__ = "0.0.4dev"

docs/absorption_chillers.rst

@@ -2,7 +2,7 @@
 
 
 ~~~~~~~~~~~~~~~~~~~~~~~
-Absorption chillers
+Absorption chiller
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Calculations for absorption chillers based on the characteristic equation method.

docs/compression_heat_pumps_and_chillers.rst

@@ -1,7 +1,7 @@
 .. _compression_heat_pumps_label:
 
-Compression Heat Pumps and Chillers
-===================================
+Compression heat pump and chiller
+=================================
 
 Simple calculations for compression heat pumps and chillers.
 
@@ -39,8 +39,8 @@ cooling (chiller).
 
 The efficiency of the heat pump cycle process can be described by
 the Coefficient of Performance (COP).
-The COP describes the ratio of useful heat (:math:`\dot{Q}_\mathrm{in}` or :math:`\dot{Q}_\mathrm{out}`) per
-electric work consumed:
+The COP describes the ratio of useful heat :math:`\dot{Q}_\mathrm{useful}` (:math:`\dot{Q}_\mathrm{in}` or :math:`\dot{Q}_\mathrm{out}`) per
+electric work :math:`P_\mathrm{el}` consumed:
 
 .. math::
         COP = \frac{\dot{Q}_\mathrm{useful}}{P_\mathrm{el}}
@@ -123,7 +123,6 @@ These arguments are input to the functions:
                     temp_low,
                     quality_grade,
                     temp_threshold_icing,
-                    consider_icing,
                     factor_icing,
                     mode)
 

docs/concentrating_solar_power.rst

@@ -31,7 +31,7 @@ solar collector based on the direct horizontal irradiance (DHI) or the direct
 normal irradiance (DNI) and information about the collector and its location.
 The losses can be calculated in 2 different ways.
 
-.. figure:: _pics/concentrating_solar_power.svg
+.. figure:: _pics/concentrating_solar_power.png
     :width: 60 %
     :alt: concentrating_solar_power.png
     :align: center
@@ -49,7 +49,7 @@ part of the absorbed heat output through thermal losses
 (:math:`\dot Q_{loss,therm}`).
 
 
-The processing of the irradiance data is done by the pvlib, which calculates
+The processing of the irradiance data is done by the `pvlib <https://github.com/pvlib/pvlib-python>`_, which calculates
 the direct irradiance on the collector. This irradiance is reduced by dust and
 dirt on the collector with:
 
@@ -129,10 +129,11 @@ These arguments are used in the formulas of the function:
 Usage
 _____
 
-It is possible to use the precalculation function as stand-alone function to calculate the collector values
-:math:`\dot Q_{coll}`, :math:`\eta_C` and :math:`E_{coll}`. Or it is possible
-to use the ParabolicTroughCollector facade to model a collector with further
-losses (e.g. in pipes or pumps) and the electrical consumption of pipes within a single step.
+It is possible to use the precalculation function as stand-alone function to
+calculate the collector values :math:`\dot Q_{coll}`, :math:`\eta_C` and
+:math:`E_{coll}`. Or it is possible to use the ParabolicTroughCollector facade
+to model a collector with further losses (e.g. in pipes or pumps) and the
+electrical consumption of pipes within a single step.
 Please note: As the unit of the input irradiance is given as power per area,
 the outputs :math:`\dot Q_{coll}` and :math:`E_{coll}` are given in the same
 unit. If these values are used in an oemof source, the unit of the nominal
@@ -142,14 +143,14 @@ value must be an area too.
 Precalculation function
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Please see the :ref:`api of the concentrating_solar_power module <api_label>`
-for all parameters which have to be provided, also the ones that are not part
-of the described formulas above.
+Please see the API documentation of the :py:class:`~oemof.thermal.concentrating_solar_power`
+module for all parameters which have to be provided, also the ones that are
+not part of the described formulas above.
 The data for ambient temperature and irradiance must have the same time index.
 Depending on the method, the irradiance must be the horizontal direct
 irradiance or the direct normal irradiance. Be aware of the correct time index
 regarding the time zone, as the utilized pvlib need the correct time stamp
-corresponding to the location.
+corresponding to the location (latitude and longitude).
 
 
 .. code-block:: python
@@ -181,14 +182,14 @@ ParabolicTroughCollector facade
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Instead of using the precalculation, it is possible to use the
-ParabolicTroughCollector facade, which will create an oemof component as a representative for the collector. It calculates the heat of the collector in the same
-way as the precalculation do. Additionally, it integrates the calculated heat as an input
-into a component, uses an electrical input for pumps and gives a heat output,
-which is reduced by the defined additional losses.
+ParabolicTroughCollector facade, which will create an oemof component as a
+representative for the collector. It calculates the heat of the collector in
+the same way as the precalculation do. Additionally, it integrates the
+calculated heat as an input into a component, uses an electrical input for
+pumps and gives a heat output, which is reduced by the defined additional losses.
 As given in the example, further parameters are required in addition to the
-ones of the precalculation. Please see the
-:ref:`api reference for the facade module <api_label>` for all parameters which
-have to be provided.
+ones of the precalculation. Please see the API documentation of the :py:class:`~oemof.thermal.facades.ParabolicTroughCollector`
+class of the facade module for all parameters which have to be provided.
 
 See example_csp_facade.py for an application example. It models the same
 system as the csp_plant_example.py, but uses the ParabolicTroughCollector facade
@@ -198,10 +199,10 @@ instead of separate source and transformer.
 .. code-block:: python
 
     from oemof import solph
-        >>> from oemof.thermal.facades import Collector
+        >>> from oemof.thermal.facades import ParabolicTroughCollector
         >>> bth = solph.Bus(label='thermal_bus')
         >>> bel = solph.Bus(label='electrical_bus')
-        >>> collector = Collector(
+        >>> collector = ParabolicTroughCollector(
         ...     label='solar_collector',
         ...     heat_bus=bth,
         ...     electrical_bus=bel,

docs/getting_started.rst

@@ -17,12 +17,13 @@ optimization).
 
 To help setting up more detailed components in a simple way, oemof.thermal provides facades based on the
 `oemof.tabular.facades module <https://oemof-tabular.readthedocs.io/en/stable/reference/oemof.tabular.html>`_.
-Facades are classes that offer a simpler interface to more complex classes. More specifically,
-the facades in this module act as simplified, energy system specific wrappers around oemof.solph's
-more abstract classes. Using the facades together with oemof.tabular also makes it possible to
-instantiate a facade using keyword arguments whose value are given as tabular data sources. Under
-the hood the facade then uses these arguments to construct an oemof.solph-component and sets it up
-to be easily used in an :py:obj:`EnergySystem`. In oemof.thermal each technology has a facade class,
+Facades are classes that offer a simpler interface to more complex classes. More specifically, the :class:`Facade` s
+in this module inherit from `oemof.solph`'s generic classes to serve as more concrete and energy specific interface.
+The concept of the facades has been derived from oemof.tabular. The idea is to be able to
+instantiate a :class:`Facade` using only keyword arguments. Under the hood the :class:`Facade` then
+uses these arguments to construct an `oemof.solph` component and sets it up to be easily used in an
+:py:obj:`EnergySystem`. Usually, a subset of the attributes of the parent class remains while another
+part can be addressed by more specific or simpler attributes. In oemof.thermal, some of the technologies have a facade class
 that can be found in the module oemof.thermal.facades. See the
 :ref:`api reference for the facade module <api_label>` for further information on the structure of
 these classes.
@@ -34,7 +35,8 @@ references to the literature are listed that the reader can refer to if she want
 information on the background.
 
 Finally, there are a couple of examples that can give an idea of how the functionality of
-oemof.thermal can be utilized.
+oemof.thermal can be utilized. Some models have undergone validation whose results you'll find
+in the section "Model validation".
 
 .. contents:: `Contents`
     :depth: 1
@@ -73,6 +75,8 @@ Examples
 --------
 
 We provide examples described in the section :ref:`examples_label`.
+Further we developed some complex models with the oemof-thermal components
+which are described in this section as well.
 
 
 Contributing to oemof.thermal

docs/index.rst

@@ -15,6 +15,7 @@ Welcome to oemof.thermal's documentation!
    getting_started
    examples
 
+
 .. toctree::
    :maxdepth: 1
    :caption: Model validation
@@ -35,6 +36,22 @@ Welcome to oemof.thermal's documentation!
    solar_thermal_collector
    stratified_thermal_storage
 
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Model validation
+
+   validation_compression_heat_pumps_and_chillers
+   validation_stratified_thermal_storage
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Theoretical considerations
+
+   theoretical_considerations
+
+
 .. toctree::
    :maxdepth: 1
    :caption: Reference

docs/solar_thermal_collector.rst

@@ -10,7 +10,7 @@ Scope
 _____
 
 This module was developed to provide the heat of a flat plate collector
-based on temperatures and collectors location, tilt and azimuth for energy
+based on temperatures and collector's location, tilt and azimuth for energy
 systems optimizations with oemof.solph.
 
 In
@@ -20,7 +20,7 @@ with flat plate collector, storage and backup to provide a given heat demand.
 The time series of the pre-calculated heat is output of a source (an oemof.solph
 component) representing the collector, and a transformer (an oemof.solph component)
 is used to hold electrical power consumption and further thermal losses of the
-collector in an energy system optimization. In addition, you will find an plot,
+collector in an energy system optimization. In addition, you will find a plot,
 which compares this precalculation with a calculation with a constant efficiency.
 
 Concept
@@ -31,13 +31,13 @@ collector based on global and diffuse horizontal irradiance and information abou
 the collector and the location. The following scheme shows the calculation procedure.
 
 .. figure:: _pics/solar_thermal_collector.png
-    :width: 80 %
+    :width: 60 %
     :alt: solar_thermal_collector.png
     :align: center
 
     Fig.1: The energy flows and losses at a flat plate collector.
 
-The processing of the irradiance data is done by the pvlib, which calculates the total
+The processing of the irradiance data is done by the `pvlib <https://github.com/pvlib/pvlib-python>`_, which calculates the total
 in-plane irradiance according to the azimuth and tilt angle of the collector.
 
 The efficiency of the collector is calculated with
@@ -102,8 +102,12 @@ value must be an area too.
 
 
 Solar thermal collector precalculations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Please see the :ref:`api of the solar_thermal_collector module <api_label>` for all parameters which have to be provided, also the ones that are not part of the described formulas above. The data for the irradiance and the ambient temperature must have the same time index. Be aware of the correct time index regarding the time zone, as the utilized pvlib needs the correct time stamp corresponding to the location.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Please see the API documentation of the :py:class:`~oemof.thermal.solar_thermal_collector`
+module for all parameters which have to be provided, also the ones that are not part of the
+described formulas above. The data for the irradiance and the ambient temperature must have
+the same time index. Be aware of the correct time index regarding the time zone, as the utilized
+pvlib needs the correct time stamp corresponding to the location.
 
 .. code-block:: python
 
@@ -148,8 +152,8 @@ way as the precalculation do. Additionally, it integrates the calculated heat as
 into a component, uses an electrical input for pumps and gives a heat output,
 which is reduced by the defined additional losses. As given in the example,
 further parameters are required in addition to the ones of the precalculation. Please see the
-:ref:`api reference for the facade module <api_label>` for all parameters which
-have to be provided.
+API documentation of the :py:class:`~oemof.thermal.facades.SolarThermalCollector`
+class of the facade module for all parameters which have to be provided.
 
 See flat_plate_collector_example_facade.py for an application example. It models the same
 system as the flat_plate_collector_example.py, but uses the SolarThermalCollector facade
@@ -181,6 +185,3 @@ instead of separate source and transformer.
     	irradiance_diffuse=input_data['diffuse_horizontal_W_m2'],
     	temp_amb_col=input_data['temp_amb'],
     )
-
-To learn about all parameters that can be passed to the facades, have a look at the
-:ref:`api reference for the facade module <api_label>`.

docs/stratified_thermal_storage.rst

@@ -28,13 +28,17 @@ A simplified 2-zone-model of a stratified thermal energy storage.
    down or up, respectively. Losses to the environment through the surface of the
    storage depend on the size of the hot and cold zone.
 
-* We assume a cylindrical storage of diameter d and height h,
+* We assume a cylindrical storage of (inner) diameter d and height h,
   with two temperature regions that are perfectly separated.
 * The temperatures are assumed to be constant and correspond to
   the feed-in/return temperature of the heating system.
 * Heat conductivity of the storage has to be passed as well as a timeseries
   of outside temperatures for the calculation of heat losses.
 * There is no distinction between outside temperature and ground temperature.
+* A single value for the thermal transmittance :math:`U` is assumed, neglecting the
+  fact that the storage's lateral surface is bent and thus has a higher thermal
+  transmittance than a flat surface. The relative error introduced here gets
+  smaller with larger storage diameters.
 * Material properties are constant.
 
 The equation describing the storage content at timestep t is the following:
@@ -79,7 +83,7 @@ Because of the space that diffuser plates for charging/discharging take up, it i
 the storage can neither be fully charged nor discharged, which is parametrised as a minimal/maximal
 storage level (indicated by the dotted lines in Fig. 1).
 
-These parameters are part of the stratified thermal storage:
+These parameters are part of the stratified thermal storage module:
 
     ========================= ===================================== ==== ===========
     symbol                    attribute                             type explanation
@@ -190,8 +194,7 @@ Using the StratifiedThermalStorage facade, you can instantiate a storage like th
 The non-usable storage volume is represented by the parameters
 :py:attr:`min_storage_level` and :py:attr:`max_storage_level`.
 
-To learn about all parameters that can be passed to the facades, have a look at the
-:ref:`api reference for the facade module <api_label>`.
+To learn about all parameters that can be passed to the facades, have a look at the API documentation of the :py:class:`~oemof.thermal.facades.StratifiedThermalStorage` class of the facade module.
 
 For the storage investment mode, you still need to provide :py:attr:`diameter`, but
 leave :py:attr:`height` and :py:attr:`capacity` open and set :py:attr:`expandable=True`.
@@ -240,13 +243,9 @@ model it, you can do so by performing the necessary pre-calculations and using o
 
 .. warning::
 
-   For this example to work as intended, please use the not yet released oemof-solph branch
-
-   https://github.com/oemof/oemof-solph/tree/dev
-
-   which contains the new attributes for GenericStorage, `fixed_losses_absolute` and
-   `fixed_losses_relative`. As soon as the feature in oemof is released, no extra steps
-   will be necessary to use them and this warning will be removed.
+   For this example to work as intended, please use oemof-solph v0.4.0 or higher
+   to ensure that the GenericStorage has the attributes :py:attr:`fixed_losses_absolute` and
+   :py:attr:`fixed_losses_relative`.
 
 The following figure shows a comparison of results of a common storage implementation using
 only a loss rate vs. the stratified thermal storage implementation

docs/theoretical_considerations.rst

@@ -0,0 +1,57 @@
+.. _theoretical_considerations:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Aggregation of domestic decentral solar thermal systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this section the aggregation of consumers using solar thermal systems is discussed. Depending on the consumers energy usage the ratio of heat load and collector
+size or storage capacity differs. If you want to model a district with domestic solar systems, it is difficult to aggregate them because of the different sizes of the components and thus different points in time, when the backup heating has to start. The picture shows a scheme of such a system:
+
+.. 	figure:: _pics/aggregation_scheme.png
+   :width: 70 %
+   :alt: aggregation_scheme.png
+   :align: center
+
+Concept
+_______
+
+
+Instead of aggregate all storages and all collectors of the system, which would be really unaccurate, we want to classify two different types of domestic solar systems:
+
+- systems for hot water provision
+- systems for hot water provision and space heating support
+
+The system shown in the picture can be characterized by two ratios:
+
+:math:`ratio 1 = \frac{V_{storage}}{A_{collector}} \quad \textrm{and} \quad ratio 2 = \frac{A_{collector}}{\dot{Q}_{demand,max}}`
+
+or, also possible:
+
+:math:`ratio 1 = \frac{V_{storage}}{A_{collector}} \quad \textrm{and} \quad ratio 2 = \frac{A_{collector}}{Q_{demand}}`
+
+Normally there are typical ratios which are used when dimensioning these types of systems.
+So it is possible to aggregate the houses within one type by defining these ratios. This would be more accurate than an aggregation of all installed systems.
+In case of special system modifications, also more than two groups could be defined.
+
+Nomenclature
+____________
+
+    ============================= =============================================
+    symbol                        explanation
+    ============================= =============================================
+    :math:`\dot{Q}_{add}`         Heat flow from external to consumer
+
+    :math:`\dot{Q}_{demand}`      Heat flow demand of the consumer 
+
+    :math:`\dot{Q}_{solar}`       Heat flow from collector
+
+    :math:`\dot{Q}_{demand,max}`  Maximal value of the consumer's heat flow
+                                  demand
+
+    :math:`Q_{demand}`            Total demand
+
+    :math:`V_{storage}`           Storage volume
+
+    :math:`A_{collector}`         Collector surface
+
+    ============================= =============================================