GENESIS 1.3

https://github.com/svenreiche/genesis-1.3-version4
Admin
GENESIS 1.3 is a scientific code that simulates the interaction of electrons in undulator magnetic...
Tokens:32,487
Snippets:256
Trust Score:7.1
License:GPL-3.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### Namelist: setup

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/MAIN_INPUT.md

Defines the mandatory configuration parameters for initializing a Genesis 1.3 simulation.

```APIDOC
## SETUP Namelist

### Description
The `setup` namelist is mandatory and must be the first in the input deck. It initializes core simulation parameters including file paths, physical constants, and numerical integration settings.

### Method
N/A (Configuration Input)

### Parameters
#### Configuration Parameters
- **rootname** (string) - Optional - Prefix for output files.
- **outputdir** (string) - Optional - Directory for simulation output.
- **lattice** (string) - Optional - Path to the undulator lattice description file.
- **beamline** (string) - Optional - Name of the beamline defined in the lattice file.
- **gamma0** (double) - Optional - Reference energy (default: 11350.3).
- **lambda0** (double) - Optional - Reference wavelength in meters (default: 1e-10).
- **delz** (double) - Optional - Preferred integration stepsize in meters (default: 0.015).
- **seed** (int) - Optional - Random number generator seed (default: 123456789).
- **npart** (int) - Optional - Macro particles per slice (default: 8192).
- **nbins** (int) - Optional - Number of beamlets for shot noise (default: 4).

#### Simulation Flags
- **one4one** (bool) - Optional - Enable one-for-one electron resolution (default: false).
- **shotnoise** (bool) - Optional - Enable shot noise calculation (default: true).
- **beam_global_stat** (bool) - Optional - Enable global beam statistics output (default: false).
- **field_global_stat** (bool) - Optional - Enable global field statistics output (default: false).
- **exclude_spatial_output** (bool) - Optional - Suppress spatial datasets (default: false).
- **exclude_fft_output** (bool) - Optional - Suppress FFT-based field output (default: false).
- **exclude_intensity_output** (bool) - Optional - Suppress intensity/phase output (default: false).
- **exclude_energy_output** (bool) - Optional - Suppress beam energy statistics (default: false).

### Request Example
&setup
  rootname = "test_run"
  gamma0 = 10000.0
  lambda0 = 1.5e-10
  npart = 4096
  shotnoise = true
/
```

--------------------------------

### Install System Dependencies for Genesis 1.3

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/build_notes/ubuntu_22.04/README.md

Installs the required build tools, MPI, HDF5, and FFTW3 libraries on Ubuntu 22.04.

```bash
sudo apt-get install build-essential
sudo apt-get install cmake
sudo apt-get install git
sudo apt-get install libopenmpi-dev
sudo apt-get install libhdf5-openmpi-dev
sudo apt-get install pkg-config
sudo apt-get install libfftw3-dev
```

--------------------------------

### GENESIS 1.3 Setup Namelist

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Defines the mandatory '&setup' namelist for GENESIS 1.3 simulations. It configures essential simulation parameters such as output root name, lattice file, reference energy, wavelength, integration step, and particle/noise settings.

```fortran
&setup
rootname=simulation          # Base name for all output files
lattice=undulator.lat        # Lattice file containing beamline definition
beamline=FEL                 # Name of beamline to use from lattice file
gamma0=11357.82              # Reference energy (electron rest mass units)
lambda0=1e-10                # Reference wavelength in meters (1 Angstrom)
delz=0.045                   # Preferred integration step size in meters
seed=123456789               # Random number generator seed
npart=8192                   # Macro particles per slice (multiple of nbins)
bins=8                      # Number of beamlets for shot noise
shotnoise=1                  # Enable (1) or disable (0) shot noise
one4one=false                # Enable one-for-one particle tracking
beam_global_stat=true        # Output global beam statistics
field_global_stat=true       # Output global field statistics
exclude_spatial_output=false # Suppress spatial output to reduce file size
exclude_fft_output=false     # Suppress FFT-based outputs
&end
```

--------------------------------

### Example Simulation Output Log for Plugin Initialization

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/misc/plugin_demo/README.md

Illustrative log output from a Genesis simulation showing the initialization process of the 'demo' plugin. It details the loading of the shared library and the registration of diagnostic objects.

```text
[..]
Running Core Simulation...
Time-dependent run with 2048 slices for a time window of 2.5392 microns
Initial analysis of electron beam and radiation field...
Setting up DiagFieldHook for libfile="./libdemo.so", obj_prefix="plugindemo"
DiagFieldHook::init
Rank 0: Loaded the library, handle is 0x2338c20
Got the library
Rank 0: Factory location is 0x2b4316dd0646
Rank 0: Destroyer location is 0x2b4316dd0694
Rank 0: Calling factory
Rank 0: Calling get_infos
Rank 0: Got class instance
   info_txt="Demo for plugin diagnostics"
   do_multi=0
   provides object named my_power
   provides object named abc
DONE: Registered DiagFieldHook
  Calculation: 0% done
[..]
```

--------------------------------

### Install Dependencies on macOS

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/INSTALLATION.md

Commands to install required libraries and compilers for Genesis 4 on macOS using MacPorts or Homebrew.

```bash
# MacPorts
sudo port install gcc12
sudo port select gcc mp-gcc12
sudo port install hdf5 +openmpi
sudo port install fftw-3

# Homebrew
brew install hdf5-mpi
brew install cmake
brew install pkg-config
```

--------------------------------

### Execute Simulation Tracking

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example1-SteadyState/README.md

The command block used to initiate the tracking process after the setup, field, and beam parameters have been defined.

```asm
&track
&end
```

--------------------------------

### Configure Genesis 1.3 Simulation Setup

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example1-SteadyState/README.md

Defines the core simulation parameters including root filenames, lattice files, reference wavelength, and energy. This block is mandatory and must appear first in the input file.

```asm
&setup
rootname=Example1
lattice=Example1.lat
beamline=FEL
lambda0=1e-10
gamma0=11357.82
delz=0.045000
shotnoise=0
nbins = 8
&end
```

--------------------------------

### Install Genesis 4 via Conda

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/INSTALLATION.md

Commands to create a conda environment and install the Genesis 4 package with either OpenMPI or MPICH support.

```bash
conda create -n genesis4 genesis4=*=mpi_openmpi*
conda create -n genesis4 genesis4=*=mpi_mpich*
conda activate genesis4
genesis4 --help
```

--------------------------------

### Output File Structure After Plugin Execution

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/misc/plugin_demo/README.md

Example output from `h5ls -r` command showing the structure of the simulation output file after the 'demo' plugin has run. It lists the newly created groups and datasets, including those generated by the plugin.

```bash
[..]
/Field/plugindemo        Group
/Field/plugindemo/abc    Dataset {26, 2048}
/Field/plugindemo/my_power Dataset {26, 2048}
/Field/power             Dataset {26, 2048}
[..]
```

--------------------------------

### CMake Project Setup and Compiler Configuration

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/CMakeLists.txt

Initializes the CMake project, sets C++ standard to C++17, disables extensions, and configures build verbosity. It also sets compiler flags for debugging.

```cmake
cmake_minimum_required(VERSION 3.12)
project(Genesis_1_3_Version4 CXX C)

option(USE_DPI "Use diagnostic plugin interface" OFF)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_EXTENTIONS OFF)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_VERBOSE_MAKEFILE OFF)
# set(CMAKE_INSTALL_RPATH "/usr/local/lib")
#set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra")
#set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g")

# developer options
set(CMAKE_VERBOSE_MAKEFILE ON)
add_compile_options(-g)

# OpenMPI: preprocessor macro to disable C++ interface (then we don't have to link libmpi_cxx)
add_compile_definitions(OMPI_SKIP_MPICXX)
```

--------------------------------

### Install GENESIS 1.3 via Conda

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Installs GENESIS 1.3 using Conda, supporting both OpenMPI and MPICH versions. It involves creating a new Conda environment and activating it.

```bash
conda create -n genesis4 genesis4=*=mpi_openmpi*
conda activate genesis4
gensis4 --help
```

```bash
conda create -n genesis4 genesis4=*=mpi_mpich*
conda activate genesis4
gensis4 --help
```

--------------------------------

### Steady-State FEL Simulation Setup

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Configuration for a steady-state Free-Electron Laser (FEL) simulation. It specifies the lattice file, beamline, particle energy, and parameters for field propagation and beam characteristics.

```genesis
# Input file: steady_state.in
&setup
rootname=steady_state
lattice=fel.lat
beamline=FEL
gamma0=11357.82
lambda0=1e-10
delz=0.045
shotnoise=0
nbins=8
&end

&lattice
zmatch=9.5                   # Match to periodic FODO cell
&end

&field
power=5e3
dgrid=2e-4
ngrid=255
waist_size=30e-6
&end

&beam
current=3000
delgam=1.0
ex=4e-7
ey=4e-7
&end

&track
&end

```

--------------------------------

### Optimize Output and Performance with Setup Namelist

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example3-TimeDependent/README.md

Configures simulation output and performance by controlling global statistics and excluding spatial or FFT data. 'field_global_stat' and 'beam_global_stat' enable global statistics, while 'exclude_spatial_output' and 'exclude_fft_output' suppress spatial information and FFT data, respectively, potentially speeding up the simulation.

```asm
&setup
...
field_global_stat = true
beam_global_stat = true
exclude_spatial_output = true
exclude_fft_output = true
&end
```

--------------------------------

### Configure SASE Simulation Parameters

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example3-TimeDependent/README.md

Sets up parameters for a SASE simulation by initializing radiation power to zero and setting the shotnoise parameter to one within the setup namelist. This configuration is crucial for initiating a Self-Amplified Spontaneous Emission simulation.

```asm
&setup
...
radiation_power = 0
shotnoise = 1
...
&end
```

--------------------------------

### Define Genesis 1.3 Sequences

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/LATTICE.md

Examples of defining different sequence types including constant, polynomial, power, and random distributions to manage parameter values in the lattice.

```Genesis 1.3
VAL: SEQUENCE = {type = const, c0 = 3.5};
VAL: SEQUENCE = {type = polynom, c0 = 3.5, c1=0.0, c2=0.0, c3=0.0, c4=0.0};
VAL: SEQUENCE = {type = power, c0 = 3.5};
VAL: SEQUENCE = {type = random, c0 = 3.5, dc=0.001};
```

--------------------------------

### Define Genesis 1.3 Beamlines

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/LATTICE.md

Examples of defining beamlines using the line element, including element multiplication, nesting, and absolute positioning using the @ operator.

```Genesis 1.3
FODO: Line = {F,DRI,D,DRI};
LAT: Line = {6*FODO};
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};
```

--------------------------------

### Time-Dependent SASE Simulation Setup

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Configuration for a time-dependent Self-Amplified Spontaneous Emission (SASE) FEL simulation. Includes parameters for shot noise, bunch length, energy chirp, and global statistics.

```genesis
# Input file: sase.in
&setup
rootname=sase_simulation
lattice=fel.lat
beamline=FEL
gamma0=11357.82
lambda0=1e-10
delz=0.045
shotnoise=1                  # Enable shot noise for SASE
nbins=8
beam_global_stat=true
field_global_stat=true
exclude_spatial_output=true
exclude_fft_output=true
&end

&lattice
zmatch=9.5
&end

&time
slen=20e-6                   # 20 micron bunch length
sample=3                     # Sample every 3 wavelengths
&end

&profile_gauss
label=current
c0=2500
s0=10e-6
sig=6e-6
&end

&profile_polynom
label=energy
c0=11347
c1=1e7
&end

&field
power=0
dgrid=2e-4
ngrid=255
waist_size=30e-6
&end

&beam
current=@current
gamma=@energy
delgam=1.0
ex=4e-7
ey=4e-7
&end

&track
output_step=3
&end

```

--------------------------------

### Define Electron Beam Parameters

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example1-SteadyState/README.md

Configures the electron beam characteristics such as current, energy spread, and normalized emittance. These values can be used to override defaults derived from the setup or lattice.

```asm
&beam
current=3000
delgam=1.000000
ex=4.000000e-07
ey=4.000000e-07
&end
```

--------------------------------

### GENESIS 1.3 Time Window Namelist

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Configures the '&time' namelist for time-dependent simulations in GENESIS 1.3. It specifies the starting point, length, sampling rate, and mode (time-dependent or scan) of the time window.

```fortran
&time
s0=0                         # Starting point of time window in meters
slen=20e-6                   # Length of time window in meters (20 microns)
sample=3                     # Sample rate in units of reference wavelength
time=true                    # Enable time-dependent (true) or scan mode (false)
&end
```

--------------------------------

### Plotting Simulation Data with xgenplot

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/XGENESIS.md

Demonstrates how to use xgenplot to visualize simulation data. The first example plots power along the undulator axis at a specific bunch frame position, while the second plots a profile at a specific undulator lattice position.

```MATLAB
xgeninit('power','normal',3e-6);
xgeninit('power','profile',11.5);
```

--------------------------------

### HGHG Seeded FEL Simulation Setup

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Configuration for a High-Gain Harmonic Generation (HGHG) seeded FEL simulation. It includes parameters for energy modulation, chicane, and particle distribution statistics.

```genesis
# Input file: hghg.in
&setup
rootname=hghg
lattice=hghg.lat
beamline=FEL
lambda0=53e-9
gamma0=1500
delz=0.038
shotnoise=1
npart=65536
&end

&lattice
zmatch=5.32
&end

&time
slen=53e-6
sample=1
&end

&profile_gauss
label=current
c0=100
s0=26.5e-6
sig=10e-6
&end

&profile_gauss
label=emod
c0=0.7
s0=26.5e-6
sig=20e-6
&end

&field
power=0
dgrid=2e-3
ngrid=255
waist_size=200e-6
&end

&beam
current=@current
delgam=0.1
ex=4e-7
ey=4e-7
&end

# Apply energy modulation and chicane transformation
&alter_beam
dgamma=@emod                 # Energy modulation amplitude
lambda=265e-9                # Seed laser wavelength
r56=1.1e-4                   # Chicane R56 in meters
&end

# Dump particle distribution before tracking
&write
beam=hghg_beam_dump
&end

&track
&end

```

--------------------------------

### Configure Beam-Frame with Time Namelist

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example3-TimeDependent/README.md

Defines the beam-frame parameters such as total length and sample rate. The sample rate influences spectral bandwidth and must be compatible with the integration step size to ensure proper interaction between field and electron slices. A sample rate of 3 is used in the example.

```asm
&time
slen = 20e-6
sample = 3
&end
```

--------------------------------

### Parse Genesis Simulation Output with Python

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example3-TimeDependent/README.md

A Python script to parse the output file generated by Genesis simulations. This script requires matplotlib and h5py packages to be installed. It generates plots for time-dependent beam parameters, pulse energy, and radiation profiles.

```python
import matplotlib.pyplot as plt
import h5py

# Example of how to read the output file (replace with actual parsing logic)
# This is a placeholder and needs to be implemented based on the Genesis output format.

def parse_genesis_output(filepath):
    # Placeholder for parsing logic
    print(f"Parsing file: {filepath}")
    # Example: Open HDF5 file if Genesis outputs in HDF5 format
    # with h5py.File(filepath, 'r') as f:
    #     # Access data groups and datasets
    #     pass
    pass

def plot_beam_parameters(data):
    # Placeholder for plotting beam parameters
    print("Plotting beam parameters...")
    # plt.figure()
    # plt.plot(data['time'], data['current'], label='Beam Current')
    # plt.plot(data['time'], data['energy'], label='Energy at Start')
    # plt.xlabel('Time')
    # plt.ylabel('Value')
    # plt.title('Time-dependent Beam Parameters')
    # plt.legend()
    # plt.show()
    pass

def plot_pulse_energy_and_intensity(data):
    # Placeholder for plotting pulse energy and far field intensity
    print("Plotting pulse energy and far field intensity...")
    # plt.figure()
    # plt.semilogy(data['z'], data['pulse_energy'], label='Pulse Energy')
    # plt.semilogy(data['z'], data['far_field_intensity'], label='On-axis Far Field Intensity')
    # plt.xlabel('Propagation Distance (z)')
    # plt.ylabel('Value')
    # plt.title('Pulse Energy and Far Field Intensity')
    # plt.legend()
    # plt.show()
    pass

def plot_radiation_profile(data):
    # Placeholder for plotting radiation profile
    print("Plotting radiation profile...")
    # plt.figure()
    # plt.imshow(data['radiation_profile'], aspect='auto', extent=[data['z_min'], data['z_max'], data['x_min'], data['x_max']])
    # plt.colorbar(label='Power')
    # plt.xlabel('Position (x)')
    # plt.ylabel('Propagation Distance (z)')
    # plt.title('Radiation Profile')
    # plt.show()
    pass

if __name__ == "__main__":
    output_file = "Example3.out" # Replace with your output file name
    # Assuming Example3.py is the script name, and it parses Example3.out
    # The actual parsing logic needs to be implemented here.
    # For demonstration, we'll just print messages.
    print("Running Genesis output analysis script.")
    print("Ensure 'matplotlib' and 'h5py' are installed: pip install matplotlib h5py")
    
    # Placeholder for data loading and processing
    # parsed_data = parse_genesis_output(output_file)
    # if parsed_data:
    #     plot_beam_parameters(parsed_data)
    #     plot_pulse_energy_and_intensity(parsed_data)
    #     plot_radiation_profile(parsed_data)
    
    print("Script finished. Replace placeholder functions with actual parsing and plotting logic.")

```

--------------------------------

### Include Directories and Build Information Output

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/CMakeLists.txt

Sets up include directories for project headers and the generated version header. It also prints build information, including compiler paths and used libraries, to the console during the build process.

```cmake
include_directories(include)
include_directories(${CMAKE_CURRENT_BINARY_DIR}/include)


# some status print out before compilation
message(STATUS "Build Info:")
message(STATUS "C++ Compiler: ${CMAKE_CXX_COMPILER}")
message(STATUS "C Compiler: ${CMAKE_C_COMPILER}")
MESSAGE(STATUS "CMAKE_C_FLAGS: " ${CMAKE_C_FLAGS} )
MESSAGE(STATUS "CMAKE_CXX_FLAGS: " ${CMAKE_CXX_FLAGS} )
Message(STATUS "Used libraries: ${_libraries}")
```

--------------------------------

### Build Demo Plugin with CMake and Make

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/misc/plugin_demo/README.md

Commands to build the demo plugin from its source code. This process generates a shared library (`.so` file) that can be linked into the simulation.

```bash
mkdir build
cd build
cmake ..
make
```

--------------------------------

### Execute Testbench in Single Process

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/misc/plugin_testbench/README.md

Run the testbench executable with a configuration file. The output is saved to plugin_data.txt.

```bash
./g4_tb demo_params.txt
```

--------------------------------

### Include Demo Plugin in Genesis Simulation Configuration

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/misc/plugin_demo/README.md

Configuration snippet to be added to the Genesis `.in` file to enable the 'demo' plugin. This specifies the library file and an object prefix for the generated data.

```fortran
&add_plugin_fielddiag
    libfile = ./libdemo.so
    obj_prefix = plugindemo
#   interface_verbose = 1
&end
```

--------------------------------

### Import External Particle Distributions

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Demonstrates how to import particle distributions from external sources, specifically Elegant simulations converted to HDF5 format. It includes parameters for charge, slice width, centering, and matching Twiss parameters.

```genesis
# First convert SDDS to HDF5 using provided script:
# bash sdds2hdf-dist-unix.sh elegant_output.sdds

&importdistribution
file=elegant_output.sdds.h5
charge=100e-12               # Total charge in Coulombs
slicewidth=0.01              # Fraction of distribution for slice reconstruction
center=true                  # Re-center distribution
gamma0=11357.82              # New center energy
match=true                   # Match to new Twiss parameters
betax=15.0
betay=15.0
alphax=0
alphay=0
settimewindow=true           # Auto-set time window from distribution
&end

```

--------------------------------

### Build GENESIS 1.3 Testbench with CMake

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/misc/plugin_testbench/README.md

Commands to configure and build the GENESIS 1.3 testbench. The -DUSE_DPI=ON flag is required to enable plugin support.

```bash
cmake -DCMAKE_BUILD_TYPE=Debug -DUSE_DPI=ON ..
make
```

--------------------------------

### Run Genesis 1.3 Command Line

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/INSTALLATION.md

Basic command to execute Genesis 1.3 with an input deck. Optional arguments allow specifying output rootname, lattice filename, and random seed.

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

--------------------------------

### Launch Genesis Simulation with MPI

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example3-TimeDependent/README.md

This command launches the Genesis simulation using mpirun with a specified number of processes and an input file. It is used for steady-state simulations tracking multiple slices.

```bash
mpirun -np 100 genesis4 Example3.in
```

--------------------------------

### Execute Testbench in MPI Environment

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/misc/plugin_testbench/README.md

Run the testbench using mpirun for parallel execution. The nslice parameter in the configuration file controls slices per process.

```bash
mpirun ./g4_tb demo_params.txt
```

--------------------------------

### Modify Simulation Input Configuration

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/build_notes/ubuntu_22.04/README.md

Adjusts the Example3.in input file to reduce resource consumption for limited hardware environments.

```diff
--- a/examples/Example3-TimeDependent/Example3.in
+++ b/examples/Example3-TimeDependent/Example3.in
@@ -19,7 +19,7 @@ zmatch=9.5
 
 &time
 slen = 20e-6
-sample = 3
+sample = 10
 &end
 
 &profile_gauss
@@ -38,7 +38,7 @@ c1=1e7.
 &field
 power=0
 dgrid=2.000000e-04
-ngrid=255
+ngrid=101
 waist_size=30e-6
 &end
 
@@ -52,5 +52,6 @@ ey=4.000000e-07
 
 &track
 output_step=3
+zstop=0.5
 &end
```

--------------------------------

### Run Genesis 1.3 Simulation

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/build_notes/ubuntu_22.04/README.md

Executes the Genesis 1.3 simulation using mpirun with 4 processes.

```bash
mpirun -np 4 /home/cl/g4/Genesis-1.3-Version4/build/genesis4 Example3.in
```

--------------------------------

### Build Genesis 1.3 with CMake

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/build_notes/ubuntu_22.04/README.md

Configures and compiles the Genesis 1.3 source code using CMake and Make.

```bash
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
```

--------------------------------

### Run GENESIS 1.3 Simulations

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Executes GENESIS 1.3 simulations using the command line. Supports single-core execution and parallel execution with MPI, including options for output file names, lattice files, and random seeds.

```bash
genesis4 input.in
```

```bash
mpirun -np 64 genesis4 input.in
```

```bash
mpirun -np 100 genesis4 -o output_name -l lattice.lat -s 12345 input.in
```

--------------------------------

### Run Genesis 1.3 with mpirun

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/INSTALLATION.md

Command to execute Genesis 1.3 in parallel using mpirun. 'xxx' specifies the number of cores. Optional arguments are the same as the single-core execution.

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

--------------------------------

### GENESIS 1.3 Profile Definitions

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Demonstrates various profile definitions used in GENESIS 1.3 for parameter dependencies within the bunch frame. Includes Gaussian current, polynomial energy chirp, step function, and loading from HDF5 files.

```fortran
# Gaussian current profile
&profile_gauss
label=current_profile
c0=2500                      # Peak current in Amperes
s0=10e-6                     # Center position in meters
sig=6e-6                     # Standard deviation in meters
&end
```

```fortran
# Polynomial energy chirp
&profile_polynom
label=energy_chirp
c0=11347                     # Constant term (gamma)
c1=1e7                       # Linear chirp coefficient
c2=0                         # Quadratic term
c3=0                         # Cubic term
c4=0                         # Quartic term
&end
```

```fortran
# Step function profile
&profile_step
label=flat_top
c0=1000                      # Value within step region
s_start=5e-6                 # Step start position
s_end=15e-6                  # Step end position
&end
```

```fortran
# Load profile from HDF5 file
&profile_file
label=external_current
xdata=beamdata.h5/s_position # Dataset for s-positions
ydata=beamdata.h5/current    # Dataset for values
isTime=false                 # Set true if xdata is in seconds
reverse=false                # Reverse lookup table order
&end
```

--------------------------------

### Build GENESIS 1.3 from Source

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Compiles GENESIS 1.3 from source using CMake, requiring MPI and HDF5 dependencies. This process involves setting up a build environment, configuring with CMake, and building the executable.

```bash
conda create -n genesis-build-env 'fftw=*=mpi_openmpi*' 'hdf5=*=mpi_openmpi*' openmpi compilers cmake
conda activate genesis-build-env
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
make -C build -j 4
ls -la build/genesis4
```

--------------------------------

### POST /profile_file_multi

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/MAIN_INPUT.md

Generates profile objects based on HDF5 look-up tables for simulation input.

```APIDOC
## POST /profile_file_multi

### Description
Generates profile objects (e.g., .gamma, .delgam, .current) corresponding to specified profile files.

### Method
POST

### Endpoint
/profile_file_multi

### Parameters
#### Request Body
- **file** (string) - Required - HDF5 filename.
- **label_prefix** (string) - Required - Prefix for each generated object.
- **xdata** (string) - Required - Path to dataset in HDF5 for s-position.
- **ydata** (string) - Required - Path to dataset in HDF5 for function values.
- **isTime** (bool) - Optional - If true, multiplies s-position by speed of light.
- **reverse** (bool) - Optional - If true, reverses the look-up table order.

### Request Example
{
  "file": "data.h5",
  "label_prefix": "beam",
  "xdata": "/pos",
  "ydata": "/val"
}
```

--------------------------------

### Configure Genesis 1.3 Post-Tracking Field Dumps

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example2-Dumps/README.md

The write namelist in the main input file allows exporting field or particle distributions after the tracking process is complete.

```asm
&write
field = dump
&end
```

--------------------------------

### Debug Plugin with GDB

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/misc/plugin_testbench/README.md

Steps to initiate a debugging session for a plugin using GDB, including setting a breakpoint on the plugin's processing method.

```bash
gdb ./g4_tb
(gdb) b DiagFieldHookedDemo::doit
(gdb) r demo_params.txt
```

--------------------------------

### Library Dependency Configuration (MPI, HDF5, FFTW)

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/CMakeLists.txt

Configures the build to find and link essential libraries such as MPI, HDF5 (parallel support preferred), and FFTW. It includes checks for compiler wrappers like h5pcc and uses PkgConfig for FFTW.

```cmake
list(APPEND CMAKE_PREFIX_PATH $ENV{FFTW_ROOT})

# container for needed librarires
list(APPEND _libraries)

# Check for macOS with MacPorts
if(EXISTS "/opt/local/bin/h5pcc")
  set(CMAKE_CXX_COMPILER /opt/local/bin/h5pcc)
endif()


if (CMAKE_CXX_COMPILER MATCHES  "h5pcc")
   Message(STATUS "h5pcc compiler wrapper found - No additional libraries needed")
else()
   Message(STATUS "h5pcc not found - looking for basic compiler")
   Message(STATUS "C++ Compiler: ${CMAKE_CXX_COMPILER}")
   Message(STATUS "C Compiler: ${CMAKE_C_COMPILER}")

   # check for MPI
   find_package(MPI REQUIRED)
   include_directories(${MPI_INCLUDE_PATH})
   Message(STATUS "MPI Found")

   # and check for HDF5
   SET(HDF5_PREFER_PARALLEL TRUE)
   find_package(HDF5 REQUIRED)
   Message(STATUS "HDF5 Found")
   Message(STATUS "Version: ${HDF5_VERSION}")
   if (TARGET HDF5::HDF5)
#       list(APPEND _libraries MPI::MPI_C hdf5_mpich)  # needed for my local computer
       list(APPEND _libraries MPI::MPI_C HDF5::HDF5)
   else()
       list(APPEND _libraries MPI::MPI_C)
   endif()
   include_directories(${HDF5_C_INCLUDE_DIRS})
   if (HDF5_IS_PARALLEL)   # this should be required - needs a better check
        Message(STATUS "Parallel HDF5 supported")
   else()
        Message(STATUS "No parallel HDF5 Support")
   endif()
endif()

# check for FFTW libraries. Cray implementation are not found but have the environmental variable FFTW_ROOT defined.
find_package(PkgConfig REQUIRED)
set(ENV{PKG_CONFIG_PATH} "$ENV{PKG_CONFIG_PATH}:$ENV{FFTW_ROOT}/lib/pkgconfig/")
pkg_check_modules(FFTW QUIET fftw3 IMPORTED_TARGET)
if (TARGET PkgConfig::FFTW)
    message(STATUS "FFTW found")
    list(APPEND _libraries PkgConfig::FFTW)
    link_libraries(PkgConfig::FFTW)
else()
        message(STATUS "FFTW not found")
        message(STATUS "Excluding FFTW specific source code")
endif()
```

--------------------------------

### Compile Genesis 4 using Conda Build Environment

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/INSTALLATION.md

Steps to create a dedicated build environment with necessary dependencies and compile the Genesis 4 binary using CMake.

```bash
conda create -n genesis-build-env 'fftw=*=mpi_openmpi*' 'hdf5=*=mpi_openmpi*' openmpi compilers cmake
conda activate genesis-build-env
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
make -C build -j 4
```

--------------------------------

### Analyze Simulation Results with Python

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Uses h5py and matplotlib to read HDF5 simulation files and visualize lattice data, power evolution, and spectral properties.

```python
import h5py
import matplotlib.pyplot as plt
import numpy as np

hid = h5py.File('simulation.out.h5', 'r')
z = hid['Lattice']['z'][()]
aw = hid['Lattice']['aw'][()]
qf = hid['Lattice']['qf'][()]
fig, ax1 = plt.subplots()
ax1.set_xlabel('z (m)')
ax1.set_ylabel('aw', color='tab:red')
ax1.step(z, aw, color='tab:red', where='post')
ax2 = ax1.twinx()
ax2.set_ylabel('k1 (1/m^2)', color='tab:blue')
ax2.step(z, qf, color='tab:blue', where='post')
plt.show()
hid.close()
```

--------------------------------

### Configure Simulation Tracking

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

The &track namelist configures the simulation run through the undulator. It defines the stopping position, output frequency, field and beam dump steps, particle sorting, periodic boundary conditions, and the field solver method.

```fortran
&track
zstop=1e9                    # Stop tracking at this position (meters)
output_step=1                # Integration steps between outputs
field_dump_step=0            # Steps between field dumps (0 = disabled)
beam_dump_step=0             # Steps between beam dumps (0 = disabled)
sort_step=0                  # Steps between particle sorting (one4one only)
periodic=false               # Enable periodic boundary conditions
fft_fieldsolver=false        # Use FFT-based field solver (more accurate, slower)
bunchharm=1                  # Bunching harmonic for output
&end
```

--------------------------------

### Configure Genesis 1.3 Periodic Tracking Dumps

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example2-Dumps/README.md

The track namelist can be configured to generate dumps at specific integration step intervals. This is useful for monitoring evolution but can generate a large volume of data.

```asm
&track
beam_dump_step = 2
&end
```

--------------------------------

### Assemble Beamline Lattice Structure

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example1-SteadyState/README.md

Uses the LINE command to organize defined elements into a FODO cell and replicate it to form the full beamline.

```asm
FODO: LINE={UND,D1,QF,D2,UND,D1,QD,D2};
FEL: LINE={6*FODO};
```

--------------------------------

### Configure Field and Beam Dumps

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Specifies intermediate output files for field and particle distributions.

```text
&write
field=intermediate_field
beam=intermediate_beam
stride=1
&end
```

--------------------------------

### CMake: Define 'demo' Shared Library

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/misc/plugin_demo/CMakeLists.txt

Defines a shared library named 'demo' for the project. This library includes source files related to field power diagnostics.

```cmake
project(demo VERSION 1.0.0 DESCRIPTION "diagdemo")
add_library(demo SHARED
	DiagFieldPowerDemo.cc
	DiagUtil.cc
)
```

--------------------------------

### Initialize Radiation Field

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example1-SteadyState/README.md

Sets the initial radiation power, grid dimensions, and waist size for the simulation. It defines the fundamental Gauss mode properties.

```asm
&field
power=5e3
dgrid=2.000000e-04
ngrid=255
waist_size=30e-6
&end
```

--------------------------------

### Configure Electron Beam Generation

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

The &beam namelist generates the electron distribution. It supports specifying mean energy, energy spread, current, emittances, beta functions, and initial particle positions and momenta. Profile references can be used for energy and current.

```fortran
&beam
gamma=11357.82               # Mean energy (or @profile_label)
delgam=1.0                   # RMS energy spread in gamma units
current=@current_profile     # Current in Amperes (or profile reference)
ex=4e-7                      # Normalized emittance in x (meters)
ey=4e-7                      # Normalized emittance in y (meters)
betax=15.0                   # Beta function in x (meters)
betay=15.0                   # Beta function in y (meters)
alphax=0.0                   # Alpha function in x
alphay=0.0                   # Alpha function in y
xcenter=0                    # Initial x centroid position
ycenter=0                    # Initial y centroid position
pxcenter=0                   # Initial x momentum (gamma*beta_x)
pycenter=0                   # Initial y momentum (gamma*beta_y)
bunch=0                      # Initial bunching factor
bunchphase=0                 # Initial bunching phase
emod=0                       # Initial energy modulation amplitude
emodphase=0                  # Initial energy modulation phase
&end
```

--------------------------------

### Analyze Simulation Results with MATLAB

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Utilizes the XGENESIS toolbox to plot power, energy, and beam characteristics from simulation output files.

```matlab
xgeninit('simulation.out.h5');
data = xgenplot('power');
data = xgenplot('power', 'normal', 10e-6);
data = xgenplot('power', 'profile', 30);
data = xgenplot('power', 'max');
data = xgenplot('energy', 'weighted');
xgenwigner(40);
xgenplot('/Beam/.size');
```

--------------------------------

### Configure Spontaneous Radiation Effects

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Enables energy loss and energy spread modeling for spontaneous radiation.

```text
&sponrad
seed=1234
doLoss=true
doSpread=true
&end
```

--------------------------------

### POST /sequence_list

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/MAIN_INPUT.md

Defines a sequence of values provided as a string for simulation parameters.

```APIDOC
## POST /sequence_list

### Description
Defines a sequence of numerical values with an optional label and default fallback.

### Method
POST

### Endpoint
/sequence_list

### Parameters
#### Request Body
- **label** (string) - Required - Label for the sequence.
- **val** (double[]) - Required - List of values.
- **default** (double) - Optional - Default value for out-of-bound indices.

### Request Example
{
  "label": "energy_steps",
  "val": [0.1, 0.2, 0.3],
  "default": 0.0
}
```

--------------------------------

### Define Current and Energy Profiles with Profile Namelists

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example3-TimeDependent/README.md

Sets up time-varying input parameters for the electron bunch, including a Gaussian current profile and a linear energy chirp. The current profile has an RMS length of 6 microns, with its peak at 10 microns. The energy chirp is defined by constant and linear terms.

```asm
&profile_gauss
label=current
c0 = 2500
s0 = 10e-6
sig = 6e-6
&end

&profile_polynom
label=energy
c0=11347.
c1=1e7.
&end
```

--------------------------------

### Configure Radiation Field Generation

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

The &field namelist generates the radiation field distribution. Parameters include wavelength, power, phase, waist position and size, grid dimensions, and harmonic number. It also supports specifying Gauss-Hermite modes and accumulation options.

```fortran
&field
lambda=1e-10                 # Wavelength (defaults to lambda0)
power=5e3                    # Radiation power in Watts
phase=0                      # Radiation phase in radians
waist_pos=0                  # Focal point position relative to undulator entrance
waist_size=30e-6             # Waist size w0 in meters
dgrid=2e-4                   # Grid half-size in meters (full grid is 2*dgrid)
ngrid=255                    # Number of grid points (odd recommended)
harm=1                       # Harmonic number
nx=0                         # Gauss-Hermite mode number in x
ny=0                         # Gauss-Hermite mode number in y
xcenter=0                    # Center position in x
ycenter=0                    # Center position in y
xangle=0                     # Injection angle in x (radians)
yangle=0                     # Injection angle in y (radians)
accumulate=false             # Add to existing field instead of replacing
&end
```

--------------------------------

### Control Output Frequency with Track Namelist

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example3-TimeDependent/README.md

Manages the frequency of output generation during time-simulation by specifying the number of integration steps between outputs. Setting 'output_step' to 3 ensures that output is generated after every third integration step, reducing file size.

```asm
&track
output_step=3
&end
```

--------------------------------

### Configure Wakefield Effects

Source: https://context7.com/svenreiche/genesis-1.3-version4/llms.txt

Defines resistive wall and geometric wakefield parameters within the Genesis 1.3 input file format.

```text
&wake
loss=0
radius=2.5e-3
roundpipe=true
conductivity=5.8e7
relaxation=3.9e-8
gap=0
lgap=1.0
transient=false
output=wake_output
&end
```

--------------------------------

### Memory Calculation for Genesis 1.3

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/INSTALLATION.md

Formulas to estimate memory requirements for time-dependent simulations in Genesis 1.3. Calculations are based on the radiation field and electron distribution.

```plaintext
Nb=ns*ng*ng*16 Bytes, (for radiation field)
Nb=ns*ne*48 Bytes, (for electron distribution)
```

--------------------------------

### Define Lattice Element Syntax

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/LATTICE.md

The general syntax for defining elements in a Genesis 1.3 lattice file. Elements are defined by a label, a type, and a set of parameters enclosed in curly braces.

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

--------------------------------

### Track Namelist

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/manual/MAIN_INPUT.md

Initiates particle and field tracking through the undulator, allowing for last-minute parameter changes and selection of field solvers.

```APIDOC
## track

### Description
This namelist initiates the actual tracking through the undulator and then writing out the results. It allows for parameter definition before or within the lattice, and enables last-minute changes to the code's behavior. It also provides options for selecting the field solver type.

### Method
Not Applicable (Namelist Configuration)

### Endpoint
Not Applicable (Namelist Configuration)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- `zstop` (double, default: 1e9) - If `zstop` is shorter than the lattice length, the tracking stops at the specified position.
- `periodic` (bool, default: false) - If set to true, Genesis uses a periodic boundary condition for the time-window. Radiation slipping out is pushed back from the other side.
- `output_step` (int, default: 1) - Defines the number of integration steps before particle and field distributions are analyzed for output.
- `field_dump_step` (int, default: 0) - Defines the number of integration steps before a field dump is written. Be cautious as this can generate many large output files for time-dependent simulations.
- `beam_dump_step` (int, default: 0) - Defines the number of integration steps before a particle dump is written. Be cautious as this can generate many large output files for time-dependent simulations.
- `sort_step` (int, default: 0) - Defines the number of integration steps before the particle distribution is sorted. Works only for one-4-one simulations.
- `s0` (double, default: <taken from TIME module>) - Option to override the default time window start from the TIME module.
- `slen` (double, default: <taken from TIME module>) - Option to override the default time window length from the TIME module.
- `field_dump_at_undexit` (bool, default: false) - Field dumps at the exit of the undulator (one dump for each undulator in the expanded lattice).
- `bunchharm` (int, default: 1) - Bunching harmonic output setting. Must be >= 1.
- `exclusive_harmonics` (bool, default: false) - If set to true, only the requested bunching harmonic is included in output. Otherwise, all harmonics up to and including the specified harmonics are included.
- `fft_fieldsolver` (bool, default: false) - Selects an FFT-based field solver instead of the Alternating Direction Implicit (ADI) method. More accurate for stronger divergent modes but increases calculation time.
- `source_filter` (bool, default: false) - Filters the source term in the field equation with a 2D sigmoid function to suppress strongly diffracting modes. Only supported for the FFT-based field solver.
- `xcut` (double, default: 1.0) - Relative cut in the spatial frequency components in the x-direction. A value of 1 aligns the edge of the sigmoid filter to half of the maximum resolvable frequency.
- `ycut` (double, default: 1.0) - Same for the y-direction.
- `sigmoid` (double, default: 1.0) - Relative steepness of the sigmoid filter.

### Request Example
```json
{
  "zstop": 100.0,
  "periodic": true,
  "output_step": 10,
  "fft_fieldsolver": true,
  "source_filter": true,
  "xcut": 0.8,
  "ycut": 0.8,
  "sigmoid": 1.5
}
```

### Response
#### Success Response (200)
This namelist does not return a direct response. Its effects are observed in the simulation output files.

#### Response Example
N/A
```

--------------------------------

### Configure Genesis 1.3 Lattice Markers for Data Dumps

Source: https://github.com/svenreiche/genesis-1.3-version4/blob/master/examples/Example2-Dumps/README.md

Markers are zero-length elements in the lattice file used to trigger field or particle distribution dumps at specific locations. This snippet demonstrates adding a marker to a FODO cell definition.

```asm
M: MARKER = {dumpfield = 1};
FODO: LINE={UND,D1,QF,D2,UND,D1,QD,D2,M};
```
Tokens:
Raw