Symplectic integration in a user-defined magnetostatic vector potential

[cemitch99]

This PR adds a new element that allows the user to track through a region with a specified magnetostatic vector potential. Symplectic integration is performed using the exact form of the nonlinear relativistic Hamiltonian. We use the semiexplicit integrator appearing in:

B. Jayawardana and T. Ohsawa, "Semiexplicit symplectic integrators for non-separable Hamiltonian systems," Math. Comput. 92, pp. 251-281 (2022), https://doi.org/10.1090/mcom/3778

To do:

• [x] add template for the basic VectorPotential element
• [x] add functions needed for the semiexplicit integrator
• [x] update the map in VectorPotential to use the correct Hamiltonian derivatives
• [x] update user-facing inputs
• [x] add simple benchmark problem(s)
• [x] check the treatment of s-dependence
• [x] add an s-dependent benchmark problem
• [x] add Python bindings
• [x] update documentation
• [x] add support for 4th-order and 6th-order integration

[cemitch99]

Note: Some host-device errors appear in CI when running on GPU that will need to be addressed.

[ax3l]

https://github.com/BLAST-ImpactX/impactx/pull/964#issuecomment-3085567714

Fixed GPU compile :) This was just lacking a host device annotation in a function declaration.

[ax3l]

The tolerances seem to fail with MPI, maybe just need a small relaxation @cemitch99 ?

Errors while running CTest
	485 - examples-fodo-vector-potential.py.analysis (Failed)
	491 - examples-exact-quad-vector-potential.py.analysis (Failed)
	512 - examples-solenoid-vector-potential.py.analysis (Failed)

[ax3l]

Something is still off with the Python tests. Besides the tolerance issues, they seem to run significantly longer than their app/executable counterparts?

ctest --test-dir build -R vector
      Start 481: fodo-vector-potential.run
 1/18 Test #481: fodo-vector-potential.run .................   Passed    3.65 sec
      Start 482: fodo-vector-potential.analysis
 2/18 Test #482: fodo-vector-potential.analysis ............   Passed    0.30 sec
      Start 483: fodo-vector-potential.cleanup
 3/18 Test #483: fodo-vector-potential.cleanup .............   Passed    0.01 sec
      Start 484: fodo-vector-potential.py.run
 4/18 Test #484: fodo-vector-potential.py.run ..............   Passed  268.34 sec
      Start 485: fodo-vector-potential.py.analysis
 5/18 Test #485: fodo-vector-potential.py.analysis .........***Failed    0.26 sec
      Start 486: fodo-vector-potential.py.cleanup
 6/18 Test #486: fodo-vector-potential.py.cleanup ..........   Passed    0.01 sec
      Start 487: exact-quad-vector-potential.run
 7/18 Test #487: exact-quad-vector-potential.run ...........   Passed    3.73 sec
      Start 488: exact-quad-vector-potential.analysis
 8/18 Test #488: exact-quad-vector-potential.analysis ......   Passed    0.57 sec
      Start 489: exact-quad-vector-potential.cleanup
 9/18 Test #489: exact-quad-vector-potential.cleanup .......   Passed    0.01 sec
      Start 490: exact-quad-vector-potential.py.run
10/18 Test #490: exact-quad-vector-potential.py.run ........   Passed   11.98 sec
      Start 491: exact-quad-vector-potential.py.analysis
11/18 Test #491: exact-quad-vector-potential.py.analysis ...***Failed    0.57 sec
      Start 492: exact-quad-vector-potential.py.cleanup
12/18 Test #492: exact-quad-vector-potential.py.cleanup ....   Passed    0.01 sec
      Start 508: solenoid-vector-potential.run
13/18 Test #508: solenoid-vector-potential.run .............   Passed    6.24 sec
      Start 509: solenoid-vector-potential.analysis
14/18 Test #509: solenoid-vector-potential.analysis ........   Passed    0.59 sec
      Start 510: solenoid-vector-potential.cleanup
15/18 Test #510: solenoid-vector-potential.cleanup .........   Passed    0.01 sec
      Start 511: solenoid-vector-potential.py.run
16/18 Test #511: solenoid-vector-potential.py.run ..........   Passed   23.76 sec
      Start 512: solenoid-vector-potential.py.analysis
17/18 Test #512: solenoid-vector-potential.py.analysis .....***Failed    0.58 sec
      Start 513: solenoid-vector-potential.py.cleanup
18/18 Test #513: solenoid-vector-potential.py.cleanup ......   Passed    0.01 sec

[ax3l]

@cemitch99 the three python run files are not yet 100% identical with the app inputs files, which should be the origin of the failing tests. I fixed the things I spotted, but some differences remain.

[cemitch99]

The three new tests currently fail only in the case OpenMP / GCC w/ MPI w/ Python. Note that the execution time (of the Python test) is very long - 32.42 sec for the solenoid example, which is only 0.56 sec on macOS / AppleClang (with similar behavior for the other two tests). Also, although the solenoid example runs successfully, the initial and final beam moments agree to all digits (and they should not), which appears to indicate that no tracking push was applied to the beam.

[ax3l]

Thanks! If they run a bit on the longer end, let us add the slow label on these (in CMakeLists.txt).