==============================================================
Realistic Foregrounds Simulation for EoR 21cm Signal Detection
==============================================================

**WARNING:**
This package is still under heavy development, and may lack some
necessary features or even fail to run correctly.
It is *NOT* recommended to use it at the moment!
Nevertheless, *tests and feedback* are always welcome!


This |fg21sim|_ package provides the tools to simulate the
*realistic* low-frequency radio foregrounds, which can be further
used to test various foreground removal or separation methods, for the
purpose of successfully detecting the 21cm cosmological signal arising
from the netrual hydrogen (HI) at epoch of reionization (EoR).


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

  + ``galactic/synchrotron``:
    Galactic synchrotron emission (*Note:* only *unpolarized* considered now)
  + ``galactic/freefree``:
    Galactic free-free emission
  + ``galactic/snr``:
    Emission from Galactic supernovae remnants (SNRs)
  + ``extragalactic/clusters``:
    Emission from extragalactic clusters of galaxies
    (*Note:* only radio *halos* considered at the moment)
  + ``extragalactic/pointsources``:
    Emission from multiple types of extragalactic discrete point sources
    (*Note:* this component was contributed by Zhixian MA, and is not well
    integrated and tested at the moment)

    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

* All-sky simulation
  (*Note:* partial-sky simulation not supported yet)
* Configuration file allowing fine-grained control
* Modular and well-designed API
* Easy-to-use command line tools (CLI)
* Full-featured Web UI
  (*Note:* recent Firefox, Chrome/Chromium, Edge, and IE >=11 are supported)
* Handy utilities


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 (e.g., package ``libhealpix-cxx0`` on Debian Linux)
  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/>`_)


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

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

2. Install the system requirements: CFITSIO, HEALPix, and LLVM.

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 this virtual environment is active and 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. Great!  You are ready to use this package.
   Just have a look, e.g.::

   $ fg21sim --help
   $ fg21sim-webui --help


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


Authors
-------
* Weitian LI <``liweitianux@live.com``>


Contributors
------------
* 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
.. |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
.. _`MIT License`: https://opensource.org/licenses/MIT
.. _`Creative Commons Attribution 3.0 License`:
   https://creativecommons.org/licenses/by/3.0/us/deed.en_US