diff --git a/docs/source/conf.py b/docs/source/conf.py index 91ea953..c66221c 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/developer/classes.rst b/docs/source/developer/classes.rst new file mode 100644 index 0000000..664bbfd --- /dev/null +++ b/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. diff --git a/docs/source/developer/developer_documentation.rst b/docs/source/developer/developer_documentation.rst index 3a29060..8ba3c69 100644 --- a/docs/source/developer/developer_documentation.rst +++ b/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 `_. .. 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 `_ 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 `_ and the -`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 diff --git a/docs/source/developer/extending.rst b/docs/source/developer/extending.rst new file mode 100644 index 0000000..7145653 --- /dev/null +++ b/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 +-------------------------- diff --git a/docs/source/developer/images/Configuration.pdf b/docs/source/developer/images/Configuration.pdf new file mode 100644 index 0000000..270474a Binary files /dev/null and b/docs/source/developer/images/Configuration.pdf differ diff --git a/docs/source/developer/images/Entry.pdf b/docs/source/developer/images/Entry.pdf new file mode 100644 index 0000000..4621dc2 Binary files /dev/null and b/docs/source/developer/images/Entry.pdf differ diff --git a/docs/source/developer/images/HotOpticalCOmponent.pdf b/docs/source/developer/images/HotOpticalCOmponent.pdf new file mode 100644 index 0000000..bf0168c Binary files /dev/null and b/docs/source/developer/images/HotOpticalCOmponent.pdf differ diff --git a/docs/source/developer/images/IRadiant.pdf b/docs/source/developer/images/IRadiant.pdf new file mode 100644 index 0000000..34de497 Binary files /dev/null and b/docs/source/developer/images/IRadiant.pdf differ diff --git a/docs/source/developer/images/OpticalComponent.pdf b/docs/source/developer/images/OpticalComponent.pdf new file mode 100644 index 0000000..babe652 Binary files /dev/null and b/docs/source/developer/images/OpticalComponent.pdf differ diff --git a/docs/source/developer/images/PSF.pdf b/docs/source/developer/images/PSF.pdf new file mode 100644 index 0000000..a3606ed Binary files /dev/null and b/docs/source/developer/images/PSF.pdf differ diff --git a/docs/source/developer/images/RadiantFactory.pdf b/docs/source/developer/images/RadiantFactory.pdf new file mode 100644 index 0000000..b2f0383 Binary files /dev/null and b/docs/source/developer/images/RadiantFactory.pdf differ diff --git a/docs/source/developer/images/Sensor.pdf b/docs/source/developer/images/Sensor.pdf new file mode 100644 index 0000000..c9592e7 Binary files /dev/null and b/docs/source/developer/images/Sensor.pdf differ diff --git a/docs/source/developer/images/SensorFactory.pdf b/docs/source/developer/images/SensorFactory.pdf new file mode 100644 index 0000000..d71b684 Binary files /dev/null and b/docs/source/developer/images/SensorFactory.pdf differ diff --git a/docs/source/developer/images/SpectralQty.pdf b/docs/source/developer/images/SpectralQty.pdf new file mode 100644 index 0000000..45b9b66 Binary files /dev/null and b/docs/source/developer/images/SpectralQty.pdf differ diff --git a/docs/source/developer/images/Target.pdf b/docs/source/developer/images/Target.pdf new file mode 100644 index 0000000..5adb9fc Binary files /dev/null and b/docs/source/developer/images/Target.pdf differ diff --git a/docs/source/developer/class_diagram.pdf b/docs/source/developer/images/class_diagram.pdf similarity index 87% rename from docs/source/developer/class_diagram.pdf rename to docs/source/developer/images/class_diagram.pdf index fd7bdb8..dbfa869 100644 Binary files a/docs/source/developer/class_diagram.pdf and b/docs/source/developer/images/class_diagram.pdf differ diff --git a/docs/source/developer/decorator_pattern.pdf b/docs/source/developer/images/decorator_pattern.pdf similarity index 100% rename from docs/source/developer/decorator_pattern.pdf rename to docs/source/developer/images/decorator_pattern.pdf diff --git a/docs/source/developer/project_structure.rst b/docs/source/developer/project_structure.rst new file mode 100644 index 0000000..3c5cd17 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/source/developer/software_architecture.rst b/docs/source/developer/software_architecture.rst new file mode 100644 index 0000000..cf53a10 --- /dev/null +++ b/docs/source/developer/software_architecture.rst @@ -0,0 +1,129 @@ +For modelling the radiation transportation, the `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 `_ 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.