BLAST-ImpactX · cemitch99 · May 15, 2025 · May 15, 2025 · May 15, 2025 · Jun 25, 2025
diff --git a/.github/workflows/cuda.yml b/.github/workflows/cuda.yml
@@ -19,7 +19,18 @@ jobs:
       CXXFLAGS: "-Werror"
       CMAKE_GENERATOR: Ninja
     steps:
-    - uses: actions/checkout@v5
+    - name: Free More Disk Space
+      uses: ax3l/free-disk-space@main
+      with:
+        tool-cache: false
+        android: true
+        dotnet: true
+        haskell: true
+        large-packages: false  # apt takes ~1:30min
+        docker-images: true
+        swap-storage: false
+
+    - uses: actions/checkout@v4
 
     - name: install dependencies
       run: |
@@ -53,4 +64,4 @@ jobs:
           -DImpactX_PRECISION=SINGLE   \
           -DAMReX_CUDA_ERROR_CROSS_EXECUTION_SPACE_CALL=ON \
           -DAMReX_CUDA_ERROR_CAPTURE_THIS=ON
-        cmake --build build -j 4
+        cmake --build build -j 1
diff --git a/docs/source/usage/examples.rst b/docs/source/usage/examples.rst
@@ -41,6 +41,7 @@ Single Particle Dynamics
    examples/reversibility/README.rst
    examples/charge_sign/README.rst
    examples/symplectic_integration/README.rst
+   examples/vector_potential/README.rst
 
 
 Collective Effects

diff --git a/docs/source/usage/parameters.rst b/docs/source/usage/parameters.rst
@@ -429,6 +429,39 @@ This element requires these additional parameters:
 * ``<element_name>.rotation`` (``float``, in degrees) rotation error in the transverse plane
 
 
+``magnetostatic_vector_potential``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Symplectic integration in a user-defined magnetostatic vector potential, using the exact Hamiltonian, which includes all
+nonlinear kinematic effects.  Integration is performed with respect to a Cartesian coordinate system local to the body of
+the element.  A symmetric, semi-explicit symplectic integration scheme is used, based on:
+
+B. Jayawardana and T. Ohsawa, ``Semiexplicit symplectic integrators for non-separable Hamiltonian systems,"
+Math. Comput. 92, pp. 251-281 (2022), `DOI:10.1090/mcom/3778 <https://doi.org/10.1090/mcom/3778>`__
+
+This element requires these additional parameters:
+
+* ``<element_name>.ds`` (``float``, in meters) the segment length
+* ``<element_name>.unit`` (``integer``) specification of units for the vector potential (default: ``0``)
+  By default, the vector potential is normalized by magnetic rigidity.  Use ``unit=1`` to specify using SI units.
+* ``<element_name>.A_x(x,y,z)`` (``float``, dimensionless OR in Tesla-meters) formula for horizontal component of vector potential
+* ``<element_name>.A_y(x,y,z)`` (``float``, dimensionless OR in Tesla-meters) formula for vertical component of vector potential
+* ``<element_name>.dA_x/dx(x,y,z)`` (``float``, in 1/meters OR in Tesla) formula for x-derivative of A_x component
+* ``<element_name>.dA_x/dy(x,y,z)`` (``float``, in 1/meters OR in Tesla) formula for y-derivative of A_x component
+* ``<element_name>.dA_y/dx(x,y,z)`` (``float``, in 1/meters OR in Tesla) formula for x-derivative of A_y component
+* ``<element_name>.dA_y/dy(x,y,z)`` (``float``, in 1/meters OR in Tesla) formula for y-derivative of A_y component
+* ``<element_name>.dA_z/dx(x,y,z)`` (``float``, in 1/meters OR in Tesla) formula for x-derivative of A_z component
+* ``<element_name>.dA_z/dy(x,y,z)`` (``float``, in 1/meters OR in Tesla) formula for y-derivative of A_z component
+* ``<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
+* ``<element_name>.aperture_x`` (``float``, in meters) horizontal half-aperture (elliptical)
+* ``<element_name>.aperture_y`` (``float``, in meters) vertical half-aperture (elliptical)
+* ``<element_name>.int_order`` (``integer``) the order used for symplectic integration (2, 4, or 6) (default: ``2``)
+* ``<element_name>.mapsteps`` (``integer``) number of integration steps per slice used for symplectic integration (default: ``5``)
+* ``<element_name>.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``)
+
+
 ``multipole``
 ^^^^^^^^^^^^^
 

diff --git a/docs/source/usage/python.rst b/docs/source/usage/python.rst
@@ -1104,6 +1104,58 @@ This module provides elements and methods for the accelerator lattice.
    :param rotation: rotation error in the transverse plane [degrees]
    :param name: an optional name for the element
 
+
+.. py:class:: impactx.elements.MagnetostaticVectorPotential(ds, unit=0, ax="0", ay="0", daxdx="0", daxdy="0", daydx="0", daydy="0", dazdx="0", dazdy="0", dx=0, dy=0, rotation=0, aperture_x=0,
+aperture_y=0, int_order=2, mapsteps=5, nslice=1, name=None)
+
+   Symplectic integration in a user-defined magnetostatic vector potential, using the exact Hamiltonian, which includes all
+   nonlinear kinematic effects.  Integration is performed with respect to a Cartesian coordinate system local to the body of
+   the element.  A symmetric, semi-explicit symplectic integration scheme is used, based on:
+
+   B. Jayawardana and T. Ohsawa, ``Semiexplicit symplectic integrators for non-separable Hamiltonian systems,"
+   Math. Comput. 92, pp. 251-281 (2022), `DOI:10.1090/mcom/3778 <https://doi.org/10.1090/mcom/3778>`__
+
+   This element requires these additional parameters:
+
+   :param ds: Segment length in m.
+   :param unit: specification of units for the vector potential and its derivatives
+              0 (default) normalize all quantities by the magnetic rigidity
+              1 provide all quantities in SI units
+   :param ax: formula for horizontal component of vector potential (dimensionless, if unit = 0 OR in T-m if unit = 1)
+   :param ay: formula for vertical component of vector potential (dimensionless, if unit = 0 OR in T-m if unit = 1)
+   :param daxdx: formula for x-derivative of A_x component (in 1/meter, if unit = 0 OR in T if unit = 1)
+   :param daxdy: formula for y-derivative of A_x component (in 1/meter, if unit = 0 OR in T if unit = 1)
+   :param daydx: formula for x-derivative of A_y component (in 1/meter, if unit = 0 OR in T if unit = 1)
+   :param daydy: formula for y-derivative of A_y component (in 1/meter, if unit = 0 OR in T if unit = 1)
+   :param dazdx: formula for x-derivative of A_z component (in 1/meter, if unit = 0 OR in T if unit = 1)
+   :param dazdy: formula for y-derivative of A_z component (in 1/meter, if unit = 0 OR in T if unit = 1)
+   :param dx: horizontal translation error in m
+   :param dy: vertical translation error in m
+   :param rotation: rotation error in the transverse plane [degrees]
+   :param aperture_x: horizontal half-aperture (elliptical) in m
+   :param aperture_y: vertical half-aperture (elliptical) in m
+   :param int_order: the order used for symplectic integration (2, 4, or 6)
+   :param mapsteps: number of integration steps per slice used for symplectic integration
+   :param nslice: number of slices used for the application of space charge
+   :param name: an optional name for the element
+
+   .. py:property:: k
+
+      quadrupole strength in 1/m^2 (or T/m)
+
+   .. py:property:: unit
+
+      unit specification for quad strength
+
+   .. py:property:: int_order
+
+      the order used for symplectic integration (2, 4, or 6)
+
+   .. py:property:: mapsteps
+
+      number of integration steps per slice used for symplectic integration
+
+
 .. py:class:: impactx.elements.ChrPlasmaLens(ds, k, unit=0, dx=0, dy=0, rotation=0, aperture_x=0, aperture_y=0, nslice=1, name=None)
 
    An active cylindrically symmetric plasma lens, with chromatic effects included.

diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
@@ -1515,6 +1515,38 @@ add_impactx_test(dogleg-jitter.py
     OFF  # no plot script yet
 )
 
+# Symplectic Integration in a FODO Cell Based on User-Provided Vector Potential ##############
+#
+# no space charge
+add_impactx_test(fodo-vector-potential
+    examples/vector_potential/input_fodo_vector_potential.in
+    ON   # ImpactX MPI-parallel
+    examples/vector_potential/analysis_fodo_vector_potential.py
+    OFF  # no plot script yet
+)
+add_impactx_test(fodo-vector-potential.py
+    examples/vector_potential/run_fodo_vector_potential.py
+    ON   # ImpactX MPI-parallel
+    examples/vector_potential/analysis_fodo_vector_potential.py
+    OFF  # no plot script yet
+)
+
+# Symplectic Integration in Exact Quads Based on User-Provided Vector Potential ##############
+#
+# no space charge
+add_impactx_test(exact-quad-vector-potential
+    examples/vector_potential/input_exact_quad_vector_potential.in
+    ON   # ImpactX MPI-parallel
+    examples/vector_potential/analysis_exact_quad_vector_potential.py
+    OFF  # no plot script yet
+)
+add_impactx_test(exact-quad-vector-potential.py
+    examples/vector_potential/run_exact_quad_vector_potential.py
+    ON   # ImpactX MPI-parallel
+    examples/vector_potential/analysis_exact_quad_vector_potential.py
+    OFF  # no plot script yet
+)
+
 # HTU Beamline Model ##############
 #
 # no space charge
@@ -1559,6 +1591,22 @@ add_impactx_test(exact-cfbend_multipole.py
     OFF  # no plot script yet
 )
 
+# Symplectic Integration Through a Soft-Edge Solenoid Using a User-Provided Vector Potential ##############
+#
+# no space charge
+add_impactx_test(solenoid-vector-potential
+    examples/vector_potential/input_solenoid_vector_potential.in
+    ON   # ImpactX MPI-parallel
+    examples/vector_potential/analysis_solenoid_vector_potential.py
+    OFF  # no plot script yet
+)
+add_impactx_test(solenoid-vector-potential.py
+    examples/vector_potential/run_solenoid_vector_potential.py
+    ON   # ImpactX MPI-parallel
+    examples/vector_potential/analysis_solenoid_vector_potential.py
+    OFF  # no plot script yet
+)
+
 # FODO Cell Based on PALS-Compliant Lattice Input ##############
 #
 # copy PALS lattice file

diff --git a/examples/vector_potential/README.rst b/examples/vector_potential/README.rst
@@ -0,0 +1,128 @@
+.. _examples-fodo-vector-potential:
+
+Symplectic Integration in a FODO Cell Based on User-Provided Vector Potential
+=============================================================================
+
+This benchmark tests the implementation of the element MagnetostaticVectorPotential, which uses symplectic integration based on the exact nonlinear Hamiltonian for a user-provided vector
+potential.  The physical example is identical to examples-fodo, except that the vector potential in the quadrupoles is provided in formulae by the user.
+
+The analysis script is identical to the analysis script used for ``examples-fodo``.
+
+Run
+---
+
+This example can be run **either** as:
+
+* **Python** script: ``python3 run_fodo_vector_potential.py`` or
+* ImpactX **executable** using an input file: ``impactx input_fodo_vector_potential.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_fodo_vector_potential.py
+          :language: python3
+          :caption: You can copy this file from ``examples/vector_potential/run_fodo_vector_potential.py``.
+
+   .. tab-item:: Executable: Input File
+
+       .. literalinclude:: input_fodo_vector_potential.in
+          :language: ini
+          :caption: You can copy this file from ``examples/vector_potential/input_fodo_vector_potential.in``.
+
+
+Analyze
+-------
+
+We run the following script to analyze correctness:
+
+.. dropdown:: Script ``analysis_fodo_vector_potential.py``
+
+   .. literalinclude:: analysis_fodo_vector_potential.py
+      :language: python3
+      :caption: You can copy this file from ``examples/vector_potential/analysis_vector_potential.py``.
+
+
+.. _examples-exact-quad-vector-potential:
+
+Symplectic Integration in Exact Quads Based on User-Provided Vector Potential
+=============================================================================
+
+This benchmark tests the implementation of the element MagnetostaticVectorPotential, which uses symplectic integration based on the exact nonlinear Hamiltonian for a user-provided vector
+potential.  The physical example is identical to examples-exact-quad, except that the vector potential in the quadrupoles is provided in formulae by the user.
+
+The analysis script is identical to the analysis script used for ``examples-exact-quad``.
+
+Run
+---
+
+This example can be run **either** as:
+
+* **Python** script: ``python3 run_exact_quad_vector_potential.py`` or
+* ImpactX **executable** using an input file: ``impactx input_exact_quad_vector_potential.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_exact_quad_vector_potential.py
+          :language: python3
+          :caption: You can copy this file from ``examples/vector_potential/run_exact_quad_vector_potential.py``.
+
+   .. tab-item:: Executable: Input File
+
+       .. literalinclude:: input_exact_quad_vector_potential.in
+          :language: ini
+          :caption: You can copy this file from ``examples/vector_potential/input_exact_quad_vector_potential.in``.
+
+
+Analyze
+-------
+
+We run the following script to analyze correctness:
+
+.. dropdown:: Script ``analysis_exact_quad_vector_potential.py``
+
+   .. literalinclude:: analysis_exact_quad_vector_potential.py
+      :language: python3
+      :caption: You can copy this file from ``examples/vector_potential/analysis_exact_quad_vector_potential.py``.
+
+
+
+.. _examples-solenoid-vector-potential:
+
+Symplectic Integration Through a Soft-Edge Solenoid Based on User-Provided Vector Potential
+============================================================================================
+
+This benchmark tests the implementation of the element MagnetostaticVectorPotential, which uses symplectic integration based on the exact nonlinear Hamiltonian for a user-provided vector
+potential.  The physical example is identical to examples-solenoid-softedge, except that the vector potential of the solenoid is provided in formulae by the user.
+
+The analysis script is identical to the analysis script used for ``examples-solenoid-softedge``.
+
+Run
+---
+
+This example can be run **either** as:
+
+* **Python** script: ``python3 run_solenoid_vector_potential.py`` or
+* ImpactX **executable** using an input file: ``impactx input_solenoid_vector_potential.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_solenoid_vector_potential.py
+          :language: python3
+          :caption: You can copy this file from ``examples/vector_potential/run_solenoid_vector_potential.py``.
+
+   .. tab-item:: Executable: Input File
+
+       .. literalinclude:: input_solenoid_vector_potential.in
+          :language: ini
+          :caption: You can copy this file from ``examples/vector_potential/input_solenoid_vector_potential.in``.