Genesis 1.3 Manual

Compilation

Main Input File

Lattice File

Output Files

GENESIS 1.3 - Compilation and Running Genesis 1.3

Compilation

macOS

Installation on macOS requires a suitable compiler and dependencies, which can be provided by MacPorts. With a working MacPorts, install these:

sudo port install gcc12
sudo port select gcc mp-gcc12
sudo port install hdf5 +openmpi 
sudo port install fftw-3

Then build Genesis:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Unix

Genesis supports now the automatic configuration with CMAKE. Following commands will build Genesis from source on Linux platforms. The minimal command to compile the code from the source code root directory is:

mkdir build
chdir build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

Depending on your compiler and system configuration, additional information may be given to CMAKE. Most important is the used compiler. This can be done with the additional definition -DCMAKE_CXX_COMPILER=#### in the cmake command overwriting the default compiler, where ### is the compiler, e.g. mpicxx or CC. If debugging is needed the CMAKE_BUILD_TARGET should be changed to Debug. The executable is found in the build directory. For a successful build the libraries openmpi/mpich and parallel HDF5 are needed. The FFTW3 is recommended but might become mandatory in upcoming releases.

To complete the installation it is recommended to install the scripts in the directory sdds2hdf in a directory (e.g. /bin), which is included in your search path. The files will convert Elegant output distribution into HDF5 format. More info can be found later in the manual. Also, the directory xgenesis includes some functions, which allows Matlab to parse the output file of Genesis and to plot the results. They are not required for running Genesis itself. To use them add the given folder to your Matlab Path or place the file in a directory, which is already in the search path.

Running

Genesis 1.3 is a command line executable and requires at least a single input argument, which is the filename of the input deck:

genesis4 [-o output-rootname] [-l lattice-filename] [-s seed] input-filename

The arguments for the lattice filename, the rootname for all output filenames and the seed for the random number generator are optional. If defined, they act as the default values in the setup namelist and thus can be omitted in the main input file. Any further information must be provided within the input deck. Starting Genesis in this way will effectively invoke a parallel job with only one single core. To start the code with just more than one core the launching command mpirun needs to be called, including the number of cores. In its simplest call it would be:

mpirun -np xxx genesis4 [-o output-rootname] [-l lattice-filename] [-s seed] input-filename

where xxx is the number of cores to be requested.

Once Genesis started, the master core, which is the core with the MPI rank 0, will provide the output to stdout. The output can vary for different input decks. Normally it is reported, once the code generates or alters particle distributions or the radiation field, tracks the beam through the lattice or when a time window is specified.

The execution produces output files whenever a tracking command is issued or a field or particle dumped is requested. All in common is the root filename which is defined in the input deck. Normal output files have the extension .out.h5 for the first tracking or .Runxxx.out.h for the xxxth run (except for the first, where the addition of ’Run’ is omitted). The file format is HDF5. The explicit format is described in a later chapter of this manual. Field or particle dumps are using the root filename as well as the default but under certain circumstances this behavior can be overruled. For more information see the corresponding namelist elements in the dedicated chapter.

For time-dependent simulations the code requires a large amount of memories to keep the entire radiation field and particle distribution in memory. This is the significant difference to previous versions where the code was able to progress through the bunch sequentially. However this excluded features such long range space charge fields, exchanging particles between slices, and large delaying chicanes in the older versions. For an estimate of the memory demand the radiation field requires

Nb=ns*ng*ng*16 Bytes,

where ns is the number of slices and ng the number of grid points.

For the electron distribution it is

Nb=ns*ne*48 Bytes,

with ne the number of macro particles per slice. Both numbers should be added up and for safety multiplied by a factor of 2 for some overhead (aligning arrays in memory, temporary working arrays, arrays to buffer the output information etc.). The memory request will be distributed over the nodes. Non time-dependent simulation should be small enough to run on any computer.

In time-dependent runs the number of slices are equally distributed over all cores. The number of slices are even increased to guarantee symmetry, extending the time-window of the simulations. More information about that can be found in the next section. Often it is useful to calculate the number of generated slices in advance, in particular if advanced option such as subharmonic conversion are used. In the case of subharmonic conversion the slices per core should be an integer of the subharmonic number. Otherwise artefacts of numerically enhanced bunching causes wrong results.

GENESIS 1.3 - Main Input Deck

Main Input File

Unlike older version, which supported only a single namelist as input, the latest version splits up the namelist and processes them sequentially as they appear in the file. Therefore the order is important, e.g. you cannot define a time window after the electron beam or the field has been already generated. On the other hand the code supports multiple tracking in one run. For that the particle and field distribution is kept in memory and then reused in the next tracking. If a fresh bunch is required the old has to be discarded and then a new one has to be generated. In that sense it is possible to combine steady-state and time-dependent run in one input deck by the sequence: generate field, generate beam, track, define time window, generate beam, generate field, and track.

The namelists themselves always start with the ampersand & and the name of the name list and are terminated with &end. Each line consists out of an assignment of a supported variable, e.g npart = 2048 in the namelist &setup. Empty lines and lines, starting with the pound symbol # are ignored. If the same variable occurs more than once the latest occurrence is used for the calculation. If Genesis encounters a variable name, which it does not recognize it stops execution and prints out a list of the supported variables.

The following describes all supported namelist with their variables, including its required format and default value.

Supported Namelists

Back

setup

The namelist setup is a mandatory namelist and should be the first in the input deck. It contains the basic parameters to control the simulations. It can only be called once. If the user want to change some parameter the namelist alter_setup should be used.

Back

alter_setup

A namelist to change some parameters within the simulation, which have been defined alread by the setup-namelist. The change values are stored in the setup module so that for another invocation of alter_setup some defaults values are use which have been defined in the preceding call of alter_setup

Back

lattice

This namelist is used to change the raw lattice from the lattice file, such as generating errors in the position of the elements. The namelist can be defined several times to add more than one error source to the lattice.

Back

time

This namelist defines the time window/range for simulation with more than just one slice. For reference the complementary axis of the undulator axis, which is normally the position in the time frame, is expressed in a position s. Normally everything is aligned to the origins = 0, in particular when external distributions are imported. Note that for parallel execution the number of slices per core must be the same for an efficient writing of the output files. Therefore Genesis extends the time-window to symmetrize the number of slices per core by extending it towards larger values of s. As an example, with XLAMDS=1e-6 and a length SLEN=20e-6 a call of Genesis with 24 cores would generate a time-window of 24 microns because each core would have one slice, while 15 cores would expand it to 30 microns with 2 slices per core each.

This module defines also scans in either field or beam parameters if the corresponding flag is set. Technically it generates the beam and field as for time-dependence but disables slippage during simulations. That way the radiation field is kept in the same slice, acting as steady-state simulations.

Back

profiles

Profiles are defining a dependence on the position in the time frame, which then can be used to defined the behavior of various parameters such as slice emittance, energy spread etc. All profiles are in common that they have to have a label with which they are referred to in other namelists. To indicate the reference to a profile and thus allows to distinguish Genesis between normal numbers the label name must have the additional character ’@’ in front. E.g. if the name of the label is energy then in the beam name list it is referred to by gamma = @energy.

profile_const

profile_gauss

profile_step

profile_polynom

profile_file

Back

sequences

Sequences act similar to profiles that they define a series of values which can be used to control dependence of certain parameters. While for profiles these are mostly properties of the electorn beam and radiation field, sequences are used for occurences of beamline elements for specific parameters. Examples are applying a taper gradiant to the undulator offset or add random offsets to the quadrupole positions. All sequences have in common that they have to have a label with which they are referred to in the lattice. To indicate the reference to a sequence and thus allows to distinguish Genesis between normal numbers the label name must have the additional character ’@’ in front. E.g. if the name of the label is taper then in the parameter list of the modulator element it is referred to by aw = @taper. A sequence is evoked for each occurence of the reference. As an example in a line which is 6 times a Fodo Cell which each space between the quadrupoles hosting an undulator, a reference by the undulator field will evoke the first 12 elements of the sequence.

sequence_const

sequence_polynom

sequence_power

sequence_random

Back

beam

This namelist initiates the generation of the particle distribution to be kept in memory. Any time-dependence has to be defined before calling this namelist.

Back

field

This namelist initiate the generation of the field distribution. It differs in one point from the generation of the beam. It can be called multiple times. If the variable accumulate is set to true, it does not delete the previous distribution but adds up the wavefronts. That way higher mode content in either spatial and time direction can be created.

Back

importdistribution

This namelist controls the import of an external distribution which are generated from Elegant. The file has to be in HDF5 format. In the distribution is a shell script to convert an Elegant sdds-output file into the HDF5 format. The distribution has to provide all 6 dimensions while the charge is supplied in this namelist. When imported the longitudinal position is changed so that the last particles is at s = 0 micron.

Note that this namelist will be expanded in the future, to enable tilts and match/center to a core part of the beam

This HDF5 file file should have the following datasets: - x is the horizontal coordinate in meters - y is the vertical coordinate in meters - xp = px/pz is the dimensionless trace space horizontal momentum - yp = py/pz is the dimensionless trace space vertical momentum - t is the time in seconds - p = relativistic γ * β, which is the total momentum divided by mec

Back

importbeam

The modules controls the import of a Genesis 1.3 particle file to replace the internal generation of the particle distribution (note that the module beam should not be called). The routine defines also the parameter for a time-dependent run if the time-namelist hasn’t been defined yet.

Back

importfield

The modules controls the import of a Genesis 1.3 field file to replace the internal generation of the field distribution (note that the module field should only be called afterwards with the accumulate-option enabled). The routine defines also the parameter for a time-dependent run if the time-namelist hasn’t been defined yet.

Back

importtransformation

Once an electron distribution is generated the namelist can be used to manipulate the distribution by shifting the particle by the vector dr or applying the transport matrix R. The applied transformation is r1 = R*r0+dr, where r0 is the initial particle vector and r1 the final one. The transformation assumes the standard 6D vector of (x,x',y,y',s,delta). the supplied vector and matrix must have the corresponding shape (6 or 6x6). The user can supply more than one vector or matrix, e.g. sampling at various positions s. Then the transformation used interpolated values. Note that in the case of transport matrices and interpolated matrix does not preserve the emittance. In this case a high sample rate should be supplied to reduce this effect to a minimum. Genesis will check the shape of the transport vector and matrices. If the rank is higher than needed (e.g. 2x6x6 for a transport matrix) then it assumes the first index refers to the sample along the s-axis. In this case the sample distance slen should be also specified. In the case that n=1 or slen=0 only a global transformation is applied.

efield

This namelist controls the long and short range space charge fields. The long range corresponds to any length scale longer than the slice length of the simulation, while the short range is on the resonant wavelength scale. Numerically they are treated differently. The calculation for the short range is done on a radial-azimuthal grid, centered to the centroid position of the electron slice, while the long range is the sum of the space charge field in the rest frame where each slice is treated as a uniform disk.

Back

sponrad

This enables the effect of spontaneous radiation outside of the frequency band of the FEL simulation.

Back

wake

Genesis supports the calculation of three types of wakefields by specifying the typical input parameters (e.g. gap length for the geometric wakefield). It first solves the single particle wake and then convolutes with the current distribution. Therefore it follows the change in the wakepotential if a chirped beams undergoes a compression in a chicane. In addition an external loss factor can be supplied, which can also refer to a profile. In this case it is treated as the full wake and subtracted from the particle energy directly.

Note that this functionality hasn’t been fully tested yet or optimized for rapid calculation

Back

sort

An empty namelist with no variables. It initiates the sorting and redistribution of particles only if one-for-one simulation is enabled. Note that harmonic conversion will automatically invokes sorting and therefore does not need to be called explicitly.

Back

write

With this name list the field or particle distributions are dumped. The placeholder character @ can be used to refer to the rootname of the simulation run, e.g. field = @.final

Back

track

This namelist initiate the actually tracking through the undulator and then writing out the results. Normally all parameter should be defined before or defined in the lattice but the namelist allows some ’last minute’ change of the behavior of the code

Back

Internal namelists

The following namelists were not previously documented and have been extracted from the source code. These may not have the same level of support when compared to the above section.

alter_field

Field manipulator (TODO).

Note that the namelist field_manipulator is deprecated and will be removed in the future. Use alter_field instead.

profile_file_multi

Generates profile objects <label_prefix>.gamma, <label_prefix>.delgam, <label_prefix>.current, etc., each one corresponding to one &profile_file.

sequence_list

A sequence of values given as a string.

sequence_filelist

A sequence list with data in a file.

add_plugin_fielddiag

Optionally-compiled plugin for field diagnostics.

add_plugin_beamdiag

Optionally-compiled plugin for beam diagnostics.

GENESIS 1.3 - Lattice File

The Lattice File

In comparison to previous versions of Genesis the definition of the undulator lattice is now completely defined in a lattice file. The main input file just refers to it and might change some parameters, such as adding undulator errors etc. Another major change is that the rigid scheme of fixed integration steps is now broken up. The lattice does not need to be aligned to a single integration step. Instead the lattice can be closer now to the real lattice.

The format of the lattice file is similar to other codes such as ELEGANT or MADX, which makes it somehow easier to convert between the formats. In general the syntax is the following:

label: element type={parameter=value[,···]};

Following beamline elements are currently supported: undulator, quadrupole, drift, corrector, chicane, phaseshifterandmarker. For the parsing of the elements Genesis only consider the first 4 letters. Therefore, undulator and unduas element name are both valid. This applies only for the elements. Other tags, such as labels and parameter have to be exact. Upper or lower cases are ignored because all letters are converted to lower case prior to parsing.

Supported Lattice Elements

Labels are used to identify elements and are referred to in the line element. More information is given at the end of this section.

undulator

Back

drift

Back

quadrupole

Back

corrector

Back

chicane

Back

phaseshifter

Back]]

marker

Back

line

The line uses the labels to define the order of the elements in the beam line. Elements can be referred to multiple times. Each time the line element creates an individual copy so that they are not treated as a single entity. That allows that in a later stage the elements can be changed differently, e.g. when errors in the alignment are generated. The line element can also contain other line elements. Genesis 1.3 is unrolling the nested references, however stops after an iteration depth of 10. This catches the error that one line element uses another and vice versa.

Elements can be duplicated by a preceding multiplication. The following is an example

FODO: Line = {F,DRI,D,DRI};
LAT: Line = {6*FODO};

There is one difference between Genesis and Elegant/Madx. It allows a superposition of secondary elements (everything except of undulator modules) so that correction and focusing can be superimposed onto the undulator field. An example is

UND: Undulator = {aw=1, lambdau=0.02, nwig=100};
FODO: Line = {UND,F@0.2,D@1.2};

The postfix @ with the position in meter places the element directly there. Note that it also resets the counter. For a 10 cm long quadrupole the next position after F@0.2 would be 0.3 m. To avoid overlapping with succeeding elements it is better to define the pointer with a marker element, e.g. the upper example can be improved with:

UND: Undulator = {aw=1, lambdau=0.02, nwig=100};
FODO: Line = {UND,F@0.2,D@1.2,M@2.0};
LAT: Line = {6*FODO};

If the absolute position places the element outside of an existing element than the missing space is padded with a drift section.

Back

GENESIS 1.3 - Output Files

Beside the input and lattice file, Genesis uses exclusively the HDF5 format for the output files, which are the main output file, and the particle and field dump. HDF5 is a well supported format by many programs or programming languages which makes it easy to read in the data. As an example, Matlab requires only a single line to read an entire dataset such as the 2d array for the power, with sample points along the undulator and beam frame, already converted to the right data type. This should make it easy to write your own postprocesser. Nevertheless the Genesis distribution comes with some Matlab routines to ease the parsing and display of the output files.

Main Output File

The main output file is written when ever the&tracknamelist is called. The name is given by the specified rootname and the extension’.out.h5’for the first call. If there are more than one tracking commands the root is extended by the run number, such as’.Run3.out.h5’ for the third time of tracking.

In the root level of the HDF5 files there are multiple groups, to organize the output data. The group ’Global’ list the basic configuration of the simulation such as reference energy and wavelength or whether it is a time-dependent or scan run. The group Lattice contains all lattice information. The undulator strength, quadrupole field and other are resolved with the resolution of the requested integration step size, which is given in the dataset dz. Most data here have a direct correspondance with the input data. Exceptions are ‘gradx’ and ‘grady’ since they are scaled by ‘ku’. For the z-position there exist two dataset. The regular onezhas the same length and describes the lattice quantities from the positionz[i]toz[i]+dz[i] of the i-th integration step. The dataset zplot is used for plotting the beam or field parameters along the undulator. Note that those are evalutated before the integration started, so that there can be one more entry than the lattice datasets. Also if the output is reduced by the output step option in the tracking command, the length of zplot is shorter because it has to match the length of the beam and field parameters. Another group is Meta which contains some additional information, which are not stricktly related to the input case. These are the version number, creation date and user, which has evoked the simulations.

The main data is contained in the Beam and Field record. In the case that additional harmonics have been selected, there are additional Field groups, where the harmonic number has been added. As an example Field3 would refer to the third harmonic. The Beam group contains parameters which are evaluated at each integration steps. They are: energy, energy spread, bunching, bunching phase, centroid position in x, y, px and py and the size in x and y. Other parameters are only evaluated at the beginning, which are the optical function, emittance and current profile, but in the future they might be becoming also larger, e.g. when sorting is enabled and the current profile can change. In theFieldgroup one can find the power, position and size in x and y as well as the on-axis intensity and phase in the near field (central grid point) or far field (summation over all grid points)

In general the units of the datasets should be given as attributes to the given dataset. This is not yet implemented.

Particle and Field Dump.

Particle dumps are following the data structure that each slice has its own 6D distribution with the datasets gamma, theta, x, y, px, and py. In additions the local current value is written as well. The slice number is encoded in the group name, which is the composition of slice and the 6 digit representation of the slice numbers. Preceding spaces are changed to zeros. E.g. the group name of the 7th slice is slice000007. The total number of slices is given by the dataset slicecount. In addition some extra information is given on the root level of the reference frame are defined by the starting position refposition and the sample length per slice slicespacing. The reference length slicelength can be used to convert the ponderomotive phase into a longitudinal position in units of meter. Whether the distribution has been generated with beamlets or resolving all electrons are indicated by the parameters beamletsize and one4one.

The field dump has very similar structure than the beam dump, except that instead of slicelength the field is wavelength to distinguish between the fundamental or harmonic radiation, while the beam is always measured against the fundamental wavelength for the ponderomotive phase. The field gridsize defines the extension of the 2D grid from the origin to the edge along of the major axis. The slice groups contains the real and imaginary part of the wavefront, however for programming reason the data record is one dimensional with ngrid2 elements. Any processing or display should convert it to a symmetric 2D array.

Particle Distribution

Genesis can import particle distribution which are generated by Elegant. However it does not support the parsing of SDDS files directly. Instead, it provides a simple shell script to convert the typical SDDS distribution into a HDF5 file. This script expects that the SDDS toolkit is installed because it extracts the columns t, p, x, y, xp, and yp from the SDDS files and converts them into datasets with the same name in the HDF5 file. The short program will add the extension’.h5’ to the newly created file. This format is the one Genesis expects to be imported. The corresponding charge is supplied in the namelist and therefore does not need to be part of the HDF5 file.

The Postprocessor XGENESIS

Although the output format of Genesis is HDF5, where entire datasets can be read with a single line in Matlab, the source code distribution also contains some Matlab functions, which help with the postprocessing. They can be found in the directory xgenesis from the root directory of the source code. It is recommended that the search path of Matlab extends to that directory or that the files are copied to a locations where the search path already points to.

The following is a brief description of the existing functions. More will come in the future.

xgeninit.

The routine requires only the name of the output file, which then is parsed for the most essential data, which is the size inzandsand the dataset tree structure. This function needs to be called once. All other functions will make use of the data, which has been parsed here. If another file needs to be read then xgeninit needs to be called again.

xgenplot

The main routine to display data from the output file and returns the data. It can generate multiple plots at the same time and the return data type is a cell array, with each element referring to a dataset in the plot. The dataset itself is a cell array as well, where the first element is the x-coordinate and the second the y.

The function requires up to three input arguments. In special cases, e.g. results from steady-state simulations some options are restricted such as plotting along the time-window coordinate is not meaningful and thus not supported.

The first element mostly refers to the corresponding dataset in the input deck. The function uses regular expression to match the dataset names with the requested plot data. As an example plotting size will plot the sizes in x and y of the electron beam and each supported radiation field, so at least 4 plots and even more if harmonics were included. To restrict the plots the requested plot can be more explicit, according to the tree structure in the output file. As an example the input argument /Beam/.size would plot the x and y sizes of only the electron beam while Field.*/.size does it for the radiation of the fundamental and all harmonics. Besides the datasets in the output file there is one derived dataset, which is the spectrum. The postprocessor can calculate it either from the near field intensity and phase on axis or the equivalent pair in the far field. If only spectrum is requested than both are plotted. To select one of them, just specify as it would be done for the intensity, e.g. spectrum-nearfield.

If no further arguments are supplied then the first slice of the specified data is plotted along the undulator axis. This is in particular enforced for any lattice function, such as the undulator field. Also if the output data is from a steady-state file then the output is always along undulator axis, despite that a profile might be requested.

The second argument specify the plotting direction: either along undulator direction or along bunch frame or frequency. If the data is a 2D array, e.g. such as the power after a time-dependent run, than plotting a line need as the third argument the specification of the orthogonal position. Here the post processor chooses the line, which lies the closest to the specified point. The default direction and plotting mode is normal plotting along the undulator. To plot the power as an example at 3 μm of the bunch frame the plot command is

xgeninit('power','normal',3e-6)
```.

The direction along the bunch frame is indicated with `profile` such as

xgeninit(‘power’,‘profile’,11.5) ```

to plot around the position 11.5 m within the undulator lattice.

For 2D datasets from time-dependent simulations or scansxgenplotallows some condensed plotting along the undulator: max for the maximum value of the given profile, mean the mean value, and rms the rms value. The evolution of the radiation bandwidth is calculated best, using the rms option. In fact, RMS values are only meaningful for primary datasets, which are power profile, spectrum and current profile. For all other parameters, such as beam size it is recommended to use the mode weighted which is defined as


$$\bar{P}(z)=\frac{\int P(s,z)\cdot W(s,z) ds}{\int W(s,z)ds}$$

where P is the parameter to be display and W the weighting function. For electron beam parameters it is the current while for radiation parameter it is the power profile.

For a two-dimensional output the modes 2d and 2dnorm can be used. The latter differs from the former that for each step along the undulator the resulting profile is normalized by its mean value. This allows to exclude the dominant exponential change in some parameters such as power, bunching or energy.

xgenwigner

This function calculates the 2D Wigner distribution at a position within the undulator, which is supplied as the input argument. The Wigner distribution is a very compact display of time and spectral properties, namely the projection onto the time axis is the power profile and the projection on the frequency axis is the power spectrum.

Where to Find Further Information

https://gitlab.ethz.ch/Genesis/Genesis4

S. Reiche, ”Numerical Studies for a Single Pass High Gain Free-Electron Laser”, DESY print, DESY-THESIS-2000-012 (2000)

FEL Basics

Numeric Basics

Other software refences