TUW-GEO · raphaelquast · Nov 22, 2023 · Nov 22, 2023 · Nov 22, 2023 · Nov 22, 2023
diff --git a/.github/workflows/Publish_to_PyPi.yml b/.github/workflows/Publish_to_PyPi.yml
@@ -30,8 +30,8 @@ jobs:
         env:
           TWINE_USERNAME: __token__
           # use the following line for deployment on pypi
-          #TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
 
           # use the following lines for testing:
-          TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
-          TWINE_REPOSITORY: testpypi
+          #TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          #TWINE_REPOSITORY: testpypi
diff --git a/.gitignore b/.gitignore
@@ -8,3 +8,9 @@ docs/examples/.ipynb_checkpoints/*
 docs/examples/.virtual_documents/*
 .virtual_documents/*
 docs/jupyter_execute/*
+docs/.jupyter_cache/*
+*.bak
+*.sav.tmp
+dist/*
+_exclude/*
+_additional_resources/*
diff --git a/codecov.yml b/codecov.yml
@@ -0,0 +1,4 @@
+ignore:
+  # ignore docscrape.py for coverage (it is inherited from numpydocs)
+  # and does not interfere with the functionality (only with docstrings)
+  - "src/rt1_model/_numpydoc_docscrape.py"
diff --git a/docs/_static/model.png b/docs/_static/model.png
diff --git a/docs/bibliography.bib b/docs/bibliography.bib
@@ -0,0 +1,45 @@
+
+@Article{Quast2016,
+  author    = {Quast, Raphael and Wagner, Wolfgang},
+  journal   = {Applied Optics},
+  title     = {Analytical solution for first-order scattering in bistatic radiative transfer interaction problems of layered media},
+  year      = {2016},
+  issn      = {1539-4522},
+  month     = jul,
+  number    = {20},
+  pages     = {5379},
+  volume    = {55},
+  doi       = {10.1364/ao.55.005379},
+  publisher = {The Optical Society},
+}
+
+
+@Article{Quast2019,
+  author    = {Quast, Raphael and Albergel, Clément and Calvet, Jean-Christophe and Wagner, Wolfgang},
+  journal   = {Remote Sensing},
+  title     = {A Generic First-Order Radiative Transfer Modelling Approach for the Inversion of Soil and Vegetation Parameters from Scatterometer Observations},
+  year      = {2019},
+  issn      = {2072-4292},
+  month     = feb,
+  number    = {3},
+  pages     = {285},
+  volume    = {11},
+  doi       = {10.3390/rs11030285},
+  publisher = {MDPI AG},
+}
+
+
+@Article{Quast2023,
+  author    = {Quast, Raphael and Wagner, Wolfgang and Bauer-Marschallinger, Bernhard and Vreugdenhil, Mariette},
+  journal   = {Remote Sensing of Environment},
+  title     = {Soil moisture retrieval from Sentinel-1 using a first-order radiative transfer model—A case-study over the Po-Valley},
+  year      = {2023},
+  issn      = {0034-4257},
+  month     = sep,
+  pages     = {113651},
+  volume    = {295},
+  doi       = {10.1016/j.rse.2023.113651},
+  publisher = {Elsevier BV},
+}
+
+@Comment{jabref-meta: databaseType:bibtex;}
diff --git a/docs/conf.py b/docs/conf.py
@@ -15,19 +15,20 @@
     "sphinx_copybutton",
     "sphinx_rtd_theme",
     "myst_nb",
+    "sphinxcontrib.bibtex",
 ]
 
+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",
-]
+myst_enable_extensions = ["dollarmath"]
+nb_execution_mode = "cache"
 
 autosummary_generate = ["api_reference.rst"]
 
-exclude_patterns = ["build", "examples/.*", "jupyter_execute/*"]
+exclude_patterns = ["build", "examples/.*", "jupyter_execute/*", ".jupyter-cache"]
 
 # autodoc_default_options = {
 #    "members": True,

diff --git a/docs/contribution_guide.rst b/docs/contribution_guide.rst
@@ -14,34 +14,9 @@ using the `conda <https://github.com/conda/conda>`_ package-manager.
 
 The contents of the ``rt1_dev.yml`` file are given below:
 
-.. code-block:: yaml
 
-    name: rt1_dev
-
-    channels:
-      - conda-forge
-
-    dependencies:
-      # ----------- required
-      - numpy
-      - scipy
-      - sympy
-
-      # ----------- optional
-      - matplotlib        # for plotting
-      - python-symengine  # to speed up symbolic calculations
-
-      # ----------- for testing
-      - pytest            # to run unittests
-      - pytest-cov        # to evaluate test-coverage
-      - nbformat          # to parse jupyter notebooks
-
-      # ----------- for building the docs
-      - sphinx            # to process docs
-      - sphinx_copybutton # a nice copy-button for code-blocks
-      - sphinx_rtd_theme  # the used documentation-theme
-      - myst-nb           # to render jupyter notebooks
-      - ipympl            # for interactive plots in notebooks
+.. literalinclude:: rt1_dev.yml
+   :language: yaml
 
 
 When the environment is set up, make sure to activate it using
@@ -51,7 +26,7 @@ When the environment is set up, make sure to activate it using
    conda activate rt1_dev
 
 
-Now you can install the ``rt1_model`` package in `editable mode <https://pip.pypa.io/en/latest/topics/local-project-installs/#editable-installs>`_.
+Now its time to install the ``rt1_model`` package in `editable mode <https://pip.pypa.io/en/latest/topics/local-project-installs/#editable-installs>`_!
 
 To do so, first clone the `GitHub repository <https://github.com/TUW-GEO/rt1_model>`_, then navigate to the parent directory
 (containing the ``pyproject.toml`` file) and execute the following command:

diff --git a/docs/doc_env.yml b/docs/doc_env.yml
@@ -3,12 +3,12 @@ channels:
   - conda-forge
 
 dependencies:
-  - docutils
-  - sphinx
-  - sphinx-copybutton
-  - matplotlib-base
-  - myst-nb
-  - ipympl
-  - pip
-  - pip:
-    - sphinx_rtd_theme
+  - docutils<0.19
+  - sphinx=7.2.6
+  - sphinx-copybutton=0.5.2
+  - matplotlib-base=3.8.2
+  - myst-nb=1.0.0
+  - ipympl=0.9.3
+  - sphinx_rtd_theme=1.3
+  - sphinxcontrib-bibtex=2.5.0
+  - python-symengine=0.10
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -9,16 +9,28 @@ Basics
 
    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.
 
+
+.. toctree::
+   :maxdepth: 1
+
+   examples/retrieval_1_static_parameters.ipynb
+   examples/retrieval_2_timeseries.ipynb
+   examples/retrieval_3_multi_temporal.ipynb
+   examples/retrieval_4_parameter_functions.ipynb
+   examples/retrieval_5_timeseries_with_aux_data.ipynb
+
 .. admonition:: What are the retrieval examples doing?
 
-    All examples show so-called "closed-loop" experiments with different setups.
+    The presented retrieval examples show so-called "closed-loop" experiments with different setups.
 
     The steps of a "closed-loop" experiment can be summarized like this:
 
@@ -27,14 +39,3 @@ retrieve model parameters from datasets via non-linear least squares optimizatio
     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::
-   :maxdepth: 1
-
-   examples/retrieval_1_static_parameters.ipynb
-   examples/retrieval_2_timeseries.ipynb
-   examples/retrieval_3_multi_temporal.ipynb
-   examples/retrieval_4_parameter_functions.ipynb
-   examples/retrieval_5_timeseries_with_aux_data.ipynb
diff --git a/docs/examples/analyzemodel.ipynb b/docs/examples/analyzemodel.ipynb
diff --git a/docs/examples/linear_combinations.ipynb b/docs/examples/linear_combinations.ipynb
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,59 +1,55 @@
 RT1 model documentation
 -----------------------
 
-Welcome to the documentation for the **RT1 python module**!
+Welcome to the documentation for the **RT1 python package**!
 
 
-The `RT1` package implements a bistatic first order scattering radiative transfer model that might be used for generic purposes.
+The ``rt1_model`` package is a ``python`` implementation for the RT1 bistatic (first order) scattering radiative transfer model as described in :cite:t:`Quast2016` :cite:t:`Quast2019`.
+that can be used to simulate the scattered radiation from a rough surface covered by a tenuous distribution of particulate media.
 
-Unique features of this model are:
 
-- Analytical solution of the radiative transfer equation up to first order with flexible BRDF and volume phase function specifications.
-- Analytical solution for the jacobian with respect to arbitrary model parameters.
-- ...
-- **TODO: write a nice intro**
+RT1 hereby provies a flexible framework to parameterize the scattering properties of the surface and volume layer via bistatic distribution functions.
 
+The ``rt1_model`` package provides the following core features:
 
-Credits and References
-----------------------
+- An object-oriented interface to easily setup, evaluate and analyze RT1 model specifications.
+- An (extensible) set of volume- and surface scattering distribution functions and capabilities to use arbitrary linear combinations thereof.
+- Fast numeric evaluation of the model up to first order (e.g. double-bounce) contributions.
+- Capabilities to evaluate the Jacobian with respect to arbitrary model parameters (for model parameter optimization).
 
-`RT1` is provided as open-source software, hoping that it will help you in your research.
-The developers would very much appreciate to receive feedback how the model is used. Also contributions and suggestions for further improvements are highly welcome.
 
 
-Please read the LICENSE agreement related to this software which gives you much flexibility to (re)use the code. Currently we use the APACHE-2.0 license.
+.. figure:: _static/model.png
+   :align: center
+   :width: 50%
+   :alt: RT1 model overview
 
+   Illustration of the scattering contributions considered in the RT1 model (from :cite:p:`Quast2023`)
 
-When you are using `RT1` as part of your publications, please give the developers credit by giving reference to the GitHub repository and to the following papers:
 
+.. note::
+
+   `RT1` is provided as open-source software, hoping that it will help you in your research.
+   The developers would very much appreciate to receive feedback how the model is used. Also contributions and suggestions for further improvements are highly welcome.
+
+
+   Please read the `LICENSE <https://github.com/TUW-GEO/rt1_model/blob/master/LICENSE>`_ agreement related to this software which gives you much flexibility to (re)use the code. Currently we use the APACHE-2.0 license.
 
-.. raw:: html
 
-   <ul>
-   <li>
-   <a href=https://opg.optica.org/ao/viewmedia.cfm?uri=ao-55-20-5379&html=true>
-   R.Quast and W.Wagner, <i>Analytical solution for first-order scattering in bistatic radiative transfer interaction problems of layered media</i>, Applied Optics (2016), doi:10.1364/AO.55.005379
-   </a>
-   </li>
-   <li>
-   <a href=https://www.mdpi.com/2072-4292/11/3/285>
-   R.Quast, C.Albergel, J.C.Calvet, W.Wagner, <i>A Generic First-Order Radiative Transfer Modelling Approach for the Inversion of Soil and Vegetation Parameters from Scatterometer Observations</i>, Remote Sensing (2019),  doi:10.3390/rs11030285
-   </a>
-   </li>
-   </ul>
+   When you are using `RT1` as part of your publications, please give the developers credit by giving reference to the `GitHub repository <https://github.com/TUW-GEO/rt1_model>`_ and to the papers :cite:t:`Quast2016`,  :cite:t:`Quast2019`:
+
+
+   Additional information on how to use the RT1 model for soil-moisture retrievals can be found in :cite:t:`Quast2023`:
 
 
-Additional information on how to use the RT1 model for soil-moisture retrievals can be found in:
 
 .. raw:: html
 
-   <ul>
-   <li>
-   <a href=https://www.sciencedirect.com/science/article/pii/S003442572300202X>
-   R.Quast, W.Wagner, B.Bauer-Marschallinger, M.Vreugdenhil: Soil moisture retrieval from Sentinel-1 using a first-order radiative transfer model—A case-study over the Po-Valley, Remote Sensing of Environment (2023), doi: 10.1016/j.rse.2023.113651
-   </a>
-   </li>
-   </ul>
+   <hr>
+
+
+.. bibliography::
+   :filter: docname in docnames
 
 
 .. toctree::