Merge 81414ca into 5febaee

docs/concentrating_solar_power.rst

@@ -82,9 +82,6 @@ returned. Losses which occur after the heat absorption in the collector
 (e.g. losses in pipes) have to be taken into account in a later step
 (see the example).
 
-Usage
-_____
-
 These arguments are used in the formulas of the function:
 
     ========================= =================================================== ===========
@@ -104,6 +101,14 @@ These arguments are used in the formulas of the function:
 
     :math:`a_2`               :py:obj:`a_2`                                       Parameter 2 for the incident angle modifier
 
+    :math:`a_3`               :py:obj:`a_3`                                       Parameter 3 for the incident angle modifier
+
+    :math:`a_4`               :py:obj:`a_4`                                       Parameter 4 for the incident angle modifier
+
+    :math:`a_5`               :py:obj:`a_5`                                       Parameter 5 for the incident angle modifier
+
+    :math:`a_6`               :py:obj:`a_6`                                       Parameter 6 for the incident angle modifier
+
     :math:`\varTheta`         :py:obj:`aoi`                                       Angle of incidence
 
     :math:`\eta_C`            :py:obj:`eta_c`                                     Collector efficiency
@@ -120,11 +125,32 @@ These arguments are used in the formulas of the function:
 
     ========================= =================================================== ===========
 
-Please see the API for all parameters which have to be provided, also the ones
-which are not part of the described formulas.
+
+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.
+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
+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.
 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.
+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.
+
 
 .. code-block:: python
 
@@ -146,6 +172,61 @@ calculated with a fix efficiency.
    :alt: compare_collector_heat_method1.png
    :align: center
 
+The results of this precalculation can be used in an oemof energy system model
+as output of a source component. To model the behaviour of a collector, it can be
+complemented with a transformer, which holds the electrical consumption of pumps
+and peripheral heat losses (see the the example csp_plant_collector.py).
+
+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.
+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.
+
+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
+instead of separate source and transformer.
+
+
+.. code-block:: python
+
+    from oemof import solph
+        >>> from oemof.thermal.facades import Collector
+        >>> bth = solph.Bus(label='thermal_bus')
+        >>> bel = solph.Bus(label='electrical_bus')
+        >>> collector = Collector(
+        ...     label='solar_collector',
+        ...     heat_bus=bth,
+        ...     electrical_bus=bel,
+        ...     electrical_consumption=0.05,
+        ...     additional_losses=0.2,
+        ...     aperture_area=1000,
+        ...     loss_method='Janotte',
+        ...     irradiance_method='horizontal',
+        ...     latitude=23.614328,
+        ...     longitude=58.545284,
+        ...     collector_tilt=10,
+        ...     collector_azimuth=180,
+        ...     x=0.9,
+        ...     a_1=-0.00159,
+        ...     a_2=0.0000977,
+        ...     eta_0=0.816,
+        ...     c_1=0.0622,
+        ...     c_2=0.00023,
+        ...     temp_collector_inlet=435,
+        ...     temp_collector_outlet=500,
+        ...     temp_amb=input_data['t_amb'],
+        ...     irradiance=input_data['E_dir_hor']
+        )
+
+
 References
 __________
 

examples/concentrating_solar_power/example_csp_facade.py

@@ -1,3 +1,13 @@
+"""
+Example to show the functionality of the ParabolicTroughCollector facade.
+This application models a csp plant, to meet an electrical demand. The plant
+itself consists of a parabolic trough collector field, a turbine, and a storage.
+The collector is build with the facade, which can be found in the facade modul.
+
+authors: Franziska Pleissner
+
+SPDX-License-Identifier: MIT
+"""
 import os
 import pandas as pd
 import oemof.outputlib as outputlib