Add documentation.

docs/source/usage/parameters.rst

@@ -378,6 +378,13 @@ Lattice Elements
             * ``<element_name>.phi_in`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the original frame
             * ``<element_name>.phi_out`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the rotated frame
 
+        * ``plane_xyrotation`` for a rotation in the x-y plane (i.e., about the reference velocity vector). This requires these additional parameters:
+
+            * ``<element_name>.angle`` (``float``, in degrees) nominal angle of rotation
+            * ``<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
+
         * ``kicker`` for a thin transverse kicker. This requires these additional parameters:
 
             * ``<element_name>.xkick`` (``float``, dimensionless OR in T-m) the horizontal kick strength

docs/source/usage/python.rst

@@ -934,6 +934,16 @@ This module provides elements for the accelerator lattice.
    :param phi_out: angle of the reference particle with respect to the longitudinal (z) axis in the rotated frame in degrees
    :param name: an optional name for the element
 
+.. py:class:: impactx.elements.PlaneXYRot(angle,  dx=0, dy=0, rotation=0, name=None)
+
+   Map for a transverse rotation in the x-y plane (i.e., about the reference velocity vector).
+
+   :param angle: nominal angle of rotation in the x-y plane, in degrees
+   :param dx: horizontal translation error in m
+   :param dy: vertical translation error in m
+   :param rotation: rotation error in the transverse plane [degrees]
+   :param name: an optional name for the element
+
 .. py:class:: impactx.elements.Aperture(xmax, ymax, shape="rectangular", dx=0, dy=0, rotation=0, name=None)
 
    A thin collimator element, applying a transverse aperture boundary.

examples/rotation/README.rst

@@ -48,3 +48,55 @@ We run the following script to analyze correctness:
    .. literalinclude:: analysis_rotation.py
       :language: python3
       :caption: You can copy this file from ``examples/rotation/analysis_rotation.py``.
+
+
+.. _examples-rotation-xy:
+
+Simple rotation in the x-y plane
+=================================
+
+A beam is rotated counter-clockwise by 90 degrees about the direction of motion.
+
+We use a 2 GeV electron beam.
+
+The second beam moments associated with the phase planes (x,px) and (y,py) are unequal, and these are exchanged under a 90 degree rotation.
+
+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.
+
+
+Run
+---
+
+This example can be run **either** as:
+
+* **Python** script: ``python3 run_rotation_xy.py`` or
+* ImpactX **executable** using an input file: ``impactx input_rotation_xy.in``
+
+For `MPI-parallel <https://www.mpi-forum.org>`__ runs, prefix these lines with ``mpiexec -n 4 ...`` or ``srun -n 4 ...``, depending on the system.
+
+.. tab-set::
+
+   .. tab-item:: Python: Script
+
+       .. literalinclude:: run_rotation_xy.py
+          :language: python3
+          :caption: You can copy this file from ``examples/rotation/run_rotation_xy.py``.
+
+   .. tab-item:: Executable: Input File
+
+       .. literalinclude:: input_rotation_xy.in
+          :language: ini
+          :caption: You can copy this file from ``examples/rotation/input_rotation_xy.in``.
+
+
+Analyze
+-------
+
+We run the following script to analyze correctness:
+
+.. dropdown:: Script ``analysis_rotation_xy.py``
+
+   .. literalinclude:: analysis_rotation_xy.py
+      :language: python3
+      :caption: You can copy this file from ``examples/rotation/analysis_rotation_xy.py``.
+