From 8deee77fdbf06432fc06a62432643196ed6636c4 Mon Sep 17 00:00:00 2001 From: Remco de Boer Date: Fri, 16 Apr 2021 13:02:07 +0200 Subject: [PATCH] docs: reread and fix documentation --- README.md | 2 +- docs/index.md | 49 +++++++++++++++++++++++--------------- docs/install.md | 43 +++++++++++++++++++++++---------- docs/usage.ipynb | 9 ++++--- docs/usage/particle.ipynb | 2 +- docs/usage/reaction.ipynb | 6 ++--- docs/usage/visualize.ipynb | 2 +- 7 files changed, 70 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index a1689622..341c941d 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ For an overview of **upcoming releases and planned functionality**, see [here](https://github.com/ComPWA/qrules/milestones?direction=asc&sort=title&state=open). QRules originates from the -[`expertsystem`](https://pypi.org/project/expertsystem) +[`expertsystem`](https://pypi.org/project/expertsystem). ## Available features diff --git a/docs/index.md b/docs/index.md index 2da252c3..6e83de7b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,13 +17,15 @@ QRules originates from its {mod}`~expertsystem.reaction` module. ::: QRules is a system for validating and generating particle reactions, using -quantum number conservation rules. The user only has to provide a basic -information of the particle reaction, such as an initial state and a final -state. Helper functions provide easy ways to configure the system, but the user -still has full control. QRules then constructs several hypotheses for what -happens during the transition from initial to final state. +quantum number conservation rules. The user only has to provide some basic +information about the particle reaction, such as an initial state and a final +state. -The {doc}`usage` pages illustrate some of the cool features of {mod}`qrules`. +Helper functions provide easy and quick ways to configure the system. QRules +then constructs several hypotheses for what happens during the transition from +initial to final state. + +The {doc}`/usage` pages illustrate some of the cool features of {mod}`qrules`. You can run each of them as Jupyter notebooks with the {fa}`rocket` launch button in the top-right corner. Enjoy! @@ -38,14 +40,15 @@ QRules consists of three major components: A {class}`.StateTransitionGraph` is a [directed graph](https://en.wikipedia.org/wiki/Directed_graph) that consists of **nodes** and **edges**. In a directed graph, each edge must be connected - to at least one node (in correspondence to Feynman graphs). This way, a - graph describes the transition from one state to another. + to at least one node (in correspondence to + [Feynman graphs](https://en.wikipedia.org/wiki/Feynman_diagram)). This way, + a graph describes the transition from one state to another. - - The edges correspond to particles/states, in other words a collection of - properties such as the quantum numbers that characterize the particle - state. + - **Edges** correspond to states (particles with spin). In other words, + edges are a collection of properties such as the quantum numbers that + characterize a state that the particle is in. - - Each node represents an interaction and contains all information for the + - **Nodes** represents interactions and contain all information for the transition of this specific step. Most importantly, a node contains a collection of conservation rules that have to be satisfied. An interaction node has $M$ ingoing lines and $N$ outgoing lines, where @@ -53,11 +56,10 @@ QRules consists of three major components: 2. **Conservation rules** - The central component are the - {mod}`conservation rules <.conservation_rules>`. They belong to individual - nodes and receive properties about the node itself, as well as properties of - the ingoing and outgoing edges of that node. Based on those properties the - conservation rules determine whether edges pass or not. + The central component are the {mod}`.conservation_rules`. They belong to + individual nodes and receive properties about the node itself, as well as + properties of the ingoing and outgoing edges of that node. Based on those + properties the conservation rules determine whether edges pass or not. 3. **Solvers** @@ -65,6 +67,15 @@ QRules consists of three major components: solvers. New properties are set for intermediate edges and interaction nodes and their validity is checked with the conservation rules. +:::{margin} + +The main solver used by {mod}`qrules` is the +[`constraint`](https://labix.org/doc/constraint) package for the +[Constraint Satisfaction Problem](https://en.wikipedia.org/wiki/Constraint_satisfaction_problem) +(CSP). + +::: + ```{rubric} QRules workflow ``` @@ -72,8 +83,8 @@ QRules consists of three major components: 1. **Preparation** 1.1. Build all possible topologies. A **topology** is represented by a - {ref}`graph `, in which the edges and - nodes are empty (no particle information). + {class}`.StateTransitionGraph`, in which the edges and nodes are empty (no + particle information). 1.2. Fill the topology graphs with the user provided information. Typically these are the graph's ingoing edges (initial state) and outgoing edges diff --git a/docs/install.md b/docs/install.md index f43d954e..a1794639 100644 --- a/docs/install.md +++ b/docs/install.md @@ -8,19 +8,30 @@ python3 -m pip install qrules This installs the [latest, stable release](https://pypi.org/project/qrules) that you can find on the -[`stable`](https://github.com/ComPWA/qrules/tree/stable) branch. The latest -version on the [`main`](https://github.com/ComPWA/qrules/tree/main) branch can -be installed as follows: +[`stable`](https://github.com/ComPWA/qrules/tree/stable) branch. + +The latest version on the [`main`](https://github.com/ComPWA/qrules/tree/main) +branch can be installed as follows: ```shell python3 -m pip install git+https://github.com/ComPWA/qrules@main ``` -In that case, however, we highly recommend using the more dynamic, +In that case, however, we highly recommend using the more dynamic {ref}`'editable installation' ` instead. This goes as follows: -1. Get the source code (see {doc}`pwa:software/git`): +:::{margin} + +```{seealso} + +{doc}`pwa:software/git` + +``` + +::: + +1. Get the source code: ```shell git clone https://github.com/ComPWA/qrules.git @@ -30,16 +41,16 @@ This goes as follows: 2. **[Recommended]** Create a virtual environment (see {ref}`here `). -3. Install the project in - {ref}`'editable installation' `, as well - as {ref}`optional dependencies ` for the - developer: +3. Install the project as an + {ref}`'editable installation' ` and + install {ref}`additional packages ` for + the developer: ```shell python3 -m pip install -e .[dev] ``` - :::{dropdown} Pinning dependencies + :::{dropdown} Pinning dependency versions In order to install the _exact same versions_ of the dependencies with which the framework has been tested, use the provided @@ -50,8 +61,14 @@ This goes as follows: python3 -m pip install -c .constraints/py3.x.txt -e .[dev] ``` + ```{seealso} + + {ref}`develop:Pinning dependency versions` + + ``` + ::: -That's all! Have a look at the {doc}`/usage` page to try out the package, and -see {doc}`pwa:develop` for tips on how to work with this 'editable' developer -setup! +That's all! Have a look at the {doc}`/usage` page to try out the package. You +can also have a look at the {doc}`pwa:develop` page for tips on how to work +with this 'editable' developer setup! diff --git a/docs/usage.ipynb b/docs/usage.ipynb index 7e2c10ba..c41457e1 100644 --- a/docs/usage.ipynb +++ b/docs/usage.ipynb @@ -58,7 +58,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Here's a small example of how to use {mod}`qrules`!" + "Here are some quick examples of how to use {mod}`qrules`. For more fine-grained control, have a look at {ref}`usage:Advanced`." ] }, { @@ -113,7 +113,7 @@ "source": [ ":::{seealso}\n", "\n", - "{doc}`usage/reaction` and {doc}`usage/amplitude`\n", + "{doc}`/usage/reaction` and {doc}`ampform:usage/amplitude`\n", "\n", ":::" ] @@ -152,9 +152,8 @@ "import qrules as q\n", "\n", "pdg = q.load_pdg()\n", - "pdg.find(22)\n", - "delta = pdg.find(\"Delta(1920)++\")\n", - "q.io.asdict(delta)" + "pdg.find(22) # by pid\n", + "pdg.find(\"Delta(1920)++\")" ] }, { diff --git a/docs/usage/particle.ipynb b/docs/usage/particle.ipynb index de5d4904..8fc54278 100644 --- a/docs/usage/particle.ipynb +++ b/docs/usage/particle.ipynb @@ -57,7 +57,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "In {doc}`reaction`, we made use of the {class}`.StateTransitionManager`. By default, if you do not specify the `particle_db` argument, the {class}`.StateTransitionManager` calls the function {func}`.load_default_particles`. This functions returns a {class}`.ParticleCollection` instance with {class}`.Particle` definitions from the [PDG](https://pdg.lbl.gov), along with additional definitions that are provided in the file {download}`additional_definitions.yml <../../src/qrules/additional_definitions.yml>`.\n", + "In {doc}`/usage/reaction`, we made use of the {class}`.StateTransitionManager`. By default, if you do not specify the `particle_db` argument, the {class}`.StateTransitionManager` calls the function {func}`.load_default_particles`. This functions returns a {class}`.ParticleCollection` instance with {class}`.Particle` definitions from the [PDG](https://pdg.lbl.gov), along with additional definitions that are provided in the file {download}`additional_definitions.yml <../../src/qrules/additional_definitions.yml>`.\n", "\n", "Here, we call this method directly to illustrate what happens (we use {func}`.load_pdg`, which loads a subset):" ] diff --git a/docs/usage/reaction.ipynb b/docs/usage/reaction.ipynb index 1897de9a..47c2859f 100644 --- a/docs/usage/reaction.ipynb +++ b/docs/usage/reaction.ipynb @@ -47,7 +47,7 @@ "\n", "The [‘expert system’](https://en.wikipedia.org/wiki/Expert_system) is responsible to give you advice on the form of an amplitude model, based on the problem set you define (initial state, final state, allowed interactions, intermediate states, etc.). Internally, the system propagates the quantum numbers through the reaction graph while satisfying the specified conservation rules. How to control this procedure is explained in more detail below.\n", "\n", - "Afterwards, the amplitude model of the expert system can be exported into [Tensorwaves](https://pwa.readthedocs.io/projects/tensorwaves). The model can for instance be used to generate a data set (toy Monte Carlo) for this reaction and to optimize its parameters to resemble an actual data set as good as possible. For more info on that see {doc}`expertsystem:usage/amplitude`." + "Afterwards, the amplitude model of the expert system can be exported into [Tensorwaves](https://pwa.readthedocs.io/projects/tensorwaves). The model can for instance be used to generate a data set (toy Monte Carlo) for this reaction and to optimize its parameters to resemble an actual data set as good as possible. For more info on that see {doc}`ampform:usage/amplitude`." ] }, { @@ -424,7 +424,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Handy if it takes a lot of computation time to generate the transitions!" + "Handy if it takes a lot of computation time to re-generate the transitions!" ] }, { @@ -441,7 +441,7 @@ "metadata": {}, "source": [ "```{tip}\n", - "The {mod}`ampform` package can formulate amplitude models based on the state transitions created by {mod}`qrules`.\n", + "The {mod}`ampform` package can formulate amplitude models based on the state transitions created by {mod}`qrules`. See {doc}`ampform:usage/amplitude`.\n", "```" ] } diff --git a/docs/usage/visualize.ipynb b/docs/usage/visualize.ipynb index 001c2260..7b5de13b 100644 --- a/docs/usage/visualize.ipynb +++ b/docs/usage/visualize.ipynb @@ -43,7 +43,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The {mod}`~qrules.io` module allows you to convert {class}`.StateTransitionGraph` and {class}`.Topology` instances to [DOT language](https://graphviz.org/doc/info/lang.html) with {func}`.asdot`. You can visualize its output with third-party libraries, such as [Graphviz](https://graphviz.org). This is particularly useful after running {meth}`~.StateTransitionManager.find_solutions`, which produces a {class}`.Result` object with a {class}`.list` of {class}`.StateTransitionGraph` instances (see {doc}`reaction`)." + "The {mod}`~qrules.io` module allows you to convert {class}`.StateTransitionGraph` and {class}`.Topology` instances to [DOT language](https://graphviz.org/doc/info/lang.html) with {func}`.asdot`. You can visualize its output with third-party libraries, such as [Graphviz](https://graphviz.org). This is particularly useful after running {meth}`~.StateTransitionManager.find_solutions`, which produces a {class}`.Result` object with a {class}`.list` of {class}`.StateTransitionGraph` instances (see {doc}`/usage/reaction`)." ] }, {