update docs

docs/conf.py

@@ -16,15 +16,19 @@
     "sphinx_rtd_theme",
     "myst_nb",
     "sphinxcontrib.bibtex",
+    "sphinx_design",
 ]
 
 bibtex_bibfiles = ["bibliography.bib"]
 
 myst_update_mathjax = False  # to use single $x^2$ for equations
 myst_render_markdown_format = "myst"  # to parse markdown output with MyST parser
+myst_enable_extensions = ["dollarmath", "colon_fence"]
+
+myst_title_to_header = True
 
-myst_enable_extensions = ["dollarmath"]
 nb_execution_mode = "cache"
+nb_execution_timeout = 120
 
 autosummary_generate = ["api_reference.rst"]
 

docs/contribution_guide.rst

@@ -12,11 +12,10 @@ using the `conda <https://github.com/conda/conda>`_ package-manager.
    conda env create -f < path to rt1_dev.yml >
 
 
-The contents of the ``rt1_dev.yml`` file are given below:
+.. dropdown:: Click to view contents of ``rt1_dev.yml``
 
-
-.. literalinclude:: rt1_dev.yml
-   :language: yaml
+    .. literalinclude:: rt1_dev.yml
+       :language: yaml
 
 
 When the environment is set up, make sure to activate it using

docs/doc_env.yml

@@ -10,5 +10,6 @@ dependencies:
   - myst-nb=1.0.0
   - ipympl=0.9.3
   - sphinx_rtd_theme=1.3
+  - sphinx-design=0.5.0
   - sphinxcontrib-bibtex=2.5.0
   - python-symengine=0.10

docs/examples.rst

@@ -8,15 +8,25 @@ Basics
    :maxdepth: 1
 
    examples/analyzemodel.ipynb
-   examples/example_fn.ipynb
    examples/linear_combinations.ipynb
 
-
 Parameter Retrieval
 ...................
 
-The following examples show how to use ``rt1_model`` package together with `scipy.optimize <https://docs.scipy.org/doc/scipy/reference/optimize.html>`_ to
-retrieve model parameters from datasets via non-linear least squares optimization.
+.. dropdown:: What are the retrieval examples doing?
+    :color: light
+    :icon: info
+
+    The retrieval examples show how to use ``rt1_model`` package together with `scipy.optimize <https://docs.scipy.org/doc/scipy/reference/optimize.html>`_ to retrieve model parameters from datasets via non-linear least squares optimization.
+
+    All examples follow the same basic structure (e.g. "closed-loop experiments"):
+
+    1) Select a model configuration.
+    2) Simulate a dataset using a set of random input-parameters.
+    3) Add some random noise to the data.
+    4) Use an optimization procedure to retrieve the parameters from the simulated dataset.
+    5) Check if the retrieved parameters are similar to the ones used for creating the dataset.
+
 
 
 .. toctree::
@@ -28,14 +38,12 @@ retrieve model parameters from datasets via non-linear least squares optimizatio
    examples/retrieval_4_parameter_functions.ipynb
    examples/retrieval_5_timeseries_with_aux_data.ipynb
 
-.. admonition:: What are the retrieval examples doing?
-
-    The presented retrieval examples show so-called "closed-loop" experiments with different setups.
+Notes on first-order corrections
+................................
 
-    The steps of a "closed-loop" experiment can be summarized like this:
+.. toctree::
+   :maxdepth: 1
 
-    1) Select a suitable model configuration.
-    2) Simulate a dataset using a set of random input-parameters.
-    3) Add some random noise to the data.
-    4) Use an optimization procedure to retrieve the parameters from the simulated dataset.
-    5) Check if the retrieved parameters are similar to the ones used for creating the dataset.
+   examples/example_fn.ipynb
+   examples/number_of_expansion_coefficients.ipynb
+   examples/untitled.md

docs/model_specification.rst

@@ -12,10 +12,11 @@ Evaluation Geometries
 
 .. currentmodule:: rt1_model
 
+In order to calculate first order corrections with respect to the chosen scattering distributions, the so-called fn-coefficients have to be evaluated.
 From the general definition of the fn-coefficients :eq:`fn_coef_definition` it is apparent that they are in principle dependent on :math:`\theta_0,\phi_0,\theta_{ex}` and :math:`\phi_{ex}`.
 If the series-expansions (:eq:`brdf_expansion` and :eq:`p_expansion`) contain a high number of Legendre-polynomials, the resulting fn-coefficients turn out to be rather lengthy and moreover their evaluation might consume a lot of time.
 Since usually one is only interested in an evaluation with respect to a specific (a-priori known) geometry of the measurement-setup, the rt1-module incorporates a parameter that allows specifying the
-geometry at which the results are being evaluated. This generally results in a considerable speedup for the fn-coefficient generation.
+geometry at which the results are being evaluated. This results in a considerable speedup for the fn-coefficient generation.
 
 
 The measurement-geometry for a given :py:class:`RT1` class instance can be set via one of the following options:

docs/rt1_dev.yml

@@ -22,15 +22,19 @@ dependencies:
   - nbformat
   - cloudpickle
 
-  # ---------- to run jupyter notebooks
-  - jupyterlab
-  - ipympl
-
   # ---------- for building the docs
   - myst-nb
   - docutils
   - sphinx
   - sphinx-copybutton
   - sphinx-autobuild
+  - sphinx-design
   - sphinx_rtd_theme
   - sphinxcontrib-bibtex
+
+  # ---------- to run jupyter notebooks
+  - jupyterlab
+  - ipympl
+  - pip
+  - pip:
+    - jupyterlab_myst # for MySt Markdown parsing in jupyterlab

docs/theory.rst

@@ -186,38 +186,13 @@ First, the so-called fn-coefficients are evaluated which are defined via:
 
 Second, :math:`I_{\textrm{interaction}}` is evaluated using the analytic solution to the remaining :math:`\theta`-integral for a given set of fn-coefficients as presented in :cite:p:`.-Quast2016`.
 
-.. admonition:: Example
-
-	In the following, a simple example on how to evaluate the fn-coefficients is given.
-	The ground is hereby defined as a Lambertian-surface and the covering layer is assumed to consist of Rayleigh-particles. Thus, we have: (:math:`R_0` hereby denotes the diffuse albedo of the surface)
-
-    .. math::
-       &BRDF(\theta, \phi, \theta_{ex},\phi_{ex}) = \frac{R_0}{\pi}
-       \\&p(\theta, \phi, \theta_{ex},\phi_{ex}) = \frac{3}{16\pi} (1+\cos(\Theta)^2)
-       \\&\textrm{with} \qquad \qquad \cos(\Theta) = \cos(\theta)\cos(\theta_{ex}) + \sin(\theta)\sin(\theta_{ex})\cos(\phi - \phi_{ex})
-
-    Evaluation of the fn coefficients:
-	.. math::
-	   &INT = \int_0^{2\pi} p(\theta_0, \phi_0, \theta,\phi) * BRDF(\pi-\theta, \phi, \theta_{ex},\phi_{ex}) d\phi =
-	   \\&\frac{3 R_0}{16 \pi^2} \int\limits_{0}^{2\pi}  \Big(1+[\cos(\theta_0)\cos(\theta) + \sin(\theta_0)\sin(\theta)\cos(\phi_0 - \phi)]^2\Big) d\phi =
-	   \\&\frac{3 R_0}{16 \pi^2} \int\limits_0^{2\pi} \Big(1+ \mu_0^2 \mu^2 + 2 \mu_0 \mu \sin(\theta_0) \sin(\theta) \cos(\phi_0 - \phi) + (1-\mu_0)^2(1-\mu)^2 \cos(\phi_0 - \phi)^2\Big) d\phi
-
-	where the shorthand-notation :math:`\mu_x = \cos(\theta_x)` has been introduced.
-
-	The above integral can now easily be solved by noticing:
-
-	.. math::
-	   \int\limits_0^{2\pi} \cos(\phi_0 - \phi)^n d\phi = \left\lbrace \begin{matrix} 2 \pi & \textrm{for } n=0 \\ 0 & \textrm{for } n=1 \\ \pi  & \textrm{for } n=2 \end{matrix} \right.
-
-	Using some algebraic manipulations we therefore find:
-
-	.. math::
-	   INT = \frac{3 R_0}{16\pi} \Big[ (3-\mu_0^2) + (3 \mu_0 -1) \mu^2 \Big] = \sum_{n=0}^2 f_n ~ \mu^n
-	   \\ \\
-	   \Rightarrow \quad f_0 = \frac{3 R_0}{16\pi}(3-\mu_0^2) \qquad f_1 = 0 \qquad f_2 = \frac{3 R_0}{16\pi}(3 \mu_0 -1) \qquad f_n = 0 ~ \forall ~n>2
-
-     An example on how to use the RT1-module to evaluate the above fn-coefficients can be found in the example notebook: :doc:`examples/example_fn`
+.. button-link:: examples/example_fn.html
+    :color: primary
+    :shadow:
+    :ref-type: doc
+    :align: center
 
+    Click here for an example how to evaluate the fn-coefficients manually and with the RT1 package.
 
 .. bibliography::
    :filter: docname in docnames