docs: improve module descriptions

cspell.json

@@ -73,6 +73,7 @@
         "itertools",
         "jsonschema",
         "jupyter",
+        "lambdifying",
         "lineshape",
         "mathbb",
         "matplotlib",

docs/conf.py

@@ -139,6 +139,7 @@
         None,
     ),
     "iminuit": ("https://iminuit.readthedocs.io/en/stable", None),
+    "jax": ("https://jax.readthedocs.io/en/stable", None),
     "matplotlib": ("https://matplotlib.org", None),
     "mypy": ("https://mypy.readthedocs.io/en/stable", None),
     "numpy": ("https://numpy.org/doc/stable", None),

docs/index.md

@@ -16,17 +16,27 @@ For an overview of upcoming releases and planned functionality, see
 ```
 ````
 
-For a quick demo of the TensorWaves workflow, see {doc}`/usage`.
-
-TensorWaves is a Python package for doing Partial Wave Analysis with
-[TensorFlow](https://www.tensorflow.org) as computational backend. The package
-originates from [pycompwa](pycompwa), which did its computations through
-[ComPWA](https://github.com/ComPWA/ComPWA) — ComPWA's function tree is similar
-to TensorFlow graphs and can therefore be replaced by the tools that TensorFlow
-already offers. The decision to completely migrate ComPWA to TensorFlow has
-been further inspired by
+TensorWaves is a fitter package that optimizes mathematical models to data
+samples. The models can be any mathematical expression (best expressed with
+{mod}`sympy`) that is then converted to any computational backend. In addition,
+the {mod}`tensorwaves.data` module allows one to generate toy data samples.
+
+```{link-button} usage
+---
+classes: btn-outline-primary btn-block
+type: ref
+text: Click here for a quick demo
+---
+```
+
+The package originates from {mod}`pycompwa`, which did its computations through
+[ComPWA](https://github.com/ComPWA/ComPWA). ComPWA's function tree is similar
+to for instance
+[TensorFlow graphs](https://www.tensorflow.org/tensorboard/graphs) and
+[SymPy expression trees](https://docs.sympy.org/latest/tutorial/manipulation.html).
+The decision to use Python only has been further inspired by
 [TensorFlowAnalysis](https://gitlab.cern.ch/poluekt/TensorFlowAnalysis)/[AmpliTF](https://github.com/apoluekt/AmpliTF)
-and [zfit](https://github.com/zfit/zfit)
+and [zfit](https://github.com/zfit/zfit).
 
 ## Table of Contents
 

docs/tensorflow.txt

@@ -3,6 +3,7 @@
 # Version: 2
 # The remainder of this file is compressed using zlib.
 
+tf.Tensor   py:class 1 tf/Tensor -
 tf.Variable py:class 1 tf/Variable -
 tensorflow.python.keras.losses.Loss py:class 1 tf/keras/losses/Loss -
 tensorflow.python.ops.stateful_random_ops.Generator py:class 1 tf/random/Generator -

docs/usage.ipynb

@@ -18,21 +18,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "```{toctree}\n",
-    "---\n",
-    "maxdepth: 2\n",
-    "---\n",
-    "usage/1_create_model\n",
-    "usage/2_generate_data\n",
-    "usage/3_perform_fit\n",
-    "```"
+    "## Overview"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Create an amplitude model"
+    "### Create an amplitude model"
    ]
   },
   {
@@ -116,7 +109,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Generate toy MC sample"
+    "### Generate toy MC sample"
    ]
   },
   {
@@ -225,7 +218,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Optimize the amplitude model"
+    "### Optimize the amplitude model"
    ]
   },
   {
@@ -413,6 +406,27 @@
     "fig.tight_layout()\n",
     "ax2.set_xlabel(\"function call\");"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step-by-step workflow"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```{toctree}\n",
+    "---\n",
+    "maxdepth: 2\n",
+    "---\n",
+    "usage/1_create_model\n",
+    "usage/2_generate_data\n",
+    "usage/3_perform_fit\n",
+    "```"
+   ]
   }
  ],
  "metadata": {

src/tensorwaves/__init__.py

@@ -1,6 +1,22 @@
-"""A fully featured Partial Wave Analysis framework in Python.
+"""A model optimization package for Partial Wave Analysis.
 
-For more info see `tensorwaves.rtfd.io <http://tensorwaves.rtfd.io/>`_.
+The `tensorwaves` package contains four main ingredients:
+
+  Model lambdifying (`tensorwaves.model`)
+    ― Convert arbitrary mathematical expressions to an computational backends
+    like `numpy`, `jax <jax.jit>`, and `tensorflow <tf.Tensor>`. This module
+    works best with `sympy` expressions as input.
+
+  Data generation (`tensorwaves.data`)
+    ― Generate phase space samples and toy Monte Carlo samples based on an
+    intensity `.Model`. This module works best in combination with the
+    `expertsystem`.
+
+  Model optimization (`tensorwaves.optimizer` and `~.estimator`)
+    ― Optimize the `.Model` with respect to some data sample and an
+    `.Estimator` (loss function).
+
+The `.interfaces` module defines how the main classes interact.
 """
 
 __all__ = [

src/tensorwaves/data/__init__.py

@@ -1,4 +1,4 @@
-"""The data module takes care of data generation."""
+"""The `.data` module takes care of data generation."""
 
 __all__ = [
     "generate",

src/tensorwaves/estimator.py

@@ -1,6 +1,6 @@
 """Defines estimators which estimate a model's ability to represent the data.
 
-All estimators have to implement the `~.interfaces.Estimator` interface.
+All estimators have to implement the `.Estimator` interface.
 """
 from typing import Callable, Dict, Mapping, Union
 

src/tensorwaves/model/__init__.py

@@ -1,4 +1,9 @@
-"""Evaluateable physics models for amplitude analysis."""
+"""Evaluateable physics models for amplitude analysis.
+
+The `.model` module takes care of lambdifying mathematical expressions to
+computational backends. Currently, mathematical expressions are implemented
+as `.sympy` expressions only.
+"""
 
 __all__ = [
     "sympy",

src/tensorwaves/model/sympy.py

@@ -1,4 +1,4 @@
-"""`.Function` Adapter for `sympy`-based models."""
+"""`.Function` and `.Model` implementation for `sympy`-based models."""
 
 from typing import Callable, Dict, FrozenSet, Mapping, Tuple, Union
 

src/tensorwaves/optimizer/__init__.py

@@ -1,4 +1,8 @@
-"""Collection of fit optimizers."""
+"""Collection of fit optimizers.
+
+Optimizers 'fit' a `.Model` to some data sample with regard to `.Estimator` as
+loss function.
+"""
 
 __all__ = [
     "minuit",