Basics
======

Overview
--------

:Name: Extragalactic Point Sources
:Author: `Shikhar Mittal <https://sites.google.com/view/shikharmittal/home>`_
:Homepage: https://github.com/shikharmittal04/epspy
:Paper: `Mittal et al (2024) <https://doi.org/10.1093/mnras/stae2111>`_

Why do you need this code?
--------------------------

Use this code to generate the foregrounds due to extragalactic point radio sources.

A cosmological global 21-cm signal hides under foregrounds due to galactic and extragalactic emissions. These foregrounds can easily be 4 to 5 orders of magnitude higher than the signal of interest. For a reliable inference, it is important to accurately model these foregrounds. While we have a reasonable understanding of galactic emission (typically fit as a log-log polynomial), we do not understand the extragalactic contributions. This package models the foregrounds due to extragalactic point radio sources.

Read more about it in the paper `Mittal et al (2024) <https://doi.org/10.1093/mnras/stae2111>`_.

Installation and requirements
-----------------------------

This package can be installed as

.. code:: bash

   pip install epspy

We recommend working on a Python version > 3.8. Packages required are 

- `numpy <https://pypi.org/project/numpy/>`_
- `scipy <https://pypi.org/project/scipy/>`_
- `matplotlib <https://pypi.org/project/matplotlib/>`_
- `mpi4py <https://pypi.org/project/mpi4py/>`_
- `healpy <https://pypi.org/project/healpy/>`_
- `transformcl <https://pypi.org/project/transformcl/>`_


Quick start
-----------

The code is run in two main steps:

-  Assign the point sources flux densities (at a chosen reference frequency) and spectral indices.
-  Then generate the sky maps at desired frequencies of observation.

The following code captures the main functionalities of this package.

.. code:: python

   from epspy import meps

   #Step-1 initialise the object with default settings
   obj = meps.eps()

   #Step-2 generate the data at the reference frequency
   obj.ref_freq()

   #Step-3 generate the sky maps at multiple frequencies as well as their sky average
   obj.gen_freq()

   #Step-4 finally, generate a sky-averaged spectrum vs frequency figure
   obj.visual()


Save the above code as (say) ``eg_script.py`` and run it as

.. code:: bash

    python eg_script.py

Running the above will generate several files. The terminal messages will guide you to these output files. The most important of all files of your interest will be ``Tb_nu_map.npy``. To visualise your outputs use the function :func:`visual`. See :ref:`api` for the available features for :func:`visual`. To learn more about the output files and code working see :ref:`detexp`. To learn about the physics of this package see our `paper <https://doi.org/10.1093/mnras/stae2111>`_.

In this package we have set the default values such that the users can run their scripts on a PC. Since modern PCs have at least 4 cores, for better performance, one could also run script ``eg_script.py`` parallelly as 

.. code:: bash

    mpirun -np 4 python eg_script.py

However, in general, and for more realistic flux density ranges and high-resolution maps, we recommend using the package on HPCs.

License and citation
--------------------
The software is free to use on the MIT open-source license. If you use the software then please cite `Mittal et al (2024) <https://doi.org/10.1093/mnras/stae2111>`_.

If the code is used in a project where the author has provided significant scientific input, guidance on methodology, or assistance with interpretation of results, then co-authorship on resulting publications is expected, following standard academic practice.

Users are encouraged to contact the author when using the code for new scientific applications or major projects.

Acknowledgement
---------------
I thank Girish Kulkarni, Dominic Anstey, and Eloy de Lera Acedo for helpful comments and feedback during the development of this code.