From 9a24a20aeb99e001bf5ba373888f159beaec8d09 Mon Sep 17 00:00:00 2001
From: Aaron LI <aaronly.me@outlook.com>
Date: Sat, 26 Nov 2016 14:29:48 +0800
Subject: Add the simple user guide: docs/guide.rst
Also update the README.rst a bit
---
README.rst | 29 ++++++++++++++++++-----------
docs/guide.rst | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 74 insertions(+), 11 deletions(-)
create mode 100644 docs/guide.rst
diff --git a/README.rst b/README.rst
index 52aef30..c495b0a 100644
--- a/README.rst
+++ b/README.rst
@@ -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``.
--
cgit v1.2.2