From 80bfcdb33412b96e046df14146d93261aac74d72 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Fri, 21 Jun 2024 14:06:04 +0200 Subject: [PATCH] DOC: address feedback to symbolics explainer (#281) * 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 <158560909+Smaldanerep1@users.noreply.github.com> --- docs/conf.py | 4 +++- docs/symbolics.ipynb | 27 ++++++++++----------------- 2 files changed, 13 insertions(+), 18 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 9357a3c2..8b3da5f3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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), @@ -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 diff --git a/docs/symbolics.ipynb b/docs/symbolics.ipynb index 916669ac..c1252ed0 100644 --- a/docs/symbolics.ipynb +++ b/docs/symbolics.ipynb @@ -8,13 +8,6 @@ "```" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "" - ] - }, { "cell_type": "markdown", "metadata": {}, @@ -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", @@ -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." ] }, { @@ -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:" ] @@ -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", ":::" ] }, @@ -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." ] @@ -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." ] }, { @@ -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", @@ -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." ] }, {