From 988cfcc0e5a57fbc529781aeaa8eac6cc88b317c Mon Sep 17 00:00:00 2001 From: LukasK13 Date: Mon, 25 May 2020 17:00:28 +0200 Subject: [PATCH] First documentation --- docs/source/configuration/configuration.rst | 18 +++ .../developer/developer_documentation.rst | 15 +++ docs/source/index.rst | 20 ++-- docs/source/usage/getting_started.rst | 112 ++++++++++++++++++ docs/source/usage/introduction.rst | 12 ++ 5 files changed, 170 insertions(+), 7 deletions(-) create mode 100644 docs/source/configuration/configuration.rst create mode 100644 docs/source/developer/developer_documentation.rst create mode 100644 docs/source/usage/getting_started.rst create mode 100644 docs/source/usage/introduction.rst diff --git a/docs/source/configuration/configuration.rst b/docs/source/configuration/configuration.rst new file mode 100644 index 0000000..f00d2d6 --- /dev/null +++ b/docs/source/configuration/configuration.rst @@ -0,0 +1,18 @@ +************************** +Building the Configuration +************************** + +Basic Structure +============================ + +Common conf +============================ + +Target +============================ + +Optical components +============================ + +Sensor +============================ diff --git a/docs/source/developer/developer_documentation.rst b/docs/source/developer/developer_documentation.rst new file mode 100644 index 0000000..2714354 --- /dev/null +++ b/docs/source/developer/developer_documentation.rst @@ -0,0 +1,15 @@ +************************************ +Developer Documentation +************************************ + +============================ +Project Structure +============================ + +============================ +Classes +============================ + +============================ +Extending ESBO-ETC +============================ diff --git a/docs/source/index.rst b/docs/source/index.rst index 601dbb5..9fc38ec 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,18 +3,24 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +#################################### Welcome to ESBO-ETC's documentation! -==================================== +#################################### .. toctree:: :maxdepth: 2 :caption: Contents: + usage/introduction + usage/getting_started + configuration/configuration + developer/developer_documentation +.. + ****************** + Indices and tables + ****************** -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` diff --git a/docs/source/usage/getting_started.rst b/docs/source/usage/getting_started.rst new file mode 100644 index 0000000..1777ec3 --- /dev/null +++ b/docs/source/usage/getting_started.rst @@ -0,0 +1,112 @@ +*************** +Getting Started +*************** +This chapter provides information on how to start using ESBO-ETC. + +============ +Installation +============ +A Python 3 installation is required to run ESBO-ETC. You can get the latest python version +`here `_. + +In order to get ESBO-ETC, clone the code from the IRS git server using + +.. code-block:: bash + :linenos: + + git clone https://egit.irs.uni-stuttgart.de/esbo_ds/ESBO-ETC.git + +or download the code from the `IRS git server `_. + +Python Virtual Environment +-------------------------- + +It is advisable to create a python virtual environment for ESBO-ETC where all necessary packages will be installed. +To create a virtual environment and install all packages, got to the project's root directory an run + +.. code-block:: bash + :linenos: + + python3 -m venv venv + source venv/bin/activate + python venv/bin/pip install -r requirements.txt + +Global Python installation +-------------------------- +Instead of a virtual environment, the global python installation can be used to run ESBO-ETC. Therefore, the necessary +packages need to be installed by running the following command from the project's root directory. + +.. code-block:: bash + :linenos: + + pip install -r requirements.txt + +================ +Running ESBO-ETC +================ +ESBO-ETC can be run using in multiple ways as explained in the following subsections. However all methods provide the +same options which can be shown using the parameter ``-h`` or ``--help``. + +The following options are available: + +:-h, -\\-help: Show the help. +:-c, -\\-config: Specify the path to the configuration file. Default is esbo-etc_defaults.xml. +:-l, -\\-logging: Specify the log level for the application. Possible levels are DEBUG, INFO, WARNING, ERROR. +:-v, -\\-version: Print version information. +:-m, -\\-manual: Print the manual. + + +Shell-Script +------------ +The recommended way to run ESBO-ETC is to use the provided shell-script which will add the project's root directory to +the PATH-variable. However the shell-script only works for virtual environment installations. + +.. code-block:: bash + :linenos: + + ./run_esbo-etc [-h] [-c config.xml] [-l LOGGING] [-v] [-m] + +Python Interpreter +------------------ +An alternative way to start ESBO-ETC is by using the python interpreter from the command line. This method works for +both a virtual environment as well as for the global python installation. Launching ESBO-ETC can be done using + +.. code-block:: bash + :linenos: + + python3 esbo_etc/esbo-etc.py [-h] [-c config.xml] [-l LOGGING] [-v] [-m] + +================== +Component Overview +================== +ESBO-ETC offers many different components to model the path from the astronomical target to the detector. All components +can be divided into the three following classes. + +Target +------ +The component class *Target* models astronomical targets, defining the spectral flux density of their signal and their +shape (point source vs. extended source). Currently, two different target types are available: + +* A target modelled as **black body** with a given temperature and apparent magnitude. +* A target with the signal's spectral flux density read from a **file**. + +Optical Component +----------------- +Multiple optical components are available for modelling the signal and background flux propagation. The hot optical +components with a thermal grey body emission form a subclass of the optical components. Currently, the following optical +components are available + +* An **atmosphere** component modelling the atmospheric tranmittance and emission, both read from files. +* A **stray light** component for modelling generic background source like zodiacal light or earth stray light. +* Hot optical components with thermal emission of a given temperature and emissivity: + + * A **mirror** component modelling the optical properties of a mirror like the mirror's reflectance. + * A **lens** component the optical properties of a lens like the lens' transmittance. + * A **beam splitter** component the optical properties of a beam splitter like the beam splitter's transmittance. + * A **filter** component the optical properties of a filter like the filter's transmittance. + +Sensor +------ +Currently, only the imager sensor component is available. The imager provides many parameters to adapt the components +to the needs like the dark current, the read noise, pixel size, array size but also parameters for the photometric +aperture like the percentage of contained energy or the shape of the photometric aperture. diff --git a/docs/source/usage/introduction.rst b/docs/source/usage/introduction.rst new file mode 100644 index 0000000..2e8d2d2 --- /dev/null +++ b/docs/source/usage/introduction.rst @@ -0,0 +1,12 @@ +************ +Introduction +************ + +ESBO-ETC aims on modelling the physical aspect of light coming from a target through optical components +(e.g. atmosphere, mirrors, lenses, ...) onto the detector. The set up of this so called optical pipeline can be +individually defined using a configuration file. Additionally, the thermal emission of optical components, the +obstruction of components as well as different PSFs including pointing jitter can be considered. + +Finally, ESBO-ETC allows the computation of either the necessary exposure time for a desired SNR, the SNR for a given +exposure time or, in case of a BlackBodyTarget, the sensitivity as the minimum apparent magnitude for a given exposure +time and SNR. All computations support a batch-mode, allowing to compute multiple set ups at once.