version 1.0

.coveragerc

@@ -39,12 +39,13 @@ exclude_lines =
 
 omit =
     ares/util/Aesthetics.py
-    ares/util/BlobBundles.py
+    ares/util/cli.py
     ares/util/MPIPool.py
     ares/util/PrintInfo.py
     ares/util/Warnings.py
     ares/analysis/*.py
     ares/inference/*.py
+    ares/data/*.py
 
 ignore_errors = True
 

.github/workflows/test_suite.yaml

@@ -38,7 +38,7 @@ jobs:
     - name: Build
       run: |
         pip install .
-        python remote.py minimal
+        ares download tests
     - name: Test with pytest
       run: |
         pytest --cov-config=.coveragerc --cov=ares --cov-report=xml -v tests/*.py

.gitignore

@@ -5,6 +5,8 @@
 ares.egg-info
 *.png
 *.tar.gz
+build
+input/*
 docs/_build
 docs/*.py
 docs/*.txt
@@ -28,6 +30,9 @@ input/bpass_v1_stars/*
 input/bpass_v2
 input/inits/*.txt
 input/nircam
+input/rubin
+input/spherex
+input/wise
 tests/.coverage
 .coverage
 coverage.xml

.readthedocs.yaml

@@ -5,16 +5,16 @@
 # Required
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/conf.py
 
-# Optionally build your docs in additional formats such as PDF
-#formats:
-#   - pdf
-
 # Optionally set the version of Python and requirements required to build your docs
 python:
-   version: "3.7"
-   install:
-   - requirements: docs/requirements.txt
+  install:
+  - requirements: docs/requirements.txt

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

@@ -1,173 +1,101 @@
+
 # **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).
+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.
 
-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:
+**Note that for some applications, ARES relies heavily on lookup tables and publicly-available software packages that should be referenced as well.** These include:
 
 - Code for Anisotropies in the Microwave Background ([CAMB](https://camb.readthedocs.io/en/latest/)).
 - The Halo Mass Function ([hmf](https://hmf.readthedocs.io/en/latest/)) package (see [Murray et al.(2013)](https://arxiv.org/abs/1306.6721)).
 - Lookup tables and fitting formulae for the fraction of photo-electron energy deposited in heat, ionization, excitation from [Shull \& van Steenberg (1985)](https://ui.adsabs.harvard.edu/abs/1985ApJ...298..268S/abstract), [Ricotti, Gnedin, \& Shull (2002)](https://ui.adsabs.harvard.edu/abs/2002ApJ...575...33R/abstract), and [Furlanetto \& Stoever (2010)](https://ui.adsabs.harvard.edu/abs/2010MNRAS.404.1869F/abstract) (see `secondary_ionization` parameter, values of 2, 3, and 4, respectively).
 - Collisional coupling coefficients for the 21-cm line from [Zygelman (2005)](https://ui.adsabs.harvard.edu/abs/2005ApJ...622.1356Z/abstract).
-- Wouthuysen-Field coupling coefficients for the 21-cm line from [Chuzhoy, Alvarez, & Shapiro (2006)](https://ui.adsabs.harvard.edu/abs/2006ApJ...651....1C/abstract), [Furlanetto \& Pritchard (2006)](https://ui.adsabs.harvard.edu/abs/2006MNRAS.372.1093F/abstract), [Hirata (2006)](https://ui.adsabs.harvard.edu/abs/2006MNRAS.367..259H/abstract), and [Mittal & Kulkarni (2021)](https://ui.adsabs.harvard.edu/abs/2021MNRAS.503.4264M/abstract) (see `approx_Salpha` parameter, values of 2, 3, 4, and 5, respectively).
+- Wouthuysen-Field coupling coefficients for the 21-cm line from [Chuzhoy & Shapiro (2006)](https://ui.adsabs.harvard.edu/abs/2006ApJ...651....1C/abstract), [Furlanetto \& Pritchard (2006)](https://ui.adsabs.harvard.edu/abs/2006MNRAS.372.1093F/abstract), [Hirata (2006)](https://ui.adsabs.harvard.edu/abs/2006MNRAS.367..259H/abstract), and [Mittal & Kulkarni (2021)](https://ui.adsabs.harvard.edu/abs/2021MNRAS.503.4264M/abstract) (see `approx_Salpha` parameter, values of 2, 3, 4, and 5, respectively).
 - Lyman-alpha transition probabilities from [Pritchard \& Furlanetto (2006)](https://ui.adsabs.harvard.edu/abs/2006MNRAS.367.1057P/abstract).
-- Stellar population synthesis model options include starburst99 ([Leitherer et al. (1999)](https://ui.adsabs.harvard.edu/abs/1999ApJS..123....3L/abstract)) and BPASS versions 1 ([Eldridge \& Stanway (2009)](https://ui.adsabs.harvard.edu/abs/2009MNRAS.400.1019E/abstract)) and 2 ([Eldridge et al. (2017)](https://ui.adsabs.harvard.edu/abs/2017PASA...34...58E/abstract),[Stanway \& Eldridge (2018)](https://ui.adsabs.harvard.edu/abs/2018MNRAS.479...75S/abstract)) (via `pop_sed` parameter, values `'starburst99'`, `'bpass_v1'`, and `'bpass_v2'`, respectively).
+- Stellar population synthesis model options include starburst99 ([Leitherer et al. (1999)](https://ui.adsabs.harvard.edu/abs/1999ApJS..123....3L/abstract)), BPASS versions 1 ([Eldridge \& Stanway (2009)](https://ui.adsabs.harvard.edu/abs/2009MNRAS.400.1019E/abstract)) and 2 ([Eldridge et al. (2017)](https://ui.adsabs.harvard.edu/abs/2017PASA...34...58E/abstract),[Stanway \& Eldridge (2018)](https://ui.adsabs.harvard.edu/abs/2018MNRAS.479...75S/abstract)), and the [Bruzual \& Charlot (2003)](https://www.bruzual.org/bc03/) models. Which model is used is controlled by the `pop_sed` parameter, values `'starburst99'`, `'bpass_v1'`, `'bpass_v2'`, and `'bc03'` respectively. Note that each of these models is essentially a big lookup table; some can be downloaded automatically (see below).
 
 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/)
+## Installation
 
-and optionally,
+To install ARES, we recommend using pip:
 
-- [camb](https://camb.readthedocs.io/en/latest/)
-- [hmf](https://github.com/steven-murray/hmf)
-- [mpi4py](http://mpi4py.scipy.org)
-- [pymp](https://github.com/classner/pymp)
-- [emcee](http://dan.iel.fm/emcee/current/)
-- [distpy](https://bitbucket.org/ktausch/distpy)
-- [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)
+```
+pip install ares-astro # actual name TBD
+```
 
-If you'd like to build the documentation locally, you'll need:
+ARES often relies on external datasets.
 
-- [numpydoc](https://numpydoc.readthedocs.io/en/latest/)
-- [nbsphinx](https://nbsphinx.readthedocs.io/en/0.8.8/)
+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):
 
-and if you'd like to run the test suite locally, you'll want:
+```
+ares init
+```
 
-- [pytest](https://docs.pytest.org/en/7.1.x/)
-- [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/)
+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.
 
-which are pip-installable.
+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).
 
-Note: **ares** has been tested only with Python 2.7.x and Python 3.7.x.
+## Quick Examples
 
-## Getting started
+To generate a math:`z=6` luminosity function, you can do
 
-To clone a copy and install:
+```python
+import ares
+import numpy as np
+import matplotlib.pyplot as plt
 
-```
-git clone https://github.org/mirochaj/ares.git
-cd ares
-python setup.py install
-```
+pars = ares.util.ParameterBundle('mirocha2020:legacy')
+pop = ares.populations.GalaxyPopulation(**pars)
 
-**ares** will look in ``ares/input`` for lookup tables of various kinds. To download said lookup tables, run:
+bins, phi = pop.get_uvlf(z=6, bins=np.arange(-25, -10, 0.1))
 
-```
-python remote.py
+plt.semilogy(bins, phi)
 ```
 
-This might take a few minutes. If something goes wrong with the download, you can run
+Note: if the plot doesn't appear automatically, set ``interactive: True`` in your matplotlibrc file or type:
 
+```python
+plt.show()
 ```
-python remote.py fresh
-```
-
-to get fresh copies of everything.
-
-## Quick Example
 
 To generate a model for the global 21-cm signal, simply type:
 
 ```python
-import ares
-
-sim = ares.simulations.Global21cm()      # Initialize a simulation object
-sim.run()   
+pars = ares.util.ParameterBundle('global_signal:basic')
+sim = ares.simulations.Simulation(**pars)               
+gs = sim.get_21cm_gs()   
 ```                                               
 
-You can examine the contents of ``sim.history``, a dictionary which contains
-the redshift evolution of all IGM physical quantities, or use some built-in
-analysis routines:
+You can examine the contents of ``gs.history``, a dictionary which contains
+the redshift evolution of all properties of the intergalactic medium, or use some built-in analysis routines:
 
 ```python
-sim.GlobalSignature()
+gs.Plot21cmGlobalSignal()
 ```    
 
-If the plot doesn't appear automatically, set ``interactive: True`` in your matplotlibrc file or type:
-
-```python
-import matplotlib.pyplot as pl
-pl.show()
-```
-
-## Help
-
-If you encounter problems with installation or running simple scripts, first check the Troubleshooting page in the documentation to see if you're dealing with a common problem. If you don't find your problem listed there, please let me know!
-
-## Contributors
-
-Primary author: [Jordan Mirocha](https://sites.google.com/site/jordanmirocha/home) (McGill)
-
-Additional contributions / corrections / suggestions from:
-
-- 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
+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).