Keywords for Arguments

In several functions of spectra-ui, a number of arguments should be given to specify the calculation conditions and parameters. The details of each function are given below.

Select the Calculation Type

Before starting any calculation in spectra-ui, the calculation type should be selected by calling "SelectCalculation()" function, using a number of keywords summarized below as its arguments.

Arguments available in the function SelectCalculation to specify the calculation type.

Category	Menu Items	Arguments
Numerical Scheme	Far Field & Ideal Condition	far
	Near Field	near
	Coherent Radiation	cohrad
	Characterization at the Source Point	srcpoint
	Coherent Mode Decomposition	CMD
	Wavefront Propagation	propagate
	Fixed Point Calculation	fixed
Method	Energy Dependence	energy
	Spatial Dependence	spatial
	K Dependence	Kvalue
	Time Dependence	temporal
	Wigner Function	wigner
Main Target Item	Angular Flux Density	fdensa
	Partial Flux	pflux
	Total Flux	tflux
	Angular Power Density	pdensa
	Partial Power	ppower
	Resolved Power Density	pdensr
	Spatial Flux Density	fdenss
	Spatial Power Density	pdenss
	Surface Power Density	spdens
	Volume Power Density	vpdens
	CMD with the Wigner Function	CMD2d
	Modal Profile	CMDPP
	Check Validity	CMDcheck
	Electric Field	efield
	Complex Amplitude	camp
	Phase-Space Distribution	phasespace
	Spatial Profile	sprof
Condition	Rectangular Slit	slitrect
	Circular Slit	slitcirc
	Along Axis	along
	Mesh: x-y	meshxy
	Mesh: r-φ	meshrphi
	Simplified Calculation	simpcalc
	Flux at a Fixed Energy	fluxfix
	Peak Flux Curve	fluxpeak
	Power	powercv
	Planar Surface: x-z	xzplane
	Planar Surface: y-z	yzplane
	Cylindrical Surface	pipe
	X-X' (Sliced)	XXpslice
	X-X' (Projected)	XXpprj
	Y-Y' (Sliced)	YYpslice
	Y-Y' (Projected)	YYpprj
	X-X'-Y-Y'	XXpYYp
Sub-Condition	Target Harmonics	tgtharm
	All Harmonics	allharm
	Sliced	Wslice
	Projected on X-X'	WprjX
	Projected on Y-Y'	WprjY
	Related Characteristics	Wrel

Main Input Parameters

After selecting the calculation type, parameters to specify the accelerator, light source, and numerical conditions may need to be modified, which can be done by calling "Set()" function with adequate arguments. For example,

spectra.Set("acc", "eGeV", 3)

means that the electron energy is set to 3 GeV. Refer to the followings for details.

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
acc	Parameters to specify the accelerator as shown in Accelerator subpanel.
src	Parameters to specify the light source as shown in Light Source subpanel.
config	Configurations to specify the numerical conditions as shown in Configurations subpanel.
outfile	Configurations to specify the output file as shown in Output File subpanel.

Accelerator parameters

Keywords to specify the accelerator parameters are summarized below. They should be used as the 2nd argument. Refer to Accelerator for more details about each parameter.

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

Notation in GUI	Argument	Detail	Format
Type	type	Type of the accelerator. In SPECTRA, the accelerators are categorized into two types: Storage Ring and Linear Accelerator.	string - one of below: 'Storage Ring' 'Linear Accelerator'
Energy (GeV)	eGeV	Total energy of the electron beam.	float
Current (mA)	imA	Average beam current of the accelerator. The former is determined by the user, while the latter is evaluated from Pulses/sec and Bunch Charge.	float
Bunches	bunches	Number of electron bunches stored in the storage ring.	int
Pulses/sec	pulsepps	Number of electron bunches/second in the linear accelerator.	int
σz (mm)	bunchlength	Bunch length and charge of the electron beam.	float
Bunch Charge (nC)	bunchcharge	↑	float
Nat. Emittance (m.rad)	emitt	Natural emittance of the electron beam.	float
Coupling Constant	coupl	Coupling constant and energy spread of the electron beam.	float
Energy Spread	espread	↑	float
βx,y (m)	beta	Twiss parameters at the center of the light source	list
αx,y	alpha	↑	list
ηx,y (m)	eta	Dispersion functions and their derivatives.	list
η'x,y	etap	↑	list
Bunch Profile	bunchtype	Specify the distribution functions of the electron beam in the spatial and temporal domains.	string - one of below: 'Gaussian' 'Current Profile' 'E-t Profile' 'Particle Distribution'
Current Profile	currdata	Dictionary data to represent the current profile of the electron bunch.	dictionary
E-t Profile	Etdata	Dictionary data to represent the electron distribution in the E-t phase space.	dictionary
Injection Condition	injectionebm	Specify the injection condition, or the position and angle of the electron beam at the entrance of the light source.	string - one of below: 'Automatic' 'Align at Entrance' 'Align at Center' 'Align at Exit' 'Custom'
x,y (mm)	xy	Horizontal/vertical positions/angles at the entrance. Available when Injection Condition is Custom	list
x',y' (mrad)	xyp	↑	list
Condition at the Center	injorg		bool
Zero Emittance	zeroemitt	Calculation is done without the effects due to the finite emittance and/or energy spread of the electron beam.	bool
Zero Energy Spread	zerosprd	↑	bool
Single Electron	singlee	SR emitted by a single electron is supposed.	bool
Additional R56 (m)	R56add	Strength of the virtual dispersive section located in front of the light source. Effective for computation of coherent radiation, if E-t Profile is chosen for the electron bunch profile.	float

Light source parameters

Keywords to specify the light source parameters are summarized below. They should be used as the 2nd argument. Refer to Light Source for more details about each parameter.

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

Notation in GUI	Argument	Detail	Format
Type	type	Type of the light source	string - one of below: 'Linear Undulator' 'Vertical Undulator' 'Helical Undulator' 'Elliptic Undulator' 'Figure-8 Undulator' 'Vertical Figure-8 Undulator' 'Multi-Harmonic Undulator' 'Bending Magnet' 'Wiggler' 'EMPW' 'Wavelength Shifter' 'Field Mapping' 'Periodic: User Defined' 'User Defined'
Field Profile	fvsz	Dictionary data to represent the whole magnetic field distribution of the light source.	dictionary
Field Profile (1 Period)	fvsz1per	Dictionary data to represent the magnetic field distribution of the light source over a single period.	dictionary
Gap (mm)	gap	Gap of the ID.	float
Bx,y (T)	bxy	Field amplitude (IDs) or uniform field (BMs).	list
B (T)	b	↑	float
Main Field (T)	bmain	Peak fields of the main and sub poles of Wavelength Shifters.	float
Sub Field (T)	subpoleb	↑	float
λu (mm)	lu	Magnetic Period Length of the ID	float
Device Length (m)	devlength	Total length of the ID	float
# of Reg. Periods	periods	Number of regular periods.	float
K0x,0y	Kxy0	Available for APPLE undulators. Maximum K values (deflection parameters) when the phase is adjusted to generate horizontal and vertical polarizations.	list
Phase Shift (mm)	phase	Longitudinal shift of each magnetic array for the APPLE undulators, defined as the displacement from the position for the horizontally-polarized mode. To be specific, K values are given as $K_x=K_{x0}sin(2\pi\Delta z/\lambda_u)$ and $K_y=K_{y0}cos(2\pi\Delta z/\lambda_u)$, where $\Delta z$ is the phase shift. In other words, it is defined as half the relative distance between two diagonal pairs of magnetic arrays.	float
Kx,y	Kxy	K values of the ID.	list
K value	K	↑	float
ε1st (eV)	e1st	Fundamental photon energy and wavelength of undulator radiation.	float
λ1st (nm)	lambda1	↑	float
Harmonic Component	multiharm	Arrange the harmonic components for Multi-Harmonic Undulators.	dictionary
ρ (m)	radius	Radius of the BM.	float
BM Length (m)	bendlength	Specify the geometric configuration of BMs.	float
BM Fringe Length (m)	fringelen	↑	float
Main Length (m)	mplength	Lengths of the main and sub poles of the Wavelength Shifter.	float
Sub Length (m)	subpolel	↑	float
BM Interval (m)	bminterv	Distance between two BMs.	float
Origin for CSR (m)	csrorg		float
Gap-Field Relation	gaplink	Specify the relation between the gap and peak field of the ID.	string - one of below: 'None' 'Automatic' 'Import Table'
Br (T)	br	Remanent field of the permanent magnet.	float
Geometrical Factor (x,y)	geofactor	Geometrical factor to reduce the peak magnetic field (x,y).	list
Gap vs. Field	gaptbl		dictionary
APPLE Configuration	apple	Enable/disable the APPLE configuration for Elliptic Undulators.	bool
Field Structure	field_str	Specify the field-distribution symmetry of the ID.	string - one of below: 'Antisymmetric' 'Symmetric'
End Correction Magnet	endmag	Put additional magnets at the both ends, for orbit compensation.	bool
Natural Focusing	natfocus	Apply the natural focusing of IDs.	string - one of below: 'None' 'Bx' 'By' 'Both'
Field Offset & Taper	fielderr	Specify if the magnetic field contains an error component.	bool
Offset x,y (T)	boffset	Magnetic field offset, such as that coming from the ambient field.	list
Lin. Taper x,y (/m)	ltaper	Linear (a1) and quadratic (a2) taper coefficients. The magnetic field amplitude is given as \[B(z)=B_0(1+a_1z+a_2z^2),\] where $B_0$ is the field amplitude corresponding to the K value.	list
Quad. Taper x,y (/m2)	qtaper	↑	list
Add Phase Error	phaseerr	If ticked, the RMS phase error and relevant parameters can be specified.	bool
Random Number Seed	seed	Seed for the random number generator to model the field error.	int
σB (%)	fsigma	RMS of the peak field variation.	float
σφ (deg.)	psigma	RMS of the phase error.	float
σx,y (mm);	xysigma	RMS of the trajectory error.	list
Tandem Arrangement	bmtandem	Calculate radiation from two BMs located at the both ends of the straight section.	bool
Segmentation	segment_type	Arrange the segmented undulator configuration.	string - one of below: 'None' 'Identical' '2nd: Swap Bx,y' '2nd: Flip Bx' '2nd: Flip By'
Number of Segments	segments	Number of undulator segments (M) if Identical is selected for Segmentation, or number of segment pair (M') for other options.	int
Half Number of Segments	hsegments	↑	int
Segment Interval (m)	interval	Distance between the center positions of adjacent undulator segments.	float
Δφ (π)	phi0	Additional phase in the unit of π.	float
Δφ1,2 (π)	phi12	Additional phase in the unit of π: subscripts 1 and 2 refer to the odd and even drift sections	list
Matching Distance (m)	mdist	Distance between virtual focusing magnets in the matching section to arrange the periodic lattice function.	float
Periodic β Function	perlattice	The betatron function is periodic with the period of segment interval.	bool

Configurations

Keywords to specify the numerical configurations are summarized below. They should be used as the 2nd argument. Refer to Configurations for more details about each parameter.

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

Notation in GUI	Argument	Detail	Format
Type	type		str
Distance from the Source (m)	slit_dist	Distance from the center of the light source to the observation point.	float
Auto Config. for Energy Range	autoe	Enable automatic configuration to define the energy range and pitch.	bool
Multi-Harmonic Condition	multihc	Cover more than one harmonic of undulator radiation besides the lowest order; effective when the target photon energy corresponds to a large harmonic number and thus the intervals between harmonics are narrow.	bool
Harmonic Range	hrange	Harmonic range or target harmonic number to be covered.	list
Skip Even Harmonics	skipeven	If true, even-number harmonics are skipped to evaluate the peak flux/brilliance.	bool
Target Harmonic	hfix	Harmonic range or target harmonic number to be covered.	int
Minimum Harmonic	hmin		float
Maximum Harmonic	hmax	Maximum harmonic number to be covered.	int
Detuning	detune	Photon energy defined as a detuned value, i.e., $\varepsilon/(n\varepsilon_1)-1$, where $n$ is the target harmonic number.	float
Energy Range (eV)	erange	Energy range and pitch for Energy Dependence calculations.	list
Energy Pitch (eV)	de	↑	float
Energy Pitch for Integration (eV)	epitch	Energy pitch for integration in Volume Power Density calculations. Needs to be defined by the user for User Defined light sources.	float
Points (Energy)	emesh	Number of energy points for Energy Dependence calculations.	int
Normalized Energy	nefix	Same as the above, but normalized by ε1st.	float
Target Energy (eV)	efix	Photon energy to be fixed.	float
Position x,y (mm)	xyfix	Transverse position/angle at the observation point.	list
Angle θx,y (mrad)	qxyfix	↑	list
Surface Pos. x (mm)	spdxfix	Position of the object and range of observation for Spatial Power Density calculations.	float
Surface Pos. y (mm)	spdyfix	↑	float
Surface Radius (mm)	spdrfix	↑	float
Θ (deg.)	Qnorm	Normal vectors to specify the inner surface of the object irradiated by SR.	float
Φ (deg.)	Phinorm	↑	float
Glancing Angle (deg.)	Qgl	Angular acceptance to confine the photon beam and resultant illuminated area of the object, and angles to define the condition of glancing incidence for Volume Power Density calculations.Azimuth of Incidence define the direction along which the object is inclined: if it is vertically tilted as in the case of a crystal monochromator, this parameter should be 90 degree, as shown in the above figure.	float
Azimuth of Incidence (deg.)	Phiinc	↑	float
Slit Pos.: x,y (mm)	slitpos	Specify the configuration of the slit positions and aperture.	list
Slit Pos.: θx,y (mrad)	qslitpos	↑	list
Δ/Σs: x,y	nslitapt	↑	list
Δx,Δy (mm)	slitapt	↑	list
Δθx,y (mrad)	qslitapt	Angular acceptance to confine the photon beam and resultant illuminated area of the object, and angles to define the condition of glancing incidence for Volume Power Density calculations.Azimuth of Incidence define the direction along which the object is inclined: if it is vertically tilted as in the case of a crystal monochromator, this parameter should be 90 degree, as shown in the above figure.	list
Slit r1,2 (mm)	slitr	Specify the configuration of the slit positions and aperture.	list
Slit θ1,2 (mrad)	slitq	↑	list
Power Upper Limit (kW)	pplimit	Upper limit of the partial power to define the width and height of the rectangular slit for K Dependence calculations.	float
z range (m)	zrange	Position of the object and range of observation for Spatial Power Density calculations.	list
Points (z)	zmesh	Number of observation points in the relevant range	int
Auto Config. for Transverse Range	autot	Enable automatic configuration to define the spatial/angular range and grid intervals.	bool
x Range (mm)	xrange	Position of the object and range of observation for Spatial Power Density calculations.	list
θx Range (mrad)	qxrange	Range of the Observation positions/angles for Spatial Dependence calculations: (a) [Along Axis] and [Mesh: x-y] and (b) [Mesh: r-φ].	list
x Range/Σ	wnxrange		list
Points (x)	xmesh	Number of observation points in the relevant range	int
δx Range (mm)	wdxrange		list
δx Range/Σ	wndxrange		list
Points (δx)	wdxmesh		float
y Range (mm)	yrange	Position of the object and range of observation for Spatial Power Density calculations.	list
θy Range (mrad)	qyrange	Range of the Observation positions/angles for Spatial Dependence calculations: (a) [Along Axis] and [Mesh: x-y] and (b) [Mesh: r-φ].	list
y Range/Σ	wnyrange		list
Points (y)	ymesh	Number of observation points in the relevant range	int
δy Range (mm)	wdyrange		list
δy Range/Σ	wndyrange		list
Points (δy)	wdymesh		float
r Range (mm)	rrange	Range of the Observation positions/angles for Spatial Dependence calculations: (a) [Along Axis] and [Mesh: x-y] and (b) [Mesh: r-φ].	list
θ Range (mrad)	qrange	↑	list
Points (r)	rphimesh	Number of observation point in the relevant range.	int
Points (θ)	qphimesh	↑	int
φ Range (deg.)	phirange	Range of the Observation positions/angles for Spatial Dependence calculations: (a) [Along Axis] and [Mesh: x-y] and (b) [Mesh: r-φ].	list
Points (φ)	phimesh	Number of observation point in the relevant range.	int
Depth Range (mm)	drange	Depth range and number of points for Volume Power Density calculations.	list
Points (Depth)	dmesh	↑	int
Transverse Grid	gridspec	Specify the transverse grid at each longitudinal step.	string - one of below: 'Automatic' 'Normalized' 'Fixed'
Interpolation (X',Y')	winterp	Specify how to interpolate the Wigner function in the angular (X',Y') coordinate before propagation. The grid interval for interpolation scales as the power of 2; namely, it becomes narrower by a factor of 2n, with n being an integer defined by this parameter. Default is 0 and no interpolation is made.	list
Finer Spatial Grid	grlevel	Specify a finer grid interval to compute the spatial profiles etc. The grid interval is defined in the same manner as parameter.	int
Optical Element	optics	Specify an optical element inserted in the beamline.	string - one of below: 'None' 'Single Slit' 'Double Slit' 'Ideal Thin Lens'
Position (m)	optpos	Longitudinal position to insert an optical element.	float
Aperture Size x,y (mm)	aptxy	Aperture size of the slit.	list
Slit Distance x,y (mm)	aptdistxy	Distance between the double slit.	list
Center x,y (mm)	aptposxy	Central position of the slit.	list
Kill Diffraction	killdiff		bool
Soft Edge Fringe Size (mm)	softedge	Fringe range of the Soft Edgeof the slit. At the edge of the slit, the photon intensity is supposed to gradually drop, as opposed to a hard-edged condition. To be specific, transmission rate is defined as \[t(x)=left(frac{x}{delta x}-frac{1}{2}right)^2,\] where $delta x$ is the fringe range and x=0 means the end position of the slit. Longer fringe ranges reduce the diffraction effects and thus the memory requirement is relaxed.	float
Limit of Diffraction Effect	diflim	Target tolerance to define the threshold of the angular range when a slit is inserted.	float
Focal Length x, y (m)	foclenxy	Focal length of an ideal lens.	list
Angular Profile	aprofile	Export the angular profile after an optical element.	bool
Wigner Function	wigner	Export the Wigner function after an optical element.	bool
Cross Spectral Density	csd	Export the cross spectral density.	bool
Degree of Coherence	degcoh	Export the degree of spatial coherence.	bool
K Range	krange	Range of the K values and number of points.	list
K⊥ Range	ckrange	↑	list
Points (K)	kmesh	↑	int
Temporal Range (fs)	trange	Temporal range and number of points for Time Dependence calculations.	list
Points (Temporal)	tmesh	↑	int
γΔθx,y	gtacc	Angular acceptance normalized by γ-1 to calculate the Wigner function.	list
X' Acceptance (mrad)	horizacc	↑	float
Slice X (mm)	Xfix	Transverse positions and angles at the source point where the Wigner function is calculated.	float
Slice Y (mm)	Yfix	↑	float
Slice X' (mrad)	Xpfix	↑	float
Slice Y' (mrad)	Ypfix	↑	float
X Range (mm)	Xrange	Calculation range/number of points of the transverse positions/angles at the source point.	list
Points (X)	Xmesh	↑	int
X' Range (mrad)	Xprange	↑	list
Points (X')	Xpmesh	↑	int
Y Range (mm)	Yrange	↑	list
Points (Y)	Ymesh	↑	int
Y' Range (mrad)	Yprange	↑	list
Points (Y')	Ypmesh	↑	int
Filtering	filter	Specify the type of filtering.	string - one of below: 'None' 'Generic Filter' 'BPF: Gaussian' 'BPF: Boxcar' 'Custom'
Filters	fmateri	Dictionary data to represent the filter materials.	dictionary
Custom Filter	fcustom	Dictionary data to represent the filter transmission rate.	dictionary
Central Energy (eV)	bpfcenter	Central photon energy of the bandpath filter (BPF).	float
Width (eV)	bpfwidth	Full width of the boxcar-type BPF.	float
Width (σ, eV)	bpfsigma	1σ of the Gaussian BPF.	float
Max. Trans. Rate	bpfmaxeff	Maximum transmission rate of the BPF.	float
Absorbers	amateri		dictionary
Depth Step	dstep	Specify how to change the energy/depth position in the calculation range.	string - one of below: 'Linear' 'Logarithmic' 'Export at Arbitrary Positions'
Depth-Position Data	depthdata	Dictionary data to represent the depth positions.	dictionary
Define Obs. Point in	defobs	Specify how to represent the transverse observation points.	string - one of below: 'Position' 'Angle'
Normalize Photon Energy	normenergy	Specify the photon energy as a normalized value.	bool
Energy Step	estep	Specify how to change the energy/depth position in the calculation range.	string - one of below: 'Linear' 'Logarithmic'
Slit Aperture Size	aperture	Specify how to represent the width and height of the rectangular slit.	string - one of below: 'Fixed' 'Normalized'
Set Upper Limit on Power	powlimit	Put an upper limit on the allowable partial power.	bool
Optimize ΔX' for Computation	optDx	Horizontal angular acceptance is virtually closed to reduce the computation time, without changing the calculation results.	bool
Level of Smoothing Along X	xsmooth	Apply smoothing for the Wigner function of BMs and wigglers; larger values results in more smooth profiles.	int
Observation in the Fourier Plane	fouriep	Calculation is done at the Fourier Plane as schematically illustrated below, to evaluate the angular profile at the source point (center of the light source)	bool
Fast Computation by Quasi Convolution	qconv	Apply Quasi Convolution scheme for fast computation of Wigner functions	bool
Cross Term Cutoff	xcutoff	Skip computation of the cross term whose contribution is below this value	float
Wiggler Approximation	wiggapprox	Apply the wiggler approximation, in which radiation incoherently summed up (as photons).	bool
Accuracy Level	acclevel		float
Accuracy	accuracy	Specify the numerical accuracy. In most cases, Default is recommended, in which case SPECTRA automatically arranges all the relevant parameters.	string - one of below: 'Default' 'Custom'
Perform CMD?	CMD	Perform Coherent Mode Decomposition after calculating the Wigner function.	bool
Apply GS Model	GSModel	Use Gaussian-Schell (GS) model to simplify the CMD and reduce computation time.	bool
GS Model X/Y	GSModelXY	Use Gaussian-Schell (GS) model for CMD. Select the axis to apply.	string - one of below: 'None' 'X' 'Y' 'Both'
Export Field Profile	CMDfld	Calculate and export the modal profiles based on the CMD results	string - one of below: 'None' 'JSON' 'BINARY' 'Both'
Export Intensity Profile	CMDint	Calculate and export the modal intensity profiles based on the CMD results	bool
Range: X,Y (mm)	fieldrangexy	Range of the spatial grid to export the modal profile.	list
Range: X (mm)	fieldrangex	↑	float
Range: Y (mm)	fieldrangey	↑	float
Step: X,Y (mm)	fieldgridxy	Intervals of the spatial grid points to export the modal profile.	list
Step: X (mm)	fieldgridx	↑	float
Step: Y (mm)	fieldgridy	↑	float
HG Order Limit (X,Y)	HGorderxy	Upper limit of the order of the Hermite-Gaussian functions to be used in the CMD.	list
HG Order Limit (X)	HGorderx	↑	float
HG Order Limit (Y)	HGordery	↑	float
Max. HG Order (X,Y)	maxHGorderxy	Maximum orders of the coherent mode.	list
Max. HG Order (X)	maxHGorderx	↑	float
Max. HG Order (Y)	maxHGordery	↑	float
Maximum CMD Order	maxmode	Maximum number of the coherent modes for post-processing (exporting the modal profile, reconstructing the Wigner functions).	float
Flux Cutoff	fcutoff	Cutoff flux (normalized) to be used to determine the maximum HG order of of each coherent mode.	float
Amplitude Cutoff	cutoff	Cutoff amplitude (normalized) of individual modes, below which Hermite-Gaussian functions are neglected.	float
Compare Wigner Function	CMDcmp	Reconstruct the Wigner function using the CMD result to check its validity.	bool
Compare Intensity Profile	CMDcmpint	Reconstruct the flux density profile using the CMD result to check its validity.	bool
FEL Mode	fel	Coherent radiation in an FEL (free electron laser) mode is calculated. If this option is enabled, interaction (energy exchange) between electrons and radiation is taken into account in solving the equation of electron motion in the 6D phase space.	string - one of below: 'None' 'Prebunched FEL' 'Seeded FEL' 'Seeded with Chirped Pulse' 'Seeded with Double Pulse' 'Seeded width Custom Pulse' 'Reuse Bunch Factor'
Seed Profile	seedspec		dictionary
Pulse Energy (mJ)	pulseE	Seed pulse energy.	float
Wavelength (nm)	wavelen	Seed wavelength.	float
Pulse Length (FWHM, fs)	pulselen	Seed pulse length.	float
TL. Pulse Length (FWHM, fs)	tlpulselen	Transform-limited pulse length of the chirped seed pulse.	float
Source Size (FWHM, mm)	srcsize	Seed source size.	float
Waist Position (m)	waistpos	Longitudinal position where the seed pulse forms a beam waist.	float
Timing (fs)	timing	Relative time of the seed pulse with respect to the electron beam.	float
GDD (fs2)	gdd	Group delay dispersion and third order dispersion of the chirped seed pulse.	float
TOD (fs3)	tod	↑	float
Pulse Energy: 1,2 (mJ)	pulseE_d	Pulse energies of the 1st and 2nd seed pulses. Available when Seeded with Double Pulse is chosen. Note that there are a number of parameters having the same suffix (1,2), which denotes that they are for the 1st and 2nd seed pulses.	list
Wavelength: 1,2 (nm)	wavelen_d		list
TL. Pulse Length: 1,2 (FWHM, fs)	tlpulselen_d		list
Source Size: 1,2 (FWHM, mm)	srcsize_d		list
Waist Position: 1,2 (m)	waistpos_d		list
Timing: 1,2 (fs)	timing_d		list
GDD: 1,2 (fs2)	gdd_d		list
TOD: 1,2 (fs3)	tod_d		list
Step: Initial, Interval (m)	svstep	Define the longitudinal step to solve the FEL equation.	list
Substeps for Radiation	radstep	↑	float
Photon Energy ROI (eV)	eproi	Photon energy range of interest to solve the FEL equation.	list
Number of Particles	particles	Number of macro-particles to represent the electron beam.	float
e- Energy Interval	edevstep	Interval of the electron energy deviation to export the electron density in the (E-t) phase space.	float
R56 (m)	R56	Strength of the virtual dispersive section. Need to be specified if option is enabled.	float
Export Intermediate Data	exportInt	Export the intermediate data evaluated during the process of solving the FEL equation.	bool
Bunch with Dispersion	R56Bunch	Export the bunch profile after the electron beam passes through a virtual dispersive section located downstream of the source, as in the high-gain harmonic generation (HGHG) FELs.	bool
E-t Data	exportEt	Export the electron density in the (E-t) phase space.	bool

Output File Settings

Keywords to specify the output file are summarized below. They should be used as the 2nd argument. Refer to Output File Subpanel 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
Format	format	Select the format of the output file from three options.	string - one of below: 'JSON' 'ASCII' 'Both'
Folder	folder	Input the path of the output file in [Folder], a prefix text in [Prefix], and a serial number in [Serial Number]. Then the output file name is given as [Folder]/[Prefix]-[Serial Number].[Format]	str: path to the directory
Prefix	prefix	↑	str
Comment	comment	Input any comment in [Comment] if necessary, which is saved in the output file and can be referred later on.	str
Serial Number	serial	Input the path of the output file in [Folder], a prefix text in [Prefix], and a serial number in [Serial Number]. Then the output file name is given as [Folder]/[Prefix]-[Serial Number].[Format]	int

Other parameters

Numerical accuracy

The numeral accuracy is specified by calling "SetAccuracy()". The 1st argument specifies the numerical procedure (integration, discretization, etc.), and should be one of the followings.

Arguments available in SetAccuracy().

Category	Menu Items	Arguments
Integration/Discretization Step	Longitudinal Step	accdisctra
	Transverse Grid	accinobs
	Electron Energy Step	accineE
	Photon Energy Step	accinpE
Integration Range	Longitudinal Range	acclimtra
	Transverse Range	acclimobs
	Photon Energy Range	acclimpE
	Electron Energy Range	acclimeE
Others	Harmonic Convergence	accconvharm
	Energy Consistency	accEcorr
	Monte Carlo Integral Tolerance	accconvMC
	Coherent Radiation Integral Tolerance	accconvMCcoh
	Limit Macroparticles	acclimMCpart
	Maximum Macroparticles	accMCpart

Unit for data import

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

Arguments available in PreProcess.SetUnit()

Menu Items	Arguments	Options
Gap	gap	mm, m, cm
Longitudinal Position (z)	zpos	↑
Magnetic Field (Bx,y)	magf	Tesla, Gauss
Depth for Volume Power Density	depth	mm, m, cm
Time for Bunch Profile	time	mm, m, fs, s, ps

Pre-Processing options

A number of options in pre-processing can be changed by calling "SetCondition()". The 1st argument specifies the data type and should be one of the followings.

Keywords available in the argument to change the configurations of Pre-Processing.

Notation in GUI	Key	Detail	Format of Value
Field Threshold (%)	thresh	Define the initial and final magnet poles of an undulator; those with the peak field below this value are regarded as non-regular poles and skipped.	float
End Poles	endpoles	Number of end poles to be neglected to evaluate the phase error.	int
Long. Coordinate	zcoord	Select the longitudinal coordinate.	string - one of below: 'Pole Number' 'z (m)'
Max. Harmonic	maxharm	Maximum harmonic number to be considered.	int
Plot Configuration	filtauto	Define how to specify the energy range to evaluate the transmission rate of a filter.	string - one of below: 'Automatic' 'Custom'
Minimum Energy (eV)	filtemin	Energy range and number of points to evaluate the transmission rate.	float
Maximum Energy (eV)	filtemax	↑	↑
Energy Points	filtpoints	↑	int
Energy Step	filtscale	Define the energy step to evaluate the transmission rate.	string - one of below: 'Linear' 'Logarithmic'

Particle data format

To load the particle data correctly, the data format should be defined by calling "ParticleDataFormat()". The 1st argument specifies the data type and should be one of the followings.

Keywords available in the argument to change the configurations of Particle Data Format.

Notation in GUI	Key	Detail	Format of Value
x & y	unitxy	Unit of the transverse coordinate of each particle.	string - one of below: 'm' 'mm'
x' & y'	unitxyp	↑	string - one of below: 'rad' 'mrad'
Time	unitt	Unit of the longitudinal position of each particle.	string - one of below: 's' 'ps' 'fs' 'm' 'mm'
Energy	unitE	Unit of the energy of each particle.	string - one of below: 'GeV' 'MeV' 'gamma'
x	colx	Index of the column to specify the coordinate of each particle	int
x'	colxp	↑	↑
y	coly	↑	↑
y'	colyp	↑	↑
t	colt	↑	↑
E	colE	↑	↑
Charge/Particle (C)	pcharge	Charge of each particle.	float
Slices in 1σs	bins	Number of slices contained in 1σ along the longitudinal position to plot the slice parameters.	int

Plot configurations

The pre/post-processing plots can be configured by "ConfigurePlot()" function, with the keyword arguments (dict) summarized below.

Keywords available in the argument to change the configurations of Plot Options.

Notation in GUI	Key	Detail	Format of Value
X auto range	xauto	Automatically set the range of the x/y scale.	bool
Y auto range	yauto	↑	↑
X range	xrange	Manually set the range of the x/y axis.	list
Y range	yrange	↑	↑
Normalize	normalize	Select how to normalize the animation plot	string - one of below: 'For Each' 'By Maximum'
X-axis Scale	xscale	Select the scale for x axis	string - one of below: 'Linear' 'Logarithmic'
Y-axis Scale	yscale	↑	↑
Plot Type	type	Select the type of the 1D plot	string - one of below: 'Line' 'Line & Symbol' 'Symbol'
Symbol Size	size	Symbol size for the (line&)symbol plot	int
Line Width	width	Line width for the line(&symbol) plot	float
2D Plot Type	type2d	Select the type of the 2D plot	string - one of below: 'Contour' 'Surface (Color Map)' 'Surface (Shaded)'
Color	shadecolor	Color of the light source for the shaded surface plot. Select from the color picker dialog (GUI) or specify by a 6-digit RGB number like #000000 (for white).	str
Color Map	colorscale	the available list	string - one of below: 'Default' 'Rainbow' 'Blackbody' 'Earth' 'Greys'
Show Scale	showscale	Show the color scale when available.	bool
Wireframe	wireframe	Draw grid lines on the surface plot.	↑

Items for Pre- and Post-Processing

In several methods to visualize the pre-processing/calculation results in PreProcess/PostProcess/PostProcessCLI classes, arguments should be given to specify the target item. The details are given below.

Items for PreProcess class

Arguments available in PreProcess class methods are described as follows.

PreProcess.Import()

This method imports custom data from an ASCII file prepared by the user. Note that relevant parameters should be set properly in advance. For example, the light source type should be "User Defined" to import the field distribution data. For details of the data import, refer to Pre-Processing. Data items available as the argument of this function are summarized below.

Importable data items available in PreProcess.Import()

Items	Details
Current Profile	Current profile of the electron bunch to be used for coherent radiation calculation
E-t Profile	Electron density in the (E-t) phase space
Field Profile	Magnetic field distribution for User Defined light source
Field Profile (1 Period)	Magnetic field distribution within a single period for Periodic: User Defined light source
Gap vs. Field	Relation between the gap and peak field of the ID
Custom Filter	Transmission rate of a filter given as a function of the photon energy
Depth-Position Data	Depth positions to compute the Volume Power Density
Seed Profile	Power and phase of the custom seed pulse for the FEL interaction

PreProcess.Plot()

This method evaluates (pre-processes) specific items available with the current parameters and configurations, and plots the results. Data items available as the argument of this function are summarized below.

Plottable items available in PreProcess.Plot()

Items	Details
betatron Functions	betatron functions within the light source
Field Distribution	Magnetic field distribution along the longitudinal axis
1st Integral	1st integrals, corresponding to the velocity of an electron
2nd Integral	2nd integrals, corresponding to the electron trajectory
Phase Error	Phase error evaluated as a function the magnet pole number. Note that the number of end poles (used for the orbit adjustment and should be eliminated for the phase error evaluation) is automatically determined; to be specific, those with the peak field less than 95% of the average are ignored.
Harmonic Intensity	Reduction of photon intensity at each harmonic due to magnetic errors evaluated by analytical methods. for details.
Transmission Rate	Transmission rate of the filter
Absorption Rate	Absorption rate of the absorber

Items for PostProcess class methods

Arguments available in PostProcess class (interactive mode) methods are described as follows.

PostProcess.Plot()

Standard output items can be plotted with this method. Specify the target item as the argument(s) of this function; available items are summarized below.

List of standard output items

Items	Details
Flux Density	Spatial (far field conditions) or angular (others) flux density
Flux	Partial photon flux passing through a finite angular acceptance, or total flux integrated over the whole solid angle
GA. Brilliance	Photon density in the 4D phase space (or its maximum). ‘GA.' stands for ‘Gaussian Approximation', meaning that it is evaluated by assuming that the photon beam is a Gaussian one.
Brilliance	↑
Prj. Brilliance	Brilliance projected on the (X,X') or (Y,Y') phase space.
PL(s1/s0)	Stokes parameters: PL, PC, PL45 correspond to the horizontal, left-hand and 45-deg.-inclined linear polarizations.
PC(s3/s0)	↑
PL45(s2/s0)	↑
Harmonic Energy	Photon energy of a target harmonic. ‘Harmonic' is defined as nε1st, where n is the harmonic number, while ‘Peak' specifies the photon energy at which the photon intensity (flux density of flux) becomes the maximum; in general this is slightly lower than the former one.
Peak Energy	↑
Power Density	Spatial (far field conditions) or angular (others) power density
Partial Power	Partial power passing through a finite angular acceptance, or total power integrated over the whole solid angle
Total Power	↑
Harmonic Power (x)	Angular power density corresponding to a specific harmonic and polarization state
Harmonic Power (y)	↑
Volume Power Density	Refer to
Natural Size	Source size and angular divergence of radiation emitted by a single electron
Natural Divergence	↑
Horizontal Size	Source size and angular divergence of a photon beam emitted by an electron beam with finite emittance and energy spread
Vertical Size	↑
Horizontal Divergence	↑
Vertical Divergence	↑
Coherent Flux	Photon flux contained in a coherent volume of radiation that is fully coherent in space
Coherent Power	Power contained in a bandwidth corresponding to 1 μm coherence length
Horizontal Coherent Fraction
Vertical Coherent Fraction
Harmonic Number	Harmonic number to generate the maximum photon intensity at a given photon energy
Observer Time	Time in the laboratory frame (for observer)
Horizontal Electric Field	Electric field of radiation
Vertical Electric Field	↑
Horizontal Real Field	Complex amplitude of radiation evaluated at a given photon energy
Horizontal Imaginary Field	↑
Vertical Real Field	↑
Vertical Imaginary Field	↑

PostProcess.SetDataType()

Besides the standard output items, non-standard ones can be plotted with PostProcess.Plot(). Before doing so, however, the data type should be selected with this method. Available data types and relevant output items are summarized below.

List of non-standard output items and their data types

Data Types	Items	Details	Condition
Modal Flux	Modal Flux, Integrated Modal Flux	Information about how much flux is contained in each coherent mode.	When Coherent Mode Decomposition is enabled.
Modal Profile	Modal Amplitude Real, Modal Amplitude Imaginary	Spatial profile of the complex field amplitude for each coherent mode. Note that the calculation range and number of points are specified in CMD Parameters.	↑
Modal Intensity	Flux Density, Linear Flux Density	Spatial profile of the intensity for each coherent mode. Note that the calculation range and number of points are specified in CMD Parameters.	↑
Flux Density Profile	Flux Density, Reconstructed, Linear Flux Density, Reconstructed	Flux density profile reconstructed from the modal and Wigner functions by projection to the real space (X,Y)	↑
Wigner Func. (X,X')	Brilliance, Reconstructed	Wigner function reconstructed from the modal profile, to be compared with the original one to check how the CMD was successful. To facilitate the comparison, both functions are projected on the (X,X') phase space.	↑
Wigner Func. (Y,Y')	↑	Same as the above, but for the (Y,Y') phase space.	↑
Angular Profile (Source)	Flux Density, Linear Flux Density	Angular profile at the source point	When Wavefront Propagation is enabled.
Wigner Function	Brilliance, Prj. Brilliance	Variation of the spatial profile and Wigner function	↑
Spatial Profile	Flux Density, Linear Flux Density	↑	↑
Angular Profile (Optical Element)	↑	Angular profile and Wigner function just after an optical element	↑
Wigner Function (Optical Element)	Brilliance, Prj. Brilliance	↑	↑
Cross Spectral Density	|CSD|, CSD Argument	Variation of the cross spectral density	↑
Cross Spectral Density (x)	↑	↑	↑
Cross Spectral Density (y)	↑	↑	↑
Degree of Coherence	Degree of Coherence	Variation of the spatial degree of coherence	↑
Degree of Coherence (x)	↑	↑	↑
Degree of Coherence (y)	↑	↑	↑
Current Profile	Current	Current profile of the electron beam.	When FEL Mode option is enabled.
E-t Profile	Current Density	Electron density in the E-t (energy-time) phase space.	↑
Current Profile with Dispersion	Current	Current profile of the electron beam after passing through a virtual dispersive section. Available if Bunch with Dispersion	↑
E-t Profile with Dispersion	Current Density	Electron density in the (E-t) phase space after the virtual dispersive section. Available if Bunch with Dispersion	↑
Bunch Factor	Bunch Factor Real, Bunch Factor Imaginary	Bunch factor of the electron beam.	↑
Pulse Energy	Radiation Pulse Energy, e- Bunch Energy Loss	Total energy of the radiation pulse.	↑
On-Axis Field	Horiozntal Electric Field, Vertical Electric Field	Waveform of the on-axis electric field of radiation in the far-field zone.	↑
Inst. Power	Partial Power	Temporal profile of the instantaneous radiation power.	↑
Spectrum	Flux	Spectrum of the radiation pulse.	↑

Items for PostProcessCLI class methods

Arguments available in PostProcessCLI class (CLI mode) methods are described as follows.

PostProcessCLI.Plot()

Unlike PostProcess.Plot(), this function requires keyword arguments to specify the target data type and output items, like PostProcessCLI.Plot(type="type", item="item"). Refer to standard output items and non-standard output items for available items and data types.