transfer matrix approach to single-particle dynamics in laser-driven rf electron guns

Project started: March 2014
Last update: July 6, 2015

Giulio Stancari
Fermi National Accelerator Laboratory


tramalargu is an algorithm and computer program for calculation of transfer matrices, particle trajectories, and beam envelopes in laser-driven radiofrequency electron guns without space charge, including solenoids. The transfer matrix approach is applied to an adaptive mesh of longitudinal slices (as opposed to time-step integration). This implementation is based upon the work by Gulliford and Bazarov, Phys. Rev. ST Accel. Beams 15, 024002 (2012). Transfer matrices are automatically symplectic for both nonrelativistic and relativistic sections of the device.

The original Gulliford-Bazarov approach was slightly modified, so that instead of 2 edge matrices at each longitudinal slice, only 1 matrix is employed. The 2 matrices accounted for the step in electric field from zero to the slice value. The single matrix accounts for the variation in electric field in the slice. This modification results in an improvement in speed and numerical accuracy of the algorithm.


This document describes the main features of the program. In the software repository, documentation can be found in the doc directory:

  • - the source document (in Markdown format, a human-readable text).

  • fig/ - directory with figures and supporting files.

Simple scripts, driven by the make utility, are used to convert the documentation into various formats (HTML, Textile, LaTeX, PDF, ...) using pandoc.

Documentation in HTML format can be found here.

Implementation with interpreted scripting language

The algorithm was first implemented using the open-source, multi-platform, data analysis software R. This slower version was used to test and debug the algorithm. Inspection and plotting of variables is easily accessible. In the repository, this implementation can be found in directory R.

The file driver.R contains the driving script, which launches the program under various scenarios and collects the results.

The algorithm is defined as a function in file tramalargu.R. It takes as inputs the cathode parameters, initial beam conditions, field maps, longitudinal extent of the simulation, the parameters of the algorithm. It outputs all dynamical quantities as a list. It can also generate diagnostic messages and plots.

(An old implementation is still kept in file rfgundyn.R.)

Tests and debugging can be done within the R environment in interactive mode. For production runs in batch mode, after verifying the parameters in the input files, one can launch the script with a command like this:

Rscript --verbose driver.R &> tmp.log &

As an example, this is a log file and these are some diagnostic plots:

Note: As of March 2014, the R version still produces different results from the Fortran version and Astra. A bug in the matrix calculation needs to be fixed.

Implementation in a compiled language

A faster and more efficient version of the algorithm was implemented in Fortran 95 (subdirectory Fortran).

The main program is tramalargu.f95. It contains the RFG module, with the definition of the main calculation, input/output routines, common variables, and utility functions.

The input parameters are specified as a Fortran namelist file. The default file name is iopar.nml. A different file name can be specified as an argument of subroutine TRAMALARGU_IO in module RFG. Input parameters are echoed as a separate namelist file (ioecho.nml by default).

Several wrapper and test routines can be found in the Fortran directory. Their descriptions and compilation rules are stored in a Makefile:

  • driver.exe for full tracking output
  • getmat.exe to obtain the main transport parameters
  • getmatR-interfaces.R to get transport parameters within R
  • accuracy_study.exe to study the stability of results vs. algorithm parameters
  • par_scan.exe to produce a lookup table of transport parameters

Note 1: Execution could be made faster by improving the adaptive slicing of the longitudinal coordinate.

Note 2: There are still erratic and occasional crashes (memory allocation) on some platforms when calling the Fortran 95 shared library directly within R. This is expected, as R only supports Fortran 77. For now, this is not critical, as communication between Fortran and R through small text files is sufficiently fast and reliable.

Accuracy study

The calculation was launched on different platforms for different values of the phase tolerance parameter to study the dependence of the results and of the computing time on the requested accuracy of the algorithm.

The program Fortran/accuracy_study.exe calls tramalargu several times with different values of the phase tolerance, writing dynamical variables and execution times to standard output.

The results are copied to subdirectory accuracy_study and analyzed and plotted with the script accuracy.R.

The following plots show how the dynamical variables depend on the phase tolerance for a test case:

The most critical outputs are the matrix elements. They require a phase tolerance of about 10-6 rad to reach a relative accuracy of 10-3.

It was also verified that emittance is conserved, i.e. the determinant of the calculated transport matrices is equal to 1 within machine precision.

Comparisons between tramalargu and Astra

A test case was developed to compare trajectories and beam envelopes calculated by Astra (fourth-order Runge-Kutta integration over time steps) and by tramalargu.

  • Common parameters:
    • beam
      • round rms spot size at cathode, rms = 0.4 mm (r = 0.8 mm)
      • average initial kinetic energy: 0.230 eV
      • initial normalized rms emittance: (0.4 mm) * sqrt(0.230 eV / 2 / (me c2)) = 0.189757488906545 um
    • rf cavity
      • ASTA/DESY rf gun field map: data | plot
      • peak gradient 40 MV/m
      • rf frequency 1.3 GHz
      • rf phase -51.492 deg in tramalargu, (90 - 51.492) deg = 38.508 deg in Astra
    • solenoid
      • ASTA solenoids at 176 mm field map: data | plot
      • 0.13 T peak field
    • boundaries
      • start at cathode, z = 0 m
      • end at first YAG screen, z = 1.06214 m
  • tramalargu parameters:
    • particle phase tolerance: 1e-6 rad
    • default step size: 0.010 m
    • max. number of steps: 1000000 (585784 used)
  • Astra parameters:
    • 8192 particles
    • no space charge
    • no longitudinal spread at emission (also tested 5 ps, no significant difference; data in test_case/Astra/sigma5ps/)
    • molybdenum cathode, photon energy 4.705 eV, effective work function 0.240 eV @ 40 MV/m => Eph-phi_eff = 0.345 eV => average kinetic energy (2/3)*(0.345 eV) = 0.230 eV
    • max. time step 1 ps, chosen by studying accuracy vs. time step. The Astra accuracy study vs. time step is stored in directory test_case/Astra/accuracy_vs_timestep. The driver and plotting routines are described in the Makefile. Results are in data files tmp-accuracy.rda and tmp-accuracy.txt. Here are the plots of the main results:

Dynamical quantities calculated by tramalargu and Astra are compared as a function of longitudinal coordinate. Here are some examples:

In this test case, the agreement is very good.


The tramalargu code calculates the single-particle transfer matrix of a laser-driven rf gun, including rf fields and focusing solenoids. It is complementary to Astra tracking in the sense that it slices the longitudinal coordinate instead of time.

Together with Astra, the code is used in the analysis of solenoid scans in the ASTA rf photoinjector for beam-based measurements of rf gradient, laser-rf relative phase, beam energy, and beam emittance.