Skip to content

Commit 1fac2c9

Browse files
authored
DOC: reorganize tutorial pages (#497)
* DOC: group amplitude nodebooks * DOC: group analyticity notebooks * DOC: improve landing page * DOC: merge `usage` into `index` * DOC: move phase space factor widget to separate notebook * DOC: update installation page * MAINT: remove ADR template
1 parent d596d3e commit 1fac2c9

37 files changed

Lines changed: 518 additions & 511 deletions

.cspell.json

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,6 @@
4242
"Dalitzplot",
4343
"Minkowski",
4444
"PYDEVD",
45-
"adrs",
4645
"aitchison",
4746
"arange",
4847
"arccos",
@@ -90,7 +89,6 @@
9089
"eqnarray",
9190
"eval",
9291
"evalf",
93-
"expertsystem",
9492
"facecolor",
9593
"figsize",
9694
"filterwarnings",
@@ -279,6 +277,7 @@
279277
"nishijima",
280278
"numpy",
281279
"parametrizations",
280+
"parametrizing",
282281
"permutate",
283282
"pydocstyle",
284283
"PyPA",

README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,17 +40,17 @@ an overview of **upcoming releases and planned functionality**, see
4040
_mathematically expressed_ with [SymPy](https://docs.sympy.org) and can be _converted
4141
to any backend_ (see [TensorWaves](https://tensorwaves.rtfd.io)).
4242
- **Spin formalisms**
43-
- [Helicity formalism](https://ampform.readthedocs.io/en/stable/usage/helicity/formalism.html)
43+
- [Helicity formalism](https://ampform.readthedocs.io/en/stable/amplitude/formalism.html)
4444
- Canonical formalism
45-
- [Spin alignment](https://ampform.readthedocs.io/en/stable/usage/helicity/spin-alignment.html)
45+
- [Spin alignment](https://ampform.readthedocs.io/en/stable/amplitude/spin-alignment.html)
4646
for generic, multi-body decays that feature different decay topologies. **See also [`ampform-dpd`](https://github.com/ComPWA/ampform-dpd)!**
4747
- **Dynamics**
4848
- [Relativistic Breit–Wigner](https://ampform.readthedocs.io/en/stable/api/ampform.dynamics.html#ampform.dynamics.relativistic_breit_wigner_with_ff),
4949
optionally with form factors and/or
5050
[energy-dependent width](https://ampform.readthedocs.io/en/stable/api/ampform.dynamics.html#ampform.dynamics.EnergyDependentWidth)
51-
- [Symbolic _K_-matrix](https://ampform.readthedocs.io/en/stable/usage/dynamics/k-matrix.html#non-relativistic-k-matrix)
51+
- [Symbolic _K_-matrix](https://ampform.readthedocs.io/en/stable/dynamics/k-matrix.html#non-relativistic-k-matrix)
5252
for an arbitrary number of poles and channels
53-
- [Symbolic _P_-vector](https://ampform.readthedocs.io/en/stable/usage/dynamics/k-matrix.html#p-vector)
53+
- [Symbolic _P_-vector](https://ampform.readthedocs.io/en/stable/dynamics/k-matrix.html#p-vector)
5454
for an arbitrary number of poles and channels
5555
- Chew–Mandelstam dispersion integral for a correct treatment of analyticity in the presence of thresholds.
5656

docs/.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
*.doctree
2+
*.gif
23
*.inv
34
*build/
45
_images/*
56
api/
67

78
!_static/*
8-
!usage/additional_particles.yml
9+
!additional_particles.yml

docs/adr/template.md

Lines changed: 0 additions & 116 deletions
This file was deleted.
Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@
133133
"cell_type": "markdown",
134134
"metadata": {},
135135
"source": [
136-
":::{seealso} {doc}`/usage/helicity/formalism`\n",
136+
":::{seealso} {doc}`amplitude/formalism`\n",
137137
"\n",
138138
":::"
139139
]
@@ -153,7 +153,7 @@
153153
"\n",
154154
":::{margin}\n",
155155
"\n",
156-
"As can be seen in {ref}`usage/amplitude:Generate transitions`, the transition that this {class}`.HelicityModel` describes features only one decay topology. This means that the main {attr}`~.HelicityModel.intensity` expression is relatively simple. In case there are more decay topologies, AmpForm {doc}`aligns spin </usage/helicity/spin-alignment>`, which makes the main intensity expression more complicated.\n",
156+
"As can be seen in {ref}`amplitude:Generate transitions`, the transition that this {class}`.HelicityModel` describes features only one decay topology. This means that the main {attr}`~.HelicityModel.intensity` expression is relatively simple. In case there are more decay topologies, AmpForm {doc}`aligns spin <amplitude/spin-alignment>`, which makes the main intensity expression more complicated.\n",
157157
"\n",
158158
":::"
159159
]
@@ -494,7 +494,7 @@
494494
"cell_type": "markdown",
495495
"metadata": {},
496496
"source": [
497-
"To set dynamics for specific resonances, use {meth}`.DynamicsSelector.assign` on the same {attr}`.HelicityAmplitudeBuilder.dynamics` attribute. You can set the dynamics to be any kind of {class}`~sympy.core.expr.Expr`, as long as you keep track of which {class}`~sympy.core.symbol.Symbol` names you use (see {doc}`/usage/dynamics/custom`).\n",
497+
"To set dynamics for specific resonances, use {meth}`.DynamicsSelector.assign` on the same {attr}`.HelicityAmplitudeBuilder.dynamics` attribute. You can set the dynamics to be any kind of {class}`~sympy.core.expr.Expr`, as long as you keep track of which {class}`~sympy.core.symbol.Symbol` names you use (see {doc}`dynamics/custom`).\n",
498498
"\n",
499499
"AmpForm does provide a few common {mod}`.dynamics` functions, which can be constructed as {class}`~sympy.core.expr.Expr` with the correct {class}`~sympy.core.symbol.Symbol` names using {meth}`.DynamicsSelector.assign`. This function takes specific {mod}`.dynamics.builder` functions and classes, such as {class}`.RelativisticBreitWignerBuilder`, which can create {func}`.relativistic_breit_wigner` functions for specific resonances. Here's an example for a relativistic Breit–Wigner _with form factor_ for the intermediate resonances and use a Blatt–Weisskopf barrier factor for the production decay:"
500500
]
@@ -521,15 +521,15 @@
521521
"cell_type": "markdown",
522522
"metadata": {},
523523
"source": [
524-
"Note that this {class}`.RelativisticBreitWignerBuilder` can also be initialized with a different {class}`.PhaseSpaceFactorProtocol`. This allows us to insert different phase space factors (see {doc}`/usage/dynamics/analytic-continuation` and {func}`.create_analytic_breit_wigner`)."
524+
"Note that this {class}`.RelativisticBreitWignerBuilder` can also be initialized with a different {class}`.PhaseSpaceFactorProtocol`. This allows us to insert different phase space factors (see {doc}`analyticity/phasespace-factors` and {func}`.create_analytic_breit_wigner`)."
525525
]
526526
},
527527
{
528528
"cell_type": "markdown",
529529
"metadata": {},
530530
"source": [
531531
"```{seealso}\n",
532-
"{doc}`/usage/dynamics/custom`\n",
532+
"{doc}`dynamics/custom`\n",
533533
"```"
534534
]
535535
},
@@ -839,7 +839,7 @@
839839
"metadata": {},
840840
"source": [
841841
"```{tip}\n",
842-
"See {doc}`/usage/interactive` for a much more didactic way to visualize the model!\n",
842+
"See {doc}`amplitude/interactive` for a much more didactic way to visualize the model!\n",
843843
"```"
844844
]
845845
},
@@ -914,7 +914,7 @@
914914
"cell_type": "markdown",
915915
"metadata": {},
916916
"source": [
917-
"By now we are only left with the masses of the final state particles ($m_1$ and $m_2$), since they appear as symbols in the {func}`.relativistic_breit_wigner_with_ff`. Final state particles 3 and 4 are the $\\pi^0$'s, so we can just substitute them with their masses. (Alternatively, see {ref}`usage/amplitude:Scalar masses`.)"
917+
"By now we are only left with the masses of the final state particles ($m_1$ and $m_2$), since they appear as symbols in the {func}`.relativistic_breit_wigner_with_ff`. Final state particles 3 and 4 are the $\\pi^0$'s, so we can just substitute them with their masses. (Alternatively, see {ref}`amplitude:Scalar masses`.)"
918918
]
919919
},
920920
{
@@ -1029,6 +1029,20 @@
10291029
"rounded = round_nested(plotted_intensity)\n",
10301030
"round_nested(rounded)"
10311031
]
1032+
},
1033+
{
1034+
"cell_type": "markdown",
1035+
"metadata": {},
1036+
"source": [
1037+
"```{toctree}\n",
1038+
":hidden:\n",
1039+
"amplitude/modify\n",
1040+
"amplitude/formalism\n",
1041+
"amplitude/symmetrization\n",
1042+
"amplitude/spin-alignment\n",
1043+
"amplitude/interactive\n",
1044+
"```"
1045+
]
10321046
}
10331047
],
10341048
"metadata": {
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@
9090
"source": [
9191
":::{margin}\n",
9292
"\n",
93-
"{ref}`usage/helicity/formalism:Coefficient names` shows how to generate different coefficient names.\n",
93+
"{ref}`amplitude/formalism:Coefficient names` shows how to generate different coefficient names.\n",
9494
"\n",
9595
":::\n",
9696
"\n",
Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040
"cell_type": "markdown",
4141
"metadata": {},
4242
"source": [
43-
"First, we create some {class}`.HelicityModel`. We could also have used {mod}`pickle` to {func}`~pickle.load` the {class}`.HelicityModel` that we created in {doc}`/usage/amplitude`, but the cell below allows running this notebook independently."
43+
"First, we create some {class}`.HelicityModel`. We could also have used {mod}`pickle` to {func}`~pickle.load` the {class}`.HelicityModel` that we created in {doc}`/amplitude`, but the cell below allows running this notebook independently."
4444
]
4545
},
4646
{
@@ -82,7 +82,7 @@
8282
"cell_type": "markdown",
8383
"metadata": {},
8484
"source": [
85-
"In this case, {ref}`as we saw <usage/amplitude:Mathematical formula>`, the overall model contains just one intensity term $I = |\\sum_i A_i|^2$, with $\\sum_i A_i$ some coherent sum of amplitudes. We can extract $\\sum_i A_i$ as follows:"
85+
"In this case, {ref}`as we saw <amplitude:Mathematical formula>`, the overall model contains just one intensity term $I = |\\sum_i A_i|^2$, with $\\sum_i A_i$ some coherent sum of amplitudes. We can extract $\\sum_i A_i$ as follows:"
8686
]
8787
},
8888
{
@@ -355,7 +355,7 @@
355355
"source": [
356356
":::{tip}\n",
357357
"\n",
358-
"See {doc}`/usage/dynamics/k-matrix` for why $\\boldsymbol{K}$-matrix dynamics are better than simple Breit–Wigners when resonances are close to each other.\n",
358+
"See {doc}`/dynamics/k-matrix` for why $\\boldsymbol{K}$-matrix dynamics are better than simple Breit–Wigners when resonances are close to each other.\n",
359359
"\n",
360360
":::"
361361
]
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@
4747
"cell_type": "markdown",
4848
"metadata": {},
4949
"source": [
50-
"As described in {doc}`compwa-report:015/index`, the {doc}`'standard' helicity formalism </usage/helicity/formalism>` is not suited for state transitions that have different decay topologies. For this reason, the {class}`.HelicityAmplitudeBuilder` can insert a number of Wigner-$D$ functions into the amplitude model to 'align' the final state spins of underlying {class}`~qrules.topology.Topology` instances in the full decay.\n",
50+
"As described in {doc}`compwa-report:015/index`, the {doc}`'standard' helicity formalism <formalism>` is not suited for state transitions that have different decay topologies. For this reason, the {class}`.HelicityAmplitudeBuilder` can insert a number of Wigner-$D$ functions into the amplitude model to 'align' the final state spins of underlying {class}`~qrules.topology.Topology` instances in the full decay.\n",
5151
"\n",
5252
"Imagine we have the following the decay:"
5353
]

0 commit comments

Comments
 (0)