Add PIP-II linac

docs/source/usage/parameters.rst

@@ -259,13 +259,17 @@ Lattice Elements
 
             * ``<element_name>.ds`` (``float``, in meters) the segment length
 
-            * ``<element_name>.k`` (``float``, in inverse meters squared) the quadrupole strength
+            * ``<element_name>.k`` (``float``, in inverse meters squared OR in T/m) the quadrupole strength
 
-                = (magnetic field gradient in T/m) / (magnetic rigidity in T-m)
+                = (magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if units = 0
+
+             OR = magnetic field gradient in T/m - if units = 1
 
               * k > 0 horizontal focusing
               * k < 0 horizontal defocusing
 
+            * ``<element_name>.units`` (``integer``) specification of units (default: ``0``)
+
             * ``<element_name>.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``)
 
         * ``quad_chromatic`` for A Quadrupole magnet, with chromatic effects included.
@@ -291,14 +295,20 @@ Lattice Elements
 
             * ``<element_name>.ds`` (``float``, in meters) the segment length
 
-            * ``<element_name>.gscale`` (``float``, in inverse meters) Scaling factor for on-axis magnetic field gradient
+            * ``<element_name>.gscale`` (``float``, in inverse meters squared OR in T/m) Scaling factor for on-axis magnetic field gradient
+
+                = (magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if units = 0
+
+             OR = magnetic field gradient in T/m - if units = 1
 
             * ``<element_name>.cos_coefficients`` (array of ``float``) cos coefficients in Fourier expansion of the on-axis field gradient
               (optional); default is a tanh fringe field model from `MaryLie 3.0 <http://www.physics.umd.edu/dsat/docs/MaryLieMan.pdf>`__
 
             * ``<element_name>.sin_coefficients`` (array of ``float``) sin coefficients in Fourier expansion of the on-axis field gradient
               (optional); default is a tanh fringe field model from `MaryLie 3.0 <http://www.physics.umd.edu/dsat/docs/MaryLieMan.pdf>`__
 
+            * ``<element_name>.units`` (``integer``) specification of units (default: ``0``)
+
             * ``<element_name>.mapsteps`` (``integer``) number of integration steps per slice used for map and reference particle push in applied fields
                (default: ``1``)
 
@@ -329,24 +339,34 @@ Lattice Elements
 
             * ``<element_name>.ds`` (``float``, in meters) the segment length
 
-            * ``<element_name>.ks`` (``float``, in meters) Solenoid strength in m^(-1) (MADX convention)
+            * ``<element_name>.ks`` (``float``, in inverse meters OR in T) Solenoid strength
+
+                  = (magnetic field Bz in T) / (rigidity in T-m) - if units = 0
+
+             OR = magnetic field Bz in T - if units = 1
 
-                  = (magnetic field Bz in T) / (rigidity in T-m)
+             * ``<element_name>.units`` (``integer``) specification of units (default: ``0``)
 
             * ``<element_name>.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``)
 
         * ``solenoid_softedge`` for a soft-edge solenoid. This requires these additional parameters:
 
             * ``<element_name>.ds`` (``float``, in meters) the segment length
 
-            * ``<element_name>.bscale`` (``float``, in inverse meters) Scaling factor for on-axis magnetic field Bz
+            * ``<element_name>.bscale`` (``float``, in inverse meters OR in T) Scaling factor for on-axis magnetic field Bz
+
+                  = (magnetic field Bz in T) / (rigidity in T-m) - if units = 0
+
+             OR = magnetic field Bz in T - if units = 1
 
             * ``<element_name>.cos_coefficients`` (array of ``float``) cos coefficients in Fourier expansion of the on-axis magnetic field Bz
               (optional); default is a thin-shell model from `DOI:10.1016/J.NIMA.2022.166706 <https://doi.org/10.1016/j.nima.2022.166706>`__
 
             * ``<element_name>.sin_coefficients`` (array of ``float``) sin coefficients in Fourier expansion of the on-axis magnetic field Bz
               (optional); default is a thin-shell model from `DOI:10.1016/J.NIMA.2022.166706 <https://doi.org/10.1016/j.nima.2022.166706>`__
 
+            * ``<element_name>.units`` (``integer``) specification of units (default: ``0``)
+
             * ``<element_name>.mapsteps`` (``integer``) number of integration steps per slice used for map and reference particle push in applied fields (default: ``1``)
 
             * ``<element_name>.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``)

docs/source/usage/python.rst

@@ -532,10 +532,12 @@ This module provides elements for the accelerator lattice.
    A Quadrupole magnet.
 
    :param ds: Segment length in m.
-   :param k:  Quadrupole strength in m^(-2) (MADX convention)
+   :param k:  Quadrupole strength in m^(-2) (MADX convention, if units = 0)
               = (gradient in T/m) / (rigidity in T-m)
+          OR  Quadrupole strength in T/m (MaryLie convention, if units = 1)
               k > 0 horizontal focusing
               k < 0 horizontal defocusing
+   :param units: specification of units for quadrupole field strength
    :param nslice: number of slices used for the application of space charge
 
 .. py:class:: impactx.elements.ChrQuad(ds, k, units, nslice=1)
@@ -616,11 +618,14 @@ References:
    A soft-edge solenoid.
 
    :param ds: Segment length in m.
-   :param bscale: Scaling factor for on-axis magnetic field Bz in inverse meters
+   :param bscale: Scaling factor for on-axis magnetic field Bz in m^(-1) (MADX convention, if units = 0)
+              = (magnetic field Bz in T) / (rigidity in T-m)
+          OR  Solenoid magnetic field Bz in T (MaryLie convention, if units = 1)
    :param cos_coefficients: array of ``float`` cosine coefficients in Fourier expansion of on-axis magnetic field Bz
             (optional); default is a thin-shell model from `DOI:10.1016/J.NIMA.2022.166706 <https://doi.org/10.1016/j.nima.2022.166706>`__
    :param sin_coefficients: array of ``float`` sine coefficients in Fourier expansion of on-axis magnetic field Bz
             (optional); default is a thin-shell model from `DOI:10.1016/J.NIMA.2022.166706 <https://doi.org/10.1016/j.nima.2022.166706>`__
+   :param units: specification of units for solenoid field strength
    :param mapsteps: number of integration steps per slice used for map and reference particle push in applied fields
    :param nslice: number of slices used for the application of space charge
 
@@ -629,7 +634,10 @@ References:
    An ideal hard-edge Solenoid magnet.
 
    :param ds: Segment length in m.
-   :param ks: Solenoid strength in m^(-1) (MADX convention) in (magnetic field Bz in T) / (rigidity in T-m)
+   :param ks: Solenoid strength in m^(-1) (MADX convention, if units = 0)
+              = (magnetic field Bz in T) / (rigidity in T-m)
+          OR  Solenoid magnetic field Bz in T (MaryLie convention, if units = 1)
+   :param units: specification of units for solenoid field strength
    :param nslice: number of slices used for the application of space charge
 
 .. py:class:: impactx.elements.PRot(phi_in, phi_out)
@@ -644,11 +652,14 @@ References:
    A soft-edge quadrupole.
 
    :param ds: Segment length in m.
-   :param gscale: Scaling factor for on-axis field gradient in inverse meters
+   :param gscale: Scaling factor for on-axis field gradient in m^(-2) (MADX convention, if units = 0)
+              = (gradient in T/m) / (rigidity in T-m)
+          OR  Quadrupole strength in T/m (MaryLie convention, if units = 1)
    :param cos_coefficients: array of ``float`` cosine coefficients in Fourier expansion of on-axis field gradient
             (optional); default is a tanh fringe field model based on `<http://www.physics.umd.edu/dsat/docs/MaryLieMan.pdf>`__
    :param sin_coefficients: array of ``float`` sine coefficients in Fourier expansion of on-axis field gradient
             (optional); default is a tanh fringe field model based on `<http://www.physics.umd.edu/dsat/docs/MaryLieMan.pdf>`__
+   :param units: specification of units for solenoid field strength
    :param mapsteps: number of integration steps per slice used for map and reference particle push in applied fields
    :param nslice: number of slices used for the application of space charge
 

examples/PIPII_linac/README.rst

@@ -0,0 +1,47 @@
+.. _examples-pipii-linac:
+
+The Fermilab PIP-II Linac
+===========================================================
+
+A version of the lattice of Fermilab's PIP-II linac, describing acceleration of a 5 mA H- / proton beam from 2.1 MeV to 800 MeV.
+
+This lattice describes propagation from the exit of the RFQ to the entry of the Booster.
+
+This file was converted from TraceWin input using a Jupyter notebook, whose corresponding script is given as "parse_lattice.py".
+
+The TraceWin lattice parser is based on https://github.com/ChristopherMayes/lume-tracewin .
+
+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 as a Python script (``python3 run_pipii_linac.py``) or with an app with an input file (``impactx input_pipii_linac.in``).
+Each can also be prefixed with an `MPI executor <https://www.mpi-forum.org>`__, such as ``mpiexec -n 4 ...`` or ``srun -n 4 ...``, depending on the system.
+
+.. tab-set::
+
+   .. tab-item:: Python Script
+
+       .. literalinclude:: run_pipii_linac.py
+          :language: python3
+          :caption: You can copy this file from ``examples/PIPII_linac/run_pipii_linac.py``.
+
+   .. tab-item:: App Input File
+
+       .. literalinclude:: input_pipii_linac.in
+          :language: ini
+          :caption: You can copy this file from ``examples/PIPII_linac/input_pipii_linac.in``.
+
+
+Analyze
+-------
+
+We run the following script to analyze correctness:
+
+.. dropdown:: Script ``analysis_pipii_linac.py``
+
+   .. literalinclude:: analysis_pipii_linac.py
+      :language: python3
+      :caption: You can copy this file from ``examples/PIPII_linac/analysis_pipii_linac.py``.