Merge pull request #13 from TUW-GEO/dev

merge for v0.5
TUW-GEO · Feb 19, 2024 · e95df02 · e95df02
2 parents d8b2dcd + 434c182
commit e95df02
Show file tree

Hide file tree

Showing 25 changed files with 1,457 additions and 1,005 deletions.
diff --git a/docs/conf.py b/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"]
 

diff --git a/docs/contribution_guide.rst b/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

diff --git a/docs/doc_env.yml b/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
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -1,22 +1,37 @@
 Examples
 --------
 
+.. note::
+
+    To run the example-notebooks, you also need the additional dependencies `matplotlib <https://matplotlib.org/>`_ and `ipympl <https://matplotlib.org/ipympl/>`_.
+
+
 Basics
 ......
 
 .. toctree::
    :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 +43,11 @@ 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
diff --git a/docs/examples/analyzemodel.ipynb b/docs/examples/analyzemodel.ipynb
diff --git a/docs/examples/example_fn.ipynb b/docs/examples/example_fn.ipynb
@@ -20,21 +20,28 @@
    "source": [
     "# Calculation of the fn-coefficients\n",
     "\n",
-    "In the following, a simple example on how to manually evaluate the fn-coefficients is given. \n",
+    ":::{admonition} About this example\n",
+    "This example shows how to evaluate the fn-coefficients required to evaluate the interaction-contribution manually as well as with the [rt1 python package](https://github.com/raphaelquast/rt1_model). \n",
     "\n",
-    "The ground is hereby defined as a Lambertian-surface and the covering layer is assumed to consist of Rayleigh-particles.  \n",
-    "\n",
-    "Within the following calculation, the symbols and functions are defined as presented in the Theory-chapter of the documentation.\n",
+    "The ground is hereby defined as an ideally rough (e.g. Lambertian surface) and the covering layer is assumed to consist of Rayleigh-particles.  \n",
+    ":::\n",
     "\n",
     "## Definition of the surface and volume scattering distribution functions:\n",
-    "- $R_0$ denotes the diffuse albedo of the surface)\n",
-    "- $\\cos(\\Theta)$ denotes the cosine of the scattering-angle which is defined as:\n",
-    "  $\\qquad \\cos(\\Theta) = \\cos(\\theta)\\cos(\\theta_{ex}) + \\sin(\\theta)\\sin(\\theta_{ex})\\cos(\\phi - \\phi_{ex})$\n",
+    "The scattering distribution function of a Lambertian surface (e.g. an isotropic BRDF) is given by:\n",
     "\n",
     "$BRDF(\\theta, \\phi, \\theta_{ex},\\phi_{ex}) = \\frac{R_0}{\\pi}$\n",
     "\n",
+    "where $R_0$ denotes the diffuse albedo of the surface.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "For the volume-scattering layer, the used Rayleigh scattering distribution function is given by:\n",
+    "\n",
     "$p(\\theta, \\phi, \\theta_{ex},\\phi_{ex}) = \\frac{3}{16\\pi} (1+\\cos(\\Theta)^2)$\n",
-    "\n"
+    "\n",
+    "where $\\cos(\\Theta)$ denotes the cosine of the scattering-angle which is defined as:  \n",
+    "\n",
+    "$\\qquad \\cos(\\Theta) = \\cos(\\theta)\\cos(\\theta_{ex}) + \\sin(\\theta)\\sin(\\theta_{ex})\\cos(\\phi - \\phi_{ex})$\n"
    ]
   },
   {
@@ -57,14 +64,17 @@
    "source": [
     "## Manual evaluation of the fn-coefficients:\n",
     "\n",
+    "```{note}\n",
+    "To be consistent with the definitions used in the rt1-model package, the incident zenizh-angle $\\theta_0$ is introduced as: $\\theta_0=\\pi - \\theta$, \n",
+    "and the shorthand-notation $\\mu_x = \\cos(\\theta_x)$ is introduced.\n",
+    "```\n",
+    "\n",
     "$INT := \\int_0^{2\\pi} p(\\theta_0, \\phi_0, \\theta,\\phi) * BRDF(\\pi-\\theta, \\phi, \\theta_{ex},\\phi_{ex}) d\\phi$\n",
     "\n",
     "$\\phantom{INT} = \\frac{3 R_0}{16 \\pi^2} \\int_{0}^{2\\pi}  (1+[\\cos(\\theta_0)\\cos(\\theta) + \\sin(\\theta_0)\\sin(\\theta)\\cos(\\phi_0 - \\phi)]^2) d\\phi$\n",
     "\n",
     "$\\phantom{INT} = \\frac{3 R_0}{16 \\pi^2} \\int_0^{2\\pi} (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 d\\phi$\n",
     "\n",
-    "\n",
-    "where the shorthand-notation $\\mu_x = \\cos(\\theta_x)$ has been introduced.\n",
     "The above integral can now easily be solved by noticing:\n",
     "\n",
     "$\\int_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.$\n",

diff --git a/docs/examples/linear_combinations.ipynb b/docs/examples/linear_combinations.ipynb
@@ -3,11 +3,19 @@
   {
    "cell_type": "markdown",
    "id": "17c61f1f-5033-47dc-8b2f-4a455a10e597",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "# Linear combinations of distribution functions\n",
     "\n",
-    "This example shows how to create linear combinations of ``surface`` and ``volume`` scattering distribution functions."
+    ":::{admonition} About this example\n",
+    "This example shows how to create linear combinations of [`surface`](rt1_model.surface) and [`volume`](rt1_model.volume) scattering distribution functions.\n",
+    ":::"
    ]
   },
   {
@@ -74,7 +82,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "030d37d61d4743af8e238812e46d0723",
+       "model_id": "90f23aafa8f64274a808b2fe4ba798a1",
        "version_major": 2,
        "version_minor": 0
       },
@@ -90,15 +98,18 @@
        "        "
       ],
       "text/plain": [
-       "Canvas(toolbar=Toolbar(toolitems=[('Home', 'Reset original view', 'home', 'home'), ('Back', 'Back to previous …"
+       "Canvas(header_visible=False, toolbar=Toolbar(toolitems=[('Home', 'Reset original view', 'home', 'home'), ('Bac…"
       ]
      },
      "metadata": {},
      "output_type": "display_data"
     }
    ],
    "source": [
-    "V = volume.LinComb([(0.5, volume.Isotropic()), (0.5, volume.HenyeyGreenstein(t=0.4, ncoefs=10))])\n",
+    "V_1 = volume.Isotropic()\n",
+    "V_2 = volume.HenyeyGreenstein(t=0.4, ncoefs=10)\n",
+    "\n",
+    "V = volume.LinComb([(0.5, V_1), (0.5, V_2)])\n",
     "V.polarplot()"
    ]
   },
@@ -132,7 +143,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "6c8df5b2a3924099a2cdad441d46edce",
+       "model_id": "604a75c9d7c64d9a9f989f3b84136cf6",
        "version_major": 2,
        "version_minor": 0
       },
@@ -148,17 +159,20 @@
        "        "
       ],
       "text/plain": [
-       "Canvas(toolbar=Toolbar(toolitems=[('Home', 'Reset original view', 'home', 'home'), ('Back', 'Back to previous …"
+       "Canvas(header_visible=False, toolbar=Toolbar(toolitems=[('Home', 'Reset original view', 'home', 'home'), ('Bac…"
       ]
      },
      "metadata": {},
      "output_type": "display_data"
     }
    ],
    "source": [
-    "V = volume.LinComb([(\"w\", volume.Rayleigh()), (\"1-w\", volume.HenyeyGreenstein(t=\"t\", ncoefs=12))])\n",
+    "V_1 = volume.Rayleigh()\n",
+    "V_2 = volume.HenyeyGreenstein(t=\"t\", ncoefs=12)\n",
+    "V = volume.LinComb([(\"w\", V_1), (\"1-w\", V_2)])\n",
     "\n",
     "f = plt.figure(figsize=(10, 4))\n",
+    "f.canvas.header_visible = False\n",
     "ax1, ax2, ax3 = f.add_subplot(131, projection=\"polar\"), f.add_subplot(132, projection=\"polar\"), f.add_subplot(133, projection=\"polar\")\n",
     "V.polarplot(ax=ax1, param_dict=dict(w=0., t=0.6), legend=False)\n",
     "V.polarplot(ax=ax2, param_dict=dict(w=0.5, t=0.6), legend=False)\n",
@@ -197,7 +211,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "d7f1630fb2bb4ee5a824c987e867e122",
+       "model_id": "560d4fb7f86040b69f706dfde0a2cf8e",
        "version_major": 2,
        "version_minor": 0
       },
@@ -213,15 +227,17 @@
        "        "
       ],
       "text/plain": [
-       "Canvas(toolbar=Toolbar(toolitems=[('Home', 'Reset original view', 'home', 'home'), ('Back', 'Back to previous …"
+       "Canvas(header_visible=False, toolbar=Toolbar(toolitems=[('Home', 'Reset original view', 'home', 'home'), ('Bac…"
       ]
      },
      "metadata": {},
      "output_type": "display_data"
     }
    ],
    "source": [
-    "SRF = surface.LinComb([(0.5, surface.Isotropic()), (0.5, surface.HenyeyGreenstein(t=0.4, ncoefs=10))])\n",
+    "SRF_1 = surface.Isotropic()\n",
+    "SRF_2 = surface.HenyeyGreenstein(t=0.4, ncoefs=10)\n",
+    "SRF = surface.LinComb([(0.5, SRF_1), (0.5, SRF_2)])\n",
     "SRF.polarplot()"
    ]
   },
@@ -256,7 +272,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "c3c6a32fc414470ab4c9098ede1ef2b7",
+       "model_id": "b9ac4674a9f44ae7aa270435ff9b844f",
        "version_major": 2,
        "version_minor": 0
       },
@@ -272,18 +288,20 @@
        "        "
       ],
       "text/plain": [
-       "Canvas(toolbar=Toolbar(toolitems=[('Home', 'Reset original view', 'home', 'home'), ('Back', 'Back to previous …"
+       "Canvas(header_visible=False, toolbar=Toolbar(toolitems=[('Home', 'Reset original view', 'home', 'home'), ('Bac…"
       ]
      },
      "metadata": {},
      "output_type": "display_data"
     }
    ],
    "source": [
-    "SRF = surface.LinComb([(\"w\", surface.HenyeyGreenstein(t=\"-t\", a=[-1, 1, 1], ncoefs=12)), \n",
-    "                       (\"1-w\", surface.HenyeyGreenstein(t=\"t\", ncoefs=12))])\n",
+    "SRF_1 = surface.HenyeyGreenstein(t=\"-t\", a=[-1, 1, 1], ncoefs=12)\n",
+    "SRF_2 = surface.HenyeyGreenstein(t=\"t\", ncoefs=12)\n",
+    "SRF = surface.LinComb([(\"w\", SRF_1), (\"1-w\", SRF_2)])\n",
     "\n",
     "f = plt.figure(figsize=(10, 4))\n",
+    "f.canvas.header_visible = False\n",
     "axes = (f.add_subplot(131, projection=\"polar\"), \n",
     "        f.add_subplot(132, projection=\"polar\"), \n",
     "        f.add_subplot(133, projection=\"polar\"))\n",