gh-496: functions for legacy mode

.gitignore

@@ -11,3 +11,4 @@ dist
 coverage*
 *.html
 .ipynb_checkpoints
+.jupyter

docs/conf.py

@@ -30,6 +30,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",
+    "sphinx_toolbox.more_autodoc.autoprotocol",
     "sphinxcontrib.katex",
 ]
 
@@ -66,6 +67,7 @@
 intersphinx_mapping = {
     "numpy": ("https://numpy.org/doc/stable", None),
     "python": ("https://docs.python.org/3", None),
+    "array_api": ("https://data-apis.org/array-api/latest", None),
 }
 
 

docs/examples.rst

@@ -45,3 +45,4 @@ More advanced examples doing multiple things at the same time.
 
    examples/2-advanced/cosmic_shear.ipynb
    examples/2-advanced/stage_4_galaxies.ipynb
+   examples/2-advanced/legacy-mode.ipynb

docs/index.rst

@@ -24,6 +24,7 @@ Table of Contents
    examples
    user/index
    reference/index
+   modules/index
 
 
 ==================

docs/modules/algorithm.rst

@@ -0,0 +1,32 @@
+.. module:: glass.core.algorithm
+
+:mod:`glass.core.algorithm` --- General purpose algorithms
+==========================================================
+
+.. currentmodule:: glass.core.algorithm
+
+This module contains general implementations of algorithms which are used by
+GLASS, but are otherwise unrelated to GLASS functionality.
+
+This module must be imported manually::
+
+    import glass.core.algorithm as algo
+
+
+Non-negative least squares
+--------------------------
+
+.. autofunction:: nnls
+
+
+Nearest correlation matrix
+--------------------------
+
+.. autofunction:: nearcorr
+
+
+Covariance matrix regularisation
+--------------------------------
+
+.. autofunction:: cov_clip
+.. autofunction:: cov_nearest

docs/modules/grf.rst

@@ -0,0 +1,35 @@
+.. module:: glass.grf
+
+:mod:`glass.grf` --- Gaussian random fields
+===========================================
+
+.. currentmodule:: glass.grf
+
+
+Gaussian angular power spectra
+------------------------------
+
+.. autofunction:: compute
+.. autofunction:: solve
+
+
+Transforming correlations
+-------------------------
+
+These functions can convert between Gaussian and transformed angular
+correlation functions, and form the basis of :func:`glass.grf.compute` and
+:func:`glass.grf.solve`.
+
+.. autofunction:: corr
+.. autofunction:: icorr
+.. autofunction:: dcorr
+
+
+Transformations
+---------------
+
+.. autoprotocol:: Transformation
+
+.. autoclass:: Normal
+.. autoclass:: Lognormal
+.. autoclass:: SquaredNormal

docs/modules/index.rst

@@ -0,0 +1,9 @@
+=======
+Modules
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   algorithm
+   grf

docs/reference/fields.rst

@@ -1 +1,130 @@
-.. automodule:: glass.fields
+Random fields
+=============
+
+.. currentmodule:: glass
+
+The following functions provide functionality for simulating random fields on
+the sphere. This is done in the form of HEALPix maps.
+
+
+Angular power spectra
+---------------------
+
+.. _twopoint_order:
+
+All functions that process sets of two-point functions expect them as a
+sequence using the following "Christmas tree" ordering:
+
+.. raw:: html
+   :file: figures/spectra_order.svg
+
+In other words, the sequence begins as such:
+
+* Index 0 describes the auto-correlation of field 0,
+* index 1 describes the auto-correlation of field 1,
+* index 2 describes the cross-correlation of field 1 and field 0,
+* index 3 describes the auto-correlation of field 2,
+* index 4 describes the cross-correlation of field 2 and field 1,
+* index 5 describes the cross-correlation of field 2 and field 0,
+* etc.
+
+In particular, two-point functions for the first :math:`n` fields are contained
+in the first :math:`T_n = n \, (n + 1) / 2` entries of the sequence.
+
+To easily generate or iterate over sequences of two-point functions in standard
+order, see the :func:`glass.enumerate_spectra` and
+:func:`glass.spectra_indices` functions.
+
+
+Preparing inputs
+----------------
+
+.. autofunction:: discretized_cls
+.. autofunction:: compute_gaussian_spectra
+.. autofunction:: solve_gaussian_spectra
+
+
+Expectations
+------------
+
+.. autofunction:: effective_cls
+
+
+Generating fields
+-----------------
+
+.. autofunction:: generate
+
+
+Lognormal fields
+----------------
+
+.. autofunction:: lognormal_fields
+
+GLASS comes with the following functions for setting accurate lognormal shift
+values:
+
+.. autofunction:: lognormal_shift_hilbert2011
+
+
+Regularisation
+--------------
+
+When sets of angular power spectra are used to sample random fields, their
+matrix :math:`C_\ell^{ij}` for fixed :math:`\ell` must form a valid
+positive-definite covariance matrix.  This is not always the case, for example
+due to numerical inaccuracies, or transformations of the underlying fields
+[Xavier16]_.
+
+Regularisation takes sets of spectra which are ill-posed for sampling, and
+returns sets which are well-defined and, in some sense, "close" to the input.
+
+.. autofunction:: regularized_spectra
+
+.. function:: regularized_spectra(..., method="nearest", tol=None, niter=100)
+   :no-index:
+
+   Compute the (possibly defective) correlation matrices of the given spectra,
+   then find the nearest valid correlation matrices, using the alternating
+   projections algorithm of [Higham02]_ with tolerance *tol* for *niter*
+   iterations.  This keeps the diagonals (i.e.  auto-correlations) fixed, but
+   requires all of them to be nonnegative.
+
+   .. seealso::
+
+      :func:`glass.core.algorithm.cov_nearest`
+         Equivalent function for covariance matrices.
+
+      :func:`glass.core.algorithm.nearcorr`
+         Nearest correlation matrix.
+
+.. function:: regularized_spectra(..., method="clip", rtol=None)
+   :no-index:
+
+   Clip negative eigenvalues of the spectra's covariance matrix to zero.  This
+   is a simple fix that guarantees positive semi-definite spectra, but can
+   affect the spectra significantly.
+
+   .. seealso::
+
+      :func:`glass.core.algorithm.cov_clip`
+         Equivalent function for covariance matrices.
+
+
+Indexing
+--------
+
+.. autofunction:: getcl
+.. autofunction:: enumerate_spectra
+.. autofunction:: spectra_indices
+.. autofunction:: glass_to_healpix_spectra
+.. autofunction:: healpix_to_glass_spectra
+.. autofunction:: cov_from_spectra
+
+
+Deprecated
+----------
+
+.. autofunction:: lognormal_gls
+.. autofunction:: generate_gaussian
+.. autofunction:: generate_lognormal

docs/user/bibliography.rst

@@ -0,0 +1,13 @@
+Bibliography
+============
+
+.. [Bro97] Bro, R. and De Jong, S. (1997), A fast non-negativity-constrained
+   least squares algorithm. J.  Chemometrics, 11, 393-401.
+
+.. [Higham02] Higham N. J., 2002, IMA J. Numer. Anal., 22, 329.
+
+.. [Lawson95] Lawson, C. L. and Hanson, R. J. (1995), Solving Least Squares
+   Problems. doi: 10.1137/1.9781611971217
+
+.. [Xavier16] Xavier H. S., et al., 2016, MNRAS, 459, 3693.
+   `doi:10.1093/mnras/stw874 <https://dx.doi.org/10.1093/mnras/stw874>`_

docs/user/index.rst

@@ -7,4 +7,5 @@ User guide
 
    how-glass-works
    publications
+   bibliography
    definitions