Developer documentation improved

docs/source/conf.py

@@ -40,7 +40,7 @@ templates_path = ['_templates']
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['configuration/target.rst', 'configuration/common.rst', 'configuration/optical_components.rst',
-                    'configuration/sensor.rst']
+                    'configuration/sensor.rst', 'developer/classes.rst']
 
 # -- Options for HTML output -------------------------------------------------
 html_show_sourcelink = False

docs/source/developer/classes.rst

@@ -0,0 +1,50 @@
+In the following, the most important classes that are used by the software but not part of the radiation transportation pipeline are explained.
+
+Spectral Quantity
+-----------------
+
+.. figure:: images/SpectralQty.pdf
+   :alt: Class Diagram
+
+   Class diagram of the Spectral Quantity.
+
+All spectral quantities used for calculations, e.g. spectral flux densities, spectral reflectances, etc., are handled as ``SpectralQty``-objects.
+They can be set up either by providing the two arrays wavelength bins and the corresponding spectral quantity as parameters to the constructor or by reading them from a file using the class method ``fromFile()``.
+In the latter case, the file must be readable by astropy and the units of the columns may be contained in the column header in square brackets.
+``SpectralQty``-objects natively support mathematical operations like addition (``__add__()``), substraction (``__sub__()``), multiplication (``__mul__()``) as well as true division (``__truediv__()``) and comparison (``__eq__()``).
+Additionally, the two methods ``rebin()`` and ``integrate()`` allow to change the spectral grid or integrate the quantity on the grid.
+
+.. _configuration:
+
+Configuration
+-------------
+
+.. figure:: images/Configuration.pdf
+   :alt: Class Diagram
+
+   Class diagram of the Configuration.
+
+The class ``Configuration`` contains all methods necessary to parse the XML-configuration file and convert it into a tree of :ref:`entry`-objects.
+This conversion is triggered in the beginning of the program flow.
+Additionally, the check of the parsed configuration is preformed by this class (``check_config()``, ``check_optical_components()``).
+In detail, the static ``checkConfig()``-method of the corresponding class is called on each Entry-object to perform the checks.
+Finally, this class also computes some meta options like the array containing the wavelength bins.
+
+.. _entry:
+
+Entry
+-----
+
+.. figure:: images/Entry.pdf
+   :alt: Class Diagram
+
+   Class diagram of the Entry.
+
+The class ``Entry`` is used to represent the tags of the XML-configuration file and provide basic test mechanisms.
+Each XML-tag is parsed by the :ref:`configuration` and converted into an ``Entry``-object.
+Thereby each attribute of the XML-tag is converted into an attribute of the corresponding ``Entry``-object.
+In case another attribute with the same name and the postfix *_unit* exists, both attributes are converted to an Astropy-Quantity object.
+In case a parameter is called ``val``, this parameter is returned if the ``Entry``-object is called.
+
+In order to allow checks on the attributes of an ``Entry``-object, the methods ``check_quantity()``, ``check_selection()``, ``check_file()``, ``check_path()`` and ``check_float()`` take the attribute name and possible a default value and return a string as check result.
+If the check is passed, ``None`` will be returned.

docs/source/developer/developer_documentation.rst

@@ -6,138 +6,27 @@ The following section provides detailed information on the the software architec
 The source code of ESBO-ETC and this documentation can be found on the `IRS Gitea-server <https://egit.irs.uni-stuttgart.de/esbo_ds/ESBO-ETC>`_.
 
 .. note::
-   In the following, methods of the source code may be mentioned without details on the required parameters or the return values. Please refer to the :ref:`api` for details.
+    In the following, methods of the source code may be mentioned without any details on the required parameters or the return values.
+    Please refer to the :ref:`api` for further information.
+
+ESBO-ETC uses `Astropy Quantities <https://docs.astropy.org/en/stable/units/>`_ for all computations in order to ensure proper unit conversion.
 
 Project Structure
 =================
 
-This project is structured into several folders as shown below. The three main folders are ``docs``, which contains the documentation,
-``esbo_etc`` containing all source files and ``tests``, where all tests are located.
-
-::
-
-    root
-    ├── docs                        Documentation files
-    │   └── source                  Source files of the documentation
-    │       ├── configuration       Configuration chapter of the documentation
-    │       ├── developer           Developer chapter of the documentation
-    │       └── usage               Usage chapter of the documentation
-    ├── esbo_etc                    Source code of ESBO-ETC
-    │   ├── classes                 Contains all classes of the source code
-    │   │   ├── optical_component   Contains all class files of the optical components
-    │   │   ├── psf                 Contains all class files to model the different types of PSF
-    │   │   ├── sensor              Contains all class files of the sensors
-    │   │   └── target              Contains all class files of the targets
-    │   ├── lib                     Contains all library functions
-    │   └── esbo-etc.py             This is the main file to run the application
-    └──  tests                      Contains all tests
-        ├── data                    Necessary data for all tests
-        ├── optical_component       Tests of the optical components
-        ├── psf                     Tests of the different PSF implementations
-        ├── sensor                  Tests of all sensors
-        └── target                  Tests of all targets
+.. include:: project_structure.rst
 
 Software Architecture
 =====================
 
-For modelling the radiation transportation, the `decorator pattern <https://en.wikipedia.org/wiki/Decorator_pattern>`_ and the
-`factory method pattern <https://en.wikipedia.org/wiki/Factory_method_pattern>`_ were used as shown in the figure below.
+.. include:: software_architecture.rst
 
-.. figure:: decorator_pattern.pdf
-   :alt: Decorator Pattern
-   :width: 100%
+Other Classes
+=============
 
-   The decorator pattern used for the radiation transportation.
-
-The radiation transportation pipeline consists always of a single target emitting the signal radiation.
-This target may be encapsulated by multiple optical components which manipulate the radiation by either adding their own background radiation or by decreasing the transmitted radiation.
-The outermost part of the radiation transportation pipeline is formed by some kind of sensor component, detecting the radiation.
-The quality of the detected signal can then be determined by calculating the signal to noise ration (SNR).
-
-.. figure:: class_diagram.pdf
-   :alt: Class Diagram
-
-   Class diagram of the software architecture.
-
-Radiant Interface
------------------
-
-In order to implement the aforementioned radiation transportation pipeline, a sophisticated software architecture has been designed.
-As shown in the class diagram, the class ``IRadiant`` forms the backbone of the structure.
-This interface class defines the two methods ``calcSignal()`` and ``calcBackground()`` and therefore the basic layout of all decorated classes.
-All targets and optical components implement this interface in oder to allow the cascading calculation of the signal and background fluxes.
-For both targets and optical components exists an abstract superclass which implements the required interface. This allows the actual
-classes to focus on the initialization and calculation of their own properties, ignoring the implementation of the interface.
-
-
-
-Target
-------
-
-The abstract class ``ATarget`` implements the interface provided by ``IRadiant`` and provides the abstract method ``checkConfig()`` which is used to check the relevant parts of the configuration file for this component.
-All available target types must inherit from ``ATarget`` and therefore must implement the method ``checkConfig()``.
-As the superclass ``ATarget`` implements the interface provided by ``IRadiant``, the compatibility to the radiation transportation pipeline is ensured.
-All subclasses therefore only set up a ``SpectralQty``-object containing the emitted radiation and call the constructor of ``ATarget``.
-
-Optical Component
------------------
-
-The abstract class ``AOpticalComponent`` implements the interface provided by ``IRadiant`` and thereby the two methods ``calcSignal()`` and ``calcBackground()``.
-This includes the treatment of central obstruction of the components as well as transmittance / reflectance coefficients.
-Additionally, ``AOpticalComponent`` provides the two methods ``propagate()`` for handling the propagation of incoming radiation through the optical component and ``ownNoise()`` for calculating the background radiation contribution of this component.
-The two function may be overwritten by the subclasses, if a custom implementation is necessary.
-Otherwise, the parameters ``transreflectivity`` and ``noise`` of the constructor method will be used for the calculations.
-In order to check the relevant parts of the configuration file for this component, the class provides the abstract method ``checkConfig()`` which has to be implement by all subclasses.
-
-According to the restrictions above, subclasses of ``AOpticalComponent`` can be implemented in two possible ways: either by providing the parameters ``transreflectivity`` and ``noise`` to the constructor of the superclass or by implementing the two methods ``propagate()`` and ``ownNoise()``.
-
-Hot Optical Component
-^^^^^^^^^^^^^^^^^^^^^
-
-The abstract class ``AHotOpticalComponent`` extends the abstract superclass ``AOpticalComponent`` by implementing the method ``ownNoise()`` assuming grey body radiation in order to model optical components with a thermal background contribution.
-This has the consequence, that every subclass of ``AHotOpticalComponent`` must implement the method ``propagate()``, which handles to propagation of the signal and backgroudn radiation through the component.
-Like ``AOpticalComponent``, the class ``AHotOpticalComponent`` provides the abstract method ``checkConfig()`` for checking the configuration file.
-
-Sensor
-------
-
-
-
-Classes
-=======
-
-All spectral quantities used for calculations, e.g. spectral flux densities, spectral reflectances, etc., are handled as ``SpectralQty``-objects, which support operations like additions, substractions, multiplications, divisions, etc.
-Additionally, ESBO-ETC uses Astropy-units for all calculations in order to avoid any conversion errors.
-The class ``Entry`` is used to represent the tags of the XML-configuration file.
+.. include:: classes.rst
 
 Extending ESBO-ETC
 ==================
 
-ESBO-ETC can be easily extended by adding new optical components or a new detector component.
-
-Adding Targets
---------------
-
-
-
-Adding Optical Components
--------------------------
-
-Extending ESBO-ETC by a new optical component consists of two tasks.
-
-First of all, the new optical component class has to be implemented in a separate file in the *classes*-folder.
-The new class must inherit from the abstract class ``AOpticalComponent`` or, in case of an optical component with thermal emission, from the abstract class ``AHotOpticalComponent`` and implement all abstract methods.
-In case of a cold optical component, the new class must implement the method ``checkConfig()`` and call the constructor of the super class.
-In case of a hot optical component, the new class must implement the method ``checkConfig()`` as well as the method ``propagate()`` and call the constructor of the super class.
-
-The method ``checkConfig()`` is used for checking the XML-configuration file and accepts as parameter the corresponding part of the configuration as ``Entry``-object.
-In case of an configuration error, the method must return the corresponding error message.
-
-The method ``propagate()`` is used to model the propagation of incoming radiation through the optical component.
-Therefore, this method receives as parameter the incoming radiation as ``SpectralQty``-object and must return the manipulated radiation as ``SpectralQty``-object.
-
-The second task consists of 
-
-Adding Detector Components
---------------------------
-
+.. include:: extending.rst

docs/source/developer/extending.rst

@@ -0,0 +1,27 @@
+ESBO-ETC can be easily extended by adding new optical components or a new detector component.
+
+Adding Targets
+--------------
+
+
+
+Adding Optical Components
+-------------------------
+
+Extending ESBO-ETC by a new optical component consists of two tasks.
+
+First of all, the new optical component class has to be implemented in a separate file in the *classes*-folder.
+The new class must inherit from the abstract class ``AOpticalComponent`` or, in case of an optical component with thermal emission, from the abstract class ``AHotOpticalComponent`` and implement all abstract methods.
+In case of a cold optical component, the new class must implement the method ``checkConfig()`` and call the constructor of the super class.
+In case of a hot optical component, the new class must implement the method ``checkConfig()`` as well as the method ``propagate()`` and call the constructor of the super class.
+
+The method ``checkConfig()`` is used for checking the XML-configuration file and accepts as parameter the corresponding part of the configuration as ``Entry``-object.
+In case of an configuration error, the method must return the corresponding error message.
+
+The method ``propagate()`` is used to model the propagation of incoming radiation through the optical component.
+Therefore, this method receives as parameter the incoming radiation as ``SpectralQty``-object and must return the manipulated radiation as ``SpectralQty``-object.
+
+The second task consists of
+
+Adding Detector Components
+--------------------------

docs/source/developer/project_structure.rst

@@ -0,0 +1,25 @@
+This project is structured into several folders as shown below. The three main folders are ``docs``, which contains the documentation,
+``esbo_etc`` containing all source files and ``tests``, where all tests are located.
+
+::
+
+    root
+    ├── docs                        Documentation files
+    │   └── source                  Source files of the documentation
+    │       ├── configuration       Configuration chapter of the documentation
+    │       ├── developer           Developer chapter of the documentation
+    │       └── usage               Usage chapter of the documentation
+    ├── esbo_etc                    Source code of ESBO-ETC
+    │   ├── classes                 Contains all classes of the source code
+    │   │   ├── optical_component   Contains all class files of the optical components
+    │   │   ├── psf                 Contains all class files to model the different types of PSF
+    │   │   ├── sensor              Contains all class files of the sensors
+    │   │   └── target              Contains all class files of the targets
+    │   ├── lib                     Contains all library functions
+    │   └── esbo-etc.py             This is the main file to run the application
+    └──  tests                      Contains all tests
+        ├── data                    Necessary data for all tests
+        ├── optical_component       Tests of the optical components
+        ├── psf                     Tests of the different PSF implementations
+        ├── sensor                  Tests of all sensors
+        └── target                  Tests of all targets

docs/source/developer/software_architecture.rst

@@ -0,0 +1,129 @@
+For modelling the radiation transportation, the `decorator pattern <https://en.wikipedia.org/wiki/Decorator_pattern>`_ was used as shown in the figure below.
+
+.. figure:: images/decorator_pattern.pdf
+   :alt: Decorator Pattern
+   :width: 100%
+
+   The decorator pattern used for the radiation transportation.
+
+The radiation transportation pipeline consists always of a single target emitting the signal radiation.
+This target may be encapsulated by multiple optical components which manipulate the radiation by either adding their own background radiation or by decreasing the transmitted radiation.
+The outermost part of the radiation transportation pipeline is formed by some kind of sensor component, detecting the radiation.
+The quality of the detected signal can then be determined by calculating the signal to noise ration (SNR).
+
+.. figure:: images/class_diagram.pdf
+   :alt: Class Diagram
+
+   Class diagram of the software architecture.
+
+Radiant Interface
+-----------------
+
+.. figure:: images/IRadiant.pdf
+   :alt: Interface IRadiant
+
+   Class diagram of the interface IRadiant.
+
+In order to implement the aforementioned radiation transportation pipeline, a sophisticated software architecture has been designed.
+As shown in the class diagram, the class ``IRadiant`` forms the backbone of the structure.
+This interface class defines the two methods ``calcSignal()`` and ``calcBackground()`` and therefore the basic layout of all decorated classes.
+All targets and optical components implement this interface in oder to allow the cascading calculation of the signal and background fluxes.
+For both targets and optical components exists an abstract superclass which implements the required interface. This allows the actual
+classes to focus on the initialization and calculation of their own properties, ignoring the implementation of the interface.
+
+Target
+^^^^^^
+
+.. figure:: images/Target.pdf
+   :alt: Target Classes
+
+   Class diagram of the target classes.
+
+The abstract class ``ATarget`` implements the interface provided by ``IRadiant`` and provides the abstract method ``checkConfig()`` which is used to check the relevant parts of the configuration file for this component.
+All available target types must inherit from ``ATarget`` and therefore must implement the method ``checkConfig()``.
+As the superclass ``ATarget`` implements the interface provided by ``IRadiant``, the compatibility to the radiation transportation pipeline is ensured.
+All subclasses therefore only set up a ``SpectralQty``-object containing the emitted radiation and call the constructor of ``ATarget``.
+
+Optical Component
+^^^^^^^^^^^^^^^^^
+
+.. figure:: images/OpticalComponent.pdf
+   :alt: Optical component classes
+
+   Class diagram of the optical components.
+
+The abstract class ``AOpticalComponent`` implements the interface provided by ``IRadiant`` and thereby the two methods ``calcSignal()`` and ``calcBackground()``.
+This includes the treatment of central obstruction of the components as well as transmittance / reflectance coefficients.
+Additionally, ``AOpticalComponent`` provides the two methods ``propagate()`` for handling the propagation of incoming radiation through the optical component and ``ownNoise()`` for calculating the background radiation contribution of this component.
+The two function may be overwritten by the subclasses, if a custom implementation is necessary.
+Otherwise, the parameters ``transreflectivity`` and ``noise`` of the constructor method will be used for the calculations.
+In order to check the relevant parts of the configuration file for this component, the class provides the abstract method ``checkConfig()`` which has to be implement by all subclasses.
+
+According to the restrictions above, subclasses of ``AOpticalComponent`` can be implemented in two possible ways: either by providing the parameters ``transreflectivity`` and ``noise`` to the constructor of the superclass or by implementing the two methods ``propagate()`` and ``ownNoise()``.
+
+Hot Optical Component
+"""""""""""""""""""""
+
+.. figure:: images/HotOpticalComponent.pdf
+   :alt: Hot optical component classes
+
+   Class diagram of the hot optical components.
+
+The abstract class ``AHotOpticalComponent`` extends the abstract superclass ``AOpticalComponent`` by implementing the method ``ownNoise()`` assuming grey body radiation in order to model optical components with a thermal background contribution.
+This has the consequence, that every subclass of ``AHotOpticalComponent`` must implement the method ``propagate()``, which handles to propagation of the signal and backgroudn radiation through the component.
+Like ``AOpticalComponent``, the class ``AHotOpticalComponent`` provides the abstract method ``checkConfig()`` for checking the configuration file.
+
+Sensor
+------
+
+.. figure:: images/Sensor.pdf
+   :alt: Sensor classes
+
+   Class diagram of the sensor components.
+
+The abstract class ``ASensor`` is the superclass that must be subclassed by every sensor class.
+It provides the three abstract methods ``calcSNR()``, ``calcExpTime()`` and ``calSensitivity()`` which must be implemented by the subclasses.
+These three abstract methods act as interface for the processing and evaluation of the incoming radiation in the detector.
+``getSNR()``, ``getExpTime()`` and ``getSensitivity()`` are called by the main application to trigger the evaluation of the radiation transportation pipeline and the subsequent calculation of the desired quantity.
+Additionally, ``ASensor`` defines the abstract method ``checkConfig()`` to allow the check of the sensor-configuration.
+
+PSF
+---
+
+.. figure:: images/PSF.pdf
+   :alt: PSF classes
+
+   Class diagram of the PSF classes.
+
+For modelling the diffraction behaviour of the telescope, the interface ``IPSF`` defines the necessary methods.
+Currently, two different implementations of PSFs are available: the class ``Airy`` allows to model the PSF as an airy disk, whereas the class ``Zemax`` allows to use a PSF calculated by the software Zemax.
+Both classes allow the computation of the reduced observation angle for a given encircled energy and the mapping of the PSF onto an pixel grid.
+
+Factories
+---------
+
+In order to instantiate the corresponding objects from the configuration file, the `factory method pattern <https://en.wikipedia.org/wiki/Factory_method_pattern>`_ was used.
+The following two factory methods are responsible for transforming the parsed configuration into the cascaded radiation transportation pipeline.
+
+Radiant Factory
+^^^^^^^^^^^^^^^
+
+.. figure:: images/RadiantFactory.pdf
+   :alt: RadiantFactory class
+
+   Class diagram of the radiant factory.
+
+The class ``RadiantFactory`` is responsible for the instantiation of all targets and optical components.
+Therefore the method ``create()`` analyzes the parsed configuration and assembles the necessary parameters for the following instantiation of the object.
+The method ``fromConfigBatch`` allows to set up a batch of objects starting with a target and continuing with possibly multiple optical components.
+
+Sensor Factory
+^^^^^^^^^^^^^^
+
+.. figure:: images/SensorFactory.pdf
+   :alt: SensorFactory class
+
+   Class diagram of the sensor factory.
+
+The class ``SensorFactory`` allows to instantiate a sensor object from the parsed configuration.
+In detail, the method ``create()`` is responsible for assembling all parameters and setting up the object.