Add docs

.github/workflows/linting.yaml

@@ -12,7 +12,7 @@ jobs:
     runs-on: "ubuntu-latest"
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - uses: conda-incubator/setup-miniconda@v4
         with:

.github/workflows/test_main_branch.yaml

@@ -16,7 +16,7 @@ jobs:
     runs-on: "ubuntu-latest"
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
@@ -55,7 +55,7 @@ jobs:
           pytest -v diffhalos --cov --cov-report=xml
 
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@v7
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 

README.rst

@@ -1,19 +1,21 @@
 diffhalos
 ============
 
+Diffhalos is a generative model of cosmological lightcones of dark matter halos, subhalos, and their merger trees. 
+This library is written in JAX, and makes differentiable predictions for halo populations in a lightcone, 
+or at a single redshift.
+
+Documentation
+-------------
+Online documentation is available at `diffhalos.readthedocs.io <https://diffhalos.readthedocs.io/en/latest/>`_
+
 Installation
 ------------
 To install diffhalos into your environment from the source code::
 
     $ cd /path/to/root/diffhalos
     $ pip install .
 
-
-Documentation
--------------
-Online documentation is available at `diffhalos.readthedocs.io <https://diffhalos.readthedocs.io/en/latest/>`_
-
-
 Testing
 -------
 To run the suite of unit tests::
@@ -24,4 +26,18 @@ To run the suite of unit tests::
 To build html of test coverage::
 
     $ pytest -v --cov --cov-report html
-    $ open htmlcov/index.html
+    $ open htmlcov/index.html
+
+Demo notebooks
+--------------
+The :code:`diffhalos_quickstart.ipynb` notebook illustrates how to use some of the core functions of diffhalos. In particular, it demonstrates 
+how to generate halo and subhalo lightcones using the Monte-Carlo and quasi-Monte Carlo versions of the generator. In addition, 
+it shows that the lightcone outputs agree well with the exact theory predictions from the halo and subhalo mass functions in Diffhalos. 
+
+In the notebook :code:`diffhalos_mah.ipynb` we go over the basics of using the DiffmahNet model in Diffhalos to generate mass assembly 
+histories (MAHs) of populations of dark matter halos. It also demonstrates how the MAH of synthetic halos is part of the standard output 
+in the lightcones.
+
+We demonstrate and explain in more detail the fundamentals of using the Monte Carlo and quasi-Monte Carlo generators, and discuss their differences, 
+in the notebook :code:`diffhalos_mc_vs_qmc.ipynb`. In there, we cover the basics of how to use each version for host halos, 
+and we talk about how they differ in their approch to lightcone generation.

diffhalos/lightcone_generators/mc_lightcone.py

@@ -450,12 +450,11 @@ def weighted_lc(
                 Base-10 log of z=0 age of the Universe for the input cosmology
 
             cen_weight: ndarray of shape (n_halos_tot, )
-
                 For centrals, cen_weight is determined by the halo mass function (HMF)
                 For satellites, cen_weight is HMF weight of the associated central
                 For satellites, cen_weight = halopop.cen_weight[halopop.halo_indx]
 
-            central : ndarray of shape (n_halos_tot, )
+            central: ndarray of shape (n_halos_tot, )
                 Integer equals 1 for central halos and 0 for subhalos
 
             sat_weight: ndarray of shape (n_halos_tot, )

diffhalos/lightcone_generators/mc_lightcone_subhalos.py

@@ -212,7 +212,7 @@ def weighted_lc_subhalos(
     subhalo_model_key=DEFAULT_DIFFMAHNET_SAT_MODEL,
 ):
     """
-    Generate a subhalo lightcone
+    Generate a weighted subhalo lightcone
 
     Parameters
     ----------

diffhalos/mah/diffmahnet_utils.py

@@ -23,7 +23,6 @@
 )
 
 from . import diffmahnet
-from .utils import rescale_mah_parameters
 
 DEFAULT_MAH_UPARAMS = get_unbounded_mah_params(DEFAULT_MAH_PARAMS)
 
@@ -58,7 +57,7 @@ def mc_mah_cenpop(
     m_obs: ndarray of shape (n_cens, )
         grid of base-10 log of mass of the halos at observation, in Msun
 
-    t_obs: ndarray of shape (n_subs, )
+    t_obs: ndarray of shape (n_cens, )
         cosmic time at observation of each halo, in Gyr
 
     randkey: key
@@ -210,9 +209,11 @@ def get_mah_from_unbounded_params(
     mah_params_uncorrected = DEFAULT_MAH_PARAMS._make(mah_params_bound)
     _, log_mah = mah_halopop(mah_params_uncorrected, t_grid, logt0)
 
-    mah_params_corrected = rescale_mah_parameters(
-        mah_params_uncorrected, m_vals, log_mah[:, -1]
-    )
+    # rescale mah parameters
+    delta_logm_obs = log_mah[:, -1] - m_vals
+    logm0_rescaled = mah_params_uncorrected.logm0 - delta_logm_obs
+    mah_params_corrected = mah_params_uncorrected._replace(logm0=logm0_rescaled)
+
     _, log_mah = mah_halopop(mah_params_corrected, t_grid, logt0)
 
     return log_mah