From 628f69845a07da1fbc437f51812f366610266c0f Mon Sep 17 00:00:00 2001 From: LukasK13 Date: Tue, 26 May 2020 22:10:21 +0200 Subject: [PATCH] Docs updated --- docs/source/conf.py | 4 +- docs/source/configuration/common.rst | 183 ++++++++++++++ .../configuration/optical_components.rst | 158 ++++++++++++ docs/source/configuration/sensor.rst | 224 ++++++++++++++++++ docs/source/configuration/target.rst | 49 ++++ 5 files changed, 617 insertions(+), 1 deletion(-) create mode 100644 docs/source/configuration/common.rst create mode 100644 docs/source/configuration/optical_components.rst create mode 100644 docs/source/configuration/sensor.rst create mode 100644 docs/source/configuration/target.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 3d9ef01..1abed5c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,10 +39,12 @@ templates_path = ['_templates'] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] +exclude_patterns = ['configuration/target.rst', 'configuration/common.rst', 'configuration/optical_components.rst', + 'configuration/sensor.rst'] # -- Options for HTML output ------------------------------------------------- +html_show_sourcelink = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. diff --git a/docs/source/configuration/common.rst b/docs/source/configuration/common.rst new file mode 100644 index 0000000..ad7ea93 --- /dev/null +++ b/docs/source/configuration/common.rst @@ -0,0 +1,183 @@ +The tag ``common`` groups common configuration parameters and is therefore mandatory. + +wl_min +------ +The minimal wavelength to consider in the computations. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the minimal wavelength. + * | **val_unit:** str, *optional* = "m" + | The unit of the minimal wavelength. This has to be one of [``m``, ``cm``, ``mm``, ``um``, ``nm``, ``pm``]. The default is ``m``. + +wl_max +------ +The maximal wavelength to consider in the computations. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the maximal wavelength. + * | **val_unit:** str, *optional* = "m" + | The unit of the maximal wavelength. This has to be one of [``m``, ``cm``, ``mm``, ``um``, ``nm``, ``pm``]. The default is ``m``. + +.. _wl_delta: + +wl_delta +-------- +*optional* -- The wavelength grid size to be used for the computations. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the wavelength grid size. + * | **val_unit:** str, *optional* = "m" + | The unit of the wavelength grid size. This has to be one of [``m``, ``cm``, ``mm``, ``um``, ``nm``, ``pm``]. The default is ``m``. + +.. _res: + +res +--- +*optional* -- The spectral resolution to be used for the computations. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the spectral resolution. + * | **val_unit:** str, *optional* = "" + | The unit of the spectral resolution. This has to be emtpy (dimensionless). The default is ``dimensionless``. + +.. note:: + Either :ref:`wl_delta` or :ref:`res` must be given in the configuration. + +d_aperture +---------- +The diameter of the telescope aperture. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the telescope aperture diameter. + * | **val_unit:** str, *optional* = "m" + | The unit of the telescope aperture diameter. This has to be one of [``m``, ``cm``, ``mm``, ``um``, ``nm``, ``pm``]. The default is ``m``. + +.. _psf: + +psf +--- +*optional* -- The PSF used for the computations. This can be either read from a Zemax file or approximated by a (obstructed) airy disk. + +.. code-block:: xml + + + +.. code-block:: xml + + + +Attributes: + * | **val:** str = "Airy" + | The PSF to be used for the computations. This can be either the path to a Zemax file or the keyword *Airy* to for an airy disk as PSF. + * | **osf:** str = "10" + | The oversampling factor to be used to calculate the contained energy and the PSF with jitter. + * | **osf_unit:** str, *optional* = "" + | The unit of the oversampling factor. This has to be emtpy (dimensionless). The default is ``dimensionless``. + +.. _jitter_sigma: + +jitter_sigma +------------ +*optional* -- The pointing jitter sigma. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the pointing jitter sigma. + * | **val_unit:** str, *optional* = "arcsec" + | The unit of the pointing jitter sigma. This has to be one of [``arcsec``, ``arcmin``, ``degree``, ``radians``]. The default is ``arcsec``. + +output +------ +*optional* -- Output settings for the results of the computation. + +.. code-block:: xml + + + +Attributes: + * | **path:** str = "." + | The path to the output directory. + * | **format:** str = "CSV" + | The format to be used for outputting the signal and noise contributions. This has to be one of [``FITS``, ``CSV``]. + +.. _exposure_time: + +exposure_time +------------- +*optional* -- The exposure time(s) for the computations. + +.. code-block:: xml + + + +.. code-block:: xml + + + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The exposure time(s) to be used for the computations. This can be either a single value, a comma separated list of values or the path to a CSV-file containing a single column of exposure time values. For details on the required file structure see also :ref:`reading_csv`. + * | **val_unit:** str, *optional* = "s" + | The unit of the exposure time. This has to be one of [``ns``, ``us``, ``ms``, ``s``, ``min``, ``h``]. If the path to a file is provided, this parameter must be omitted. The default is ``s``. + +.. _snr: + +snr +--- +*optional* -- The signal to noise ration (SNR) for the computations. + +.. code-block:: xml + + + +.. code-block:: xml + + + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The SNR(s) to be used for the computations. This can be either a single value, a comma separated list of values or the path to a CSV-file containing a single column of SNR values. For details on the required file structure see also :ref:`reading_csv`. + * | **val_unit:** str, *optional* = "" + | The unit of the exposure time. This has to be emtpy (dimensionless). If the path to a file is provided, this parameter must be omitted. The default is ``dimensionless``. + +.. note:: + The two parameters :ref:`exposure_time` and :ref:`snr` control the desired output of the computations. + If only the exposure time is given, the corresponding signal to noise ration will be calculated and vice versa. + If both the exposure time and the SNR is given as well as a black body target, the sensitivity will be calculated as limiting apparent magnitude. \ No newline at end of file diff --git a/docs/source/configuration/optical_components.rst b/docs/source/configuration/optical_components.rst new file mode 100644 index 0000000..1e141fd --- /dev/null +++ b/docs/source/configuration/optical_components.rst @@ -0,0 +1,158 @@ +Each optical component consists of the basic tag ```` and the attribute ``type`` and possible other +component-specific attributes. + +.. code-block:: xml + + + +Attributes: + * | **type:** str + | The type of the optical component. This can be one of the following types. + +Atmosphere +---------- +This component models the behaviour of an atmosphere which has a spectral transmittance and a spectral emission. + +.. code-block:: xml + + + +Attributes: + * | **transmittance:** str + | The path to the file containing the spectral transmittance coefficients. For details on the required file structure see also :ref:`reading_csv`. + * | **emission:** str, *optional* + | The path to the file containing the spectral radiance of the emission. For details on the required file structure see also :ref:`reading_csv`. + +StrayLight +---------- +This component allows to model generic noise sources like stray light or zodiacal light from a file containing the spectral radiance of the emission. + +.. code-block:: xml + + + +Attributes: + * | **emission:** str, *optional* + | The path to the file containing the spectral radiance of the emission. For details on the required file structure see also :ref:`reading_csv`. + +Mirror +------ +Model a mirror including the mirror's thermal emission as well as possible obstruction of the mirror and the thermal emission of the obstructing component. + +.. code-block:: xml + + + +Attributes: + * | **reflectance:** str + | The path to the file containing the spectral reflectance coefficients. For details on the required file structure see also :ref:`reading_csv`. + * | **emissivity:** str, *optional* + | The path to the file containing the spectral emissivity coefficients. For details on the required file structure see also :ref:`reading_csv`. + * | **temp:** str, *optional* + | The temperature of the mirror for the thermal emission. + * | **temp_unit:** str, *optional* + | The unit of the mirror's temperature. This has to be one of [``K``, ``Celsius``]. The default is ``K``. + * | **obstruction:** str, *optional* + | The obstruction factor of the mirror as ratio of the areas A\ :sub:`obstructor` / A\ :sub:`mirror`. + * | **obstructor_temp:** str, *optional* + | The temperature of the obstructing component for the thermal emission. + * | **obstructor_temp_unit:** str, *optional* + | The unit of the obstructing component's temperature. This has to be one of [``K``, ``Celsius``]. The default is ``K``. + * | **obstructor_emissivity:** str, *optional* + | The emissivity of the obstructing component for the thermal emission. Valid ranges are 0.0 - 1.0. The default is 1.0. + +Lens +---- +Model a lens including the lens' thermal emission as well as possible obstruction of the lens and the thermal emission of the obstructing component. + +.. code-block:: xml + + + +Attributes: + * | **transmittance:** str + | The path to the file containing the spectral transmittance coefficients. For details on the required file structure see also :ref:`reading_csv`. + * | **emissivity:** str, *optional* + | The path to the file containing the spectral emissivity coefficients. For details on the required file structure see also :ref:`reading_csv`. + * | **temp:** str, *optional* + | The temperature of the lens for the thermal emission. + * | **temp_unit:** str, *optional* + | The unit of the lens' temperature. This has to be one of [``K``, ``Celsius``]. The default is ``K``. + * | **obstruction:** str, *optional* + | The obstruction factor of the lens as ratio of the areas A\ :sub:`obstructor` / A\ :sub:`lens`. + * | **obstructor_temp:** str, *optional* + | The temperature of the obstructing component for the thermal emission. + * | **obstructor_temp_unit:** str, *optional* + | The unit of the obstructing component's temperature. This has to be one of [``K``, ``Celsius``]. The default is ``K``. + * | **obstructor_emissivity:** str, *optional* + | The emissivity of the obstructing component for the thermal emission. Valid ranges are 0.0 - 1.0. The default is 1.0. + +BeamSplitter +------------ +Model a beam splitter including the beam splitter's thermal emission as well as possible obstruction of the beam splitter and the thermal emission of the obstructing component. + +.. code-block:: xml + + + +Attributes: + * | **transmittance:** str + | The path to the file containing the spectral transmittance coefficients. For details on the required file structure see also :ref:`reading_csv`. + * | **emissivity:** str, *optional* + | The path to the file containing the spectral emissivity coefficients. For details on the required file structure see also :ref:`reading_csv`. + * | **temp:** str, *optional* + | The temperature of the beam splitter for the thermal emission. + * | **temp_unit:** str, *optional* + | The unit of the beam splitter's temperature. This has to be one of [``K``, ``Celsius``]. The default is ``K``. + * | **obstruction:** str, *optional* + | The obstruction factor of the beam splitter as ratio of the areas A\ :sub:`obstructor` / A\ :sub:`beam splitter`. + * | **obstructor_temp:** str, *optional* + | The temperature of the obstructing component for the thermal emission. + * | **obstructor_temp_unit:** str, *optional* + | The unit of the obstructing component's temperature. This has to be one of [``K``, ``Celsius``]. The default is ``K``. + * | **obstructor_emissivity:** str, *optional* + | The emissivity of the obstructing component for the thermal emission. Valid ranges are 0.0 - 1.0. The default is 1.0. + +Filter +------ +Model a beam splitter including the beam splitter's thermal emission as well as possible obstruction of the beam splitter and the thermal emission of the obstructing component. + +.. code-block:: xml + + + +.. code-block:: xml + + + +.. code-block:: xml + + + +Attributes: + * | **transmittance:** str + | The path to the file containing the spectral transmittance coefficients. For details on the required file structure see also :ref:`reading_csv`. + * | **band:** str + | The spectral Band of the filter. This has to be one of [``U``, ``B``, ``V``, ``R``, ``I``, ``J``, ``H``, ``K``, ``L``, ``M``, ``N``] + * | **start:** str + | The start wavelength of the pass band of the filter. + * | **start_unit:** str + | The unit of the start wavelength. This has to be one of [``m``, ``cm``, ``mm``, ``um``, ``nm``, ``pm``]. The default is ``m``. + * | **end:** str + | The end wavelength of the pass band of the filter. + * | **end_unit:** str + | The unit of the end wavelength. This has to be one of [``m``, ``cm``, ``mm``, ``um``, ``nm``, ``pm``]. The default is ``m``. + * | **emissivity:** str, *optional* + | The path to the file containing the spectral emissivity coefficients. For details on the required file structure see also :ref:`reading_csv`. + * | **temp:** str + | The temperature of the beam splitter for the thermal emission. + * | **temp_unit:** str, *optional* + | The unit of the beam splitter's temperature. This has to be one of [``K``, ``Celsius``]. The default is ``K``. + * | **obstruction:** str, *optional* + | The obstruction factor of the beam splitter as ratio of the areas A\ :sub:`obstructor` / A\ :sub:`filter`. + * | **obstructor_temp:** str, *optional* + | The temperature of the obstructing component for the thermal emission. + * | **obstructor_temp_unit:** str, *optional* + | The unit of the obstructing component's temperature. This has to be one of [``K``, ``Celsius``]. The default is ``K``. + * | **obstructor_emissivity:** str, *optional* + | The emissivity of the obstructing component for the thermal emission. Valid ranges are 0.0 - 1.0. The default is 1.0. \ No newline at end of file diff --git a/docs/source/configuration/sensor.rst b/docs/source/configuration/sensor.rst new file mode 100644 index 0000000..f5cac6f --- /dev/null +++ b/docs/source/configuration/sensor.rst @@ -0,0 +1,224 @@ +Currently, ESBO-ETC only supports detectors of the type :ref:`imager`. + +.. code-block:: xml + + + +Attributes: + * | **type:** str + | The type of the detector. Has to be one of [``Imager``]. + +.. _imager: + +Imager +------ +The Imager sensor type allows to model a generic imaging sensor which uses a pixel based array to create only spatially resolved images. The imager-component contains several parameters which are explained in the following. + +.. code-block:: xml + :linenos: + + + + + + + + + + + + + + + + + + + +f_number +^^^^^^^^ +The working focal number of the instrument. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the working focal number of the instrument. + * | **val_unit:** str, *optional* = "" + | The unit of the working focal number of the instrument. This has to be emtpy (dimensionless). + +.. _pixel_geometry: + +pixel_geometry +^^^^^^^^^^^^^^ +The geometry of the sensor's pixel array. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The geometry of the sensor's pixel array as a comma separated list of the number of pixels per dimension (X, Y). + * | **val_unit:** str, *optional* = "pix" + | The unit of the geometry of the sensor's pixel array. This has to be ``pix``. + +.. _center_offset: + +center_offset +^^^^^^^^^^^^^ +The PSF's center offset from the arithmetical center of the detector array which is defined as half of the number of pixels per dimension as defined in :ref:`pixel_geometry` + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | PSF's center offset as a comma separated list of the offset in pixels per dimension (X, Y). + * | **val_unit:** str, *optional* = "pix" + | The unit of the PSF's center offset. This has to be ``pix``. + +pixel +^^^^^ +The pixel-container contains parameters which apply to all pixels of the sensor array. + +.. code-block:: xml + :linenos: + + + + + + + + + +quantum_efficiency +"""""""""""""""""" +The quantum efficiency of a detector pixel. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The path to the file containing the quantum efficiency values. For details on the required file structure see also :ref:`reading_csv`. + +pixel_size +"""""""""" +The spatial size of each detector pixel. Each pixel is assumed to be of quadratic. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the edge length of a detector pixel. + * | **val_unit:** str, *optional* = "m" + | The unit of the edge length of a detector pixel. This has to be one of [``m``, ``cm``, ``mm``, ``um``, ``nm``, ``pm``]. The default is ``m``. + +dark_current +"""""""""""" +The dark current of a detector pixel. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the dark current of a detector pixel. + * | **val_unit:** str, *optional* = "electron / (pix * s)" + | The unit of the dark current of a detector pixel. This has to be ``electron / (pix * s)``. + +sigma_read_out +"""""""""""""" +The read out noise of a detector pixel. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the read out noise of a detector pixel. + * | **val_unit:** str, *optional* = "electron(1/2) / pix" + | The unit of the read out noise of a detector pixel. This has to be ``electron(1/2) / pix``. + +well_capacity +""""""""""""" +The well capacity of a detector pixel. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The value of the well capacity of a detector pixel. + * | **val_unit:** str, *optional* = "electron" + | The unit of the well capacity of a detector pixel. This has to be ``electron``. + +photometric_aperture +^^^^^^^^^^^^^^^^^^^^ +*optional* + +The photometric_aperture-container contains parameters for the photometric aperture of the observation. This container is only required, if the :ref:`target` has the shape ``point``. + +.. code-block:: xml + :linenos: + + + + + + + +shape +""""" +The shape of the photometric aperture which will be placed around the center of the PSF which is defined by :ref:`center_offset`. After the radius of the photometric aperture was calculated using a disk for the given :ref:`contained_energy`, this radius will be used as radius or edge length of the photometric aperture shape. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The shape of the photometric aperture. This has to be one of [``circle``, ``square``]. + +.. _contained_energy: + +contained_energy +"""""""""""""""" +*optional* + +The energy to be contained within the photometric aperture. This value will used for the computation of the radius of the photometric aperture. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The energy to be contained within the photometric aperture. This can be either the percentage of contained energy or one of [``Peak``, ``FWHM``, ``Min``]. + +contained_pixels +"""""""""""""""" +*optional* + +The number of pixels to be contained within the photometric aperture. If this parameter is given, the :ref:`contained_energy` parameter will be ignored. The square root of this value will be used as the radius of the photometric aperture. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The number of pixels to be contained within the photometric aperture. + * | **val_unit:** str, *optional* = "pix" + | The unit of the number of pixels to be contained within the photometric aperture. This has to be ``pix``. diff --git a/docs/source/configuration/target.rst b/docs/source/configuration/target.rst new file mode 100644 index 0000000..c4fc1ce --- /dev/null +++ b/docs/source/configuration/target.rst @@ -0,0 +1,49 @@ +Currently ESBO-ETC supports the following two different types of targets. A configuration can contain only one target +which has to be contained in the container ````. Each target consists of the basic tag +```` and possible other target-type specific attributes. + +.. code-block:: xml + + + +Attributes: + * | **type:** str + | The type of the target. Currently, only :ref:`blackbodytarget` and :ref:`filetarget` are supported. + * | **size:** str + | The size of the target which can be either ``point`` or ``extended``. In case of a point-source, a PSF will be used to determine the irradiance of each pixel. In case of a extended source, a uniform PSF is assumed, ignoring the parameters :ref:`psf`, :ref:`jitter_sigma`, and some instrument specific parameters. + +.. _blackbodytarget: + +BlackBodyTarget +--------------- +Model a target as a black body of a given temperature and apparent magnitude. + +.. code-block:: xml + + + +Attributes: + * | **temp:** str + | The temperature of the black body. + * | **temp_unit:** str, *optional* = "K" + | The unit of the black body's temperature. This has to be one of [``K``, ``Celsius``]. The default is ``K``. + * | **mag:** str + | The apparent magnitude of the black body in magnitudes. + * | **mag_unit:** str, *optional* = "mag" + | The unit of the black body's magnitude. This has to be ``mag``. The default is ``mag``. + * | **band:** str + | The band used for fitting the black body's flux density to Vega's flux density. This has to be one of [``U``, ``B``, ``V``, ``R``, ``I``, ``J``, ``H``, ``K``, ``L``, ``M``, ``N``]. + +.. _filetarget: + +FileTarget +---------- +Create a target from a file containing the spectral flux densities of the target. + +.. code-block:: xml + + + +Attributes: + * | **val:** str + | The path to the file containing the spectral flux densities. For details on the required file structure see also :ref:`reading_csv`.