Prepare for PyPI package

INSTALL.rst

@@ -0,0 +1,94 @@
+Installation
+++++++++++++
+
+Dependencies
+------------
+If installed via pip, ARES' dependencies will be built automatically.
+
+But, in case you're curious, the core dependencies are:
+
+- [numpy](http://www.numpy.org/)
+- [scipy](http://www.scipy.org/)
+- [matplotlib](http://matplotlib.org/)
+- [h5py](http://www.h5py.org/)
+
+and the optional dependencies are:
+
+- [camb](https://camb.readthedocs.io/en/latest/)
+- [hmf](https://github.com/steven-murray/hmf)
+- [astropy](https://www.astropy.org/)
+- [dust_extinction](https://dust-extinction.readthedocs.io/en/stable/index.html)
+- [dust_attenuation](https://dust-extinction.readthedocs.io/en/stable/index.html)
+- [mpi4py](http://mpi4py.scipy.org)
+- [pymp](https://github.com/classner/pymp)
+- [progressbar2](http://progressbar-2.readthedocs.io/en/latest/)
+- [setuptools](https://pypi.python.org/pypi/setuptools)
+- [mpmath](http://mpmath.googlecode.com/svn-history/r1229/trunk/doc/build/setup.html)
+- [shapely](https://pypi.python.org/pypi/Shapely)
+- [descartes](https://pypi.python.org/pypi/descartes)
+
+If you'd like to build the documentation locally, you'll need:
+
+- [numpydoc](https://numpydoc.readthedocs.io/en/latest/)
+- [nbsphinx](https://nbsphinx.readthedocs.io/en/0.8.8/)
+
+and if you'd like to run the test suite locally, you'll want:
+
+- [pytest](https://docs.pytest.org/en/7.1.x/)
+- [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/)
+
+which are all pip-installable.
+
+Note: ARES has been tested only with Python 2.7.x and Python 3.7.x.
+
+External datasets: stellar population synthesis (SPS) models
+------------------------------------------------------------
+As discussed in the `README </README.rst>`_, ARES relies on many external datasets. The `ares init` command builds a minimal install, including some cosmological initial conditions, a single metallicity, :math:`Z=0.004`, constant star formation rate, single-star stellar population synthesis model from BPASS version 1.0, and a high redshift lookup table for the Tinker et al. 2010 halo mass function generated with `hmf <https://github.com/steven-murray/hmf>`.
+
+There are many more external datasets that can be downloaded easily using the ARES CLI. For example, to fetch the complete set of BPASS v1 models (all metallicities, constant star formation and simple stellar populations, single star and binaries), you can do
+
+```
+ares download bpass_v1
+```
+
+There are now newer versions of BPASS, which must be downloaded by hand. To download BPASS v2 models, navigate to `this page <https://bpass.auckland.ac.nz/9.html>`_ and download the desired models in the ``$HOME/.ares/bpass_v2`` directory. If you initialized ARES with a different path (via the `--path` flag; see `README </README.md`_), make sure you instead move files there.
+
+ARES is also setup to handle the starburst99 or Bruzual \& Charlot models, which can be downloaded via
+
+```
+ares download starburst99
+ares download bc03
+ares download bc03_2013   # for the 2013 update to the BC03 models
+```
+
+Pre-processing
+~~~~~~~~~~~~~~
+The spectral resolution of the BPASS models (and some other SPS models) is 1 Angstrom, which is much better than we need for most ARES modeling. So, many examples use "degraded" BPASS models, which just smooth the standard BPASS SEDs with a tophat of some width, generally 10 Angstroms. To do this SED degradation, we use the ARES CLI:
+
+```python
+import os
+from ares.util import cli as ares_cli
+
+ares_cli.generate_lowres_sps(f"{os.environ.get('HOME')}/.ares/bpass_v2/BPASSv2_imf135_300/OUTPUT_CONT", degrade_to=10)
+ares_cli.generate_lowres_sps(f"{os.environ.get('HOME')}/.ares/bpass_v2/BPASSv2_imf135_300/OUTPUT_POP", degrade_to=10)
+```
+
+Whether or not these files are required should be discussed in the various examples in the documentation, so please be sure to check there first for instructions if you get errors indicative of missing files.
+
+
+External datasets: filter transmission curves
+---------------------------------------------
+For generating mock photometry, we must convolve modeled SEDs with the transmission curves of a given telescope's photometric filters. We've got many common filters available, which you can download via, e.g., ::
+
+
+    for telescope in roman euclid rubin wise 2mass spherex wise dirbe irac sdss
+      ares download $telescope
+
+
+Again, be sure to supply the ``--path`` flag if your `$HOME` directory has a small quota.
+
+External datasets: posteriors for cosmological parameters from Planck
+---------------------------------------------------------------------
+Instead of supplying cosmological parameters by hand, you can also draw from published Planck chains directly via the `cosmology_name`, `cosmology_id`, and `cosmology_number` parameters. But first, you need the chains themselves. As per usual, you can do: ::
+
+    ares download planck

README.md

@@ -2,39 +2,30 @@
 # **ARES**
 [![Documentation Status](https://readthedocs.org/projects/ares/badge/?version=latest)](http://ares.readthedocs.io/en/latest/?badge=latest) ![Tests](https://github.com/mirochaj/ares/actions/workflows/test_suite.yaml/badge.svg) [![codecov](https://codecov.io/gh/mirochaj/ares/branch/main/graph/badge.svg?token=Q3CCKIMQJF)](https://codecov.io/gh/mirochaj/ares) [![Last Commit](https://img.shields.io/github/last-commit/mirochaj/ares)](https://img.shields.io/github/last-commit/mirochaj/ares)
 
-The Accelerated Reionization Era Simulations (ARES) code was designed to
-rapidly generate models for the global 21-cm signal. It can also be used as a
+The Accelerated Reionization Era Simulations (ARES) code was originally designed to
+rapidly generate models for the global 21-cm signal. However, it can also be used as a
 1-D radiative transfer code, stand-alone non-equilibrium chemistry solver,
-global radiation background calculator, or semi-analytic galaxy formation model.
+global radiation background calculator, or semi-empirical galaxy formation model.
 
 The documentation is [here](https://ares.readthedocs.io/en/latest/index.html).
 
 ## Technical Details
 
 The main papers that describe how ARES works include:
 
-- 1-D radiative transfer: [Mirocha et al. (2012)](http://adsabs.harvard.edu/abs/2012ApJ...756...94M)
-- Uniform backgrounds \& global 21-cm signal: [Mirocha (2014)](http://adsabs.harvard.edu/abs/2014MNRAS.443.1211M)
-- Galaxy luminosity functions: [Mirocha, Furlanetto, & Sun (2017)](https://ui.adsabs.harvard.edu/abs/2017MNRAS.464.1365M/abstract)
-- Population III star formation: [Mirocha et al. (2018)](http://adsabs.harvard.edu/abs/2018MNRAS.478.5591M)
-- Rest-ultraviolet colours at high-z: [Mirocha, Mason, & Stark (2020)](https://ui.adsabs.harvard.edu/abs/2020arXiv200507208M/abstract)
+- Galaxy luminosity functions (LFs): [Mirocha, Furlanetto, & Sun (2017)](https://ui.adsabs.harvard.edu/abs/2017MNRAS.464.1365M/abstract)
+- Self-consistent LFs and rest-ultraviolet colours: [Mirocha, Mason, & Stark (2020)](https://ui.adsabs.harvard.edu/abs/2020arXiv200507208M/abstract)
 - Near-infrared background and nebular emission: [Sun et al. (2021)](https://ui.adsabs.harvard.edu/abs/2021MNRAS.508.1954S/abstract)
-
-Plus some more applications:
-
-- [Mirocha & Furlanetto (2019)](http://adsabs.harvard.edu/abs/2018arXiv180303272M)
-- [Schneider (2018)](http://adsabs.harvard.edu/abs/2018PhRvD..98f3021S)
-- [Tauscher et al. (2017)](http://adsabs.harvard.edu/abs/2018ApJ...853..187T)
-- [Mirocha, Harker, & Burns (2015)](http://adsabs.harvard.edu/abs/2015ApJ...813...11M)
+- High-z UV and X-ray background \& global 21-cm signal: [Mirocha (2014)](http://adsabs.harvard.edu/abs/2014MNRAS.443.1211M)
+- Population III star formation: [Mirocha et al. (2018)](http://adsabs.harvard.edu/abs/2018MNRAS.478.5591M)
+- 1-D radiative transfer: [Mirocha et al. (2012)](http://adsabs.harvard.edu/abs/2012ApJ...756...94M)
 
 Be warned: this code is still under active development -- use at your own
 risk! Correctness of results is not guaranteed.
 
 ## Citation
 
-If you use ARES in paper please reference [Mirocha (2014)](http://adsabs.harvard.edu/abs/2014MNRAS.443.1211M) if it's an application of the global 21-cm modeling machinery and [Mirocha et al. (2012)](http://adsabs.harvard.edu/abs/2012ApJ...756...94M) if you use the 1-D radiative transfer and/or SED optimization. For galaxy semi-analytic modeling, please have a look at [Mirocha, Furlanetto, & Sun (2017)](http://adsabs.harvard.edu/abs/2016arXiv160700386M), [Mirocha, Mason, & Stark (2020)](https://ui.adsabs.harvard.edu/abs/2020arXiv200507208M/abstract), and [Mirocha (2020)](https://ui.adsabs.harvard.edu/abs/2020MNRAS.499.4534M/abstract), and for PopIII star modeling, see [Mirocha et al. (2018)](http://adsabs.harvard.edu/abs/2018MNRAS.478.5591M).
-
-Please also provide a link to [this page](https://github.com/mirochaj/ares) as a footnote.
+If you use ARES, please be sure to cite the relevant papers above depending on your use case (see [here](CITATION.rst) for bibtex entries). Please also provide a link to [this page](https://github.com/mirochaj/ares) as a footnote.
 
 **Note that for some applications, ARES relies heavily on lookup tables and publicly-available software packages that should be referenced as well.** These include:
 
@@ -48,165 +39,63 @@ Please also provide a link to [this page](https://github.com/mirochaj/ares) as a
 
 Feel free to get in touch if you are unsure of whether any of these tools are being used under the hood for your application.
 
-## Dependencies
-
-You will need:
-
-- [numpy](http://www.numpy.org/)
-- [scipy](http://www.scipy.org/)
-- [matplotlib](http://matplotlib.org/)
-- [h5py](http://www.h5py.org/)
-
-and optionally,
-
-- [camb](https://camb.readthedocs.io/en/latest/)
-- [hmf](https://github.com/steven-murray/hmf)
-- [astropy](https://www.astropy.org/)
-- [dust_extinction](https://dust-extinction.readthedocs.io/en/stable/index.html)
-- [dust_attenuation](https://dust-extinction.readthedocs.io/en/stable/index.html)
-- [mpi4py](http://mpi4py.scipy.org)
-- [pymp](https://github.com/classner/pymp)
-- [progressbar2](http://progressbar-2.readthedocs.io/en/latest/)
-- [setuptools](https://pypi.python.org/pypi/setuptools)
-- [mpmath](http://mpmath.googlecode.com/svn-history/r1229/trunk/doc/build/setup.html)
-- [shapely](https://pypi.python.org/pypi/Shapely)
-- [descartes](https://pypi.python.org/pypi/descartes)
-
-If you'd like to build the documentation locally, you'll need:
-
-- [numpydoc](https://numpydoc.readthedocs.io/en/latest/)
-- [nbsphinx](https://nbsphinx.readthedocs.io/en/0.8.8/)
-
-and if you'd like to run the test suite locally, you'll want:
-
-- [pytest](https://docs.pytest.org/en/7.1.x/)
-- [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/)
-
-which are pip-installable.
-
-Note: ARES has been tested only with Python 2.7.x and Python 3.7.x.
 
 ## Installation
 
-To clone a copy and install:
+To install ARES, we recommend using pip:
 
 ```
-git clone https://github.org/mirochaj/ares.git
-cd ares
-pip install . # or pip install -e .
+pip install ares-astro # actual name TBD
 ```
 
-ARES will look in ``$HOME/.ares`` for lookup tables of various kinds. To download the core set of lookup tables needed for the most common use-cases, we can use the ARES command-line interface (CLI):
-
-```
-ares download all
-```
+ARES often relies on external datasets.
 
-This might take a few minutes. If something goes wrong with the download, e.g., you lose your internet connection, you can run
+To download the core set of lookup tables needed for the most common use-cases, and perform some pre-processing, we can use the ARES command-line interface (CLI):
 
 ```
-ares download all --fresh
+ares init
 ```
 
-to get fresh copies of everything. You can also download or re-download one dataset at a time, e.g.,
+By default, ARES will download files to ``$HOME/.ares``. However, if your ``$HOME`` quota is small, do provide the flag ``--path=<someplace-with-plenty-of-disk-space>`` to ``ares init``, and setup a symbolic link that points from ``$HOME/.ares`` to this new location.
 
-```
-ares download bc03
-```
+Note that ``ares init`` sets up a minimal ARES installation with only the most oft-used external datasets. For more information about what is needed for broader applications, see [this page](INSTALL.rst).
 
-The examples within the documentation should say whether they require any non-standard lookup tables that, e.g., cannot be downloaded automatically using `ares download`. Please keep an eye out for that -- if you don't see any special instructions, and you're getting `IOError` or `OSError` or the like, do reach out.
+## Quick Examples
 
-Last note on this front. If you are running ARES on a machine with a very small quota in the `$HOME` directory, our trick of hiding lookup tables in `$HOME/.ares` will cause problems. A quick solution to this is to move the contents of `$HOME/.ares` somewhere else with plenty of disk space, and then make the file `$HOME/.ares` a symbolic link that points to this new folder. Probably we should add a flag to the CLI that can re-direct downloads to a user-supplied location to automate this hack in the future.
+To generate a math:`z=6` luminosity function, you can do
 
-## Pre-processing
+```python
+import ares
+import numpy as np
+import matplotlib.pyplot as plt
 
-Not only do some ARES calculations rely on external datasets, they often benefit from using slightly-modified versions of those datasets. For example, the spectral resolution of the BPASS models is 1 Angstrom, which is much better than we need for most ARES modeling. So, many examples use "degraded" BPASS models, which just smooth the standard BPASS SEDs with a tophat of some width, generally 10 Angstroms. To do this SED degradation, we also use the ARES CLI:
+pars = ares.util.ParameterBundle('mirocha2020:legacy')
+pop = ares.populations.GalaxyPopulation(**pars)
 
-```python
-import os
-from ares.util import cli as ares_cli
+bins, phi = pop.get_uvlf(z=6, bins=np.arange(-25, -10, 0.1))
 
-ares_cli.generate_lowres_sps(f"{os.environ.get('HOME')}/.ares/bpass_v2/BPASSv2_imf135_300/OUTPUT_CONT", degrade_to=10)
-ares_cli.generate_lowres_sps(f"{os.environ.get('HOME')}/.ares/bpass_v2/BPASSv2_imf135_300/OUTPUT_POP", degrade_to=10)
+plt.semilogy(bins, phi)
 ```
 
-Once again, this kind of information should be included in our examples, so please check there for instructions if you get errors indicative of missing files.
+Note: if the plot doesn't appear automatically, set ``interactive: True`` in your matplotlibrc file or type:
 
-## Quick Examples
+```python
+plt.show()
+```
 
 To generate a model for the global 21-cm signal, simply type:
 
 ```python
-import ares
-
-pars = ares.util.ParameterBundle('global_signal:basic') # Parameters
-sim = ares.simulations.Simulation(**pars)               # Initialize a simulation object
+pars = ares.util.ParameterBundle('global_signal:basic')
+sim = ares.simulations.Simulation(**pars)               
 gs = sim.get_21cm_gs()   
 ```                                               
 
 You can examine the contents of ``gs.history``, a dictionary which contains
-the redshift evolution of all IGM physical quantities, or use some built-in
-analysis routines:
+the redshift evolution of all properties of the intergalactic medium, or use some built-in analysis routines:
 
 ```python
 gs.Plot21cmGlobalSignal()
 ```    
 
-If the plot doesn't appear automatically, set ``interactive: True`` in your matplotlibrc file or type:
-
-```python
-import matplotlib.pyplot as plt
-plt.show()
-```
-
-To generate a quick luminosity function, you could do
-
-```python
-pars = ares.util.ParameterBundle('mirocha2017:base').pars_by_pop(0, 1)
-pop = ares.populations.GalaxyPopulation(**pars)
-
-bins, phi = pop.get_uvlf(z=6, bins=np.arange(-25, -10, 0.1))
-
-plt.semilogy(bins, phi)
-```
-
 If you're a pre-version-1.0 ARES user, most of this will look familiar, except these days we're running all models (21-cm, near-infrared background, etc.) through the `ares.simulations.Simulation` interface rather than specific classes. There's also a lot more consistency in call sequences, e.g., we adopt the convention of naming commonly-used functions and attributes as `get_<something>` and `tab_<something>`. A much longer list of v1 convention changes can be found in [Pull Request 61](https://github.com/mirochaj/ares/pull/61).
-
-## Contributors
-
-Primary author: [Jordan Mirocha](https://sites.google.com/site/jordanmirocha/home)
-
-Additional contributions / corrections / suggestions from:
-
-.. hlist::
-   :columns: 3
-
-   * Geraint Harker               
-   * Jason Sun
-   * Keith Tauscher
-   * Jacob Jost
-   * Greg Salvesen
-   * Adrian Liu
-   * Saurabh Singh
-   * Rick Mebane
-   * Krishma Singal
-   * Donald Trinh
-   * Omar Ruiz Macias
-   * Arnab Chakraborty
-   * Madhurima Choudhury
-   * Saul Kohn
-   * Aurel Schneider
-   * Kristy Fu
-   * Garett Lopez
-   * Ranita Jana
-   * Daniel Meinert
-   * Henri Lamarre
-   * Matteo Leo
-   * Emma Klemets
-   * Felix Bilodeau-Chagnon
-   * Venno Vipp
-   * Oscar Hernandez
-   * Joshua Hibbard
-   * Trey Driskell
-   * Judah Luberto
-   * Paul La Plante

THANKS.rst

@@ -0,0 +1,38 @@
+:orphan:
+
+Acknowledgements
+----------------
+ARES has benefited from many helpful contributions, corrections, and suggestions over the years from:
+
+.. hlist::
+   :columns: 3
+
+   * Geraint Harker
+   * Jason Sun
+   * Keith Tauscher
+   * Jacob Jost
+   * Greg Salvesen
+   * Adrian Liu
+   * Saurabh Singh
+   * Rick Mebane
+   * Krishma Singal
+   * Donald Trinh
+   * Omar Ruiz Macias
+   * Arnab Chakraborty
+   * Madhurima Choudhury
+   * Saul Kohn
+   * Aurel Schneider
+   * Kristy Fu
+   * Garett Lopez
+   * Ranita Jana
+   * Daniel Meinert
+   * Henri Lamarre
+   * Matteo Leo
+   * Emma Klemets
+   * Felix Bilodeau-Chagnon
+   * Venno Vipp
+   * Oscar Hernandez
+   * Joshua Hibbard
+   * Trey Driskell
+   * Judah Luberto
+   * Paul La Plante

ares/analysis/MultiPhaseMedium.py

@@ -15,7 +15,6 @@
 import matplotlib.pyplot as pl
 from ..util.Stats import get_nu
 from ..util.Pickling import read_pickle_file
-from scipy.misc import derivative
 from ..physics.Constants import *
 from scipy.integrate import cumulative_trapezoid
 from scipy.interpolate import interp1d