Merge pull request #212 from halomod/docs-for-extrapolate-eh

docs: add FAQ about high-k camb transfer

Author: steven-murray

CHANGELOG.rst

@@ -4,6 +4,11 @@ Releases
 dev-version
 ----------------------
 
+**Changes**
+
+* Changed the ``CAMB`` transfer model to use ``extrapolate_with_eh=True`` by default,
+  which improves the accuracy of the HMF at low mass.
+
 **Fixes**
 
 * The Behroozi mass function model has been corrected to modify the Tinker08 mass
@@ -18,7 +23,6 @@ v3.4.3 [12 Sep 2022]
 ----------------------
 
 **Changes**
------------
 
 - No longer supporting <py38
 - Fixes to setup.cfg (#150)

docs/faq.rst

@@ -44,3 +44,27 @@ can specify more accurately what kind of model you want::
 
 Here the kind is the *name* of the class defining this component (see above section
 for how to determine what kinds are available).
+
+My mass function looks wrong at small masses, why?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+One common reason for this is that the mass function is being calculated at masses
+that correspond to scales at higher *k* than the transfer function was calculated at.
+You can set your *kmax* to be higher to fix this.
+
+However, note that setting a higher *kmax* for the CAMB transfer function will not
+automatically fix this, since the underlying CAMB code only calculates the transfer
+function up to an internally-specific *kmax*, and this is extrapolated by HMF.
+This can be easily fixed by setting the CAMB-specific parameter
+``transfer_params = {"kmax": some_high_number}``. However, note that this will slow down
+the calculation of the transfer function quite significantly.
+
+A cheaper way to fix the problem is to leave the default *kmax* for CAMB, and instead
+use ``extrapolate_with_eh=True``, which will use Eisenstein & Hu's fitting formula to
+extrapolate the transfer function to higher *k* values. This is not as accurate as
+calculating the transfer function with CAMB out to  higher *k* values, but is much faster.
+
+.. note:: From v3.5.0, the default behaviour is to extrapolate with Eisenstein & Hu
+          fitting formula. This is because the default *kmax* for CAMB is too low for
+          the default *kmax* for the mass function, and this was causing problems for
+          users. If you want to use the old behaviour, you can set
+          ``extrapolate_with_eh=False``.

setup.cfg

@@ -70,10 +70,11 @@ tests =
     pre-commit
     mpmath>=1.0.0
     colossus>=1.2.1
-    halomod
+    halomod>=1.4.6
     numba
 dev =
     hmf[docs,tests]
+    setuptools_scm
 cosmo =
     colossus>=1.2.1
 fit =

src/hmf/density_field/transfer_models.py

@@ -164,7 +164,7 @@ class CAMB(FromFile):
         _defaults = {
             "camb_params": None,
             "dark_energy_params": {},
-            "extrapolate_with_eh": False,
+            "extrapolate_with_eh": None,
             "kmax": None,
         }
 
@@ -229,6 +229,14 @@ def __init__(self, *args, **kwargs):
                     w=self.cosmo.w0, wa=self.cosmo.wa
                 )
 
+            if self.params["extrapolate_with_eh"] is None:
+                warnings.warn(
+                    "'extrapolate_with_eh' was not set. Defaulting to True, which is "
+                    "different behaviour than versions <=3.4.4. This warning may be "
+                    "removed in v4.0. Silence it by setting extrapolate_with_eh explicitly."
+                )
+                self.params["extrapolate_with_eh"] = True
+
             if self.params["extrapolate_with_eh"]:
                 # Create an EH transfer to extrapolate to at high k.
                 self._eh = EH(self.cosmo)