zonca · zonca · Oct 5, 2021 · Oct 7, 2021 · Oct 7, 2021 · Oct 7, 2021
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -4,13 +4,13 @@ build:
   image: latest
 
 python:
-  version: 3.7
+  version: 3.8
   system_packages: true
   install:
     - method: pip
       path: .
       extra_requirements:
         - docs
-        - all
+        - test
 
 formats: []
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,7 +1,13 @@
-3.3.2 (unreleased)
+3.3.3 (unreleased)
 ==================
 
+3.3.2 (2021-10-29)
+==================
+
+- `Improvements to install documentation <https://github.com/galsci/pysm/pull/93>`_
 - Moved Github repository from `healpy/pysm` to `galsci/pysm`, under the Panexperiment Galactic Science group organization
+- Changes in this release are related to the `JOSS Review <https://github.com/openjournals/joss-reviews/issues/3783>`_
+- Turned `UserWarning` into `logging`, `Pull Request 88 <https://github.com/galsci/pysm/pull/88>`_
 
 3.3.1 (2021-06-30)
 ==================

diff --git a/CITATION b/CITATION
@@ -1,13 +1,18 @@
-@misc{pysm3,
-      title={The Python Sky Model 3 software}, 
-      author={Andrea Zonca and Ben Thorne and Nicoletta Krachmalnicoff and Julian Borrill},
-      year={2021},
-      eprint={2108.01444},
-      archivePrefix={arXiv},
-      primaryClass={astro-ph.IM}
+@article{Zonca_2021,
+  doi = {10.21105/joss.03783},
+  url = {https://doi.org/10.21105/joss.03783},
+  year = {2021},
+  publisher = {The Open Journal},
+  volume = {6},
+  number = {67},
+  pages = {3783},
+  author = {Andrea Zonca and Ben Thorne and Nicoletta Krachmalnicoff and Julian Borrill},
+  title = {{The Python Sky Model 3 software}},
+  journal = {Journal of Open Source Software}
 }
+
 @article{Thorne_2017,
-   title={The Python Sky Model: software for simulating the Galactic microwave sky},
+   title={{The Python Sky Model: software for simulating the Galactic microwave sky}},
    volume={469},
    ISSN={1365-2966},
    url={http://dx.doi.org/10.1093/mnras/stx949},

diff --git a/README.rst b/README.rst
@@ -26,9 +26,11 @@ Install
 
 See the `documentation <https://pysm3.readthedocs.io/en/latest/#installation>`_
 
-* Install with ``pip install .``
+* Install with ``pip install .`` or with ``pip install .[test]`` to also install the requirements for running tests
+* Optionally, if you have an MPI environment available and you would like to test the MPI capabilities of PySM, install ``mpi4py`` and ``libsharp``, check the documentation link above for more details.
 * Check code style with ``tox -e codestyle``
 * Test with ``pytest`` or ``tox -e test``
+* Building docs requires ``pandoc``, not the python package, the actual ``pandoc`` command line tool, install it with conda or your package manager
 * Build docs locally with ``tox -e build_docs``
 
 Support

diff --git a/docs/index.rst b/docs/index.rst
@@ -50,7 +50,14 @@ Python, which is slower, but easier to debug::
 
     export NUMBA_DISABLE_JIT=1
 
-In order to run in parallel with MPI, it also needs:
+Run PySM with MPI support
+-------------------------
+
+PySM 3 is capable of running across multiple nodes using a MPI communicator.
+
+See the details in the `MPI section of the tutorial <mpi.ipynb>`_.
+
+In order to run in parallel with MPI, it also needs a functioning MPI environment and:
 
 * `mpi4py`
 
@@ -98,10 +105,41 @@ Create a development installation with::
 
     pip install -e .
 
+Install the requirements for testing with::
+
+    pip install -e .[test]
+
 Execute the unit tests with::
 
     pytest
 
+Configure verbosity
+-------------------
+
+PySM uses the `logging` module to configure its verbosity,
+by default it will only print warnings and errors, to configure logging
+you can access the "pysm3" logger with::
+
+    import logging
+    log = logging.getLogger("pysm3")
+
+configure the logging level::
+
+    log.setLevel(logging.DEBUG)
+
+redirect the logs to the console::
+
+    handler = logging.StreamHandler()
+    log.addHandler(handler)
+
+or customize their format::
+
+    log_format="%(name)s - %(levelname)s - %(message)s"
+    formatter = logging.Formatter(log_format)
+    handler.setFormatter(formatter)
+
+For more details see the `Python documentation <https://docs.python.org/3/library/logging.html>`_.
+
 Tutorials
 =========
 

diff --git a/docs/models.rst b/docs/models.rst
@@ -55,7 +55,7 @@ Dust
 Synchrotron
 ===========
 
-- **s1**: A power law scaling is used for the synchrotron emission, with a spatially varying spectral index. The emission templates are the Haslam 408 MHz, 57' resolution data reprocessed by Remazeilles et al 2015 MNRAS 451, 4311, and the WMAP 9-year 23 GHz Q/U maps (Bennett, C.L., et.al., 2014, ApJS, 208, 20B). The polarization maps have been smoothed with a Gaussian kernel of FWHM 5 degrees and had small scales added. The intensity template has had small scales added straight to the template. The details of the small scale procedure is outlined in the accompanying paper. The spectral index map was derived using a combination of the Haslam 408 MHz data and WMAP 23 GHz 7-year data (Miville-Deschenes, M.-A. et al., 2008, A&A, 490, 1093). The same scaling is used for intensity and polarization. This is the same prescription as used in the Planck Sky Model's v1.7.8 'power law' option (Delabrouille et al. A&A 553, A96, 2013), but with the Haslam map updated to the Remazeilles version. A 'curved power law' model is also supported with a single isotropic curvature index. The amplitude of this curvature is taken from Kogut, A. 2012, ApJ, 753, 110.
+- **s1**: A power law scaling is used for the synchrotron emission, with a spatially varying spectral index. The emission templates are the Haslam 408 MHz, 57' resolution data reprocessed by Remazeilles et al 2015 MNRAS 451, 4311, and the WMAP 9-year 23 GHz Q/U maps (Bennett, C.L., et.al., 2013, ApJS, 208, 20B). The polarization maps have been smoothed with a Gaussian kernel of FWHM 5 degrees and had small scales added. The intensity template has had small scales added straight to the template. The details of the small scale procedure is outlined in the accompanying paper. The spectral index map was derived using a combination of the Haslam 408 MHz data and WMAP 23 GHz 7-year data (Miville-Deschenes, M.-A. et al., 2008, A&A, 490, 1093). The same scaling is used for intensity and polarization. This is the same prescription as used in the Planck Sky Model's v1.7.8 'power law' option (Delabrouille et al. A&A 553, A96, 2013), but with the Haslam map updated to the Remazeilles version. A 'curved power law' model is also supported with a single isotropic curvature index. The amplitude of this curvature is taken from Kogut, A. 2012, ApJ, 753, 110.
 
 - **s2**: synchrotron index steepens off the Galactic plane, from -3.0 in the plane to -3.3 off the plane. Consistent with WMAP.
 

diff --git a/docs/mpi.ipynb b/docs/mpi.ipynb
@@ -15,22 +15,85 @@
     "\n",
     "The requirements to run with MPI are `mpi4py` and, just for distributed smoothing, `libsharp`.\n",
     "\n",
-    "The input maps are read from the first process in order to prevent overloading the filesystem, and then maps are distributed rings by rings across all processes, not overlapping.\n",
+    "The input maps are read from the first process in order to prevent overloading the filesystem, and then maps are distributed across all processes, not overlapping.\n",
     "\n",
-    "The `pysm.MapDistribution` object takes care of handling the metadata about how the data are distributed.\n",
+    "## Distribution of maps across MPI processes\n",
+    "\n",
+    "The `pysm.MapDistribution` object takes care of handling the metadata about how the data are distributed, there are 3 ways to distribute the pixels:\n",
+    "\n",
+    "* the most common, which is required to support smoothing over MPI with `libsharp`, is a distribution by ring, where HEALPix rings (stripes of pixels at the same latitude) are distributed symmetrically, i.e. the process that takes first ring close to the North pole also takes the ring close to the South Pole. This is the default distribution if `pixel_indices` is None and a MPI communicator is provided, given that the `libsharp` package is importable:\n",
+    "\n",
+    "```python\n",
+    "map_dist = pysm.MapDistribution(\n",
+    "pixel_indices=None, nside=nside, mpi_comm=MPI.COMM_WORLD\n",
+    ")\n",
+    "```\n",
+    "\n",
+    "* in case `libsharp` is not available, it is not possible to smooth the maps, but generating models and integrating bandpass works. The configuration of `MapDistribution` is the same as before, when `libsharp` is not importable. In this case the pixels are distributed uniformly across the processes.\n",
+    "\n",
+    "* the final case is a custom distribution, where each MPI process specifies an array of not-overlapping local pixel indices. This is also useful when running serially, if you only want to simulate a small patch of sky:\n",
+    "\n",
+    "```python\n",
+    "map_dist = pysm.MapDistribution(\n",
+    "pixel_indices=local_pixels_indices, nside=nside, mpi_comm=MPI.COMM_WORLD\n",
+    ")\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Creation of the `Sky` object\n",
+    "\n",
+    "Next you pass the `MapDistribution` object to `Sky` to have all the models being distributed,\n",
+    "\n",
+    "```python\n",
+    "sky = pysm.Sky(nside=nside, preset_strings=[\"d1\", \"s1\", \"f1\", \"a1\"], map_dist=map_dist)\n",
+    "```\n",
     "\n",
     "When the emission is requested, each process independently computes the emission just on its own portion of the sky.\n",
     "\n",
+    "```python\n",
+    "\n",
+    "m = sky.get_emission(\n",
+    "    freq=np.arange(50, 55) * u.GHz, weights=np.array([0.1, 0.3, 0.5, 0.3, 0.1])\n",
+    ")[0]\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Distributed smoothing\n",
+    "\n",
     "When smoothing is applied, `libsharp` is used to efficiently perform a distributed spherical harmonics transform.\n",
     "\n",
+    "```python\n",
+    "m_smoothed = pysm.apply_smoothing_and_coord_transform(\n",
+    "    m, fwhm=1 * u.deg, map_dist=map_dist\n",
+    ")\n",
+    "```\n",
+    "\n",
+    "After smoothing, each process holds the smoothed version of their local pixels,\n",
+    "this can then be used for example to generate timelines, or be collected to a single process for writing (not implemented in PySM currently, please open an issue if you need it)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example\n",
+    "\n",
     "Check [`pysm3_mpi.py`](https://github.com/galsci/pysm/blob/master/mpi_examples/pysm3_mpi.py) from the repository as an example.\n",
     "\n",
     "Execute with (remove `#` to actually execute it):"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [

diff --git a/mpi_examples/pysm3_mpi_so_pysm_models.py b/mpi_examples/pysm3_mpi_so_pysm_models.py
@@ -1,7 +1,7 @@
 import numpy as np
 import healpy as hp
-import pysm
-import pysm.units as u
+import pysm3 as pysm
+import pysm3.units as u
 from so_pysm_models import get_so_models
 import so_pysm_models
 

diff --git a/paper/paper.bib b/paper/paper.bib
@@ -3,7 +3,7 @@ @ARTICLE{gorski05
 	{Wandelt}, B.~D. and {Hansen}, F.~K. and {Reinecke}, M. and 
 	{Bartelmann}, M.},
     title = "{HEALPix: A Framework for High-Resolution Discretization and Fast Analysis of Data Distributed on the Sphere}",
-  journal = {\apj},
+  journal = {The Astrophysical Journal},
    eprint = {astro-ph/0409513},
  keywords = {Cosmology: Cosmic Microwave Background, Cosmology: Observations, Methods: Statistical},
      year = 2005,
@@ -24,12 +24,12 @@ @article{healpy09
   number = {35},
   pages = {1298},
   author = {Andrea Zonca and Leo P. Singer and Daniel Lenz and Martin Reinecke and Cyrille Rosset and Eric Hivon and Krzysztof M. Gorski},
-  title = {healpy: equal area pixelization and spherical harmonics transforms for data on the sphere in Python},
+  title = {{healpy: equal area pixelization and spherical harmonics transforms for data on the sphere in Python}},
   journal = {Journal of Open Source Software}
 }
 
 @article{pysm17,
-   title={The Python Sky Model: software for simulating the Galactic microwave sky},
+   title={{The Python Sky Model: software for simulating the Galactic microwave sky}},
    volume={469},
    ISSN={1365-2966},
    url={http://dx.doi.org/10.1093/mnras/stx949},
@@ -51,7 +51,7 @@ @ARTICLE{wmap13
 	{Kogut}, A. and {Limon}, M. and {Meyer}, S.~S. and {Tucker}, G.~S. and 
 	{Wright}, E.~L.},
     title = "{Nine-year Wilkinson Microwave Anisotropy Probe (WMAP) Observations: Final Maps and Results}",
-  journal = {\apjs},
+  journal = {The Astrophysical Journal Supplement Series},
 archivePrefix = "arXiv",
    eprint = {1212.5225},
  keywords = {cosmic background radiation, cosmology: observations, dark matter, early universe, instrumentation: detectors, space vehicles, space vehicles: instruments, telescopes},
@@ -107,7 +107,7 @@ @article{libsharp
    ISSN={1432-0746},
    url={http://dx.doi.org/10.1051/0004-6361/201321494},
    DOI={10.1051/0004-6361/201321494},
-   journal={Astronomy & Astrophysics},
+   journal={Astronomy and Astrophysics},
    publisher={EDP Sciences},
    author={Reinecke, M. and Seljebotn, D. S.},
    year={2013},
@@ -122,7 +122,7 @@ @article{astropy2013
 Doi = {10.1051/0004-6361/201322068},
 Eid = {A33},
 Eprint = {1307.6212},
-Journal = {\aap},
+Journal = {Astronomy and Astrophysics},
 Keywords = {methods: data analysis, methods: miscellaneous, virtual observatory tools},
 Month = oct,
 Pages = {A33},
@@ -177,7 +177,7 @@ @ARTICLE{astropy2018
          {Weaver}, B.~A. and {Whitmore}, J.~B. and {Woillez}, J. and
          {Zabalza}, V. and {Astropy Contributors}},
         title = "{The Astropy Project: Building an Open-science Project and Status of the v2.0 Core Package}",
-      journal = {\aj},
+      journal = {The Astronomical Journal},
      keywords = {methods: data analysis, methods: miscellaneous, methods: statistical, reference systems, Astrophysics - Instrumentation and Methods for Astrophysics},
          year = 2018,
         month = sep,