Add Python bindings and element docs.

docs/source/usage/parameters.rst

@@ -516,6 +516,22 @@ Lattice Elements
             * ``<element_name>.dy`` (``float``, in meters) vertical translation error
             * ``<element_name>.rotation`` (``float``, in degrees) rotation error in the transverse plane
 
+        * ``tapered_pl`` for a thin nonlinear (tapered) plasma lens.
+          This requires these additional parameters:
+
+            * ``<element_name>.k`` (``float``, in inverse meters OR in T) the integrated plasma lens focusing strength
+                = (length in m) * (azimuthal magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if units = 0
+
+             OR = (length in m) * (azimuthal magnetic field gradient in T/m) - if units = 1
+
+            * ``<element_name>.units`` (``integer``) specification of units (default: ``0``)
+            * ``<element_name>.taper`` (``float``, in 1/meters) horizontal taper parameter
+                = 1 / (target horizontal dispersion in m)
+
+            * ``<element_name>.dx`` (``float``, in meters) horizontal translation error
+            * ``<element_name>.dy`` (``float``, in meters) vertical translation error
+            * ``<element_name>.rotation`` (``float``, in degrees) rotation error in the transverse plane
+
         * ``beam_monitor`` a beam monitor, writing all beam particles at fixed ``s`` to openPMD files.
           If the same element name is used multiple times, then an output series is created with multiple outputs.
 

docs/source/usage/python.rst

@@ -899,6 +899,35 @@ This module provides elements for the accelerator lattice.
 
    * G. Ripken and F. Schmidt, Thin-Lens Formalism for Tracking, CERN/SL/95-12 (AP), 1995.
 
+.. py:class:: impactx.elements.TaperedPL(k, taper, units, dx=0, dy=0, rotation=0)
+
+   An active cylindrically symmetric plasma lens, with chromatic effects included.
+   The Hamiltonian is expanded through second order in the transverse variables
+   (x,px,y,py), with the exact pt dependence retained.
+
+   :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)
+          OR  integrated focusing strength in T (if units = 1)
+              = (length in m) * (azimuthal magnetic field gradient in T/m)
+   :param taper: horizontal taper parameter in m^(-1)
+              = 1 / (target horizontal dispersion in m)
+   :param units: specification of units for plasma lens focusing strength
+   :param dx: horizontal translation error in m
+   :param dy: vertical translation error in m
+   :param rotation: rotation error in the transverse plane [degrees]
+
+   .. py:property:: k
+
+      integrated plasma lens focusing strength in 1/m (or T)
+
+   .. py:property:: taper
+
+      horizontal taper parameter in 1/m
+
+   .. py:property:: units
+
+      unit specification for plasma lens focusing strength
+
 
 Coordinate Transformation
 -------------------------

src/python/elements.cpp

@@ -1080,6 +1080,38 @@ void init_elements(py::module& m)
     ;
     register_beamoptics_push(py_ThinDipole);
 
+    py::class_<TaperedPL, elements::Thin, elements::Alignment> py_TaperedPL(me, "TaperedPL");
+    py_TaperedPL
+        .def("__repr__",
+             [](TaperedPL const & taperedpl) {
+                 std::string r = "<impactx.elements.TaperedPL (taperedpl=";
+                 r.append(std::to_string(taperedpl.m_k))
+                  .append(", k=")
+                  .append(std::to_string(taperedpl.m_taper))
+                  .append(", taper=")
+                  .append(")>");
+                 return r;
+             }
+        )
+        .def(py::init<
+                amrex::ParticleReal,
+                amrex::ParticleReal,
+                int,
+                amrex::ParticleReal,
+                amrex::ParticleReal,
+                amrex::ParticleReal
+             >(),
+             py::arg("k"),
+             py::arg("taper"),
+             py::arg("units") = 0,
+             py::arg("dx") = 0,
+             py::arg("dy") = 0,
+             py::arg("rotation") = 0,
+             "A thin nonlinear plasma lens with transverse taper."
+        )
+    ;
+    register_beamoptics_push(py_TaperedPL);
+
 
     // free-standing push function
     m.def("push", &Push,