Realistic Foreground Simulation for 21 cm Reionization Signal Detection
=======================================================================

The |fg21sim|_ is a low-frequency radio foregrounds simulator
aiming to provide the realistic simulation of the common foregrounds
impeding the EoR 21cm signal detection.
The simulated foregrounds can be used to evaluate the impacts of
different foreground components on the EoR signal, and can be also
used to help develop and test various foreground removal/separation
methods.

Features
--------
* Supported foreground components:

  + ``galactic/synchrotron``:
    Galactic synchrotron emission
    (*Note:* only the *unpolarized* part considered)
  + ``galactic/freefree``:
    Galactic free-free emission
  + ``galactic/snr``:
    Emission from Galactic supernovae remnants (SNRs)
  + ``extragalactic/clusters``:
    Emission from extragalactic galaxy clusters
    (*Note:* only giant radio halos)
  + ``extragalactic/pointsources``:
    Emission from multiple types of extragalactic discrete point sources
    (*WARNING:* need updates and integration!)

    Current supported point sources types:

    - Star-forming galaxies
    - Starburst galaxies
    - Radio-quiet AGNs
    - Fanaroff-Riley type I (FR-I) AGNs
    - Fanaroff-Riley type II (FR-II) AGNs

* All-sky simulation by utilizing HEALPix
  (*Note:* not all components are currently supported)
* High-resolution simulation within sky patches
* Configuration file allowing fine-grained control
* Well organized and detail comments
* Modular and extensible
* Handy command line tools, utilities, and modules
* Simple Web UI
  (*WARNING:* need significant updates!)


Requirements
------------
* Linux operating system (other UNIX-like systems not tested)
* `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 required by `healpy <https://github.com/healpy/healpy>`_.
* `LLVM <http://llvm.org/>`_:
  (required by `llvmlite <http://llvmlite.pydata.org/>`_ which is a
  dependency of `Numba <http://numba.pydata.org/>`_)


Installation
------------
1. Clone this repository::

   $ git clone https://github.com/liweitianux/fg21sim

2. Install the above required software and libraries.

3. Install the required third-party Python packages.
   And it is recommended to use the `virtual environment`_::

   $ cd fg21sim/
   $ make venv
   $ . ./venv/bin/activate

   Check to make sure that this virtual environment is activated so that the
   default ``python3`` and ``pip3`` is pointed to the virtual environment.

4. Install this ``fg21sim`` package to the virtual environment::

   $ python3 setup.py install

5. You are ready to use this package. Just have a look, e.g.::

   $ fg21sim --help


Development
-----------
To ease the development and tests, you may want to install this package
in the **editable state**::

    $ cd fg21sim/
    $ pip3 install --user -r requirements.txt
    $ pip3 install --editable .

In addition, setting the environment variable ``DEBUG_FG21SIM`` forces
this package running with ``DEBUG`` logging level.


Documentations
--------------
To get started, read the `User Guide`_.

**WARNING:**
The documentation is *out-of-date* with the current code, and needs
significant updates!


Contributions
-------------
Great!  Be sure to consult the guidelines in |CONTRIBUTING.md|_.


Authors
-------
* Weitian LI <``weitian@aaronly.me``>
* Zhixian MA <``zxma_sjtu@qq.com``>


License
-------
Unless otherwise declared:

* Codes developed by us are distributed under the `MIT License`_;
* Documentations and products generated by us are distributed under the
  `Creative Commons Attribution 3.0 License`_;
* Third-party codes and products used are distributed under their own
  licenses.  See also |LICENSE-3RDPARTY|_.


..
   Workaround for nested inline markups:
   http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible
   https://stackoverflow.com/a/4836544/4856091

.. |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