Documentation fixes (#192)

* better docs, fixed in RTD
LSSTDESC · Jun 6, 2024 · 08d981f · 08d981f
1 parent 5bb75c6
commit 08d981f
Show file tree

Hide file tree

Showing 18 changed files with 102 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ python -m pip install pymaster [--user]
 If all the above fail, try to install NaMaster from its source. You should first clone this [github repository](https://github.com/LSSTDESC/NaMaster). Then follow these steps:
 
 #### 1. Install dependencies.
-Install the dependencies listed [here](#dependencies). Note that some of them (libsharp and HEALPix) may not be necessary, as pymaster will attempt to install them automatically.
+Install the dependencies listed [here](#dependencies). Note that some of them (HEALPix) may not be necessary, as pymaster will attempt to install them automatically.
 
 #### 2. Install the python module
 Installing the python module `pymaster` should be as simple as running
@@ -86,9 +86,8 @@ NaMaster has the following dependencies, which should be present in your system
 * [FFTW](http://www.fftw.org/). Version 3 required. Install with `--enable-openmp` and potentially also `--enable-shared`.
 * [cfitsio](https://heasarc.gsfc.nasa.gov/fitsio/). Any version >3 should work.
 
-Besides these, NaMaster will attempt to install the following two dependencies. If this fails, or if you'd like to use your own preinstalled versions, follow these instructions:
-* [libsharp](https://github.com/Libsharp/libsharp). Libsharp is automatically installed with NaMaster. `setup.py` attempts to download and install libsharp automatically. This is done by running the script `scripts/install_libsharp.sh`. If you encounter any trouble during this step, inspect the contents of that file. Libsharp gets installed in `_deps/lib` and `_deps/include`. However, if you want to use your own preinstalled version of libsharp, you should simlink it into the directory `_deps`, such that `_deps/lib/libsharp.a` can be seen. See instructions in [NERSC_installation.md](NERSC_installation.md) for more details on libsharp. 
-* [HEALPix](https://sourceforge.net/projects/healpix/). Like libsharp, HEALPix is automatically installed by `setup.py` by running the script `scripts/install_libchealpix.sh` (have a look there if you run into trouble). HEALPix gets installed in `_deps/lib` and `_deps/include`. However, if you want to use your own preinstalled version , you should simlink it into the directory `_deps`, such that `_deps/lib/libchealpix.a` can be seen. Any version >2 should work. Only the C libraries are needed.
+Besides these, NaMaster will attempt to install the following additional dependency. If this fails, or if you'd like to use your own preinstalled versions, follow these instructions:
+* [HEALPix](https://sourceforge.net/projects/healpix/). HEALPix is automatically installed by `setup.py` by running the script `scripts/install_libchealpix.sh` (have a look there if you run into trouble). HEALPix gets installed in `_deps/lib` and `_deps/include`. However, if you want to use your own preinstalled version , you should simlink it into the directory `_deps`, such that `_deps/lib/libchealpix.a` can be seen. Any version >2 should work. Only the C libraries are needed.
 
 
 ## Licensing, credits and feedback

diff --git a/doc/api/pymaster.bins.rst b/doc/api/pymaster.bins.rst
@@ -0,0 +1,7 @@
+pymaster.bins module
+====================
+
+.. automodule:: pymaster.bins
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/pymaster.covariance.rst b/doc/api/pymaster.covariance.rst
@@ -0,0 +1,7 @@
+pymaster.covariance module
+==========================
+
+.. automodule:: pymaster.covariance
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/pymaster.field.rst b/doc/api/pymaster.field.rst
@@ -0,0 +1,7 @@
+pymaster.field module
+=====================
+
+.. automodule:: pymaster.field
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/pymaster.rst b/doc/api/pymaster.rst
@@ -0,0 +1,22 @@
+pymaster package
+================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   pymaster.bins
+   pymaster.covariance
+   pymaster.field
+   pymaster.utils
+   pymaster.workspaces
+
+Module contents
+---------------
+
+.. automodule:: pymaster
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/pymaster.utils.rst b/doc/api/pymaster.utils.rst
@@ -0,0 +1,7 @@
+pymaster.utils module
+=====================
+
+.. automodule:: pymaster.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/pymaster.workspaces.rst b/doc/api/pymaster.workspaces.rst
@@ -0,0 +1,7 @@
+pymaster.workspaces module
+==========================
+
+.. automodule:: pymaster.workspaces
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/apidoc.sh b/doc/apidoc.sh
@@ -1,3 +1,3 @@
 # bash
 
-sphinx-apidoc -T -f -e -o api/ ../pymaster/ ../pymaster/tests/* ../pymaster/tests ../pymaster/nmtlib.py
+sphinx-apidoc -d 1 -T -f -e -o api/ ../pymaster/ ../pymaster/tests/* ../pymaster/tests ../pymaster/nmtlib.py
diff --git a/doc/conf.py b/doc/conf.py
@@ -25,7 +25,8 @@
 if os.path.isdir(root_path):
     sys.path.insert(0, root_path)
 
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+on_rtd = True
+#os.environ.get('READTHEDOCS', None) == 'True'
 if on_rtd:
     try:
         from unittest.mock import MagicMock
@@ -79,7 +80,7 @@ def __getattr__(cls, name):
 
 # General information about the project.
 project = u'pymaster'
-copyright = u'2023 David Alonso'
+copyright = u'2024 David Alonso'
 author = u'David Alonso'
 
 # The version info for the project you're documenting, acts as replacement for

diff --git a/doc/index.rst b/doc/index.rst
@@ -3,14 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to pymaster's documentation!
+Welcome to NaMaster's documentation!
 ====================================
 
-pymaster is the python implementation of the NaMaster library. The main purpose of this library is to provide support to compute the angular power spectrum of fields defined on a limited region of the sphere using the so-called pseudo-CL formalism.
+NaMaster is a python package that provides support to compute tha angular power spectrum of masked fields with arbitrary spin pymaster using the so-called pseudo-Cl formalism. ``pymaster`` is the python implementation of the NaMaster library. Below you can find links to NaMaster's full documentation and various example scripts showcasing its usage. Understanding these scripts will allow you to make the most efficient use of this package.
 
-Below you can find links to pymaster's full documentation and 8 different example scripts showcasing its usage. Understanding the last script in particular will allow you to make the most efficient use of this module.
-
-We recommend that users read NaMaster's :download:`scientific documentation <doc_scientific.pdf>` to have a good understanding of the methods implemented in it.
+We recommend that users read NaMaster's :download:`scientific documentation <doc_scientific.pdf>`, as well as the original paper `Alonso et al. 2019 <https://arxiv.org/abs/1809.09603>`_ to have a good understanding of the methods implemented in the library. Additional useful information, particularly regarding the calculation of covariance matrices, can be found in `Garcia-Garcia et al. 2019 <https://arxiv.org/abs/1906.11765>`_, and `Nicola et al. 2021 <https://arxiv.org/abs/2010.09717>`_. We kindly request that you cite these papers where relevant.
 
 .. toctree::
    :maxdepth: 1

diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -1,6 +1,7 @@
-sphinx==6
+sphinx
 sphinx_mdinclude
 numpy
 scipy
-docutils>=0.18
-sphinx_rtd_theme==1.2.0rc3
+healpy
+docutils
+sphinx_rtd_theme
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
@@ -37,7 +37,7 @@ If all the above fail, try to install NaMaster from its source. You should first
 1. Install dependencies.
 ------------------------
 
-Install the dependencies listed :ref:`here <dependencies>`. Note that some of them (libsharp and HEALPix) may not be necessary, as pymaster will attempt to install them automatically.
+Install the dependencies listed :ref:`here <dependencies>`. Note that some of them (HEALPix) may not be necessary, as pymaster will attempt to install them automatically.
 
 2. Install the python module
 ----------------------------
@@ -108,7 +108,6 @@ NaMaster has the following dependencies, which should be present in your system
 * `FFTW <http://www.fftw.org/>`_. Version 3 required. Install with ``--enable-openmp`` and potentially also ``--enable-shared``.
 * `cfitsio <https://heasarc.gsfc.nasa.gov/fitsio/>`_. Any version >3 should work.
 
-Besides these, NaMaster will attempt to install the following two dependencies. If this fails, or if you'd like to use your own preinstalled versions, follow these instructions:
+Besides these, NaMaster will attempt to install the following additional dependency. If this fails, or if you'd like to use your own preinstalled versions, follow these instructions:
 
-* `libsharp <https://github.com/Libsharp/libsharp>`_. Libsharp is automatically installed with NaMaster. ``setup.py`` attempts to download and install libsharp automatically. This is done by running the script ``scripts/install_libsharp.sh``. If you encounter any trouble during this step, inspect the contents of that file. Libsharp gets installed in ``_deps/lib`` and ``_deps/include``. However, if you want to use your own preinstalled version of libsharp, you should simlink it into the directory ``_deps``, such that ``_deps/lib/libsharp.a`` can be seen. See instructions in ``NERSC_installation.md`` for more details on libsharp. 
-* `HEALPix <https://sourceforge.net/projects/healpix/>`_. Like libsharp, HEALPix is automatically installed by ``setup.py`` by running the script ``scripts/install_libchealpix.sh`` (have a look there if you run into trouble). HEALPix gets installed in ``_deps/lib`` and ``_deps/include``. However, if you want to use your own preinstalled version , you should simlink it into the directory ``_deps``, such that ``_deps/lib/libchealpix.a`` can be seen. Any version >2 should work. Only the C libraries are needed.
+* `HEALPix <https://sourceforge.net/projects/healpix/>`_. HEALPix is automatically installed by ``setup.py`` by running the script ``scripts/install_libchealpix.sh`` (have a look there if you run into trouble). HEALPix gets installed in ``_deps/lib`` and ``_deps/include``. However, if you want to use your own preinstalled version , you should simlink it into the directory ``_deps``, such that ``_deps/lib/libchealpix.a`` can be seen. Any version >2 should work. Only the C libraries are needed.
diff --git a/pymaster/__init__.py b/pymaster/__init__.py
@@ -1,5 +1,5 @@
 """
-:mod:`pymaster` contains three basic classes:
+:mod:`pymaster` contains four basic classes:
 
 - :class:`pymaster.field.NmtField`
 - :class:`pymaster.bins.NmtBin`
@@ -34,21 +34,28 @@
 spectra (arrays with one element per angular multipole) \
 or bandpowers (binned versions of power spectra). In \
 all cases, these are returned and provided as 2D arrays \
-with shape [n_cls][nl], where n_cls is the number of \
-power spectra and nl is either the number of multipoles \
-or bandpowers. In all cases, n_cls should correspond \
+with shape ``[n_cls][nl]``, where ``n_cls`` is the number of \
+power spectra and ``nl`` is either the number of multipoles \
+or bandpowers. In all cases, ``n_cls`` should correspond \
 with the spins of the two fields being correlated, and \
 the ordering is as follows:
 
-- Two spin-0 fields: n_cls=1, [C_T1T2]
-- One spin-0 field and one spin>0 field: n_cls=2, [C_TE,C_TB]
-- Two spin>0 fields: n_cls=4, [C_E1E2,C_E1B2,C_E2B1,C_B1B2]
+- Two spin-0 fields: ``n_cls`` = 1, [C_T1T2]
+- One spin-0 field and one spin>0 field: ``n_cls`` = 2, [C_TE,C_TB]
+- Two spin>0 fields: ``n_cls`` = 4, [C_E1E2,C_E1B2,C_E2B1,C_B1B2]
 
-All sky maps accepted and returned by these functions are \
-in the form of HEALPix maps exclusively with RING ordering.
+By defaut, all sky maps accepted and returned by the curved-sky \
+functions are in the form of HEALPix maps exclusively with RING \
+ordering. Note that NaMaster also supports CAR (Plate Carree) \
+pixelization (see Example 9 in documentation).
 """
-from importlib.metadata import version
-__version__ = version(__name__)
+try:
+    from importlib.metadata import version
+    __version__ = version(__name__)
+except:  # noqa
+    # This will happen on RTD, but that's fine
+    __version__ = 'RTD'
+    pass
 
 from pymaster import nmtlib as lib  # noqa
 import numpy as np  # noqa

diff --git a/pymaster/bins.py b/pymaster/bins.py
@@ -17,8 +17,8 @@ class NmtBin(object):
     """:obj:`NmtBin` objects define the set of bandpowers used in the
     computation of the pseudo-:math:`C_\\ell` estimator. The
     definition of bandpowers is described in Section 2.1.3 of the
-    NaMaster paper, and Section 3.6 of the
-    scientific documentation. We provide several convenience
+    `NaMaster paper <https://arxiv.org/abs/1809.09603>`_, and Section
+    3.6 of the scientific documentation. We provide several convenience
     constructors that cover a range of common use cases requiring
     fewer parameters (see :meth:`NmtBin.from_nside_linear`,
     :meth:`NmtBin.from_lmax_linear` and :meth:`NmtBin.from_edges`).
@@ -62,7 +62,7 @@ def __init__(self, *, bpws, ells, lmax=None, weights=None,
     def from_nside_linear(cls, nside, nlb, is_Dell=False, f_ell=None):
         """ Convenience constructor for HEALPix maps with linear
         binning, starting at :math:`\\ell=2`, and up to
-        :math:`\\ell=3 N_{\\rm side}`. Although this will also be the
+        :math:`\\ell=3 N_{\\rm side}-1`. Although this will also be the
         maximum multipole associated with this :obj:`NmtBin` object,
         only bandpowers containing a total of ``nlb`` multipoles within
         this range will be used (i.e. the last bin will be discarded
@@ -87,7 +87,7 @@ def from_nside_linear(cls, nside, nlb, is_Dell=False, f_ell=None):
                 this bandpower scheme. If not ``None``, the value of
                 ``is_Dell`` is ignored. If provided, it must be sampled at
                 all :math:`\\ell` s up to (and including)
-                :math:`3 N_{\\rm side}`.
+                :math:`3 N_{\\rm side}-1`.
         """
         ells, bpws = _get_bpw_arrays_linear(3*nside-1, nlb)
         weights = np.ones(len(ells))
@@ -309,7 +309,8 @@ def unbin_cell(self, cls_in):
 class NmtBinFlat(object):
     """ An :obj:`NmtBinFlat` object defines the set of bandpowers used in
     the computation of the pseudo-:math:`C_\\ell` estimator. The definition
-    of bandpowers is described in Section 2.5.1 of the NaMaster paper, or
+    of bandpowers is described in Section 2.5.1 of the
+    `NaMaster paper <https://arxiv.org/abs/1809.09603>`_, or
     Section 3.6 of the scientific documentation. Note that NaMaster only
     supports top-hat bandpowers for flat-sky power spectra.
 

diff --git a/pymaster/utils.py b/pymaster/utils.py
@@ -57,7 +57,7 @@ class NmtParams(object):
     All variables can be changed using the ``set_`` methods described below,
     and their current values can be checked with :meth:`get_default_params`.
     Note that, except for ``sht_calculator``, all of these variables can
-    be tweaked when calling different various NaMaster functions. The
+    be tweaked when calling various NaMaster functions. The
     values stored in this object only hold the values they default to if
     they are not set in those function calls.
     """

diff --git a/sandbox_validation/timing/Makefile b/sandbox_validation/timing/Makefile
@@ -2,7 +2,7 @@ CC = icc
 OPTIONS = -Wall -openmp -O3
 INC=-I/users/damonge/include -I../../src -I./src
 LIB=-L/users/damonge/lib -L/usr/local/lib64
-LIBALL=-lnmt -lfftw3 -lfftw3_omp -lgsl -lgslcblas -lcfitsio -lsharp -lfftpack -lc_utils -lm
+LIBALL=-lnmt -lfftw3 -lfftw3_omp -lgsl -lgslcblas -lcfitsio -lfftpack -lc_utils -lm
 
 UTILS = src/timing_utils.o
 FIELD = src/timing_field.o

diff --git a/scripts/install_libchealpix.sh b/scripts/install_libchealpix.sh
@@ -30,7 +30,7 @@ make
 if [ $? -eq 0 ]; then
     echo "Successful make."
 else
-    echo "ERROR: couldn't compile libsharp. Make sure CFITSIO is installed."
+    echo "ERROR: couldn't compile HEALPix. Make sure CFITSIO is installed."
     echo "       You may need to add the correct path to CPPFLAGS, LDFLAGS and LD_LIBRARY_PATHS."
     echo "       E.g.:"
     echo "         >$ export CPPFLAGS+=\" -I/path/to/cfitsio/include\""

diff --git a/setup.py b/setup.py
@@ -32,7 +32,7 @@
 
 libs = ['cfitsio', 'gsl', 'gslcblas', 'm'] + FFTW_LIBS
 
-use_icc = False  # Set to True if you compiled libsharp with icc
+use_icc = False
 if use_icc:
     extra = []
     if USE_OPENMP: