Docs (#205)

* Included AVX512 for custom weights (#203) * Fixed two long-standing issues with the docs. * Added a summary of changes [ci skip] * Needed to add the actual API docs files * Fixed the citation entries. Needs decision [ci skip] * Updated the citation info * Clarified the terminology * Fixing a doc warning * Better shell practices for temp files and filenames * Changing the bib item for the MNRAS paper to ADS [ci skip]
manodeep · Dec 23, 2019 · 9b60cea · 9b60cea
1 parent ae2e4ba
commit 9b60cea
Show file tree

Hide file tree

Showing 8 changed files with 179 additions and 200 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -20,6 +20,8 @@ now also tests for ``python3.7``.
 Enhancements
 ------------
 - Improved code quality and adherence to PEP8 [#189]
+- Documentation no longer shows duplicate entries [#205]
+
 
 
 Bug fixes
@@ -28,7 +30,7 @@ Bug fixes
 - Large Rmax to Lbox ratio now supported for periodic boundaries [#192]
 - Workaround for GNU Assembler bug causing incorrect calculations [#196]
 - Only report runtime isa support if we also have compiler support [#200]
-
+- Example code to illustrate how to code custom weights with AVX512F [#205]
 
 2.3.1 (2019-06-21)
 ================

diff --git a/README.rst b/README.rst
@@ -7,9 +7,10 @@
 Description
 ===========
 
-This repo contains a set of codes to calculate correlation functions and
-other clustering statistics in a cosmological box (co-moving XYZ)
-or on a mock (RA, DEC, CZ). Read the documentation on `corrfunc.rtfd.io <http://corrfunc.rtfd.io/>`_.
+This repo contains a suite of codes to calculate correlation functions and
+other clustering statistics for **simulated** galaxies in a cosmological box (co-moving XYZ)
+and on **observed** galaxies with on-sky positions (RA, DEC, CZ). Read the
+documentation on `corrfunc.rtfd.io <http://corrfunc.rtfd.io/>`_.
 
 Why Should You Use it
 ======================
@@ -109,8 +110,22 @@ pre-requisites, please see the `FAQ <FAQ>`__ or `email
 the Corrfunc mailing list <mailto:corrfunc@googlegroups.com>`__. Also, feel free to create a new issue
 with the ``Installation`` label.
 
-Clustering Measures on a Cosmological box
------------------------------------------
+Clustering Measures on simulated galaxies
+------------------------------------------
+
+Input data
++++++++++++
+
+The input galaxies (or any discrete distribution of points) are derived from a
+simulation. For instance, the galaxies could be a result of an Halo Occupation
+Distribution (HOD) model, a Subhalo Abundance matching (SHAM) model, a
+Semi-Empirical model (SEM), or a Semi-Analytic model (SAM) etc. The input set of
+points can also be the dark matter halos, or the dark matter particles from
+a cosmological simulation. The input set of points are expected to have
+positions specified in Cartesian XYZ.
+
+Types of available clustering statistics
++++++++++++++++++++++++++++++++++++++++++
 
 All codes that work on cosmological boxes with co-moving positions are
 located in the ``theory`` directory. The various clustering measures
@@ -133,8 +148,27 @@ are:
 
 6. ``vpf`` -- Measures the void probability function + counts-in-cells.
 
-Clustering measures on a Mock
------------------------------
+Clustering measures on observed galaxies
+----------------------------------------
+
+Input data
++++++++++++
+
+The input galaxies are typically observed galaxies coming from a large-scale
+galaxy survey. In addition, simulated galaxies that have been projected onto the sky
+(i.e., where observational systematics have been incorporated and on-sky
+positions have been generated) can also be used. We generically refer to both
+these kinds of galaxies as "mocks".
+
+
+The input galaxies are expected to have positions specified in spherical
+co-ordinates with at least right ascension (RA) and declination (DEC).
+For spatial correlation functions, an approximate "co-moving" distance
+(speed of light multiplied by redshift, CZ) is also required.
+
+
+Types of available clustering statistics
++++++++++++++++++++++++++++++++++++++++++
 
 All codes that work on mock catalogs (RA, DEC, CZ) are located in the
 ``mocks`` directory. The various clustering measures are:
@@ -344,24 +378,34 @@ Corrfunc was designed by Manodeep Sinha and is currently maintained by
 Citing
 ======
 
-If you use the code, please cite using the `ascl entry <http://ascl.net/1703.003>`_ as indexed by `ADS <http://adsabs.harvard.edu/abs/2017ascl.soft03003S>`_. The BibTex entry for the code is
+If you use ``Corrfunc`` for research, please cite using the MNRAS code paper with the following
+bibtex entry:
 
 ::
 
-      @misc{2017ascl.soft03003S,
-         author = {{Sinha}, M. and {Garrison}, L.},
-         title = "{Corrfunc: Blazing fast correlation functions on the CPU}",
-         keywords = {Software},
-         howpublished = {Astrophysics Source Code Library},
-         year = 2017,
-         month = mar,
-         archivePrefix = "ascl",
-         eprint = {1703.003},
-         adsurl = {http://adsabs.harvard.edu/abs/2017ascl.soft03003S},
-         adsnote = {Provided by the SAO/NASA Astrophysics Data System}
-      }
-
-If you are using ``Corrfunc v2.3.0`` or later, please additionally cite this paper:
+   @ARTICLE{2020MNRAS.491.3022S,
+       author = {{Sinha}, Manodeep and {Garrison}, Lehman H.},
+       title = "{CORRFUNC - a suite of blazing fast correlation functions on
+       the CPU}",
+       journal = {\mnras},
+       keywords = {methods: numerical, galaxies: general, galaxies:
+       haloes, dark matter, large-scale structure of Universe, cosmology:
+       theory},
+       year = "2020",
+       month = "Jan",
+       volume = {491},
+       number = {2},
+       pages = {3022-3041},
+       doi = {10.1093/mnras/stz3157},
+       adsurl =
+       {https://ui.adsabs.harvard.edu/abs/2020MNRAS.491.3022S},
+       adsnote = {Provided by the SAO/NASA
+       Astrophysics Data System}
+   }
+
+
+If you are using ``Corrfunc v2.3.0`` or later, **and** you benefit from the
+enhanced vectorised kernels, then please additionally cite this paper:
 
 ::
 
@@ -433,4 +477,4 @@ Project URL
 
 .. |Paper II| image:: https://img.shields.io/badge/arXiv-1911.08275-%23B31B1B
    :target: https://arxiv.org/abs/1911.08275
-   :alt: Corrfunc Paper II 
+   :alt: Corrfunc Paper II
diff --git a/docs/source/api/Corrfunc.mocks.rst b/docs/source/api/Corrfunc.mocks.rst
@@ -1,44 +1,8 @@
-Corrfunc\.mocks package
-=======================
+Corrfunc.mocks package
+======================
 
 .. automodule:: Corrfunc.mocks
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Submodules
-----------
-
-Corrfunc\.mocks\.DDrppi\_mocks module
--------------------------------------
-
-.. automodule:: Corrfunc.mocks.DDrppi_mocks
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.mocks\.DDsmu\_mocks module
-------------------------------------
-
-.. automodule:: Corrfunc.mocks.DDsmu_mocks
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.mocks\.DDtheta\_mocks module
---------------------------------------
-
-.. automodule:: Corrfunc.mocks.DDtheta_mocks
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.mocks\.vpf\_mocks module
-----------------------------------
-
-.. automodule:: Corrfunc.mocks.vpf_mocks
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
diff --git a/docs/source/api/Corrfunc.rst b/docs/source/api/Corrfunc.rst
@@ -2,59 +2,31 @@ Corrfunc package
 ================
 
 .. automodule:: Corrfunc
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 Subpackages
 -----------
 
 .. toctree::
 
-    Corrfunc.mocks
-    Corrfunc.theory
+   Corrfunc.mocks
+   Corrfunc.theory
 
-Submodules
-----------
-
-Corrfunc\.call\_correlation\_functions module
----------------------------------------------
-
-.. automodule:: Corrfunc.call_correlation_functions
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.call\_correlation\_functions\_mocks module
-----------------------------------------------------
-
-.. automodule:: Corrfunc.call_correlation_functions_mocks
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.io module
--------------------
+Corrfunc.io module
+------------------
 
 .. automodule:: Corrfunc.io
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.tests module
-----------------------
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
-.. automodule:: Corrfunc.tests
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.utils module
-----------------------
+Corrfunc.utils module
+---------------------
 
 .. automodule:: Corrfunc.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
diff --git a/docs/source/api/Corrfunc.theory.rst b/docs/source/api/Corrfunc.theory.rst
@@ -1,60 +1,8 @@
-Corrfunc\.theory package
-========================
+Corrfunc.theory package
+=======================
 
 .. automodule:: Corrfunc.theory
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Submodules
-----------
-
-Corrfunc\.theory\.DD module
----------------------------
-
-.. automodule:: Corrfunc.theory.DD
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.theory\.DDrppi module
--------------------------------
-
-.. automodule:: Corrfunc.theory.DDrppi
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.theory\.DDsmu module
-------------------------------
-
-.. automodule:: Corrfunc.theory.DDsmu
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.theory\.vpf module
-----------------------------
-
-.. automodule:: Corrfunc.theory.vpf
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.theory\.wp module
----------------------------
-
-.. automodule:: Corrfunc.theory.wp
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-Corrfunc\.theory\.xi module
----------------------------
-
-.. automodule:: Corrfunc.theory.xi
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
diff --git a/docs/source/apidoc.sh b/docs/source/apidoc.sh
@@ -1,6 +1,27 @@
-# bash
+#! /bin/bash
 
 if ! python -c 'import numpydoc'; then easy_install --user numpydoc; fi
 if ! python -c 'import sphinx'; then easy_install --user sphinx; fi
 
-sphinx-apidoc -H "Comprehensive API reference" -M -f -o source/api/ ../Corrfunc/
+outdir=source/api
+sphinx-apidoc -H "Comprehensive API reference" -M -f -o "$outdir" ../Corrfunc/ ../Corrfunc/tests.py ../Corrfunc/call_correlation_functions.py ../Corrfunc/call_correlation_functions_mocks.py
+
+tmpfile="$(mktemp)"
+# Fix the blank sub-modules in the Corrfunc file
+for docfile in "$outdir/Corrfunc.rst"
+do
+    # Delete three lines following the "submodules"
+    sed -e '/Submodules/{N;N;d;}' "$docfile" > "$tmpfile"
+    mv "$tmpfile"  "$docfile"
+done
+
+
+# Fix the duplicate entries for the various pair-counters
+# (e.g., Corrfunc.theory.DD *and* Corrfunc.theory.DD.DD)
+for docfile in "$outdir/Corrfunc.mocks.rst" "$outdir/Corrfunc.theory.rst"
+do
+    # Delete ALL lines following this "submodule" line in the theory/mocks
+    # auto-generated documentation
+    sed  -n '/Submodules/q;p' "$docfile" > "$tmpfile"
+    mv "$tmpfile"  "$docfile"
+done