Keywords for Arguments

In several functions of simplex-ui, a number of arguments should be given to specify the simulation conditions and parameters. For example, parameters to specify the electron beam can be modified by calling "Set()" function with 3 arguments. For example,

simplex.Set("ebeam", "eenergy", 3)

means that the electron energy is set to 3 GeV. Refer to the followings for details. The 1st, 2nd, and 3rd aguments define the category, name, and value of the parameter to be set.

Main Input Parameters

Parameter category (1st argument)

The 1st argument should specify the category of the parameter to be set. It should be given by one of the keywords as summarized below.

Arguments available in the function Set to set a parameter.

Arguments

Remarks

ebeam

Parameters to specify the electron beam shown in Electron Beam panel.

seed

Parameters to specify the seed light shown in Seed Light panel.

spxout

Configurations to import the former simulation result shown in SIMPLEX Output panel.

undulator

Parameters to specify the undulator shown in Undulator panel.

lattice

Parameters to specify the lattice arrangement shown in Lattice panel.

alignment

Parameters to specify the alignment error in Alignment panel.

wake

Parameters to specify the wake field shown in Wakefield panel.

chicane

Parameters to specify the chicane shown in Chicane panel.

dispersion

Parameters to specify the dispersion function shown in Dispersion panel.

condition

Parameters to specify the simulation conditions in Simulation Conditions panel.

datadump

Parameters to specify how to dump the simulation results shown in Data Dump Configurations panel.

felprm

Target photon energy or wavelength of radiation shown in FEL Performance panel.

outfile

Parameters to specify the output file shown in Output File panel.

Parameter name (2nd argument)

The 2nd argument should specify the name of the parameter to be set, and be given by one of the keywords as summarized below.

Electron Beam

Keywords to specify the parameters for the electron beam are summarized below. Refer to Electron Beam for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("ebeam", arg2, arg3) to change the parameters and options of Electron Beam.

Notation in GUI

Argument

Detail

Format

Bunch Profile

bmprofile

Bunch profile of the electron beam in the 6D phase space.

string - one of below:
'Gaussian'
'Boxcar'
'SIMPLEX Output'
'Slice Parameters'
'Current Profile'
'E-t Profile'
'Particle Distribution'

Slice Parameters

slicefile

dictionary

Current Profile

currfile

dictionary

E-t Profile

etfile

dictionary

Particle Distribution

partfile

Path to a local file containing the particle data

str: path to the data file

Electron Energy (GeV)

eenergy

Slice (representative) energy of the electron beam.

float

RMS Bunch Length (m)

bunchleng

RMS bunch length of the electron beam.

float

Bunch Length (m)

bunchlenr

Full bunch length of the electron beam. Available if Boxcar is chosen for the electron bunch profile.

float

Bunch Charge (nC)

bunchcharge

Bunch charge of the electron beam.

float

εx,y (mm.mrad)

emitt

Normalized emittance of the electron beam.

list

RMS Energy Spread

espread

Energy spread and chirp of the electron beam.

float

Energy Chirp (m-1)

echirp

↑

float

ηx,y (m)

eta

Dispersion functions of the electron beam.

list

Peak Current (A)

pkcurr

Peak current of the electron beam evaluated from relevant parameters.

float

σ0x,0y (mm)

ebmsize

Beam size and angular divergence at the undulator entrance.

list

σ0x',0y' (mrad)

ediv

↑

list

<σx,y> (mm)

avgsize

list

R56 (m)

r56

Strength of the virtual dispersive section located in front of the undulator. Available if SIMPLEX Output is chosen for the electron bunch profile, and may be needed to simulate the HGHG/EEHG FELs

float

Bunch Twiss Prms.

twissbunch

string - one of below:
'Projected'
'Sliced (Optimized)'
'Sliced (Custom)'

Slice Position (m)

twisspos

float

Seed Light

Keywords to specify the parameters for the seed light are summarized below. Refer to Seed Light for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("seed", arg2, arg3) to change the parameters and options of Seed Light.

Notation in GUI

Argument

Detail

Format

Seed Light

seedprofile

Type of the seed light

string - one of below:
'N.A.'
'Gaussian Beam'
'Chirp Pulse'
'SIMPLEX Output'

Peak Power (W)

pkpower

Peak power of the seed light.

float

Δλ/λ1

relwavelen

Wavelength of the seed light relative to the undulator fundamental wavelength.

float

FWHM Pulse Length (fs)

pulselen

Pulse energy and pulse length of the seed light.

float

FWHM Spot Size (mm)

spotsize

Source size and Rayleigh length of the seed light.

float

Position of Waist (m)

waistpos

Longitudinal position where the seed light forms a beam waist

float

Relative Time (fs)

timing

float

Carrier Envelope Phase (°)

CEP

Carrier envelope phase, group delay dispersion and third order dispersion of the seed light.

float

GDD (fs2)

gdd

↑

float

TOD (fs3)

tod

↑

float

Phase Offset (°)

phase

float

SIMPLEX Output

Keywords to specify the parameters for importing the former simulation result are summarized below. Refer to SIMPLEX Output for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("spxout", arg2, arg3) to change the parameters and options of SIMPLEX Output.

Notation in GUI

Argument

Detail

Format

Data Name

spxfile

Path to the output data file

str: path to the data file

Step Index to Retrieve Data

spxstep

Step index to retrieve the raw data of the former simulation, counted from the final step. For example, -1 means that the raw data at the (N-1)-th step are used.

int

Exported Positions (m)

spxstepzarr

dictionary

Total Beamlets

bmletsout

float

Particles/Beamlet

paticlesout

float

Drift Length (m)

matching

float

Photon Energy (eV)

spxenergy

Fundamental energy used in the former simulation

float

Undulator

Keywords to specify the parameters for the undulator are summarized below. Refer to Undulator for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("undulator", arg2, arg3) to change the parameters and options of Undulator.

Notation in GUI

Argument

Detail

Format

Undulator Type

utype

Undulator type.

string - one of below:
'Linear'
'Helical'
'Elliptical'
'Multi-Harmonic'

K Value

K

Deflection parameter (K value) of the undulator. Note that K⊥ is defined as \[K_{\perp}=\sqrt{K_x^2+K_y^2}\]

float

K⊥

Kperp

↑

float

Multi-Harmonic Contents

multiharm

Arrange the harmonic components of Multi-Harmonic.

dictionary

tan-1(Kx/Ky) (°)

epukratio

Specifies the ratio of the horizontal and vertical K values.

float

λu (mm)

lu

Magnetic Period Length of the undulator

float

Length/Segment (m)

length

Parameters to specify the undulator line, which is supposed to be composed of several segments and drift sections in between.

float

Number of Segments

segments

↑

int

Segment Interval

interval

↑

float

Extra Slippage (°)

exslippage

Extra slippage in the drift section

float

Tapering

taper

Type of undulator taper.

string - one of below:
'N.A.'
'Stair-Like'
'Continuous'
'Custom'

Optimization

opttype

Specifies how to optimize the taper rate.

string - one of below:
'N.A.'
'Compensate Wake'
'Projection'
'Slice'

Target Slice Position (m)

slicepos

Target slice position for taper optimization

float

Initial Segment

initial

Four parameters to specify the undulator taper. For details, refer to

int

Increment Segment Interval

incrseg

↑

int

Base Linear Taper (m-1)

base

↑

float

Taper Increment (m-1)

incrtaper

↑

float

K Value@Exit

Kexit

K value at the exit of the undulator

float

Resonance Detuning@Exit

detune

Detuning at the exit of the undulator

float

Custom Taper

tapercustom

dictionary

Undulator Model

umodel

Type of undulator model.

string - one of below:
'Ideal'
'Specify Error'
'Import Data'

Random Number Auto Seeding

umautoseed

If enabled, seed number for the random number generator is automatically determined

bool

Random Number Seed

umrandseed

Seed number for the random number generator to model the undulator error

int

σφ (°)

phaseerr

RMS phase error

float

σB/B (%)

berr

RMS field deviation

float

σx,y (mm)

xyerr

RMS trajectory error

list

Apply to All Segments

allsegment

Apply the error to all the segments

bool

Target Segment

tgtsegment

int

Lattice

Keywords to specify the parameters for the arrangement of focusing magnets are summarized below. Refer to Lattice for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("lattice", arg2, arg3) to change the parameters and options of Lattice.

Notation in GUI

Argument

Detail

Format

Lattice Type

ltype

Type of the lattice.

string - one of below:
'FUDU (QF-U-QD-U)'
'DUFU (QD-U-QF-U)'
'FUFU (QF-U-QF-U)'
'Doublet (QF-QD-U)'
'Triplet (QF-QD-QF-U)'
'Undulator Combined'

QF Gradient (T/m)

qfg

Field gradient of the quadrupole magnets.

float

QD Gradient (T/m)

qdg

↑

float

QF Length (m)

qfl

Length of the quadrupole magnets.

float

QD Length (m)

qdl

↑

float

QF-QD Distance (m)

dist

Distance between the focusing and defocusing mangets.

float

# Periods/Segment

lperiods

Number of FODO periods in a single undulator segment.

int

βx0,y0 (m)

betaxy0

Initial Twiss parameters at the undulator entrance.

list

αx0,y0 (m)

alphaxy0

↑

list

Alignment

Keywords to specify the parameters for the alignment error are summarized below. Refer to Alignment for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("alignment", arg2, arg3) to change the parameters and options of Alignment.

Notation in GUI

Argument

Detail

Format

Undulator Alignment

ualign

Type of the undulator alignment error.

string - one of below:
'Ideal'
'Specify Tolerance'
'Specify Offset'

ΔK Tolerance

Ktol

RMS deviation of the K value

float

Slippage Tolerance (°)

sliptol

RMS deviation of the phase slip

float

Offset for Each Segment

sigsegment

Specifies the offset of the K values and slippage for each segment

dictionary

BPM Alignment

BPMalign

Type of the BPM alignment error.

string - one of below:
'Ideal'
'Specify Tolerance'

x,y Tolerance (mm)

xytol

Tolerance of the BPM alignment

list

Random Number Auto Seeding

alautoseed

If enabled, seed number for the random number generator is automatically determined

bool

Random Number Seed

alrandseed

Seed number for the random number generator to model the alignment errors

int

Wakefield

Keywords to specify the parameters for the wakefield are summarized below. Refer to Wakefield for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("wake", arg2, arg3) to change the parameters and options of Wakefield.

Notation in GUI

Argument

Detail

Format

Wakefield On

wakeon

Enables the wakefield

bool

Aperture (m)

aperture

Aperture of the surrounding beam duct

float

Resistive

resistive

Enables the resistive wall wakefield

bool

Resistivity (Ωm)

resistivity

Resistivity and relaxation time of the wall material

float

Relaxation Time (sec)

relaxtime

↑

float

Parallel Plate

paralell

If enabled, a parallel-plate configuration is used for the resistive-wall wakefield

bool

Surface Roughness

roughness

Enables the wakefield induced by surface roughness

bool

RMS Height (m)

height

Height and correlation length to specify the profile of the rough surface

float

Correlation Length (m)

corrlen

↑

float

Dielectric Layer

dielec

Enables the space charge effect

bool

ε/ε0

permit

Permitivity and thickness of the dielectric layer

float

Thickness (m)

thickness

↑

float

Space Charge

spcharge

bool

Additional Custom Wake

wakecustom

Enables the additional wakefield defined by custom data

bool

Wakefield Data

wakecustomdata

dictionary

Chicane

Keywords to specify the parameters for inserting a chicane are summarized below. Refer to Chicane for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("chicane", arg2, arg3) to change the parameters and options of Chicane.

Notation in GUI

Argument

Detail

Format

Chicane On

chicaneon

Replaces a single undulator segment by a magnetic chiane composed of 4 identical bending magnets.

bool

Electron Delay (fs)

delay

Trajectory offset and time delay given by the chicane.

float

Chicane Position

chpos

Undulator segment number to be replace by the chicane.

int

Rearrange After Chicane

rearrange

If enabled, the macroparticles are rearranged so that the microbunches induced before the chicane are smeared out.

bool

Monochromator Type

monotype

Type of the monochromator to be inserted in the chicane for the self-seeding scheme.

string - one of below:
'N.A.'
'Transmission'
'Reflection'
'Customize'

Monochromator Data

monodata

dictionary

Crystal Type

xtaltype

Type of the crystal for the monochromator

string - one of below:
'Diamond (400)'
'Diamond (220)'
'Silicon (111)'
'Customize'

ℏω (eV)

monoenergy

Photon energy of the monochromator

float

|Fg|

formfactor

Form factor, lattice constant, and unit cell volume of the crystal

float

Lattice Spacing (nm)

latticespace

↑

float

Unit Cell Volume (nm3)

unitvol

↑

float

Crystal Thickness (mm)

xtalthickness

Thickness of the crystal

float

Relative Timing (fs)

reltiming

Arrival time of radiation with respect to the electron beam after the chicane

float

Dispersion

Keywords to specify the parameters for the dispersion function are summarized below. Refer to Dispersion for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("dispersion", arg2, arg3) to change the parameters and options of Dispersion.

Notation in GUI

Argument

Detail

Format

e- Injection Error

einjec

Enables the injection error of the electron beam.

bool

Δx,y (mm)

exy

Positional and anglular offset of the electron beam at the undulator entrance.

list

Δx',y' (mrad)

exyp

↑

list

Single Kick

kick

Adds a single kick at a certain position in the undulator line.

bool

Kick Position (m)

kickpos

Longitudinal position and angle of the single kick.

float

Kick Angle x,y (mrad)

kickangle

↑

list

Seed Injection Error

sinjec

Enables the injection error of the seed light.

bool

Seed Δx,y (mm)

sxy

Positional and anglular offsets of the seed light at the undulator entrance.

list

Seed Δx',y' (mrad)

sxyp

↑

list

Simulation Conditions

Keywords to specify the parameters for the simulation condition are summarized below. Refer to Simulation Conditions for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("condition", arg2, arg3) to change the parameters and options of Simulation Conditions.

Notation in GUI

Argument

Detail

Format

Simulation Mode

simmode

Selects the simulation mode.

string - one of below:
'Time Dependent'
'Steady State'
'Cyclic'

Simulation Option

simoption

Enables a special numerical algorithm to reduce the number of macropaticles needed to obtain a resliable simulation result.

string - one of below:
'N.A.'
'Gaussian Mode'
'Disable Quiet Loading'
'Kill Shotnoize'
'Real Electron Number'

Skip Wavefront Transfer Process

skipwave

bool

Auto Integration Step

autostep

The longitudinal step to solver the FEL equation is automatically determined based on the approximate gain length.

bool

Random Number Auto Seeding

autoseed

If enabled, seed number for the random number generator is automatically determined

bool

Random Number Seed

randseed

Seed number for the random number generator to generate the macroparticles

int

Integration Step

step

Longitudinal step normalized by the undulator period to solve the FEL equation.

int

Total Beamlets

beamlets

Total number of beamlets and number of macroparticles in a single beamlet.

float

Total Electrons

electrons

float

Max. Electrons/Slice

sliceels

float

Electrons/Slice

sliceelsss

float

Max. Harmonic

maxharmonic

Maximum harmonic number to be considered

int

Particles/Beamlet

particles

Total number of beamlets and number of macroparticles in a single beamlet.

int

Spatial Window/σ

spatwin

Specifies the spatial range to evaluate the radiation field

int

Temporal Window (m)

simrange

Temporal window of the electron bunch

list

Bunch Position (m)

simpos

Slice position in the electron bunch

float

Enable Parallel Computing

enablempi

Enables the parallel computing by MPI. Note that MPI environment should be installed (Open MPI for LINUX and macOS, MS-MPI for MS-Windows) and path to mpiexec should be set.

bool

Number of Processes

mpiprocs

Number of MPI processes

int

Data Dump Configurations

Keywords to specify the parameters for data dump are summarized below. Refer to Data Dump Configurations for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("datadump", arg2, arg3) to change the parameters and options of Data Dump Configurations.

Notation in GUI

Argument

Detail

Format

Temporal Profile

temporal

Specifies if the related radiation profiles are saved in the output JSON file.

bool

Spectral Profile

spectral

↑

bool

Spatial Profile

spatial

↑

bool

Angular Profile

angular

↑

bool

Output Interval

profstep

Step interval to evaluate the above profiles. Note the results at the final step are always exported. For example, data export is done at the steps of the 1st, 4th, … 97th and 100th, if the total number of steps is 100 and this parameter is set at 3.

int

Particle Data

particle

Saves the macroparticle raw data in a binary file (*.par).

bool

Radiation Data

radiation

Saves the radiation raw data in a binary file (*.fld).

bool

Output Steps

expstep

Specifies the steps to save the raw data.

string - one of below:
'All Segments'
'Specific Segments'
'Final Step'
'Regular Interval'

Initial Segment

iniseg

Initial segment and segment interval to save the raw data.

int

Segment Step

segint

↑

int

Step Interval

stepinterv

Step interval to save the raw data, if Regular Interval is chosen for Output Steps.

int

FEL Performance

Keywords to specify the parameters for target photon energy or wavelength of radiation are summarized below. Refer to FEL Performance for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("felprm", arg2, arg3) to change the parameters and options of FEL Performance.

Notation in GUI

Argument

Detail

Format

ℏω1st (eV)

e1st

Fundamental photon energy and wavelength

float

λ1st (nm)

l1st

↑

float

Output File

Keywords to specify the parameters for the output file are summarized below. Refer to Output File for more details about each parameter.

Keywords available in the 2nd argument (arg2) of Set("outfile", arg2, arg3) to change the parameters and options of Output File.

Notation in GUI

Argument

Detail

Format

Folder

folder

Input the path to the output JSON file in [Folder], a prefix text in [Prefix], and a serial number in [Serial Number]. The data name is given as [Folder]/[Prefix]-[Serial Number], like /Users/data/test-1, where /Users/data, test, and 1 refer to [Folder], [Prefix] and [Serial Number]. Note that the serial number can be -1 (negative), in which case it is not attached to the data name.

str: path to the directory

Prefix

prefix

↑

str

Serial Number

serial

↑

int

Other Parameters

Unit for data import

To import the data prepared by the user, its unit should be specified by calling "SetUnit()". The 1st argment specifies the data type and should be one of the followings.

Arguments available in PreProcess.SetUnit()

Menu Items

Arguments

Options

Bunch Position

bpos

m, mm, s, ps, fs

Electron Energy

energy

GeV, MeV, gamma

Longitudinal Position (z)

zpos

m, mm

Magnetic Field (Bx,y)

bxy

Tesla, Gauss

Parameters for processing the raw data

Parameters and options for processing the raw data (radiation field or particle distribution) generated by a former simulation in the post-processor should be specified by calling "PostProcess.SetDataProcessing()". The 1st argument specifies the parameter or option and should be one of the followings.

Keywords available in the 1st argument of PostProcess.SetDataProcessing()

Notation in GUI

Argument

Detail

Format

Target

item

Target item to be evaluate by Raw Data Processing

string - one of below:
'Radiation Power'
'Photon Flux'

Domain

domain

string - one of below:
'Spatial'
'Temporal'

Real/Imaginary Part

realimag

Select real/imaginary component for an item given by a complex number

string - one of below:
'Real Part'
'Imaginary Part'
'Both'

Ex,y

Exy

Select horizontal/vertical component for the radiation field

string - one of below:
'x'
'y'
'Both'

Axis

axis

string - one of below:
'x'
'y'

S1 (Horizontal)

s1

If enabled, relevant Stoke parameters are evaluated

bool

S2 (45-deg.)

s2

↑

bool

S3 (Circular)

s3

↑

bool

Harmonic Number

harmonic

Target harmonic number

int

Zone

zone

Select the observation zone (near or far field)

string - one of below:
'Near Field'
'Far Field'

Coordinate System

coord

Select the coordinates to retrieve the macroparticle data

string - one of below:
'(s, Δγ/γ)'
'(s, x)'
'(s, y)'

Step

zrange

Select how to specify the range of interest (ROI) for respective variables. Whole means that the whole range used in the simulation is assumed, while Set Window put a window on the ROI.

string - one of below:
'Whole'
'Set Window'

Slice

timerange

↑

string - one of below:
'Whole'
'Set Window'

Photon Energy

energyrange

↑

string - one of below:
'Whole'
'Set Window'

Space

spatrange

↑

string - one of below:
'Whole'
'Set Window'

Angle

anglrange

Half range of the observation angle

string - one of below:
'Whole'
'Set Window'

Step (z)

zwindow

Range of the step and corresponding range of the longitudinal coordinate (z)

list

Slice (s)

timewindow

Range of the slice and corresponding range of the bunch position (s)

list

Energy (ℏω)

energywindow

Range of the photon energy

list

Spatial (x,y)

spatwindow

Half range of the transverse position

list

Angular (x',y')

anglindow

list

z (m)

zvalue

Range of the step and corresponding range of the longitudinal coordinate (z)

list

s (m)

timevalue

Range of the slice and corresponding range of the bunch position (s)

list

ℏω (eV)

energyvalue

Range of the photon energy

list

Δx,y (mm)

spatvalue

Half range of the transverse position

list

Δx',y' (mrad)

anglvalue

Half range of the observation angle

list

Integration (s)

alongs

Enable integration over the ROI

bool

Integration (x,y)

overxy

↑

bool

Integration (x',y')

overxyf

↑

bool

Smoothing: (s,ℏω)

smoothing

list

σs (m), σℏω (eV)

smvalues

list

R56 (m)

r56pp

Virtual longitudinal dispersion to be added after each step. This is convenient to evaluate the reasonable R56 to enhance the microbunching.

float

Data Serial Number

serialpp

Serial number to be attached to the data file to save the post-processed data.

int

Beamlets

bmletspp

float

Particles/Beamlet

particlespp

float