Skip to content

Commit

Permalink
DOC: address feedback to symbolics explainer (#281)
Browse files Browse the repository at this point in the history 
* DOC: switch transparency logo to material-regular `local_library`
* MAINT: remove `/en` from `expertsystem` API link
* MAINT: remove redundant `no-set-nbcells` comment
  (not checked anymore by ComPWA/policy)

---------

Co-authored-by: Smaldanerep1 <[email protected]>
  • Loading branch information
@redeboer @Smaldanerep1
redeboer and Smaldanerep1 authored Jun 21, 2024
1 parent 7dacea5 commit 80bfcdb
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 18 deletions.
4 changes: 3 additions & 1 deletion docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ def install_ijulia() -> None:
"ampform-0.14.x": ("https://ampform.readthedocs.io/0.14.x", None),
"ampform": ("https://ampform.readthedocs.io/stable", None),
"attrs": (f"https://www.attrs.org/en/{pin('attrs')}", None),
"expertsystem": ("https://expertsystem.readthedocs.io/en/stable", None),
"expertsystem": ("https://expertsystem.readthedocs.io/stable", None),
"graphviz": ("https://graphviz.readthedocs.io/en/stable", None),
"hepstats": ("https://scikit-hep.org/hepstats", None),
"IPython": (f"https://ipython.readthedocs.io/en/{pin('IPython')}", None),
Expand Down Expand Up @@ -217,6 +217,8 @@ def install_ijulia() -> None:
"http://127.0.0.1:8000",
"https://atom.io", # often instable
"https://doi.org/10.1002/andp.19955070504", # 403 for onlinelibrary.wiley.com
"https://doi.org/10.1155/2020/6674595", # 403 hindawi.com
"https://downloads.hindawi.com", # 403
"https://github.com/organizations/ComPWA/settings/repository-defaults", # private
"https://github.com/orgs/ComPWA/projects/5", # private
"https://github.com/orgs/ComPWA/projects/6", # private
Expand Down
27 changes: 10 additions & 17 deletions docs/symbolics.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,6 @@
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<!-- no-set-nb-cells -->"
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand Down Expand Up @@ -62,7 +55,7 @@
"We want to quickly formulate a wide range of amplitude models, given the latest theoretical and experimental insights.\n",
":::\n",
"\n",
":::{card} {material-regular}`school` Transparency\n",
":::{card} {material-regular}`local_library` Transparency\n",
":link: transparency\n",
":link-type: ref\n",
"It should be easy to inspect the implemented amplitude models, ideally by using mathematical formulas, so that the analysis can easily be reproduced or compared to results from other experiments, tools, or theoretical models.\n",
Expand Down Expand Up @@ -313,7 +306,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Python offers us flexibility to write concise and understandable code that can be run code interactively through a terminal or with Jupyter Notebooks. As we saw, [array-oriented computational backends](#array-oriented) make this code suitable for high-performance, parallelized computations over large data samples. The fact that array-oriented code looks so similar for different accelerated computational libraries begs the question whether we can find a way to **directly convert the mathematical expressions that we as physicists are familiar with into these fast numerical functions**. It turns out that we can do this using a Computer Algebra System."
"Python offers us flexibility to write concise and understandable code that can be run interactively through a terminal or with Jupyter Notebooks. As we saw, [array-oriented computational backends](#array-oriented) make this code suitable for high-performance, parallelized computations over large data samples. The fact that array-oriented code looks so similar for different accelerated computational libraries begs the question whether we can find a way to **directly convert the mathematical expressions that we as physicists are familiar with into these fast numerical functions**. It turns out that we can do this using a Computer Algebra System."
]
},
{
Expand All @@ -327,7 +320,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Programs like [Mathematica](https://www.wolfram.com/mathematica), [Maple](https://www.maplesoft.com/products/Maple) and [Matlab](https://www.mathworks.com/products/matlab.html) are popular examples for mathematics, physicists, and engineers, as they allow to simplify expression, solve equations or integrals, investigate their behavior with plots, et cetera. At core, these programs are [Computer Algebra Systems](https://en.wikipedia.org/wiki/List_of_computer_algebra_systems) (CAS) that represent mathematical expressions as graphs or trees and transform and modify them through algorithms that implement algebraic operations.\n",
"Programs like [Mathematica](https://www.wolfram.com/mathematica), [Maple](https://www.maplesoft.com/products/Maple) and [Matlab](https://www.mathworks.com/products/matlab.html) are popular examples for mathematics, physicists, and engineers, as they allow to simplify expressions, solve equations or integrals, investigate their behavior with plots, et cetera. At their core, these programs are [Computer Algebra Systems](https://en.wikipedia.org/wiki/List_of_computer_algebra_systems) (CAS) that represent mathematical expressions as graphs or trees and transform and modify them through algorithms that implement algebraic operations.\n",
"\n",
"The most commonly used CAS in Python is [SymPy](https://docs.sympy.org) and it has a major advantage over commercial CAS programs in that it is [open source and can be used as a library](https://docs.sympy.org/latest/tutorials/intro-tutorial/intro.html#why-sympy). This allows us to integrate it into our own applications for amplitude analysis or build up simple mathematical expressions in Jupyter notebooks, so that we can inspect them in $\\LaTeX$ form. For example, a simple Breit-Wigner function is written as:"
]
Expand All @@ -350,7 +343,7 @@
"metadata": {},
"source": [
":::{note}\n",
"SymPy orders symbolic terms [its own way](https://stackoverflow.com/a/36344627) if they are commutative, independent on the Python code given by the user.\n",
"SymPy orders symbolic terms [its own way](https://stackoverflow.com/a/36344627) if they are commutative, independent of the Python code given by the user.\n",
":::"
]
},
Expand Down Expand Up @@ -620,7 +613,7 @@
"tags": []
},
"source": [
"The example as described here is small for illustrative purposes. It turns out that code generation works just as well for **expressions with a much larger number of mathematical operations**, even if in the order of hundreds of thousands. This is exactly what is needed for fitting amplitude models to data.\n",
"The example as described here is small for illustrative purposes. It turns out that code generation works just as well for **expressions with a much larger number of mathematical operations**, even if in the order of hundreds of thousands (see e.g. the [`tensorwaves` amplitude analysis example](https://tensorwaves.readthedocs.io/stable/amplitude-analysis/)). This is exactly what is needed for fitting amplitude models to data.\n",
"\n",
"We now have a flexible and transparent way of formulating amplitude models that can be easily modified with algebraic operations. The models can immediately be inspected as mathematical expressions and can be used as template for generating array-oriented numerical functions for efficient computations over large data samples. In addition, any algebraic operations that simplify the expression tree directly map onto the generated array-oriented code, which can result in better numerical performance of the generated code."
]
Expand All @@ -645,14 +638,14 @@
},
"source": [
"(transparency)=\n",
"## {material-regular}`school` Transparency"
"## {material-regular}`local_library` Transparency"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We have seen how a Computer Algebra System that generates array-oriented code allows us to formulate [performant](#performance) and [flexible](#flexibility) amplitude models. Physicists can now focus on implementing theory in a central place, while the computations are outsourced to optimized libraries. In itself, these are ingredients that make it much easier to write analysis code. However, the set-up offers major indirect benefits to the wider amplitude analysis community as well."
"We have seen how a Computer Algebra System that generates array-oriented code allows us to formulate [performant](#performance) and [flexible](#flexibility) amplitude models. Physicists can now focus on implementing theory in a central place, while the computations are outsourced to optimized libraries. In itself, these are ingredients that make it much easier to write analysis code. We will see that the set-up offers major indirect benefits to the wider amplitude analysis community as well: it makes it easier to inspect, share, and explain amplitude models."
]
},
{
Expand All @@ -666,7 +659,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The combination of a CAS, performant code generation, and a dynamically typed language like Python is ideal when working with Jupyter notebooks. Amplitude models can be built up interactively with the option to directly inspect their implementation as mathematical formulas or plot their behavior with visualization libraries. Fast, numerical performance is near at hand through automatic code generation, which bridges the gab between formulating amplitude models to performing fits.\n",
"The combination of a CAS, performant code generation, and a dynamically typed language like Python is ideal when working with Jupyter notebooks. Amplitude models can be built up interactively with the option to directly inspect their implementation as mathematical formulas or plot their behavior with visualization libraries. Fast, numerical performance is near at hand through automatic code generation, which bridges the gap between formulating amplitude models to performing fits.\n",
"\n",
"This ties in perfectly with recent trends in data science and modern publishing tools. In recent years, there have been several initiatives that render Jupyter notebooks as publication-ready documents (websites, PDF files, etc.). Community-wide examples are the [Executable Book Project](https://executablebooks.org), [Curvenote](https://curvenote.com), and [Quarto](https://quarto.org), while CERN has launched platforms like [SWAN](https://swan.docs.cern.ch) for running notebooks with direct access to CERN computing resources and [Reana](https://www.reanahub.io) for making analyses more reproducible and scalable.\n",
"\n",
Expand All @@ -692,9 +685,9 @@
"\n",
"First of all, the [self-documenting workflow](#self-documenting-workflow) with symbolic expressions removes the need for readers to dive through the underlying code, as the formulas are directly visible to the reader. Mathematics is the language we all speak. This easily allows others to reimplement models into their own framework of choice, now or in the future, in e.g. new programming languages.\n",
"\n",
"Second, a symbolic amplitude model can be serialized to human-readable format with [code generation](#code-generation). Just as with the generation of numerical functions, the model's [expression tree](#expression-trees) can be used to generate nodes in a serialization format like YAML or JSON. Other analysis frameworks can then import the model for cross-checks or for adapting the analysis to other experiments.\n",
"Second, [code generation](#code-generation) makes it possible to serialize symbolic amplitude models to human-readable format for preservation on disk or sharing with others. For example, just as with the generation of numerical functions, the model's [expression tree](#expression-trees) can be used to generate nodes in a serialization format like YAML or JSON. Other analysis frameworks can then import the model for cross-checks or for adapting the analysis to other experiments.\n",
"\n",
"On a technical note, the Python ecosystem in combination with Jupyter Notebooks and Sphinx makes it possible for any reader to directly rerun analysis in the browser or in some local environment. [Pinned dependencies](https://github.com/ComPWA/update-pip-constraints) ensure that the analysis produces the same results."
"On a technical note, the Python ecosystem in combination with Jupyter Notebooks and [Sphinx](https://www.sphinx-doc.org) (a documentation builder) makes it possible for any reader to directly rerun analysis in the browser or in some local environment. [Pinned dependencies](https://github.com/ComPWA/update-pip-constraints) ensure that the analysis produces the same results."
]
},
{
Expand Down

0 comments on commit 80bfcdb

Please sign in to comment.