Reorganize the User’s manual (#342)

* Use PyData as the default theme for docs and update Sphinx and deps

* Rework the structure of the documentation

* Merge `Bandpasses` chapter into Detector and split `Scanning`

* Remove duplicated material

* Add missing reference

* Remove spurious comma

* Fix the grammar of a few sentences

* Fix grammar and broken links, update references where needed

* example in the noise page included, argument random in Simulation.add_noise is now optional

* removed part of last commit

* [skip ci] Update CHANGELOG

---------

Co-authored-by: Luca Pagano <[email protected]>

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 -   **Breaking change**: Redefinition (ωt instead of 2ωt) of the hwp angle returned by `get_pointings()`. Change in the pointing returned by `Observation.get_pointings()`, now behaving as it was before this [commit](https://github.com/litebird/litebird_sim/pull/319/commits/b3bc3bb2049c152cc183d6cfc68f4598f5b93ec0). Documentation updated accordingly. [#340](https://github.com/litebird/litebird_sim/pull/340)
 
+-   Restructure the manual and use a new, cleaner style [#342](https://github.com/litebird/litebird_sim/pull/342)
+
 -   Module for including nonlinearity in the simulations [#331](https://github.com/litebird/litebird_sim/pull/331)
 
 -   Improve the documentation of the binner and the destriper [#333](https://github.com/litebird/litebird_sim/pull/333)

docs/source/appendix.rst

@@ -0,0 +1,7 @@
+Appendices
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   bibliography.rst

docs/source/conf.py

@@ -17,7 +17,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "LiteBIRD simulation pipeline"
+project = "LBS"
 copyright = "2020, The LiteBIRD Simulation Team"
 author = "The LiteBIRD Simulation Team"
 
@@ -58,7 +58,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "pydata_sphinx_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/source/detectors.rst

@@ -286,10 +286,80 @@ each stage of the simulation:
     - 000_000_004_QB_040_T
 
 
+Bandpasses
+----------
+
+Any electromagnetic detector is sensitive only to some frequencies of
+the spectrum, and it is vital to know what they are. We refer to these
+as the «bandpass», i.e., the list of frequencies that can «pass
+through the detector» and be detected. A bandpass is a function
+:math:`B(\nu)` that associates the frequency :math:`\nu` with a pure
+number in the range 0…1, representing the fraction of power that is
+actually measured by the instrument. The functional form of
+:math:`B(\nu)` is usually called the *bandshape*, and it is usually
+nonzero in a limited subset of the real space.
+
+A widely used analytical model of the bandshape is the top-hat bandpass:
+
+.. math::
+    :name: eq:tophatbandpass
+
+    B(\nu) = \begin{cases}
+    1\,\text{ if } \nu_0 - \Delta\nu/2 < \nu < \nu_0 + \Delta\nu/2,\\
+    0\,\text{ otherwise.}
+    \end{cases}
+
+Given a bandshape :math:`B(\nu)`, two quantities are usually employed
+to synthetically represent it:
+
+- The *central frequency* :math:`\left<\nu\right>`, which is just the
+  average value of :math:`\nu` when weighted with :math:`B(\nu)`:
+
+  .. math::
+      \left<\nu\right> = \frac{\int_0^\infty \nu B(\nu)\,\mathrm{d}\nu}{\int_0^\infty B(\nu)\,\mathrm{d}\nu}
+
+  which is of course the formula of the weighted average. For the
+  top-hat band, the central frequency is :math:`\nu_0`.
+
+- The *bandwidth* :math:`\Delta\nu`, which is the *width* of the band,
+  i.e., a measurement of how wide is the subrange of the
+  electromagnetic spectrum sampled by the detector:
+
+  .. math::
+
+      \Delta\nu^2 = \frac{\left(\int_0^\infty B(\nu)\,\mathrm{d}\nu\right)^2}{\int_0^\infty B^2(\nu)\,\mathrm{d}\nu},
+
+  which is again inspired by the formula of the standard square
+  deviation. For the top-hat bandshape, the value of :math:`\Delta\nu`
+  in :math:numref:`eq:tophatbandpass` is exactly the bandwidth.
+
+
+Modeling bandshapes
+~~~~~~~~~~~~~~~~~~~
+
+In the LiteBIRD Simulation Framework, bandpasses are encoded in the
+class :class:`.BandPassInfo`, which can be used either to load
+bandpasses from the IMO or to generate them on scratch. In the latter
+case, you must specify the central frequency and the bandwidth,
+alongside with other parameter that introduce a random component meant
+to make the band more realistic. Here is a simple example, which shows
+how to create a bandpass and then how to add «noise» to make it more
+realistic:
+
+.. plot:: pyplots/bandpass_demo.py
+   :include-source:
+
+
+
 API reference
 -------------
 
 .. automodule:: litebird_sim.detectors
     :members:
     :undoc-members:
     :show-inheritance:
+
+.. automodule:: litebird_sim.bandpasses
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/dipole.rst

@@ -4,19 +4,22 @@ Dipole anisotropy
 =================
 
 The LiteBIRD Simulation Framework provides tools to simulate the
-signal associated with the relative velocity between the spacecraft's
-rest frame with respect to the CMB. The motion of the spacecraft in
-the rest frame of the CMB is the composition of several components:
+signal associated with the relative velocity between the rest frame of
+the spacecraft with respect to the CMB. The motion of the spacecraft
+in the rest frame of the CMB is the composition of several components:
 
 1. The motion of the spacecraft around L2;
+
 2. The motion of the L2 point in the Ecliptic plane;
+
 3. The motion of the Solar System around the Galactic Centre;
+
 4. The motion of the Milky Way.
 
 Components 1 and 2 are simulated by the LiteBIRD Simulation Framework
-using appropriate models for the motions, while components 3 and 4 are
-included using the Sun velocity derived by the solar dipole measured
-by the Planck satellite. 
+using appropriate motion models, while components 3 and 4 are included
+using the Sun velocity derived by the solar dipole measured by the
+Planck satellite.
 
 The motion of the spacecraft around L2 is modelled using a Lissajous
 orbit similar to what was used for the WMAP experiment
@@ -28,21 +31,21 @@ Position and velocity of the spacecraft
 
 The class :class:`.SpacecraftOrbit` describes the orbit of the
 LiteBIRD spacecraft with respect to the Barycentric Ecliptic Reference
-Frame and the motion of Barycentric Ecliptic Reference Frame with respect
-to the CMB; this class is necessary because the class
+Frame and the motion of the Barycentric Ecliptic Reference Frame with
+respect to the CMB; this class is necessary because the class
 :class:`.ScanningStrategy` (see the chapter :ref:`scanning-strategy`)
 only models the *direction* each instrument is looking at but knows
 nothing about the velocity of the spacecraft itself.
 
-The class :class:`.SpacecraftOrbit` is a dataclass that is able to
-initialize its members to sensible default values, which are taken
-from the literature. As the LiteBIRD orbit around L2 is not fixed yet,
-the code assumes a WMAP-like Lissajous orbit, :cite:`2008:wmap:cavaluzzi`.
-For the Sun velocity it assumes Planck 2018 solar dipole 
+The class :class:`.SpacecraftOrbit` is a dataclass that can initialize
+its members to sensible default values taken from the literature. As
+the LiteBIRD orbit around L2 is not fixed yet, the code assumes a
+WMAP-like Lissajous orbit, :cite:`2008:wmap:cavaluzzi`. For the Sun
+velocity it assumes Planck 2018 solar dipole
 :cite:`2020:planck:hfi_data_processing`.
 
 To compute the position/velocity of the spacecraft, you call
-:func:`.spacecraft_pos_and_vel`; it requires either a time span or an
+:func:`.spacecraft_pos_and_vel`; it requires either a period or an
 :class:`.Observation` object, and it returns an instance of the class
 :class:`.SpacecraftPositionAndVelocity`:
 
@@ -75,9 +78,9 @@ the table with the positions and the velocities in the fields
 arrays of shape ``(nsamples, 3)``.
 
 Here is a slightly more complex example that shows how to plot the
-distance between the spacecraft and the Sun as a function of time, as
-well as its speed. The latter quantity is of course most relevant when
-computing the CMB dipole.
+distance between the spacecraft and the Sun as a function of time and
+speed. The latter quantity is, of course, most relevant when computing
+the CMB dipole.
 
 .. plot:: pyplots/spacecraft_demo.py
    :include-source:
@@ -118,13 +121,13 @@ and :math:`\mathrm{BB}(\nu, T)` is the spectral radiance of a
 black-body according to Planck's law:
 
 .. math:: \mathrm{BB}(\nu, T) = \frac{2h\nu^3}{c^2} \frac1{e^{h\nu/k_B T} - 1} = \frac{2h\nu^3}{c^2} \frac1{e^x - 1}.
-      
-There is no numerical issue in computing the full formula, but often
-models use some simplifications, to make the math easier to work on
-the blackboard. The LiteBIRD Simulation Framework implements several
-simplifications of the formula, which are based on a series expansion
-of :eq:`dipole`; the caller must pass an object of type
-:class:`.DipoleType` (an `enum class
+
+There is no numerical issue in computing the complete formula, but
+often, models use some simplifications to make the math more
+manageable to work on the blackboard. The LiteBIRD Simulation
+Framework implements several simplifications of the formula, which are
+based on a series expansion of :eq:`dipole`; the caller must pass an
+object of type :class:`.DipoleType` (an `enum class
 <https://docs.python.org/3/library/enum.html>`_), whose value signals
 which kind of approximation to use:
 
@@ -184,8 +187,8 @@ Methods of class simulation
 ---------------------------
 
 The class :class:`.Simulation` provides two simple functions that compute
-poisition and velocity of the spacescraft :func:`.Simulation.compute_pos_and_vel`, 
-and add the solar and orbital dipole to all the observations of a given 
+poisition and velocity of the spacescraft :func:`.Simulation.compute_pos_and_vel`,
+and add the solar and orbital dipole to all the observations of a given
 simulation :func:`.Simulation.add_dipole`.
 
 .. testcode::
@@ -253,7 +256,7 @@ simulation :func:`.Simulation.add_dipole`.
    3.45712e-03
 
 Note that even if :func:`Simulation.compute_pos_and_vel` is not explicitly
-invoked, :func:`Simulation.add_dipole` takes care of that internally initializing 
+invoked, :func:`Simulation.add_dipole` takes care of that internally initializing
 :class:`SpacecraftOrbit` and computing positions and velocities.
 
 API reference