Doc: TaperedPL Details

Add more details to the documentation.

Author: ax3l

docs/source/usage/python.rst

@@ -918,7 +918,13 @@ This module provides elements for the accelerator lattice.
 
 .. py:class:: impactx.elements.TaperedPL(k, taper, units, dx=0, dy=0, rotation=0)
 
-   A thin nonlinear plasma lens with transverse taper.
+   A thin nonlinear plasma lens with transverse (horizontal) taper
+
+   .. math::
+
+      B_x = g \left( y + \frac{xy}{D_x} \right), \quad \quad B_y = -g \left(x + \frac{x^2 + y^2}{2 D_x} \right)
+
+   where :math:`g` is the (linear) field gradient in T/m and :math:`D_x` is the targeted horizontal dispersion in m.
 
    :param k:  integrated focusing strength in m^(-1) (if units = 0)
               = (length in m) * (azimuthal magnetic field gradient in T/m) / (rigidity in T-m)

examples/achromatic_spectrometer/README.rst

@@ -4,14 +4,22 @@ Achromatic Spectrometer
 =======================
 
 A spectrometer beamline using a bending dipole.
-A transversely-tapered plasma lens is added for chromatic correction.
+A :py:class:`transversely-tapered plasma lens <impactx.elements.TaperedPL>` is added for chromatic correction.
 The tapered plasma lens design is based on:
 
 C. A. Lindstrom, presentation at the EuroNNAc Special Topics Workshop 2022, `slides <https://agenda.infn.it/event/28376/contributions/178724/attachments/96899/133588/Lindstr%C3%B8m,%20EuroNNAc%20workshop,%2022%20Sep%202022.pdf>`__
 "Solutions and challenges for a multi-stage plasma accelerator",
 
 https://agenda.infn.it/event/28376/contributions/178724/attachments/96899/133588/Lindstr%C3%B8m,%20EuroNNAc%20workshop,%2022%20Sep%202022.pdf
 
+with a transverse (horizontal) taper
+
+.. math::
+
+   B_x = g \left( y + \frac{xy}{D_x} \right), \quad \quad B_y = -g \left(x + \frac{x^2 + y^2}{2 D_x} \right)
+
+where :math:`g` is the (linear) field gradient in T/m and :math:`D_x` is the targeted horizontal dispersion in m.
+
 We use a 1 GeV electron beam with initial normalized rms emittance of 2 microns and 2% rms relative energy spread.
 
 In this test, the initial and final values of :math:`\sigma_x`, :math:`\sigma_y`, :math:`\sigma_t`, :math:`\epsilon_x`, :math:`\epsilon_y`, and :math:`\epsilon_t` must agree with nominal values.

src/python/elements.cpp

@@ -1156,7 +1156,14 @@ void init_elements(py::module& m)
              py::arg("dx") = 0,
              py::arg("dy") = 0,
              py::arg("rotation") = 0,
-             "A thin nonlinear plasma lens with transverse taper."
+             R"doc(A thin nonlinear plasma lens with A thin nonlinear plasma lens with transverse (horizontal) taper
+
+             .. math::
+
+                B_x = g \left( y + \frac{xy}{D_x} \right), \quad \quad B_y = -g \left(x + \frac{x^2 + y^2}{2 D_x} \right)
+
+             where :math:`g` is the (linear) field gradient in T/m and :math:`D_x` is the targeted horizontal dispersion in m.
+             )doc"
         )
     ;
     register_beamoptics_push(py_TaperedPL);