Copyright Notice

Copyright 1998-2024 Takashi Tanaka

This software is free for use, however, the author retains the copyright to this software. It may be distributed in its entirety only and may not be included in any other product or be distributed as part of any commercial software.

This software is distributed with NO WARRANTY OF ANY KIND. Use at your own risk. The author is not responsible for any damage done by using this software and no compensation is made for it.

This software has been developed, improved and maintained as voluntary work of the author. Even if problems and bugs are found, the author is not responsible for improvement of them or version up of the software.

If you are submitting articles to scientific journals with the results obtained by using this software, please cite the relevant references. For details, refer to Introduction.

Introduction

This document describes the instruction to use the free software SPECTRA, a synchrotron radiation (SR) calculation code, and is located in "[SPECTRA Home]/help", where "[SPECTRA Home]" is the directory where SPECTRA has been installed. Brief explanations on the software and numerical implementation of SR calculation are given here, together with a simple instruction of how to get started. Note that "MathJax" javascript library is needed to correctly display the mathematical formulas, which is available online. If you need to read this document offline, "MathJax" should be installed in "[SPECTRA Home]/help" directory.

Overview

SPECTRA is a computer program to numerically evaluate the characteristics of radiation emitted from various synchrotron radiation (SR) sources, such as bending magnets and insertion devices (IDs, i.e., wigglers and undulators). In addition, SR sources with arbitrary magnetic fields are available by importing the magnetic field data prepared by the user. This makes it possible to estimate the real performance of the SR source by using the magnetic field distribution actually measured by field measurement instruments such as Hall probes.

To compute the characteristics of radiation and evaluate the performances of SR sources, a large number of parameters are required to specify the electron beam, light source, observation conditions, and options for numerical operations. SPECTRA is equipped with a fully graphical user interface (GUI) which facilitates configurations of them. In addition, a post-processor is included to verify the computation results graphically. Since version 11.0, the GUI is written based on the web technologies, i.e., HTML, CSS and Javascript, with the assistance of "node.js" and "tauri" to build a standalone application. For visualization of calculation results and imported data, "Plotly" library is used. Thanks to portability of these libraries, SPECTRA will run on most of the platforms such as Microsoft Windows, Macintosh OS X and Linux. SPECTRA does not require any other commercial software or libraries.

The numerical part of SPECTRA ("solver") is written in C++11 with the standard template library (STL). For bending magnets, wigglers and undulators, numerical implementation is based on the well-known expressions on SR, and the so-called far-field approximation is available for fast computation. For more accurate evaluation, expressions on SR in the near-field region are used for numerical computation. In this case, characteristics of SR emitted from both the ideal- and arbitrary-field devices can be calculated. For details of numerical implementation, refer to [1] and [2]. The users who are publishing their results obtained with SPECTRA are kindly requested to cite [3].

Before ver. 7.2, the magnetic field was assumed to be constant in the transverse (x-y) plane. In other words, only the dipole components were taken into account. This considerably simplifies the numerical algorithm not only in the trajectory calculation but also in the spatial integration to take into account the finite electron beam emittance. In ver. 8.0, an arbitrary magnetic field has been supported to enable the evaluation of the effects due to quadrupole magnets between undulator segments and the undulator natural focusing, which would be significant for low-energy electrons. In ver. 9.0, an arbitrary electron bunch profile has been supported. The user can specify the longitudinal bunch profile, or import the macroparticle coordinates in the 6D phase space, which is usually created by the start-to-end simulation for accelerators.

In ver. 10.0, a new function to compute the photon flux density in the 4D phase space (x,x',y,y') has been implemented[4], which enables the rigorous estimation of the brilliance (brightness) of typical SR sources and the photon distribution at the source point to be utilized in other computer codes for ray-tracing simulations. Based on the phase-space density computed with this function, a numerical scheme to decompose the partially-coherent radiation into a number of coherent modes (coherent mode decomposition: CMD)[5] has been later implemented in version 10.1, which is explained in more detail here. The users who are publishing their results obtained using these numerical schemes are kindly requested to cite the relevant references. Also implemented in ver. 10.1 is a function to compute the surface power density, which is convenient to compute the heat load on the inner wall of a vacuum chamber located near the SR source and exposed to SR with a shallow incident angle.

In ver. 11.0, the solver has been widely revised to be consistent with the C++11 standard and to facilitate the maintenance and bug fix. A new function has been also implemented to compute the volume power density; this is to evaluate the heat load of SR incident on an object, which gradually decays while it transmits the object. The output data will probably be used later for heat analysis of high heat-load components in the SR beamline based on the finite element method. In addition to the above revisions, two important upgrades have been made in ver. 11. First, the format of the input parameter file has been changed from the original one (and thus not readable in other applications) to JSON (JavaScript Object Notation) format. Because the output data is also given by a JSON file, it is now easy to communicate with other 3rd-party applications. Second, the framework (GUI library) has been switched to those based on web technologies (HTML, CSS, and JavaScript). This enhances the portability between different platforms (operating systems).

In ver. 12.0, the python support, which was experimentally implemented in ver 11.0, has been extensively enhanced. Python package as a user interface to communicate with the SPECTRA GUI has been developed and is available from the Python Package Index repository (by a normal pip command). Note that this function is based on "Selenium" framework that is usually used to automatically operate the web browser. For details about how it works, refer to Python User Interface

Following the enhancement of the python support deseribed abvove, an imporant decision has been made in ver. 12.0 regarding the support for Linux platforms; because of the too diverse versions of relevant (not only GUI but also core) libraries, it is almost impossible to prepare the conventional desktop application to support all the potential distributions. Thus, only one package compiled on Ubuntu 20.04, which can be installed through dpkg/apt, is prepared as of May 2024. The users of other Linux distributions are kindly recommended to try the python version.

Getting Started

1. Open a parameter file by running [File]-[Open a Parameter File] command, or run [File]-[Create a New Parameter File] command to start with a new parameter set.
2. Select the calculation type from submenus in [Select Calculation].
3. Edit the parameters if necessary and specify the directory and data name to save the calculation results.
4. Run [Run]-[Start Calculation] command to start a calculation with current parameters.
5. A "Progressbar" appears to inform the calculation status.
6. To verify the calculation results after completion of the calculation, click "Post-Processing" tab, select the name of the output file and item(s) to check for visualization. Refer to Post-Processing for details.

Operation of the GUI

SPECTRA GUI is composed of three tabbed panels entitled as "Main Parameters", "Pre-Processing", and "Post-Processing", which are explained in what follows.

Main Parameters

The "Main Parameters" tabbed panel is composed of a number of subpanels entitled as "Accelerator", "Light Source", "Configurations", "Output File", and "Calculation Status/Processes". Note that the "Accelerator", "Light Source""Output File" subpanels are always displayed, while the others are shown when necessary.

Accelerator Subpanel

Display and edit the parameters and numerical conditions related to the electron beam. For details, refer to Accelerator Parameter List.

Light Source Subpanel

Display and edit the parameters and numerical conditions related to the light source. For details, refer to Light Source Parameter List.

Configurations Subpanel

Display and edit the parameters and numerical conditions related to the observation of radiation. For details, refer to Configurations Parameter List.

Output File Subpanel

Specify the path, name and format of the output file.

Note that a spread sheet "Output Data" is shown in this subpanel, if "Fixed Point Calculation" is selected as the calculation type. Click "Start Calculation" to start a calculation using current parameters and options, then the results are displayed when it is completed.

Calculation Status/Processes Subpanel

Display the status of a calculation in progress, or the list of Calculation Status/Processes. Click "Cancel" to stop the calculation currently running, "Cancel All" to terminate all the calculations, and "Remove" to remove the selected process.

Pre-Processing

The "Pre-Processing" tabbed panel assists the pre-processing, or the arrangement of numerical conditions not displayed in the "Main Parameters" panel.

Data Import

Import a data set prepared by the user, which is necessary for several types of calculations. The types of data sets available in SPECTRA are summarized below.

Meanings of the items and variables are as follows.

• time: arrival time, or longitudinal position along the electron bunch
• DE/E: normalized energy deviation (dimensionless)
• I: beam current (A)
• j: beam current density (A/100%)
• z: longitudinal coordinate along the beam axis
• Bx,By: horizontal and vertical magnetic fields
• Gap: gap of the ID
• Depth: depth positions where the Volume Power Density is calculated

The unit of j may need to be explained; it is given as the current per unit energy band; in a mathematical form, \[I(t)=\int j\left(t, \frac{DE}{E}\right) d\frac{DE}{E}\]

The format of the ASCII file for the 1D data is as follows (magnetic field distribution as an example)

z	Bx	By
-8.959978e-01	5.174e-05	7.035e-06
-8.949972e-01	5.423e-05	7.062e-06
-8.939967e-01	5.646e-05	7.244e-06
		(omitted)
 8.979989e-01	4.801e-05	6.639e-06
 8.989994e-01	4.582e-05	6.327e-06
 9.000000e-01	4.409e-05	6.456e-06

The 1st line (title) is optional. In the above format, the interval of the independent variable (z) does not have to be necessarily constant, which is not the case for the 2D data; the format should as follows

time	DE/E	j
-1.0e-3	-0.01	0.001
-0.9e-3	-0.01	0.002
-0.8e-3	-0.01	0.003
    (omitted)
0.8e-3	-0.01	0.003
0.9e-3	-0.01	0.002
1.0e-3	-0.01	0.001
-1.0e-3	-0.008	0.001
-0.9e-3	-0.008	0.002
-0.8e-3	-0.008	0.003
    (omitted)
0.8e-3	-0.008	0.003
0.9e-3	-0.008	0.002
1.0e-3	-0.008	0.001
    (omitted)
-1.0e-3	0.01	0.001
-0.9e-3	0.01	0.002
-0.8e-3	0.01	0.003
    (omitted)
0.8e-3	0.01	0.003
0.9e-3	0.01	0.002
1.0e-3	0.01	0.001

For reference, such a data format is created in the C/C++ language as follows.

for(n = 0; n < N; n++){
  for(m = 0; m < M; m++){
    cout << t[m] << " " << de[n] << " " <<  j[m][n] << endl;
  }
}

Note that the order of the "for loop" is arbitrary; the 1st and 2nd lines can be swapped in the above example.

After preparing the ASCII file, click "Import" button and specify the file name in the dialog box to import it. The unit of each item should be chosen before importing, in the Units for Data Import dialog box that pops up by running [Edit]-[Units for Data Import] command or clicking "Edit Units" button. Note that the unit of the imported data cannot be changed, so you need to import the data again with the correct unit in case a wrong unit has been chosen. Also note that the units of several items (I, j, DE/E) are fixed, and cannot be selected when importing.

Visualization

After importing, the data sets can be visualized to verify if the configurations (unit and format of the data file) are correct. An example is shown below.

Besides the imported data sets as described above, there exist a number of items that can be visualized, which are listed in the top left of this subpanel. Just click one of them for visualization. Note that several of them are available only under specific conditions, which are summarized below.

Analytical Method to Evaluate the Harmonic Intensity

It is well known that the effects due to magnetic errors in undulators can be evaluated using an analytical formula \[I_r/I_0=\exp(-k^2\sigma_{\phi}^2),\] where $I_0$ means the photon intensity available with an ideal condition, $I_r$ means that in a real condition with magnetic errors, $k$ is the harmonic number, and $\sigma_{\phi}$ is the RMS phase error.

Although the above formula is valid for radiation emitted by a single electron observed on axis (with an infinitely narrow angular acceptance), it overestimates the effects due to magnetic errors in a more realistic condition that the electron beam emittance and energy spread are finite, and/or the the angular acceptance in the beamline is not narrow; these factors effectively work to recover the normalized intensity $I_r/I_0$. To estimate $I_r/I_0$ with these recovery factors, an alternative method [9] can be used, whose results are shown together with those using the conventional method.

Analyze Particle Data

"Analyze Particle Data" pre-processing operation is available when "Particle Distribution" is selected as "Bunch Profile", as shown below. Note that the user needs to specify in advance the data file containing the macroparticle positions in the 6D phase space, which is usually generated by another simulation code. Refer to Particle Distribution for details.

Once "Bunch Profile" is specified, SPECTRA automatically loads the file to analyze the particle data. For convenience, part of the data file is shown in "File Contents" Select the unit and column index for each coordinate variable of the 6D (x,x',y,y',t,E) phase space and input relevant parameters. In the above example, each macroparticle has the charge of 3.5fC with "x" coordinate (horizontal position) located in the 1st column and the unit of m. Note that"Slices in 1σ_s" specifies the number of bins in the RMS bunch length, to be used for data analysis. Then, additional configurations appear in the GUI to specify how to visualize the results of analysis. In the above example, the current profile is plotted. Upon revision of the configurations above, SIMPLEX automatically analyzes the data with the new configuration and visualizes the result.

Besides the slice parameters shown in the above example, macroparticle distributions can be directly plotted. For example, distribution in the (E-t) phase space is plotted in the figure below.

The result of analysis can be exported and saved as an ASCII file; "Export Selected" exports the data currently plotted, while "Export Slice Data" exports the whole slice data (slice paramters vs. s). The exported data file can be used later as the custom data file for slice parameters or current profile.

Post-Processing

The "Post-Processing" tabbed panel assists the user to visualize the calculation results. The output file is automatically loaded upon completion of a calculation, or alternatively, the existing output files can be imported. To do so, click "Import" button and specify the path of the output file.

For visualization, select more than one item from "Items to Plot". The dimension of the plot depends on the calculation type of the loaded file. In a 1D plot, a desired area can be zoomed in by dragging. Other options are available to operate the plot, by clicking one of the small icons located in the right top of the plot. For details, refer to the documents about "Plotly" library to be found online.

Besides the above options, the plot can be configured in a dialog panel that appears by clicking a small icon (pencil) located in the top right of the plot. Options available are as follows; switch the scale (linear or log), change the 2D plot type (contour, color-scale surface or shaded surface), or change the method of scaling in each frame for multidimensional plot (see below).

Comparative Plot

If more than one output file with the same calculation type is loaded, "Comparative Plot" is available, and possible data names are shown. Click the desired ones to compare the results. Note that 1D data sets are shown in the same plot, however, 2D data sets are plotted separatory and thus more than one plots are shown. How to arrange the plots can be specified by "Plot Windows/Row" parameter. If there are 6 plots in total and this parameter is set to 3, they are arranged in 3 columns times 2 rows.

Multiple Plot

This option is available for more than two data sets having different calculation types and thus "Comparative Plot" is not available. It tries to create a number of plots and display in the plot area. How to arrange the plots can be specified by "Subplots/Row" parameter. If there are 6 plots in total and this parameter is set to 3, they are arranged in 3 columns times 2 rows.

Plotting 3/4-Dimensional Data

There exist a number of calculation types to generate 3D or 4D output data in SPECTRA (including the Scanning a Parameter option), which cannot be plotted in a straightforward manner. In SPECTRA, the 3D/4D data are "sliced" into a number of data sets and plotted as a 1D or 2D graph. As an example, let us consider the visualization of a Wigner function calculated in the 4D phase space (X,X',Y,Y'). SPECTRA offers several combinations for plotting and slicing variables. If a pair (X,X') is chosen as the plotting variable, then the data is sliced at each (Y,Y') position, and 2D plot (Brilliance vs X,X') is created. Note that the coordinates of the slicing variables can be arbitrary chosen within the possible range, by dragging the sliders indicating their positions.

The post-processed output data can be saved as another JSON file in two methods explained below.

Export as ASCII

The visualization result, or the data set(s) currently plotted, are exported as an ASCII file.

Save

The plot configurations together with the output data are saved in a JSON file. The file can be later imported by the post-processor to reproduce the plot.

Parameter Set

In SPECTRA, parameters and numerical conditions displayed in the "Accelerator", "Light Source" and "Configurations" subpanels are separately saved in JSON objects, each of which is referred to as a Parameter Set. For example, "Accelerator Parameter Set" means a JSON object that stores the parameters displayed in the "Accelerator" subpanel. In addition, "Beamline Parameter Set" is available to bundle the three Parameter Sets, which represent a "beamline" in a specific SR facility. Each Parameter Set can be switched from one to another by selecting from the submenus in "Parameter Set" main menu. To configure (rename, duplicate, or delete) the parameter sets, run Edit menu command. Then a modal dialog box pops up to show the current contents of all the parameter set as shown below.

Select the target item for configuration; in the above example, "Beamline bl03" is the target parameter set. Click one of the buttons for operation; for example, to rename or duplicate the parameter set currently in selection, enter a new name in the text entry box in the left bottom and click [Rename] or [Duplicate] button. To delete the parameter set, click [Delete] button; note that at least one parameter set should be left.

Menu Commands

File

Select Calculation

Select the type of calculation. Refer to Calculation Type for details.

Run

Parameter Set

Select and edit the "Parameter Set", Refer to Parameter Set for details.

Edit

Open one of the Setup Dialogs to set up various configurations, not included in the Parameter Sets.

Help

Open the reference manual or show the information about SPECTRA.

Setup Dialogs

Open a dialog to edit miscellaneous parameters besides those displayed in the main panel. Details of each dialog are explained below.

Setup Dialogs opened by running a submenu of "Edit" menu

Submenu	Details
Filter/Absorber Material	Open a dialog to edit the material available for the filters and absorbers. In SPECTRA, a number of built-in materials are available (gray-painted ones), which cannot be edited. To add a new material, input its name and density in an empty column, together with the atomic number (Z) and mass ratio (Ratio) of each element constituting the material. The total amount of the mass ratio should be 1. The numbers of columns (materials) and rows (elements) are automatically increased when necessary.
Units for Data Import	Open a dialog to select the unit of items in the Data Import. Note that the selection should be made before importing the data. After importing, change of the unit in this dialog has no effect.
Numerical Accuracy	Open a dialog to customize the target numerical accuracy. Note that this menu is not available if "Default" is selected for Accuracy option. There are a number of parameters to specify the numerical accuracy, according to the numerical method and target item. Refer to the table below. Configurations to specify the target numerical accuracy. Item Details/Example Integration/Discretization Step Step size for integration or discretization of a function. Larger numbers mean finer steps. Longitudinal Step Along the longitudinal axis. For example, steps to comupte the electron trajectory in the SR source. Transverse Grid Over the transverse (spatial and/or angular) coordinate. For example, convolution with the spatial distribution function of the electron beam. Electron Energy Step Photon energy steps. For example, spectrum of SR emitted by a single electron, which is obtained by FFT. Photon Energy Step Electron energy steps in convolution with the energy distribution function of the electron beam. Integration Range Integration range for integration or discretization of a function. Larger numbers mean broader ranges. Longitudinal Range Downstream and upstream ends of the longitudinal coordinate. Transverse Range Transverse range for integration and convolution. Photon Energy Range Photon energy range to be taken into account. Electron Energy Range Ehoton energy range to be taken into account Others Harmonic Convergence An integer to judge the convergence of harmonics (maximum harmonic number to be taken into account). Larger numbers mean higher harmonics Energy Consistency Adjust the energy loss of the electron beam to be consistent with the FEL gain. Available when FEL Mode option is enabled. Monte Carlo Integral Tolerance A real number to judge the convergence of integration for Monte-Carlo method. Coherent Radiation Integral Tolerance A real number to judge the convergence of integration for coherent raddiation calculation. Limit Macroparticles If checked, limit the number of macroparicles for Monte-Carlo method. Maximum Macroparticles Maximum number of macroparticles (see above).
MPI Settings	Open a dialog to configure the parallel computing. Tick "Enable Parallel Computing" to enable the parallel computing and input a number of processes to launch in "Number of MPI Processes". Note that MPI (message passing interface) environment should be installed for parallel computing, and the path to "mpiexec" should be set.

Edit the Plot

Besides standard Plotly.js configurations, a number of options to edit the graphical plot in the post- and pre-processors are available. To do so, click the small icon located in the top-right side of the plot. Then a dialog box pops up to let the user edit the plot in the following configurations.

Parameter List

All the parameters available in the subpanels of the "Main Parameters" panel are summarized below, for each subpanel.

Accelerator

       x        x'      y        y'        t     DE/E
 6.20E-4 -6.08E-5 4.83E-4 -7.72E-5 -7.68E-15 -0.00133
-2.88E-4 -1.83E-5 7.21E-4 -4.09E-5 -5.49E-15 -9.08E-4
                ...
 9.22E-4 -1.09E-5 0.00160 -1.47E-4  5.33E-16  3.48E-4

Light Source

Parameter/Option	Detail
Main Parameters
Gap (mm)	Gap of the ID.
Bx,y (T)	Field amplitude (IDs) or uniform field (BMs).
B (T)
Main Field (T)	Peak fields of the main and sub poles of Wavelength Shifters.
Sub Field (T)
λu (mm)	Magnetic Period Length of the ID
Device Length (m)	Total length of the ID
Reg. Magnet Length (m)	Length of the ID for the regular period.
# of Reg. Periods	Number of regular periods.
K0x,0y	Available for APPLE undulators. Maximum K values (deflection parameters) when the phase is adjusted to generate horizontal and vertical polarizations.
Phase Shift (mm)	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.
Kx,y	K values of the ID.
K value
K⊥	Composite K value defined as $\sqrt{K_x^2+K_y^2}$.
ε1st (eV)	Fundamental photon energy and wavelength of undulator radiation.
λ1st (nm)
Harmonic Component	Arrange the harmonic components for Multi-Harmonic Undulators. Kx Ratio ($=R_n$) and Phase ($=P_n$, in degrees) refer to the fraction and phase of the horizontal field of the n-th harmonic component, where n is the number indicated in the 1st row. The K value corresponding to the n-th harmonic is defined as \[K_{xn}=K_x\frac{R_n}{\sqrt{R_1^2+R_2^2+\cdots+R_N^2}},\] where $K_x$ is the (total) K value and $N$ is the maximum harmonic number. The field distribution is defined as \[B_{x}(z)=\sum_{n=1}^{N}B_{xn}\sin\left[2\pi\left(\frac{nz}{\lambda_u}+\frac{P_n}{360}\right)\right],\] where $B_{xn}$ is the peak field corresponding to the K value of the n-th harmonic. Similar definitions of $K_{yn}$ and $B_{y}(z)$.
ρ (m)	Radius of the BM.
BM Length (m)	Specify the geometric configuration of BMs. "Origin for CSR" defines the longitudinal coordinate where the electron bunch length or the temporal profile is defined to calculate coherent radiation.
BM Fringe Length (m)
Origin for CSR (m)
Main Length (m)	Lengths of the main and sub poles of the Wavelength Shifter.
Sub Length (m)
BM Interval (m)	Distance between two BMs.
Field Mapping Data	File name containing the 3D magnetic field data. Refer to Magnetic data format for custom sources for details.
σr,r' (mm,mrad)	Natural source size and angular divergence of radiation.
σrx,rx' (mm,mrad)
σry,ry' (mm,mrad)
Σx,x' (mm,mrad)	Effective source size and angular divergence of the photon beam, convoluted with those of the electron beam.
Σy,y' (mm,mrad)
Flux Density	Approximate values of the on-axis flux density, available flux, and brilliance at ε1st.
Flux1st
Brilliance1st
Peak Brilliance	Peak brilliance at ε1st evaluated with the peak current of the electron beam.
Bose Degeneracy	Bose degeneracy evaluated for the Peak Brilliance.
εc (eV)	Critical photon energy and wavelength.
λc (nm)
Total Power (kW)	Total radiation power.
Total Power/Rev. (kW)	Total power/revolution and linear power density of the BM.
Lin. Pow. Density (kW/mrad)
Options
Gap-Field Relation	Specify the relation between the gap and peak field of the ID. "None": no relation is given. The Gap parameter is not available. "Automatic": evaluate according to an analytical formula of Halbach array defined as \[B(g)=1.8G B_r\mbox{exp}(-\pi g/\lambda_u),\] where $B_r$ is the remanent field of the magnet and $G$ is a geometrical (reduction) factor coming from the physical boundary conditions such as the finite dimension of magnet blocks. "Import Table": evaluate by interpolating the imported data.
APPLE Configuration	Enable/disable the APPLE configuration for Elliptic Undulators.
Field Structure	Specify the field-distribution symmetry of the ID. "Antisymmetric": anti-symmetric with respect to the center (sine-like). "Symmetric": symmetric with respect to the center (cosine-like).
Br (T)	Remanent field of the permanent magnet.
Geometrical Factor (x,y)	Geometrical factor to reduce the peak magnetic field (x,y).
End Correction Magnet	Put additional magnets at the both ends, for orbit compensation.
Natural Focusing	Apply the natural focusing of IDs. "None": no focusing considered. "Bx": horizontal field (and focusing). "By": vertical field (and focusing). "Both": focus in the both directions.
Tandem Arrangement	Calculate radiation from two BMs located at the both ends of the straight section.
Parameters for the Field-Error Condition
Field Offset & Taper	Specify if the magnetic field contains an error component.
Offset x,y (T)	Magnetic field offset, such as that coming from the ambient field.
Lin. Taper x,y (/m)	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.
Quad. Taper x,y (/m2)
Parameters to Specify the Phase Error
Add Phase Error	If ticked, the RMS phase error and relevant parameters can be specified.
Random Number Seed	Seed for the random number generator to model the field error.
σB (%)	RMS of the peak field variation.
σφ (deg.)	RMS of the phase error [6].
σx,y (mm);	RMS of the trajectory error.
Parameters for the Segmented Undulator Option
Segmentation	Arrange the segmented undulator configuration. For details of how these segmentation schemes work to improve the characteristics of radiation, refer to [7] and [8]. To adjust the optical phase ($\Delta\phi$) in each drift section, SPECTRA assumes that a phase shifter, or a 1.5-period undulator with the same periodic length, is installed at the center of the drift section, whose amplitude is tuned to generate the specified phase. Five options are available as explained below. "None": no segmentation. "Identical": all segments have the same specification (a). "2nd: Swap Bx,y": horizontal and vertical fields are swapped in even segments (b). "2nd: Flip Bx": polarity of the horizontal field is swapped in even segments (b). "2nd: Flip By": polarity of the vertical field is swapped in even segments (b).
Number of Segments	Number of undulator segments (M) if "Identical" is selected for "Segmentation", or number of segment pair (M') for other options.
Half Number of Segments
Segment Interval (m)	Distance between the center positions of adjacent undulator segments.
Number of Phase Slip@λ1	Slippage in the drift section given in the unit of λ1st.
Δφ (π)	Additional phase in the unit of π.
Δφ1,2 (π)	Additional phase in the unit of π: subscripts 1 and 2 refer to the odd and even drift sections
Matching Distance (m)	Distance between virtual focusing magnets in the matching section to arrange the periodic lattice function.
Periodic β Function	The betatron function is periodic with the period of segment interval.

Light Source Type

Details of the type of the light sources available in SPECTRA are summarized below.

Magnetic data format for custom sources

When one of the custom light sources ("User Defined", "Periodic: User Defined", and "Field Mapping") is chosen, the user should prepare a data file to import the magnetic data. The format of the data file depends on the ligt source and is summarized below.

z	Bx	By
-8.959978e-01	5.174e-05	7.035e-06
-8.949972e-01	5.423e-05	7.062e-06
-8.939967e-01	5.646e-05	7.244e-06
		(omitted)
 8.979989e-01	4.801e-05	6.639e-06
 8.989994e-01	4.582e-05	6.327e-06
 9.000000e-01	4.409e-05	6.456e-06

0.2	0.3	0.5	11	13	421
1.23456e-1	2.3456e-1	3.4557e-1
2.23456e-1	3.3456e-1	6.4557e-1
	...
4.23456e-1	5.3456e-1	8.4557e-1
2.23456e-1	3.3456e-1	6.4557e-1

Configurations

Parameter/Option	Detail
Main Parameters
Position x,y (mm)	Transverse position/angle at the observation point.
Angle θx,y (mrad)
Energy Range (eV)	Energy range and pitch for Energy Dependence calculations.
Energy Pitch (eV)
Energy Pitch for Integration (eV)	Energy pitch for integration in Volume Power Density calculations. Needs to be defined by the user for User Defined light sources.
Points (Energy)	Number of energy points for Energy Dependence calculations.
Detuning	Photon energy defined as a detuned value, i.e., $\varepsilon/(n\varepsilon_1)-1$, where $n$ is the target harmonic number.
Target Energy (eV)	Photon energy to be fixed.
Normalized Energy	Same as the above, but normalized by ε1st.
Auto Config. for Energy Range	Enable automatic configuration to define the energy range and pitch.
Auto Config. for Transverse Range	Enable automatic configuration to define the spatial/angular range and grid intervals.
x Range (mm)	Range of the Observation positions/angles for "Spatial Dependence" calculations: (a) [Along Axis] and [Mesh: x-y] and (b) [Mesh: r-φ].
θx Range (mrad)
y Range (mm)
θy Range (mrad)
r Range (mm)
θ Range (mrad)
φ Range (deg.)
Points (x)	Number of observation point in the relevant range.
Points (y)
Points (r)
Points (θ)
Points (φ)
Distance from the Source (m)	Distance from the center of the light source to the observation point.
Slit Pos.: x,y (mm)	Specify the configuration of the slit positions and aperture.
Slit Pos.: θx,y (mrad)
Δ/Σs: x,y
Δx,Δy (mm)
Slit r1,2 (mm)
Slit θ1,2 (mrad)
Depth Range (mm)	Depth range and number of points for Volume Power Density calculations.
Points (Depth)
Δθx,y (mrad)	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.
Illuminated x,y (mm)
Glancing Angle (deg.)
Azimuth of Incidence (deg.)
x Range (mm)	Position of the object and range of observation for Spatial Power Density calculations. Note that SPECTRA distinguishes the inner and outer sides of the surface. To be specific, the above figure shows the case when the inner size indicated by a red line is facing the beam axis, and thus receives the radiation power. If, in contrast, the object with the same normal vector is located at a negative position of x, the inner surface is facing outsize and it does not receive any radiation
y Range (mm)
z range (m)
Surface Pos. x (mm)
Surface Pos. y (mm)
Surface Radius (mm)
Points (x)	Number of observation points in the relevant range
Points (y)
Points (z)
Θ (deg.)	Normal vectors to specify the inner surface of the object irradiated by SR. In "Fixed Point Calculation" calculations, the normal vector to the object surface is specified more flexibly by two angles as schematically illustrated below. For example, Θ = Φ = 0 means that the surface of the object is parallel to the y-z plane, with its inner side facing the beam axis. Angles of the normal vector to define the inner surface illuminated by radiation for Spatial Power Density calculations.
Φ (deg.)
Σx,y@ε1st (mm)	Photon beam size and divergence at the observation position, defined at ε1st. Note this is a rough estimation and does not take into account the energy spread of the electron beam.
Σx',y'@ε1st (mrad)
Σpx,py (mm)	Spatial spread and divergence of the radiation power at the observation position
Σpx',py' (mrad)
K Range	Range of the K values and number of points.
K⊥ Range
Points (K)
ε1st Range (eV)	Range of the fundamental energy determined by the above K-value range.
Power Upper Limit (kW)	Upper limit of the partial power to define the width and height of the rectangular slit for K Dependence calculations.
Harmonic Range	Harmonic range or target harmonic number for K-value dependence calculations.
Target Harmonic
Temporal Range (fs)	Temporal range and number of points for Time Dependence calculations.
Points (Temporal)
Maximum Harmonic	Maximum harmonic number to be considered.
Slice X (mm)	Transverse positions and angles at the source point where the Wigner function is calculated. These parameters should be distinguished from those indicated by lower letters, which mean the transverse positions at a certain longitudinal position downstream of the light source.
Slice Y (mm)
Slice X' (mrad)
Slice Y' (mrad)
X Range (mm)	Calculation range/number of points of the transverse positions/angles at the source point. Should be distinguished from those indicated by lower letters (see above).
Points (X)
X' Range (mrad)
Points (X')
Y Range (mm)
Points (Y)
Y' Range (mrad)
Points (Y')
γΔθx,y	Angular acceptance normalized by γ-1 to calculate the Wigner function.
X' Acceptance (mrad)
Optical Element	Optical element to be inserted.
Position (m)	Position of the optical element.
Aperture x (mm)	Aperture size of the slit.
Aperture y (mm)
Slit Distance x (mm)	Distance of the double slit.
Slit Distance y (mm)
Soft Edge Fringe Size (mm)	Length of the soft-edge region.
Limit of Diffraction Effect	Target tolerance to define the threashold of the angular range when a slit is inserted.
Larger Angular Range	An integer to define the angular range to evaluate the CSD.
Larger Angular Range	An integer to define the angular range to evaluate the CSD.
Larger Angular Range	An integer to define the angular range to evaluate the CSD.
Focal Length x (m)	Focal length of the thin lens.
Focal Length y (m)
Angular Profile	Export the angular profile
Wigner Function	Export the Wigner function after the optical element.
Cross Spectral Density	Export the CSD.
Degree of Coherence	Export the spatial degree of coherence.
Options
Filtering	Specify the type of filtering. "None": no filter is assumed. "Generic Filter": slab or layer that attenuates the photon beam, made of any material. "BPF: Gaussian": Gaussian bandpath filter. "BPF: Boxcar": boxcar-type bandpath filter. "Custom": evaluate the transmission rate by interpolating the imported data.
Energy Step	Specify how to change the energy/depth position in the calculation range. "Linear": linear variation (constant interval). "Logarithmic": logarithmic variation (constant ratio).
Depth Step
Slit Aperture Size	Specify how to represent the width and height of the rectangular slit. "Fixed": fixed aperture "Normalized": normalized by Σx,y@ε1st (mm),, and is varied for K Dependence calculations
Define Obs. Point in	Specify how to represent the transverse observation points. "Position": in position. "Angle": in angle.
Normalize Photon Energy	Specify the photon energy as a normalized value.
Set Upper Limit on Power	Put an upper limit on the allowable partial power.
Optimize ΔX' for Computation	Horizontal angular acceptance is virtually closed to reduce the computation time, without changing the calculation results.
Level of Smoothing Along X	Apply smoothing for the Wigner function of BMs and wigglers; larger values results in more smooth profiles.
Observation in the Fourier Plane	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)
Wiggler Approximation	Apply the wiggler approximation, in which radiation incoherently summed up (as photons).
Spectral Smoothing	Apply the spectral smoothing; this is useful to reduce the computation time by smoothing the spectral fine structure potentially found in undulator radiation.
Smoothing Window (%)	Smoothing window in %; this means that the photon flux at 1000 eV is given as the average from 995 to 1005 eV.
Accuracy	Specify the numerical accuracy. In most cases, "Default" is recommended, in which case SPECTRA automatically arranges all the relevant parameters. If "Custom" is selected, the user should configure each parameter. Refer to Numerical Accuracy for details.
Parameters to Specify the BPF
Central Energy (eV)	Central photon energy of the bandpath filter (BPF).
Width (eV)	Full width of the boxcar-type BPF.
Width (σ, eV)	1σ of the Gaussian BPF.
Max. Trans. Rate	Maximum transmission rate of the BPF.
Parameters for the CMD (coherent mode decomposition)
Perform CMD?	Perform "Coherent Mode Decomposition" after calculating the Wigner function.
Export Field Profile	Calculate and export the modal profiles based on the CMD results "None": do not export. "JSON": export in the JSON format. "BINARY": export in the binary format. "Both": export in the both formats.
Export Intensity Profile	Calculate and export the modal intensity profiles based on the CMD results
Compare Wigner Function	Reconstruct the Wigner function using the CMD result to check its validity.
Compare Intensity Profile	Reconstruct the flux density profile using the CMD result to check its validity.
Apply GS Model	Use Gaussian-Schell (GS) model to simplify the CMD and reduce computation time.
GS Model X/Y	Use Gaussian-Schell (GS) model for CMD. Select the axis to apply. "None": do not use GS model. "X": GS model for horizontal axis. "Y": GS model for vertical axis. "Both": GS model for both axes.
HG Order Limit (X,Y)	Upper limit of the order of the Hermite-Gaussian functions to be used in the CMD.
HG Order Limit (X)
HG Order Limit (Y)
Max. HG Order (X,Y)	Maximum orders of the coherent mode.
Max. HG Order (X)
Max. HG Order (Y)
Maximum CMD Order	Maximum number of the coherent modes for post-processing (exporting the modal profile, reconstructing the Wigner functions).
Flux Cutoff	Cutoff flux (normalized) to be used to determine the maximum HG order of of each coherent mode.
Amplitude Cutoff	Cutoff amplitude (normalized) of individual modes, below which Hermite-Gaussian functions are neglected.
Range: X,Y (mm)	Range of the spatial grid to export the modal profile.
Range: X (mm)
Range: Y (mm)
Step: X,Y (mm)	Intervals of the spatial grid points to export the modal profile.
Step: X (mm)
Step: Y (mm)
Parameters for the FEL mode
FEL Mode	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."Reuse Bunch Factor": reuse the bunch factor evaluated in the former calculations. This option is available by opening a former calculation result of coherent radiation, with the FEL mode option enabled.
Pulse Energy (mJ)	Seed pulse energy.
Wavelength (nm)	Seed wavelength.
Pulse Length (FWHM, fs)	Seed pulse length.
TL. Pulse Length (FWHM, fs)	Transform-limited pulse length of the chirped seed pulse.
Source Size (FWHM, mm)	Seed source size.
Waist Position (m)	Longitudinal position where the seed pulse forms a beam waist.
Timing (fs)	Relative time of the seed pulse with respect to the electron beam.
GDD (fs2)	Group delay dispersion and third order dispersion of the chirped seed pulse.
TOD (fs3)
Pulse Energy: 1,2 (mJ)	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.
Step: Initial, Interval (m)	Define the longitudinal step to solve the FEL equation. Refer to the schematic drawing for details. The light source is divided into a number of steps (indicated by yellow arrows), and each step is further divided into a number of substeps (blue arrows). The bunch factor of the electron beam is assumed to be constant within a step and is updated at the end, which is then used to calculate the coherent radiation in the next step. The radiation waveform is assumed to be constant within a substep besides the slippage effect and is updated at the end, which is then used to evaluate the interaction with electrons in the next substep. A number of data sets used in each step is saved in the output file, if Export Intermediate Data option is enabled.
Substeps for Radiation
Photon Energy ROI (eV)	Photon energy range of interest to solve the FEL equation.
Number of Particles	Number of macro-particles to represent the electron beam.
e- Energy Interval	Interval of the electron energy deviation to export the electron density in the (E-t) phase space.
R56 (m)	Strength of the virtual dispersive section. Need to be specified if Bunch with Dispersion option is enabled.
Export Intermediate Data	Export the intermediate data evaluated during the process of solving the FEL equation.
Bunch with Dispersion	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.
E-t Data	Export the electron density in the (E-t) phase space.
Parameters for the wavefront propagation
Transverse Grid	Specify the transverse grid at each longitudinal step. "Automatic": automatically determined. "Normalized": specify the grid intervals normalized by the RMS beam size at each longitudinal step. "Fixed": specify the grid intervals directly.
Finer Spatial Grid	Specify a finer grid interval if "Automatic"is selected for "Transverse Grid". Default is 0 and a larger number means a finer interval.
Optical Element	Specify an optical element inserted in the beamline. "None": no optical elements. "Single Slit": insert a single slit. "Double Slit": insert a double slit. "Ideal Thin Lens": insert an ideal thin lens.
Position (m)	Longitudinal position to insert an optical element.
Aperture x (mm)	Horizontal aperture size.
Slit Distance x (mm)	Distance between the double slit in the horizontal direction.
Aperture y (mm)	Vertical aperture size.
Slit Distance y (mm)	Distance between the double slit in the vertical direction.
Soft Edge Fringe Size (mm)	Range of the "Soft Edge"of the slit. At the edge of the slit, the photon intensity is supposed to gradually drop, as opposed to a hard-edged condition. Longer soft-edge ranges reduce the diffraction effects. In addition, the memory requirement is relaxed as well.
Limit of Diffraction Effect	Specify the threshold to cut off the diffraction effects and determine the angular range to compute the Wigner function after passing through a slit.
Required Memory (MB) ~	Approximate memory size needed during the computation. The parameters should be arranged so that this value is not too large.
Focal Length x (m)	Focal length of an ideal lens in the horizontal direction.
Focal Length y (m)	Focal length of an ideal lens in the vertical direction.
Larger Angular Range	Specify the angular range to evaluate the Wigner function after an optical element. If set to 0, the angular range is determined to be consistent with the relevant parameters; a larger number means a large angular range.
Wigner Function	Export the Wigner function after an optical element.
Angular Profile	Export the angular profile after an optical element.
Cross Spectral Density	Export the cross spectral density.
Degree of Coherence	Export the degree of spatial coherence.

Binary Format for the Modal Profile

The binary format to export the modal profile is defined below.

• Integer (4 byte) $\times\:3$: $N_m$, $N_X$, $N_Y$
• Double (8 byte) $\times\:2$: $\Delta X$, $\Delta Y$
• Double (8 byte) $\times\:N_XN_Y$: 0-th Mode Profile Real Part
• Double (8 byte) $\times\:N_XN_Y$: 0-th Mode Profile Imaginary Part
• ...
• Double (8 byte)$\times N_XN_Y$: ($N_m$-1)-th Mode Profile Imaginary Part

where $N_m$ is the number of coherent modes, $\Delta X$ and $N_{X}$ are the interval and number of positions along the horizontal (X) axis, and similar expressions for the vertical (Y) axis. The order index j in each array representing the real/imaginary part of the complex amplitude is given as \[j=j_x+j_yN_X\] where $j_x$ and $j_y$ refer to the order indices corresponding to the X and Y positions. To be specific, the X index changes first.

Calculation Setup

Details of how to setup and start the calculations are presented here, together with explanations of the type of calculations and output items available in SPECTRA.

General Method

Open a Parameter File

Upon being started, SPECTRA tries to load parameters from the parameter file that was opened last time. If successful, the parameters are shown in the "Main Parameters" panel. If SPECTRA is run for the first time after installation, default parameters will be shown. To open a new SPECTRA parameter file, run [File]-[Open a Parameter File] command. In the initial setting, the parameter files are found in the directory "[SPECTRA Home]/prm" with a default suffix "json", where "[SPECTRA Home]" is the directory in which SPECTRA has been installed.

Select a Calculation Type

Before starting any calculation, "Calculation Type" should be selected by running one of the submenus in [Select Calculation]. Refer to Calculation Type for details of each calculation type.

Arrange the Output File

Arrange the output file to save the calculation results in the Output File subpanel.

Start Calculation

Run [Run]-[Start Calculation] command to start a single calculation. Then "Calculation Status/Processes" subpanel is displayed in the "Main Parameters" panel to indicate the progress of calculation. To cancel the calculation, click "Cancel" button. Note that the serial number is automatically incremented once the calculation is started, unless it is not negative (-1). This is to avoid the overlap of the output file name in performing successive calculations. When the calculation is completed, the "Calculation Status/Processes" subpanel vanishes and the result is imported in the "Post-Processing" panel for visualization.

Verify the Result

Upon completion of a calculation, the output file is automatically loaded and one of the items is plotted in the "Post-Processing" subpanel to quickly view the results. Refer to Post-Processing for details about how to operate the post-processor.

Calculation Type

To start any calculation in SPECTRA, the "Calculation Type" should be specified first. This is shown as the submenus of [Select Calculation] main menu in the GUI. The meanings and details of the submenus are summarized in the table below. After selection, the calculation type is shown in the top of the "Configurations" subpanel, which is represented by a string given by concatenating a number of submenu items. Note that a "double colon (::)" is inserted between items for clarity.

Output Items

The output items specific to respective calculation types are summarized below.

Calculation Status/Processes

To configure a number of calculations with different conditions, run [Run]-[Create Process] command every time you finish specifying all the parameters. Then the "Calculation Status/Processes" subpanel appears in the "Main Parameters" panel to show the calculation list currently saved in a temporary memory. Repeat it until all the calculations are specified. Click "Remove" button to delete the selected process, or "Cancel All" to clear out all the processes. Run [Run]-[Start Calculation] command to start the calculation processes, then a progressbar is displayed to show the status of each process.

Scanning a Parameter

Besides the method described above, it is possible to configure a lot of Calculation Status/Processes at once by scanning a specific parameter. To do so, right click the target parameter in one of the subpanels after selecting the Calculation Type, and click [Scan This Parameter] in the context menu. Then specify the configurations for scanning in the dialog box as shown below. Note that the context menu does not pop up for parameters that cannot be used for scanning.

Input the initial & final values, and number of points for scanning. For several parameters to be specified by an integer, scanning interval instead of the number of points should be given. Note that the "Bundle the output data" option is to bundle all the output data into a single output file, which can be retrieved later in the "Post-Processing" panel. The availability of this option depend on the selected Calculation Type.

If the target parameter forms a pair, such as β_{x, y} (horizontal and betatron functions), the user is requested to select the dimension for scanning: [Scan Parameter 1D/2D]. For the 2D scanning, configurations for the both parameters are needed.

After configuration, click "OK" button to create a "Calculation Status/Processes". Then the specified parameters are saved in a temporary memory and the scanning process is saved in the calculation list. Run [Run]-[Start Calculation] command to start the calculation.

Notes on Scanning ε_1st

When scanning the fundamental energy of undulators having both (horizontal and vertical) K values (K_x and K_y), such as elliptic undulators, the ratio of the two (K_x/K_y) depends on "Gap-Field Relation" option as summarized below.

Parallel Computing

To reduce the computation time, parallel computing based on the MPI is available in SPECTRA. To enable this option, refer to MPI Settings setup dialog.

Advanced Functions

Besides the fundamental properties of SR such as the flux and radiation power, which can be calculated in a rather straightforward manner, SPECTRA offers a method to evaluate a number of special characteristics of SR: Surface Power Density, Volume Power Density, Characterization at the Source Point, Coherent Mode Decomposition. In what follows, details of them are explained.

Surface Power Density

The surface power density is defined as the radiation power per unit surface area of the target object, which should be distinguished from the (normal) power density defined as the power per unit area of the transverse (x,y) plane. If the normal vector of the surface of the target object is parallel to z, there is no difference between the two. This is not the case when the normal vector is perpendicular to z; the surface power density in this configuration is much lower than the normal power density as easily understood.

Computation of the surface power density is usually much more complicated than that of the normal power density. This comes from the fact that the incident angle of SR largely depends on the longitudinal position where it is emitted, if the surface of the target object has a small glancing angle. This is not the case for computing the normal power density, where the incident angle is always nearly 90 degrees.

Volume Power Density

The volume power density is defined as the radiation power absorbed per unit volume in an object illuminated by radiation. In a mathematical form it is given by \[\frac{d^3P(x,y,D)}{dxdydD}=C\int \frac{d^2F(x,y,\omega)}{dxdy}[1-\mbox{e}^{-\mu(\omega)D}]\mu_{en}(\omega)d\omega,\] where $\mu$ & $\mu_{en}$ are the linear attenuation & energy absorption coefficients at the photon energy $\hbar\omega$, $D$ is the distance from the surface of the object ("Depth"), and $C$ is a unit conversion factor. Note that glancing-incidence conditions can be specified as explained in the relevant parameters.

Characterization at the Source Point

In contrast to other calculations in which the observation point is assumed to be located downstream of the light source, characteristics exactly at the source point (center of the light source, z=0) are evaluated in this calculation. This is possible by propagating the emitted radiation backward to the source point using wave optics. Two options are available as follows.

Wigner Function

The photon flux density in the phase space spanned by the spatial $(x,y)=\boldsymbol{r}$ and angular $(x',y')=\boldsymbol{r}'$ coordinates, which is referred to as the phase-space density and denoted by $d(x,y,x',y')$, is an important physical quantity to characterize SR as a light source. Its maximum value, which is known as brilliance or brightness, gives the information of how many coherent photons are available. Its distribution in the phase space is necessary to carry out the ray-trace simulation based on the geometrical optics.

It is worth noting that the angular profile of SR in the far-field region is obtained by integrating $d(x,y,x',y')$ over $(x,y)$, while the spatial profile in the near-field region is obtained by integrating over $(x',y')$. Also note that these spatial and angular profiles can be computed directly from an analytical formulas based on classical electrodynamics. It should be noted, however, that there is no analytical method to calculate $d(x,y,x',y')$ directly from the first principle. The Wigner function $W(x,y,x',y')$ is introduced in SR formulation to solve this problem and makes it possible to compute $d(x,y,x',y')$ from the complex amplitude of radiation.

SPECTRA is equipped with several functions to compute the phase-space density not only for the single electron, but also for more practical conditions, i.e., the electron beam with finite emittance and energy spread. The resultant phase-space density can be computed as a function of various variables: photon energy, K value, and phase-space coordinates. For details of numerical implementation of the Wigner function, refer to [4].

Energy Dependence

The phase-space density is calculated as a function of the photon energy with other conditions being fixed. In the case of undulator radiation, the target harmonic number should be specified as well.

K Dependence

The phase-space density of undulator radiation at a specific harmonic is calculated as a function of the undulator K value. Note that the photon energy should be given as a detuning parameter with respect to the exact harmonic energy. If the calculation is done on-axis (x=y=x'=y'=0), the resultant data are comparable to the brilliance roughly estimated by a Gaussian approximation, but are based on a more rigorous method using the Wigner function.

Phase-Space Distribution

The distribution of the phase-space density is calculated as a function of the phase-space coordinate variables: x, y, x', and y'. Five types of calculation conditions are available as follows.

1. X-X' (Sliced): $W(x,y_{fix},x',y_{fix}')$
2. X-X' (Projected): $W_x(x,x')$
3. Y-Y' (Sliced): $W(x_{fix},y,x_{fix}',y')$
4. Y-Y' (Projected): $W_y(y,y')$
5. X-X-Y-Y' : $W(x,y,x',y')$

where $W_x$ is defined as \[W_x=\int\!\!\!\!\int W(x,x',y,y')dydy',\] and a similar expression for $W_y$.

Related Characteristics

When the 4D phase-space density is calculated, two important properties related to the Wigner function method are available: separability and total degree of spatial coherence. The details of them are explained as follows.

Note that the above properties, $\kappa$, $\zeta$, $\zeta_x$, and $\zeta_y$ are evaluated by a simple summation of quadratic forms of Wigner functions given at a number of grid points specified by the user, and the accuracy of integration is not checked. The user is required to input the range and number of mesh that are sufficiently wide and large to obtain a reliable result. One solution is to first check the profile of the projected Wigner functions in the 2D phase space, then input these parameters.

Spatial Profile

Spatial profile of the photon density, i.e., the spatial flux density is computed at the source point. This may be useful when discussing the profile of the photon beam after focusing optical components in the SR beamline. To be more specific, the spatial profile computed with this scheme reproduces the photon beam profile at the focal point of the unit magnification optical system.

Coherent Mode Decomposition

Coherent Mode Decomposition is a mathematical method to decompose the partially coherent radiation into a number of coherent modes. Because the propagation of each mode can be described by wave optics, designing the optical elements can be much more reliable than that with the conventional ray-tracing that is based on geometrical optics.

Mathematical Form

In the numerical CMD implemented in SPECTRA, the Wigner function $W$ is supposed to be approximated by $W'$ composed of several coherent modes, namely, \[W'=f\sum_{p=0}^{M}\mathscr{W}(\Psi_p,\Psi_p),\] with $\mathscr{W}$ meaning an operator to calculate the Wigner function of the $p$-th order coherent mode, whose complex amplitude is represented by a function $\Psi_p$, and $M$ is the maximum order of the coherent modes. The function $\Psi_p$ is assumed top have a form \[\Psi_p=\sum_{q=0}^{N_p}a_{h,j}\phi_h(\hat{x})\phi_j(\hat{y}),\] with \[\phi_m(\zeta)=\frac{2^{1/4}}{\sqrt{2^m m!}}\mbox{e}^{-\pi\zeta^2}H_m(\sqrt{2\pi}\zeta),\] denoting the m-th order Hermite-Gaussian (HG) function, where $\hat{\boldsymbol{r}=(\hat{x},\hat{y})=(x/\sqrt{\pi}w_x,y/\sqrt{\pi}w_y)}$ is the normalized transverse coordinate, $a_{h,j}$ is the amplitude of the HG function of $\phi_h(\hat{x})\phi_j(\hat{y})$, $H_m$ is the Hermite polynomial of the order $m$, and $N_p$ denotes the maximum order of the HG modes in the p-th coherent mode. Note that the indices $h$ and $j$ are given as a function of the integer $q$ and order $p$. The coefficient $f$ and the dimension of $a_{h,j}$ are chosen arbitrarily as long as the above formulas are satisfied. In SPECTRA, they are determined so that $a_{h,j}$ is dimensionless, and \[\sum_{p=0}^{\infty}\int|\Psi_p|^2d\hat{\boldsymbol{r}}=1\] is satisfied. The purpose of the numerical CMD is to compute the coefficient $a_{h,j}$ so that the resultant Wigner function $W'$ well reproduces the original function $W$. For details of the CMD method in SPECTRA, refer to [5].

How to Do?

To perform the CMD in SPECTRA, follow the steps explained below.

• Preparation of the Wigner Function: Before starting the CMD, the user should compute the Wigner function in the phase space. In addition to the 4D Wigner function $W(x,y,x',y')$, the projected ones ($W_x$ and $W_y$), are also available, in which case 1D modal functions are given in the target direction (horizontal or vertical). The range and number of points to calculate the Wigner function should be reasonably wide and large. Note that the JSON format should be chosen as the format of the output file.
• Load the Wigner Function: Open the JSON output file for the Winger function data generated in the above step, by running [File]-[Load Output File]-[Wigner Function for CMD] command. If the Wigner function data is successfully loaded, [CMD with the Wigner Function] menu is enabled under the [Select Calculation]-[Coherent Mode Decomposition] menu. Run it to show configurations for the CMD.
• Arrange the Parameters: In the Configurations subpanel, edit the parameters and options related to the CMD; refer to CMD Parameters for details. After configuration, run [Run]-[Start Calculation] command to start the CMD process.
• Verify the Result: The results of the CMD, such as the modal amplitude $a_{h,j}$, maximum orders of the HG functions, and numerical errors in the CMD process, are save in the output file, which can be directly verified by opening the output file in any text editor.
• Visualization: other data sets specified in the options before starting the CMD, such as the modal profiles and reconstructed Wigner functions, are saved as well, which can be visualized in the "Post-Processing" panel.

Wavefront Propagation

Wavefront Propagation is a function to describe the propagation of synchrotron radiation using the Wigner function. In contrast to the conventional wavefront propagation based on the multi-electron or CMD scheme, it has a potential to complete the computation with a much shorter time. The basic concept has been proposed in 1980's and is found in [10]. Besides simple porpagation in the drift space, two typical optical elements are available: single/double slit and ideal lens. Although the availability is currently limited, efforts are under way to extend the capability of this scheme to a wider variety of components.

How to Do?

To perform the wavefront propagation, follow the steps explained below.

• Prepare and Load the Wigner Function: before starting, the Wigner function data should be generated and loaded. Refer to file:///T:/SourceCode11/spectra/12.0/prj/src/spectra.html#How%20to%20Do? for details.
• Arrange the Parameters: In the Configurations subpanel, edit the parameters and options related to the wavefront propagation; refer to Wavefront Propagation Parameters for details. After configuration, run [Run]-[Start Calculation] command to start the wavefront propagation process.
• Verify the Result: The results of the CMD, such as the modal amplitude $a_{h,j}$, maximum orders of the HG functions, and numerical errors in the CMD process, are save in the output file, which can be directly verified by opening the output file in any text editor.
• Visualization: other data sets specified in the options before starting the CMD, such as the modal profiles and reconstructed Wigner functions, are save as well, which can be visualized in the "Post-Processing" panel.

File Format

Besides the operation based on the GUI, SPECTRA (more precisely, the solver) can be utilized to communicate with external codes for the so-called start-to-end simulations. This actually requires the knowledge of the format of the input and output files, which is explained in the followings.

JSON Format

To deal with the many parameters and options, SPECTRA utilizes the JSON (JavaScript Object Notation) format, which is described by a number of "objects". The object contains a number of "pairs" formed by a "key" and "value", separated by a colon ":", and should be enclosed by a curly bracket {}. The value can be one of the followings: number, array, string and (another) object. An example of the SPECTRA input file is as follows.

{
  "Accelerator": {
    "Energy (GeV)": 8,
    "Current (mA)": 100,
    ....
    "Options": {
      "Zero Emittance": false,
      "Zero Energy Spread": false
    }
  },
  "Light Source": {
    "B (T)": 0.33467954834861074,
    "λu (mm)": 32,
    ....
  },
  "Configurations": {
    "Distance from the Source (m)": 30,
    ....
  },
  "Output File": {
    "Comment": "",
    ....
  }
}

In this example, four JSON objects are found, whose keys are "Accelerator", "Light Source", "Configurations", and "Output File". The value of each object is also an object, which actually specifies the parameters and options, such as "Energy (GeV)": 8, denoting the energy of the electron beam to be 8 GeV.

For details of the JSON format, please refer to any document available online or found in the text.

Input Format

The input file to be loaded by the solver should have 4 JSON objects: "Accelerator", "Light Source", "Configurations", and"Output File". Details of each object are summarized below, where "GUI Notation" is the parameter name displayed in the "Main Parameters" GUI panel, "Key" is the name of the key to be used in the input file, "Format" is the format of the value, and "Default" is the default value. Note that the key name can be either of the "Full" or "Simplified" expression.

Accelerator Object

Light Source Object

Configurations Object

Output File Object

Output Format

If "JSON" or "Both" is chosen as the "Format" option in the Output File subpanel, a JSON format output file is generated after the calculation completes. Besides the visualization in the "Post-Processing" panel, it can be used for further processing with other external codes. To facilitate it, the structure of the output file is explained below. Note that the order index (for example of an array, column, etc.) in the followings is defined as starting from "0", but not from "1".

"Input" Object

All the parameters and options are stored in this object with the same format as the Input Format. If the output file is opened in the GUI (as an input parameter file), these parameters are displayed and can be used again.

"Output" Object

The calculation results are stored in this object.

The format of the "data" object (2D array) is as follows.

• 0th ~ (n-1)-th array: independent variables, where n is the dimension. The length of each array corresponds to the number of calculation points. For example, it is defined by "Points (Energy)" parameter for "Energy Dependence" calculations.
• n-th ~ (n+m-1)-th array: calculated items, where m is the number of items. The length of each array corresponds to the product of the lengths of the independent variable arrays.

As an example, let us consider an "Output" object as follows

"Output": {
    "dimension": 1,
    "titles": ["Energy","Flux Density","GA. Brilliance","PL(s1/s0)","PC(s3/s0)","PL45(s2/s0)"],
    "units": ["eV","ph/s/mr^2/0.1%B.W.","ph/s/mm^2/mr^2/0.1%B.W.","","",""],
    "data": [
      [5000,5005,...,49995,50000],
      [4.02638e+14,3.98914e+14,...,6.66718e+16,6.81642e+16],
      [3.2776e+16,3.24789e+16,...,6.64598e+18,6.79476e+18],
      [0.999949,0.999947,...,0.999703,0.999713],
      [0,0,...,0,0],
      [-8.67036e-18,-8.97758e-18,...,-1.72714e-17,-1.6893e-17]
    ]
  }

The data is composed of 1 independent variable (Energy) and 5 items (Flux Density etc.). The 0th array ([5000,...]) corresponds to the photon energy, and the 1st ([4.02638e+14,...]) to the flux density, etc.

In case the dimension is larger than 1 and thus more than one independent variables exist, the order index j of the item array is given as \[j=j_0+j_1N_0+j_2N_0N_1+\cdots,\] where $j_i$ and $N_i$ refer to the order index and number of data points of the $i$-th variable.

In some case, 3D data array composed of a number of 2D arrays with the same format as above is stored; each of 2D array is characterized by the "details" object. An example is shown below.

  "Output": {
    "dimension": 1,
    "titles": ["Harmonic Energy","Peak Energy","K Value","Gap","Flux Density",...],
    "units": ["eV","eV","","","ph/s/mr^2/0.1%B.W.",...],
    "details": ["Harmonic: 1","Harmonic: 3","Harmonic: 5"],
    "data": [
      [
        [18977.5,18707.1,...,4702.57,4336.24],
        [18927.2,18657.6,...,4692.37,4326.97],
        [0.040015,0.174748,...,2.46527,2.6],
        [50,35.2675,...,8.58047,8.01609],
        [7.24659e+15,1.3423e+17,...,1.90452e+18,1.82972e+18],
        [6.91663e+17,1.27995e+19,...,1.5325e+20,1.44896e+20],
        [0.999995,0.999995,...,0.999998,0.999998],
        [0,0,...,0,0],
        [-6.23832e-19,-6.15261e-19,...,-8.10339e-19,-7.90166e-19]
      ],
      [
        [56932.5,56121.2,54374,...,14107.7,13008.7],
        [47488.9,56019.4,54276.1,...,15312,14087.7,12990.4],
        [0.040015,0.174748,...,2.46527,2.6],
        [50,35.2675,...,8.58047,8.01609],
        [3.235e+10,5.91631e+13,...,1.21888e+18,1.20334e+18],
        .....
      ],
      [
        [94887.4,93535.3,...,23512.9,21681.2],
        [85444.8,84227.3,...,23487.4,21658],
        [0.040015,0.174748,...,2.46527,2.6],
        [50,35.2675,...,8.58047,8.01609],
        [7.1207e+11,1.37382e+13,...,7.22944e+19,7.31154e+19],
        .....
      ]
    ]
  }

The "details" object in this example specify the harmonic number, i.e., 1st, 3rd and 5th harmonics, and the maximum flux density near the harmonic energy, and other related characteristics are calculated as a function of the K value, for the three different harmonic numbers. The "data" object is then composed of three 2D arrays and thus forms a 3D array.

Objects Related to CMD

The results of Coherent Mode Decomposition, such as the modal amplitude and profiles, are saved separately from the "data" object described above. The details of them are explained below.

"Coherent Mode Decomposition" Object

How to retrieve the flux and Wigner function from the modal amplitue?

The flux density ($I_n$) and Wigner function ($W_n$) of the $n$-th mode can be retrieved form the complex amplitude $a_n$ determined by the CMD according to the following formulas, using the symbols summarized in the above table.

For 1D case (CMD with 2D Wigner function):\[I_n(x)=|a_n(x)|^2\frac{F}{2\sqrt{\pi}\sigma}\times 10^{-3},\] \[W_n(x,\theta_x')=\frac{W_0}{2\sqrt{\pi}\sigma}\int a_n\left(x-\frac{x'}{2}\right)a_n^*\left(x+\frac{x'}{2}\right)\mbox{e}^{ik\theta_x x'}dx',\]

For 2D case (CMD with 4D Wigner function):\[I_n(\boldsymbol{r})=|a_n(\boldsymbol{r})|^2\frac{F}{4\pi\sigma_x\sigma_y}\times 10^{-6},\] \[W_n(\boldsymbol{r},\boldsymbol{\theta})=\frac{W_0}{4\pi\sigma_x\sigma_y}\int a_n\left(\boldsymbol{r}-\frac{\boldsymbol{r}'}{2}\right)a_n^*\left(\boldsymbol{r}+\frac{\boldsymbol{r}'}{2}\right)\mbox{e}^{ik\boldsymbol{\theta}\boldsymbol{r}'}d\boldsymbol{r}',\]

where $k=2\pi/\lambda$ is the wavenumber of radiation.

Other Objects

A number of data sets evaluated by post-processing the CMD results described above are saved as follows. Note that the format of each object is the same as that of the "data" object.

Objects Related to FEL Mode

When FEL Mode and Export Intermediate Data options are enabled, numerical data generated while solving the FEL equation, such as variation of the electron beam temporal profile and growth of the FEL radiation pulse, are recorded as summarized below.

Standalone Mode

Besides the desktop application as described above, the solver of SPECTRA can be run in a standalone mode. Note that in the followings, [spectra_home] refers to the directory where SPECTRA has been installed.

When [Run]-[Start Calculation] command is executed, the SPECTRA GUI creates an input parameter file ("*.json") and invokes the solver ("spectra_solver" or "spectra_solver_nompi" depending on whether the parallel computing option is enabled or not) located in the same directory as the main GUI program, with the input file as an argument. This means that SPECTRA (solver) can be run without the GUI, if the input file is prepared by an alternative method, and a batch process will be possible. To do so, prepare the input file according to the descriptions in Input Format and run the solver as follows

[spectra_home]/spectra_solver_nompi -f [input file]

without parallel computing, or

mpiexec -n 4 [spectra_home]/spectra_solver_nompi -f [input file]

with parallel computing (4 processes in this example).

It should be noted that the names of the parameters and options ("key" of the object) should be totally correct, including the units and inserted space characters. In addition, the number of parameters and options actually needed for a specific calculation depend on its condition. To avoid potential errors and complexity in preparing the input file, it is recommended to create a "master input file" specific to the desired calculation type, by running [Run]-[Export as ASCII] command. Then, just modify the values of desired parameters to prepare the input file.

Note that this usage has not been officially supported before ver. 11.0, simply because the input file format was original and difficult to read.

Python User Interface

To support the expanding users of python language, SPECTRA has started official support for python, since ver. 12.0. To make use of this function, python version 3.8 or later is needed, and the user is requested to install a python package spectra-ui (SPECTRA User Interface). Refer to the instructions for details of spectra-ui.

References

1. T. Tanaka and H. Kitamura, "SPECTRA - a synchrotron radiation calculation code," J. Synchrotron Radiation 8, 1221 (2001)
2. T. Tanaka and H. Kitamura, "Recent Progress of the Synchrotron Radiation Calculation Code SPECTRA", Proc. 9th Int. Conf. Synchrotron Rad. Instrum. (SRI2006), 355
3. T. Tanaka, "Major upgrade of the synchrotron radiation calculation code SPECTRA," J. Synchrotron Radiation 28, 1267 (2021)
4. T. Tanaka, "Numerical methods for characterization of synchrotron radiation based on the Wigner function method," Phys. Rev. ST-AB 17, 060702 (2014)
5. T. Tanaka, "Coherent mode decomposition using mixed Wigner functions of Hermite-Gaussian beams," Optics Letters 42, 1576 (2017)
6. R. Walker, "Interference effects in undulator and wiggler radiation sources", Nucl. Instrum. Methods Phys. Res., Sect. A 335, 328 (1993)
7. T. Tanaka and H. Kitamura, "Simple scheme for harmonic suppression by undulator segmentation," Journal of Synchrotron Radiation 9, 266 (2002)
8. T. Tanaka and H. Kitamura, "Production of linear polarization by segmentation of helical undulator," Nucl. Instrum. Meth. A490, 583 (2002)
9. T. Tanaka, "Universal representation of undulator phase errors," Phys. Rev. AB 21, 110704 (2018)
10. K. J. Kim, "Characteristics of Synchrotron Radiation," in Physics of Particle Accelerators, AIP Conf. Proc. 184 (Am. Inst. Phys., New York, 1989), p. 565.

Acknowledgements

This software includes the work that is distributed in the Apache License 2.0, and relies on a number of libraries & database as summarized below, which are gratefully appreciated.

• Node.js: Javascript runtime environment to run Javascript code without a web browser (https://nodejs.org/en/).
• tauri: application toolkit to build software for all major desktop operating systems using web technologies. (https://tauri.app/)
• Plotly.js: Javascript graphing library to facilitate data visualization (https://nodejs.org/en/)
• Boost C++: Set of libraries for the C++ language (https://www.boost.org/)
• EIGEN: C++ template library for linear algebra (https://eigen.tuxfamily.org/index.php?title=Main_Page)
• mathjax: Javascript library to display mathematical formulas in HTML documents (https://www.mathjax.org/)
• picojson: JSON parser for C++ language (https://github.com/kazuho/picojson)
• mucal.c: Source code to calculate the x-ray absorption coefficients (http://www.csrri.iit.edu/mucal.html)
• NIST database: Database for the mass energy-absorption coefficients (https://www.nist.gov/pml/x-ray-mass-attenuation-coefficients)
• General Purpose FFT Package (https://www.kurims.kyoto-u.ac.jp/~ooura/fft.html)