Review all doc pages before tagging v3 (#1116)

* Updated docs * Updated CHANGELOG.md * Update README.md --------- Co-authored-by: Hsin Fan <57552401+hsinfan1996@users.noreply.github.com> Co-authored-by: Tilman Troester <tilman.troester@gmail.com>
LSSTDESC · Aug 8, 2023 · 29d4697 · 29d4697
1 parent bbbaffd
commit 29d4697
Show file tree

Hide file tree

Showing 46 changed files with 647 additions and 586 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,19 @@
 # Unreleased
 
+# v3.0.0 Changes
+
+## Python library
+- Improvements to Einasto, NFW and Hernquist profiles (#1093, #1096).
+- LPT non-linear bias (#1097).
+- Power spectrum emulators (#1094, #1102, #1103, #1108).
+- Bug fix in virial overdensity (#1100) and streamlined collapse threshold (#1101).
+- sigma_8 usable as a parameter for camb when computing non-linear power spectra (#1106).
+- Reverted to better value of Neff (#1111).
+- New baryonic effects models (#1102, #1110).
+- Restored convenience baryonic effects in Cosmology initialisation (#1113).
+- Bocquet et al. 2020 mass function emulatr (#1115)
+- Modified gravity parameter structures (#1119).
+
 # v2.8.0 Changes
 
 ## Python library

diff --git a/README.md b/README.md
@@ -16,19 +16,20 @@ STYLE CONVENTION USED
 [![Documentation](https://readthedocs.org/projects/ccl/badge/?version=latest)](https://ccl.readthedocs.io/en/latest/)&nbsp;
 [![DOI](https://img.shields.io/badge/DOI-10.3847%2F1538--4365%2Fab1658-B31B1B.svg)](https://iopscience.iop.org/article/10.3847/1538-4365/ab1658)
 
-The Core Cosmology Library (CCL) is a standardized library of routines to calculate
-basic observables used in cosmology. It will be the standard analysis package used by the
-LSST Dark Energy Science Collaboration (DESC).
+The Core Cosmology Library (CCL) is a public standardized library of routines to calculate
+basic observables used in cosmology. It will be the standard theoretical prediction package
+used by the LSST Dark Energy Science Collaboration (DESC), although we hope it will have
+broader applicability.
 
 The core functions of this package include:
 
-  - Matter power spectra `P(k)` from numerous models including CLASS, the Mira-Titan Emulator and halofit
-  - Hubble constant `H(z)` as well as comoving distances `\chi(z)` and distance moduli `\mu(z)`
-  - Growth of structure `D(z)` and `f`
-  - Correlation functions `C_\ell` for arbitrary combinations of tracers including galaxies, shear and number counts
-  - Halo mass function `{\rm d}n/{\rm d}M` and halo bias `b(M)`
-  - Approximate baryonic modifications to the matter power spectra `\Delta^2_{\rm baryons}`
-  - Simple modified gravity extensions `\Delta f(z)` and `\mu-\Sigma`
+  - Background quantities (Hubble parameter $H(z)$, distances etc.).
+  - Linear growth factor $D(z)$ and growth rate $f(z)$.
+  - Linear matter power spectra $P(k)$ from Boltzmann codes (CLASS, CAMB), emulators, and approximate fitting functions.
+  - Non-linear matter power power spectra using a variety of prescriptions, including emulators, and including the impact of baryonic effects.
+  - Angular power spectra $C_\ell$ and correlation functions $\xi(\theta)$ for arbitrary combinations of tracers including number counts, shear, CMB lensing, ISW, thermal SZ, CIB, as well as custom-made tracers.
+  - A comprehensive halo model framework able to combine different prescriptions for the halo mass function $dn/dM$, halo bias $b(M)$, concentration-mass relation $c(M)$, mass definitions, and halo profiles, as well as to provide predictions for summary statistics (power spectra, non-Gaussian covariances) of arbitrary quantities.
+  - Support for $\Lambda$ CDM, and $w_0-w_a$CDM cosmologies with curvature and massive neutrinos, as well as simple modified gravity extensions (e.g. $\mu-\Sigma$ ).
 
 This software is a publicly released LSST DESC product which was developed within the LSST
 DESC using LSST DESC resources. DESC users should use it in accordance with the

diff --git a/include/ccl_core.h b/include/ccl_core.h
@@ -39,11 +39,6 @@ typedef struct ccl_physical_constants {
    */
   double MPC_TO_METER;
 
-  /**
-   * pc to meters (from PDG 2013)
-   */
-  double PC_TO_METER;
-
   /**
    * Rho critical in units of M_sun/h / (Mpc/h)^3
    */
@@ -182,14 +177,6 @@ typedef struct ccl_gsl_params {
   // growth
   double EPS_SCALEFAC_GROWTH;
 
-  // halo model
-  double HM_MMIN;
-  double HM_MMAX;
-  double HM_EPSABS;
-  double HM_EPSREL;
-  size_t HM_LIMIT;
-  int HM_INT_METHOD;
-
   // Flags for using spline integration
   bool NZ_NORM_SPLINE_INTEGRATION;
   bool LENSING_KERNEL_SPLINE_INTEGRATION;

diff --git a/pyccl/background.py b/pyccl/background.py
@@ -173,11 +173,17 @@ def luminosity_distance(cosmo, a):
 
 
 def distance_modulus(cosmo, a):
-    """Distance Modulus, defined as 5 * log10(luminosity distance / 10 pc).
+    """Distance Modulus, defined as
+
+    .. math::
+        \\mu = 5\\,\\log_{10}(d_L/10\\,{\\rm pc})
+
+    where :math:`d_L` is the luminosity distance.
 
     .. note :: The distance modulus can be used to convert between apparent
-               and absolute magnitudes via m = M + distance modulus, where m
-               is the apparent magnitude and M is the absolute magnitude.
+               and absolute magnitudes via :math:`m = M + \\mu`, where
+               :math:`m` is the apparent magnitude and :math:`M` is the
+               absolute magnitude.
 
     Args:
         cosmo (:class:`~pyccl.cosmology.Cosmology`): Cosmological parameters.
@@ -325,7 +331,7 @@ def growth_factor_unnorm(cosmo, a):
 
 def growth_rate(cosmo, a):
     """Growth rate defined as the logarithmic derivative of the
-    growth factor, dlnD/dlna.
+    growth factor, :math:`f\\equiv d\\log D/d\\log a`.
 
     .. warning:: CCL is not able to compute the scale-dependent growth
                  rate for cosmologies with massive neutrinos.

diff --git a/pyccl/baryons/baccoemu_baryons.py b/pyccl/baryons/baccoemu_baryons.py
@@ -10,12 +10,12 @@
 class BaccoemuBaryons(Baryons):
     """ The baryonic boost factor computed with the baccoemu baryons emulators.
 
-    See https://arxiv.org/abs/2011.15018 and
-    https://bacco.dipc.org/emulator.html
+    See `Arico et al. 2021 <https://arxiv.org/abs/2011.15018>`_ and
+    https://bacco.dipc.org/emulator.html.
 
-    Note that masses are in units of :math:`M_\\odot`, differently from the
-    original paper and baccoemu public code (where they are
-    in :math:`M_\\odot/h`)
+    .. note:: Note that masses are in units of :math:`M_\\odot`, differently
+              from the original paper and baccoemu public code (where they are
+              in :math:`M_\\odot/h`)
 
     Args:
         log10_M_c (:obj:`float`): characteristic halo mass to model baryon
@@ -86,8 +86,8 @@ def boost_factor(self, cosmo, k, a):
             a (:obj:`float` or `array`): Scale factor.
 
         Returns:
-            :obj:`float` or `array`: Correction factor to apply to
-                the power spectrum.
+            :obj:`float` or `array`: Correction factor to apply to \
+            the power spectrum.
         """ # noqa
 
         # Check a ranges
@@ -156,8 +156,23 @@ def update_parameters(self, log10_M_c=None, log10_eta=None,
                           log10_beta=None, log10_M1_z0_cen=None,
                           log10_theta_out=None, log10_theta_inn=None,
                           log10_M_inn=None):
-        """Update BCM parameters. All parameters set to ``None`` will
+        """Update parameters. All parameters set to ``None`` will
         be left untouched.
+
+        Args:
+            log10_M_c (:obj:`float`): characteristic halo mass to model baryon
+                mass fraction (in :math:`M_\\odot`)
+            log10_eta (:obj:`float`): extent of ejected gas
+            log10_beta (:obj:`float`): slope of power law describing baryon
+                mass fraction
+            log10_M1_z0_cen (:obj:`float`): characteristic halo mass scale for
+                central galaxies (in :math:`M_\\odot`)
+            log10_theta_out (:obj:`float`):  outer slope of density profiles of
+                hot gas in haloes
+            log10_theta_inn (:obj:`float`): inner slope of density profiles of
+                hot gas in haloes
+            log10_M_inn (:obj:`float`): transition mass of density profiles of
+                hot gas in haloes (in :math:`M_\\odot`)
         """
         _kwargs = locals()
         _new_bcm_params = {key: _kwargs[key] for key in

diff --git a/pyccl/baryons/schneider15.py b/pyccl/baryons/schneider15.py
@@ -7,26 +7,21 @@
 
 
 class BaryonsSchneider15(Baryons):
-    """The "BCM" model boost factor for baryons.
+    """The "BCM" model boost factor for baryons. BCM stands for the
+    "baryonic correction model" of `Schneider & Teyssier 2015
+    <https://arxiv.org/abs/1510.06034>`_. See the
 
-    .. note:: BCM stands for the "baryonic correction model" of `Schneider &
-              Teyssier 2015 <https://arxiv.org/abs/1510.06034>`_. See the
-              `DESC Note <https://github.com/LSSTDESC/CCL/blob/master/doc\
-/0000-ccl_note/main.pdf>`_
-              for details.
-
-              The boost factor is applied multiplicatively so that
-              :math:`P_{\\rm bar.}(k, a) = P_{\\rm DMO}(k, a)\\,
-              f_{\\rm BCM}(k, a)`.
+    The boost factor is applied multiplicatively so that
+    :math:`P_{\\rm bar.}(k, a) = P_{\\rm DMO}(k, a)\\, f_{\\rm BCM}(k, a)`.
 
     Args:
         log10Mc (:obj:`float`): logarithmic mass scale of hot
             gas suppression. Defaults to
             :math:`\\log_{10}(1.2\\,10^{14}\\,M_\\odot)`.
-        eta_b (:obj:`float`): ratio of escape to ejection radii (see
-            Teyssier et al. 2015). Defaults to 0.5.
+        eta_b (:obj:`float`): ratio of escape to ejection radii.
+            Defaults to 0.5.
         k_s (:obj:`float`): Characteristic scale (wavenumber) of
-            the stellar component in units of :math:`{\\rm Mpc}\\,h^{-1}`.
+            the stellar component in units of :math:`h\\,{\\rm Mpc}^{-1}`.
             Defaults to 55.
     """
     name = 'Schneider15'
@@ -46,8 +41,8 @@ def boost_factor(self, cosmo, k, a):
             a (:obj:`float` or `array`): Scale factor.
 
         Returns:
-            :obj:`float` or `array`: Correction factor to apply to
-                the power spectrum.
+            :obj:`float` or `array`: Correction factor to apply to \
+            the power spectrum.
         """ # noqa
         a_use, k_use = map(np.atleast_1d, [a, k])
         a_use, k_use = a_use[:, None], k_use[None, :]

diff --git a/pyccl/baryons/vandaalen19.py b/pyccl/baryons/vandaalen19.py
@@ -7,29 +7,22 @@
 
 
 class BaryonsvanDaalen19(Baryons):
-    """The "van Daalen+ 2019" model boost factor for baryons.
+    """The baryonic boost factor model of
+    `van Daalen et al. 2019, <https://arxiv.org/abs/1906.00968>`_.
 
-    .. note:: First presented in
-              `van Daalen et al., <https://arxiv.org/abs/1906.00968>`_. See the
-              `DESC Note <https://github.com/LSSTDESC/CCL/blob/master/doc\
-/0000-ccl_note/main.pdf>`_
-              for details.
+    The boost factor is applied multiplicatively so that
+    :math:`P_{\\rm bar.}(k, a) = P_{\\rm DMO}(k, a)\\, f_{\\rm vD19}(k, a)`.
 
-              The boost factor is applied multiplicatively so that
-              :math:`P_{\\rm bar.}(k, a) = P_{\\rm DMO}(k, a)\\,
-              f_{\\rm BCM}(k, a)`.
-
-              Notice the model has only been tested at z=0 and is valid for
+    .. note:: The model has only been tested at z=0 and is valid for
               :math:`k\\leq 1 \\,h/{\\rm Mpc}`.
 
     Args:
-        fbar (:obj:`float`): the fraction of baryons in a halo within
-            an overdensity of X times the critical density, given in units
+        fbar (:obj:`float`): the fraction of baryons in a halo in units
             of the ratio of :math:`\\Omega_b` to :math:`\\Omega_m`.
-            Default to 0.7 which is approximately compatible with observations.
-            See Figure 16 of the paper.
-        mass_def (:obj:`string`): whether the mass definition corresponds to
-            X=500 or 200 critical. Options are "500c" or "200c".
+            Default to 0.7 which is approximately compatible with observations
+            (see Fig. 16 of the paper).
+        mass_def (:obj:`string`): spherical overdensity mass definition.
+            Options are "500c" or "200c".
 
     """
     name = 'vanDaalen19'
@@ -43,16 +36,16 @@ def __init__(self, fbar=0.7, mass_def='500c'):
                              "for van Daalen 2019 model.")
 
     def boost_factor(self, cosmo, k, a):
-        """The vd19 model boost factor for baryons.
+        """The vD19 model boost factor for baryons.
 
         Args:
             cosmo (:class:`~pyccl.cosmology.Cosmology`): Cosmological parameters.
             k (:obj:`float` or `array`): Wavenumber (in :math:`{\\rm Mpc}^{-1}`).
             a (:obj:`float` or `array`): Scale factor.
 
         Returns:
-            :obj:`float` or `array`: Correction factor to apply to
-                the power spectrum.
+            :obj:`float` or `array`: Correction factor to apply \
+            to the power spectrum.
 
         """ # noqa
         a_use, k_use = map(np.atleast_1d, [a, k])
@@ -90,11 +83,9 @@ def update_parameters(self, fbar=None, mass_def=None):
         ``None`` will be left untouched.
 
         Args:
-            fbar (:obj:`float`): baryonic fraction in halos
-                within X times the critical density.
-
-            mass_def (:obj:`string`): mass definition: whether 500 ("500c")
-                or 200 critical ("200c").
+            fbar (:obj:`float`): baryonic fraction in halos.
+            mass_def (:obj:`string`): mass definition ("500c" or
+                "200c")
         """
         if fbar is not None:
             self.fbar = fbar

diff --git a/pyccl/correlations.py b/pyccl/correlations.py
@@ -221,9 +221,15 @@ def correlation_multipole(cosmo, *, r, a, beta, ell,
 
 def correlation_3dRsd(cosmo, *, r, a, mu, beta,
                       p_of_k_a=DEFAULT_POWER_SPECTRUM, use_spline=True):
-    """
+    r"""
     Compute the 3D correlation function with linear RSDs using
-    multipoles.
+    multipoles:
+
+    .. math::
+        \xi(r,\mu) = \sum_{\ell\in\{0,2,4\}}\xi_\ell(r)\,P_\ell(\mu)
+
+    where :math:`P_\ell(\mu)` are the Legendre polynomials, and
+    :math:`\xi_\ell(r)` are the correlation function multipoles.
 
     Args:
         cosmo (:class:`~pyccl.cosmology.Cosmology`): A Cosmology object.
@@ -269,7 +275,8 @@ def correlation_3dRsd_avgmu(cosmo, *, r, a, beta,
                             p_of_k_a=DEFAULT_POWER_SPECTRUM):
     """
     Compute the 3D correlation function averaged over angles with
-    RSDs.
+    RSDs. Equivalent to calling :func:`correlation_multipole`
+    with ``ell=0``.
 
     Args:
         cosmo (:class:`~pyccl.cosmology.Cosmology`): A Cosmology object.
@@ -309,13 +316,17 @@ def correlation_3dRsd_avgmu(cosmo, *, r, a, beta,
 
 def correlation_pi_sigma(cosmo, *, pi, sigma, a, beta,
                          use_spline=True, p_of_k_a=DEFAULT_POWER_SPECTRUM):
-    """
-    Compute the 3D correlation in :math:`(\\pi,\\sigma)` space.
+    r"""
+    Compute the 3D correlation in :math:`(\pi,\sigma)` space. This is
+    just
+
+    .. math::
+        \xi(\pi,\sigma) = \xi(r=\sqrt{\pi^2+\sigma^2},\mu=\pi/r).
 
     Args:
         cosmo (:class:`~pyccl.cosmology.Cosmology`): A Cosmology object.
         pi (:obj:`float`): distance times cosine of the angle (in Mpc).
-        sigma (float or array-like): distance(s) times sine of the angle
+        sigma (:obj:`float` or `array`): distance(s) times sine of the angle
             (in Mpc).
         a (:obj:`float`): scale factor.
         beta (:obj:`float`): growth rate divided by galaxy bias.