Documentation: new figure for the AT coordinate system (#876)

* Added a figure for the coordinate system
* PDF figure for the PDF documentation

Author: lfarv

docs/common/indx.rst

@@ -5,25 +5,36 @@ The Accelerator Toolbox is based on a fast and modular tracking engine.
 
 Coordinate system
 -----------------
-AT runs in 6 dimensions using the following coordinate system:
+The AT coordinate system is based on a design trajectory along which the magnetic
+elements are aligned, and a reference particle:
+
+.. image:: /images/coord_system.*
+   :alt: coordinate system
+   :align: center
+
+By convention, the reference particle travels along the design trajectory at constant
+nominal energy and defines the phase origin of the RF voltage.
+
+The 6-d coordinate vector :math:`\vec Z` is:
 
 .. math::
 
    \vec Z =
    \begin{pmatrix}
-   x \\ p_x \\
-   y \\ p_y \\
+   x \\ p_x/p_0 \\
+   y \\ p_y/p_0 \\
    \delta \\ \beta c\tau
    \end{pmatrix}
 
+:math:`p_0` is the nominal momentum,
+
+:math:`\delta=\dfrac{p-p_0}{p_0}` is the relative momentum deviation.
+
 AT works with relative path lengths: the 6\ :sup:`th` coordinate :math:`\beta c\tau`
 represents the path lengthening with respect to the reference particle. :math:`\tau`
 is the delay with respect to the reference particle: the particle is late for
 :math:`\tau > 0`.
 
-The reference particle is conventionally a particle travelling on the reference orbit
-at constant nominal energy and crossing the RF cavities at their 0 voltage.
-
 Tracking
 --------
 All the AT processing is based on tracking. For instance, linear optics properties

docs/conf.py

@@ -87,6 +87,7 @@
 # -- Options for the myst markdown parser ------------------------------------
 
 myst_enable_extensions = [
+    "attrs_inline",
     "colon_fence",
     "dollarmath",
     "replacements",

docs/images/coord_system.pdf

@@ -32,16 +32,29 @@
     "charged particle beam simulation. It was created by Andrei Terebilo in\n",
     "the late 1990’s. The original papers[^at1][^at2] still serve as a good introduction to AT. The AT described in those papers is AT1.3, the latest version produced by Terebilo. The next version of AT is considered AT2.0[^nash]. Here we provide examples showing some of the changes from AT1.3, but also serving as an introduction for someone just starting AT.\n",
     "\n",
-    "### Coordinates\n",
+    "### AT Coordinate system\n",
     "\n",
-    "The 6-d phase space coordinates used in AT are as follows:\n",
+    "The AT coordinate system is based on a design trajectory along which the magnetic elements are aligned,\n",
+    "and a reference particle:\n",
+    "\n",
+    "```{image} /images/coord_system.*\n",
+    ":alt: coordinate system\n",
+    ":align: center\n",
+    "```\n",
+    "\n",
+    "By convention, the reference particle travels along the design trajectory at constant nominal energy and defines the phase origin of the RF voltage.\n",
+    "\n",
+    "The 6-d coordinate vector $\\vec Z$ is:\n",
     "\n",
     "$$\n",
-    "\\vec Z = \\begin{pmatrix} x \\\\ \\frac{p_x}{p_0} \\simeq x'(1+\\delta) \\\\ y \\\\ \\frac{p_y}{p_0} \\simeq y'(1+\\delta) \\\\ \\delta=\\frac{\\left(p-p_0\\right)}{p_0} \\\\ \\beta c \\tau\\end{pmatrix}\n",
+    "\\vec Z = \\begin{pmatrix} x \\\\ \\dfrac{p_x}{p_0} \\approx x'(1+\\delta) \\\\ y \\\\ \\dfrac{p_y}{p_0} \\approx y'(1+\\delta) \\\\ \\delta=\\dfrac{p-p_0}{p_0} \\\\ \\beta c \\tau\\end{pmatrix}\n",
     "$$\n",
     "\n",
-    "$p_0$ is the reference momentum. $\\tau$ is the\n",
-    "time lag relative to the ideal particle."
+    "$p_0$ is the reference momentum.\n",
+    "\n",
+    "AT works with relative path lengths: the 6{sup}`th` coordinate $\\beta c\\tau$ represents\n",
+    "the path lengthening with respect to the reference particle. $\\tau$ is the delay with\n",
+    "respect to the reference particle: the particle is late for $\\tau > 0$.\n"
    ]
   },
   {
@@ -1760,7 +1773,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.10"
+   "version": "3.9.21"
   },
   "toc-autonumbering": false,
   "toc-showcode": false,