diff options
| -rw-r--r-- | README.rst | 29 | ||||
| -rw-r--r-- | docs/guide.rst | 56 |
2 files changed, 74 insertions, 11 deletions
@@ -36,11 +36,11 @@ Features Current supported point sources types: - - star-forming galaxies - - star-bursting galaxies - - radio-quiet AGNs - - Fanaroff-Riley type I (FRI) AGNs - - Fanaroff-Riley type II (FRII) AGNs + - Star-forming galaxies + - Star-bursting galaxies + - Radio-quiet AGNs + - Fanaroff-Riley type I (FR-I) AGNs + - Fanaroff-Riley type II (FR-II) AGNs * All-sky simulation (*Note:* partial-sky simulation not supported yet) @@ -58,8 +58,7 @@ Requirements * `Python <https://www.python.org/>`_: >= 3.4 * `CFITSIO <https://heasarc.gsfc.nasa.gov/fitsio/fitsio.html>`_ * `HEALPix <http://healpix.sourceforge.net/>`_: - only the C++ library (e.g., package ``libhealpix-cxx0`` on Debian Linux) - required by `healpy <https://github.com/healpy/healpy>`_. + only the C++ library required by `healpy <https://github.com/healpy/healpy>`_. * `LLVM <http://llvm.org/>`_: = 3.8 (required by `llvmlite <http://llvmlite.pydata.org/>`_ which is a dependency of `Numba <http://numba.pydata.org/>`_) @@ -71,10 +70,10 @@ Installation $ git clone https://github.com/liweitianux/fg21sim -2. Install the system requirements: CFITSIO, HEALPix, and LLVM. +2. Install the above system requirements: CFITSIO, HEALPix, and LLVM. 3. Install the required third-party Python packages. - And it is recommended to use the *virtual environment*:: + And it is recommended to use the `virtual environment`_:: $ cd fg21sim/ $ make venv @@ -87,13 +86,17 @@ Installation $ python3 setup.py install -5. Great! You are ready to use this package. - Just have a look, e.g.:: +5. You are ready to use this package. Just have a look, e.g.:: $ fg21sim --help $ fg21sim-webui --help +Documentations +-------------- +To get started, read the `User Guide`_. + + Contributions ------------- Great! Be sure to consult the guidelines in |CONTRIBUTING.md|_. @@ -127,12 +130,16 @@ Unless otherwise declared: .. |fg21sim| replace:: **fg21sim** .. _fg21sim: https://github.com/liweitianux/fg21sim +.. _`User Guide`: + https://github.com/liweitianux/fg21sim/blob/master/docs/guide.rst .. |CONTRIBUTING.md| replace:: ``CONTRIBUTING.md`` .. _CONTRIBUTING.md: https://github.com/liweitianux/fg21sim/blob/master/CONTRIBUTING.md .. |LICENSE-3RDPARTY| replace:: ``LICENSE-3RDPARTY`` .. _LICENSE-3RDPARTY: https://github.com/liweitianux/fg21sim/blob/master/LICENSE-3RDPARTY +.. _`virtual environment`: + https://docs.python.org/3/library/venv.html .. _`MIT License`: https://opensource.org/licenses/MIT .. _`Creative Commons Attribution 3.0 License`: https://creativecommons.org/licenses/by/3.0/us/deed.en_US diff --git a/docs/guide.rst b/docs/guide.rst new file mode 100644 index 0000000..e0f0536 --- /dev/null +++ b/docs/guide.rst @@ -0,0 +1,56 @@ +========== +User Guide +========== + +This is a simple guide on how to use the **fg21sim** package to carry +out the foregrounds simulation, which produces the all-sky maps of the +enabled foreground components. + +The simulation of several foreground components (e.g., +``galactic/synchrotron``, ``galactic/freefree``) uses the semi-empirical +method, thus it requires specific template map(s) and/or +observational/simulation catalog(s) as the input. + +* ``galactic/synchrotron``: + requires the Haslam 408 MHz survey as the template map, and the + spectral index map. +* ``galactic/freefree``: + requires the Hα map and the dust map. +* ``galactic/snr``: + requires the catalog of the Galactic SNRs. +* ``extragalactic/clusters``: + requires the catalog of the clusters of galaxies. + +All the required input templates and catalogs can be retrieved using +the ``fg21sim-download-data`` CLI tool, by providing it with this +`data manifest <data-manifest.json>`_. + +Then, a configuration file is required to run the foregrounds simulation, +which controls all aspects of the simulation behaviors. +There are two types of configuration options: +*required* (which require the user to explicitly provide the values) +and *optional* (which already have sensible defaults, however, the user +can also override them). + +There is an `example configuration file <fg21sim.conf.example>`_ with +detailed explanations on each configuration option. +Also there is a brief `test configuration file <fg21sim-test.conf>`_ +which may be useful to test whether this package is correctly installed +and runs smoothly. + +Finally, the foregrounds simulation can be kicked off using the CLI tool:: + + $ fg21sim --logfile fg21sim.log fg21sim.conf + +This way, the simulation program will take configurations from +file ``fg21sim.conf``, and log messages to both the screen and file +``fg21sim.log``. + + +On the other hand, the Web UI can also be used, which provides a more +intuitive and friendly way to tune the configurations, to view the +logging messages, as well as to navigate the simulation products:: + + $ fg21sim-webui --debug & + +Then the Web UI can be accessed at ``http://localhost:21127``. |