API Functions List

Brief explanations of the API functions available in simplex-ui are given here.

simplex.Start(**kwargs)

Launch SIMPLEX with options

Parameters:

**kwargs (dict) – parameters to specify the configurations. See below for possible keys and their meanings.
src (str) – specify the location of the source files; “r” = remote (default), “l” = local
browser (str) – specify the browser; “c” = Chrome (default), “e” = Edge, “f” = Firefox, “s” = Safari
file (str) – path to the parameter file to open (default = “”)

Returns:

None

Examples

>>> simplex.Start(src="l", file="./sample.json")
# open the source files in the local repository with the Chrome browser,
# with the parameter file "sample.json"

simplex.Exit()

Finish SIMPLEX and exit

Parameters:: None
Returns:: None

simplex.Open(file)

Opens a SIMPLEX parameter file.

Parameters:: file (str) – path to the parameter file
Returns:: None

Examples

>>> simplex.Open("./sample.json")
# open a parameter file "sample.json" in the current directory

simplex.Set(category, label, value)

Set a parameter or an option

Parameters:

category (string) – specify the category of the target parameter
label (string) – name of the target parameter
value (any) – value to be set

Returns:

None

Examples

>>> simplex.Set("ebeam", "eenergy", 6.0)
# set the electron energy to 6.0 GeV

Note

Refer to the keyword list for the name of the target parameter.

simplex.Get(category, label)

Get a value of a parameter automatically evaluated and being shown in the GUI

Parameters:

category (string) – specify the category of the target parameter
label (string) – name of the target parameter

Returns:

value of the specified parameter

Examples

>>> simplex.Get("felprm", "rho")
# Get the FEL parameter

Note

Refer to the keyword list for the name of the target parameter.

simplex.StartSimulation(**kwargs)

Start the calculation process

Parameters:

kwargs["folder"] (str) – directory to put the output file
kwargs["prefix"] (str) – name of the output file
kwargs["serial"] (str) – serial number of the output file

Returns:

None

Examples

>>> simplex.StartSimulation(folder=".", prefix="sample", serial=1)
# start the calculation to generate an output file "./sample-1.json"

Note

If more than one calculation process is created before, this funcion simply launches the existing processes and the arguments are not functional.

simplex.CreateProcess(**kwargs)

Create a calculation process with the current parameters

Parameters:

kwargs["folder"] (str) – directory to put the output file
kwargs["prefix"] (str) – name of the output file
kwargs["serial"] (str) – serial number of the output file

Returns:

None

Examples

>>> simplex.CreateProcess(folder=".", prefix="sample", serial=1)
# create a calculation process to generate an output file "./sample-1.json"

simplex.LoadOutput(file)

Load an output file generated in the former calculation for post-processing.

Parameters:: file (str) – path to the output file
Returns:: None

Examples

>>> simplex.LoadOutput("./output.json") # load the output file "output.json" in the current directory

simplex.ShowPreProcessor()

Switch the tabbled panel to “Pre-Processing”.

Parameters:: None
Returns:: None

simplex.ShowPostProcessor()

Switch the tabbled panel to “Post-Processing”.

Parameters:: None
Returns:: None

simplex.Scan(category, label, initial, final, points=11, **kwargs)

Create a parameter-scan process (1D).

Parameters:

category (string) – specify the category of the target parameter
label (string) – name of the target parameter
initial (number) – initial value for scanning
final (number) – final value for scanning
points (number) – number of points for scanning
kwargs["folder"] (str) – directory to put the output file
kwargs["prefix"] (str) – name of the output file
kwargs["serial"] (number) – serial number of the output file
kwargs["iniSN"] (number) – initial suffix number for scan
kwargs["interval"] (number) – step interval if the target parameter is an integer

Returns:

None

Examples

>>> simplex.Scan("ebeam", "eenergy", 6, 8, folder=".", prefix="scan")
    # scan the electron energy from 6 to 8 GeV with an interval of 0.2 GeV (11 points);
    # the output files are "./scan-1.json" etc.

simplex.ScanX(category, label, initial, final, points=11, **kwargs)

Create a parameter-scan process (1D, along x axis).

Parameters:

category (string) – specify the category of the target parameter, should be either of “acc” (Accelerator), “src” (Light Source) or “config” (Configurations)
label (string) – name of the target parameter
initial (number) – initial value for scanning
final (number) – final value for scanning
points (number) – number of points for scanning
kwargs["folder"] (str) – directory to put the output file
kwargs["prefix"] (str) – name of the output file
kwargs["serial"] (str) – serial number of the output file
kwargs["iniSN"] (number) – initial suffix number for scan
kwargs["interval"] (number) – step interval if the target parameter is an integer

Returns:

None

Examples

>>> simplex.ScanX("ebeam", "emitt", 0.5, 1, 6, folder=".", prefix="scanx")
    # scan the horizontal emittance from 0.5 to 1 mm.mrad with an interval of 0.1 mm.mrad (6 points);
    # the output files are "./scanx-1.json" etc.

simplex.ScanY(category, label, initial, final, points=11, **kwargs)

Create a parameter-scan process (1D, along y axis).

Parameters:

category (string) – specify the category of the target parameter, should be either of “acc” (Accelerator), “src” (Light Source) or “config” (Configurations)
label (string) – name of the target parameter
initial (number) – initial value for scanning
final (number) – final value for scanning
points (number) – number of points for scanning
kwargs["folder"] (str) – directory to put the output file
kwargs["prefix"] (str) – name of the output file
kwargs["serial"] (str) – serial number of the output file
kwargs["iniSN"] (number) – initial suffix number for scan
kwargs["interval"] (number) – step interval if the target parameter is an integer

Returns:

None

Examples

>>> simplex.ScanY("ebeam", "emitt", 0.5, 1, 6, folder=".", prefix="scany")
    # scan the vertical emittance from 0.5 to 1 mm.mrad with an interval of 0.1 mm.mrad (6 points);
    # the output files are "./scany-1.json" etc.

simplex.ScanXY(category, label, initial, final, points=[11, 11], **kwargs)

Create a parameter-scan process (2D over x-y plane).

Parameters:

category (string) – specify the category of the target parameter, should be either of “acc” (Accelerator), “src” (Light Source) or “config” (Configurations)
label (string) – name of the target parameter
initial (list) – initial value for scanning
final (list) – final value for scanning
points (list) – number of points for scanning in x and y directions
kwargs["folder"] (str) – directory to put the output file
kwargs["prefix"] (str) – name of the output file
kwargs["serial"] (str) – serial number of the output file
kwargs["iniSN"] (number) – initial suffix number for scan
kwargs["interval"] (list) – step interval if the target parameter is an integer
kwargs["link"] (bool) – if enabled, X and Y prameters are scanned at the same time

Returns:

None

Examples

>>> simplex.ScanXY("ebeam", "emitt", [0.5, 0.5], [1, 1], [5, 5], folder=".", prefix="scanxy")
    # scan the observation position in the 2D rectangular grid points defined by
    # (0.5,0.5) and (1,1) with an interval of 0.1 mm.mrad in both directions (6x6 points);
    # the output files are "./scanxy-1-1.json" etc.

simplex.FitWindow()

Adjust the size of the browser to show the whole parameters in the Main window. Not effective when Pre-Processing or Post-Processing windows are shown.

Parameters:: None
Returns:: None

simplex.ExpandWindow(**kwargs)

Expand or shrink the size of the browser.

Parameters:

kwargs["width"] (kwargs["w"] or) – scaling factor in the horizontal direction
kwargs["height"] (kwargs["h"] or) – scaling factor in the vertical direction

Returns:

None

Examples

>>> simplex.ExpandWindow("w"=1.2, "h"=0.8)
    # expand/shrink the window size by 1.2 (horizontal) and 0.8 (vertical)

simplex.MoveWindowX(pos)

Move the browser horizontally.

Parameters:: pos (str or number) – “l” (left), “c” (center), “r” (right), or a pixel number to specify the horizontal position
Returns:: None

Examples

>>> simplex.MoveWindowX("l") # move to the left
>>> simplex.MoveWindowX(100) # move to x = 100px

simplex.MoveWindowY(pos)

Move the browser vertically.

Parameters:: pos (str or number) – “t” (top), “c” (center), “b” (bottom), or a pixel number to specify the vertical position
Returns:: None

Examples

>>> simplex.MoveWindowY("t") # move to the top
>>> simplex.MoveWindowY(100) # move to y = 100px

simplex.MoveWindowXY(x, y)

Move the browser in both directions.

Parameters:

x (str or number) – “l” (left), “c” (center), “r” (right), or a pixel number to specify the horizontal position
y (str or number) – “t” (top), “c” (center), “b” (bottom), or a pixel number to specify the vertical position

Returns:

None

Examples

>>> simplex.MoveWindowXY("l", "t") # move to the left & top
>>> simplex.MoveWindowXY(100, 100) # move to (x, y) = (100px, 100px)

simplex.LoadPostProcessed(file)

Load an output file generated by post-processing the raw data generated in a former simulation.

Parameters:: file (str) – path to the output file
Returns:: None

Examples

>>> simplex.LoadPostProcessed("./output.json") # load the output file "output.json" in the current directory

class simplex.CLI

CLI class is available only in the CLI mode and is basically a collection of functions to manage the output data that cannot be imported for visualization (because of no GUI).

static GetDataNames()

Get the names of the output data stored in the buffer.

Parameters:: None
Returns:: list of the data names

Examples

>>> simplex.CLI.GetDataNames()
["sample-1", "sample-2"]

static GetLatestDataName()

Get the name of the latest output data stored in the buffer.

Parameters:: None
Returns:: string of the data name

Examples

>>> simplex.CLI.GetLatestDataName()
"sample-2"

static GetDimension(dataname)

Get the dimension of the output data, which means the number of independent variables of the target output data.

Parameters:: dataname – name of the output data
Returns:: dimension

Examples

>>> simplex.CLI.GetDimension("sample-1")
1

static GetTitle(dataname)

Get the titles of items in the output data.

Parameters:: dataname – name of the output data
Returns:: list of the titles

Examples

>>> simplex.CLI.GetTitle("sample-1")
["Energy","Flux Density","GA. Brilliance","PL(s1/s0)","PC(s3/s0)","PL45(s2/s0)"]

static GetUnit(dataname)

Get the units of items in the output data.

Parameters:: dataname – name of the output data
Returns:: list of the titles

Examples

>>> simplex.CLI.GetUnit("sample-1")
["eV","ph/s/mr^2/0.1%B.W.","ph/s/mm^2/mr^2/0.1%B.W.","","",""]

static GetDetail(dataname)

Available when the output data is composed of more than two independent data sets; for example, spatial dependence calculations along the x and y axes generate 2 independent data sets. In such a case, this function helps to retrieve keywords (=details) to specify each data set.

Parameters:: dataname – name of the output data
Returns:: list of the details (of respective data sets)

Examples

>>> simplex.CLI.GetDetail("sample-2")
["Along x","Along y"]

static GetData(dataname, index, detail=None)

Retrieve the desired item from the output data.

Parameters:

dataname – name of the output data
index – index (starting from 0) of the target item
detail – keyword to specify the dataset when more than two independent data sets are contained in the output data

Returns:

list of the data

Examples

>>> simplex.CLI.GetData("sample-1", 1) # Get "GA. Brilliance"
[4.02638e+14,3.98914e+14,...]
>>> simplex.GetData("sample-2", 0, "Along x") # Get "Flux Density"
[4.02638e+14,3.98914e+14,...]

static GetAxis(dataname, detail=None)

Retrieve the independent variables from the output data.

Parameters:

dataname – name of the output data
detail – keyword to specify the dataset when more than two independent data sets are contained in the output data

Returns:

list of the independent variables

Examples

>>> simplex.CLI.GetAxis("sample-1")
[5000,5005,5010,...]  "Energy"
>>> simplex.GetAxis("sample-2", "Along x")
[-0.2,-0.18,-0.16,-0.14,...]  "Position" ("Along x")

static ClearBuffer()

Clear the buffer data to reduce the memory consumption. Recommended to call this function if the exsiting output data (stored in the memory buffer) are no more necessary.

Parameters:: None
Returns:: None

class simplex.PreProcess

PreProcess class bundles various functions for the operation of pre-processor.

static Import(item, filename)

Import the data for the target item from a file.

Parameters:

item (str) – name of the target item
filename (str) – name of the data file

Returns:

None

Examples

>>> simplex.PreProcess.Import("Field Profile", "./uerror_model.dat")
# import the data file "uerror_model.dat" in the current directory as the field distribution

static LoadParticle(filename=None)

Load the particle data

Parameters:: filename (str) – name of the data file, load “Particle Data” path if not specified
Returns:: None

Examples

>>> simplex.PreProcess.LoadParticle("./particles.dat")
# load the particle data from "particles.dat" in the current directory

static ParticleDataFormat(**kwargs)

Set the particle data format

Parameters:

kwargs["unitxy"] (str) – unit for x and y (m, mm)
kwargs["unitxyp"] (str) – unit for x’ and y’ (rad, mrad)
kwargs["unitt"] (str) – unit for time (s, ps, fs, m, mm)
kwargs["unitE"] (str) – unit for energy (GeV, MeV, gamma)
kwargs["index"] (list) – column indices for x, x’, y, y’, t, E
kwargs["pcharge"] (number) – charge/particle (C)
kwargs["bins"] (number) – number of bins/RMS bunch length to evaluate slice parameters

Returns:

None

Examples

>>> spectra.PreProcess.ParticleDataFormat(index=[2,3,4,5,1,6], unitE="gamma")
# the particle data is arranged as t, x, x', y, y', E
# the energy is given in gamma (Lorentz factor)

static PlotSliceParameter(item)

Plot the slice parameter along the electron bunch

Parameters:: item (str) – name of the target parameter
Returns:: None

Examples

>>> simplex.PreProcess.PlotSliceParameter("Current Profile")
# plot the current profile of the electron bunch

static PlotParticles(**kwargs)

Plot the particle distribution in a given 2D phase space

Parameters:

kwargs["x"] (str)
kwargs["y"] (str)
kwargs["max"] (number) – maximum particles to plot

Returns:

None

Examples

>>> simplex.PreProcess.PlotParticles(x="s (m)",y="Energy (GeV)",max=10000)
# plot E-t phase space distribution with maximum number of 10000

static Plot(item)

Calculate and plot the target item.

Parameters:: item (str) – name of the target item
Returns:: None

Examples

>>> simplex.PreProcess.Plot("2nd Integral")
# calculate and plot the 2nd field integral (electron orbit)

static Export(dataname)

Export the pre-processed (and currently plotted) result as an ASCII file.

Parameters:: dataname (str) – file name to export the data
Returns:: None

Examples

>>> simplex.PreProcess.Export("./export.txt")
# export the data to an ASCI file "export.txt"

static PlotScale(**kwargs)

Change the axis scale of the 1D plot.

Parameters:

kwargs["xscale"] (kwargs["x"] or) – select the scale of abscissa, “linear” or “log”
kwargs["yscale"] (kwargs["y"] or) – select the scale of ordinate, “linear” or “log”

Returns:

None

Examples

>>> simplex.PreProcess.PlotScale(x="log",y="log")
# Switch to the log-log plot

static PlotRange(**kwargs)

Specify the plotting range of the 1D or contour plot.

Parameters:

kwargs["xrange"] (kwargs["x"] or) – specify the x range
kwargs["yrange"] (kwargs["y"] or) – specify the y range

Returns:

None

Examples

>>> simplex.PreProcess.PlotRange(x=[1,10],y=[-1,1])
# Specify the x range as [1, 10] and y range as [-1, 1]

static LinePlot(width, size)

Switch to the line plot.

Parameters:

width – width of lines (should be > 0)
size – size of symbols (if 0, simple line plot)

Returns:

None

static SymbolPlot(size)

Switch to the symbol plot.

Parameters:: size – size of symbols (should be > 0)
Returns:: None

static ContourPlot()

Switch to the contour plot.

Parameters:: None
Returns:: None

static SurfacePlot(**kwargs)

Switch to the surface plot.

Parameters:

kwargs["type"] – select the type of the surface plot; “shade” for a shaded surface plot, “color” for a surface plot with a color map
kwargs["wireframe"] – if True, wireframe is drawn on the surface

Returns:

None

Examples

>>> simplex.PreProcess.SurfacePlot(type=shade, wireframe=True)
# Switch to the surface plot with "shading" and "wireframe"

static SetUnit(item, unit)

Select the unit of the data to be imported.

Parameters:

item (str) – name of the target item
unit (str) – “unit” of the target item

Returns:

None

Examples

>>> simplex.PreProcess.SetUnit("zpos", "mm")
# The longitudinal position is given in mm in the data file to be imported.

Note

Refer to the keyword list for the name of the target parameter.

static DuplicatePlot(*titles)

Open a new window to duplicate the current plot with the same configuration.

Parameters:: titles (variable length list) – titles of the plot
Returns:: None

static OptimizeLattice(betaxy)

Optimize the Twiss parameters and focusing magnets for betatron matching.

Parameters:: betaxy (list) – average betatron functions in horizontal and vertical directions
Returns:: None

Examples

>>> simplex.PreProcess.OptimizeLattice([10, 10])
# try optimization with the average betatron functions of 10 m in both directions.

class simplex.PostProcess

PostProcess class bundles various functions for the operation of post-processor.

static Import(filename)

Import the output data for post-processing (visualization).

Parameters:: filename (str) – name of the output data file
Returns:: None

static SelectData(dataname)

Select the data name for post-processing from those already imported.

Parameters:: dataname (str) – name of the output data to be selected
Returns:: None

static Clear()

Clear all the output data that have been imported.

Parameters:: None
Returns:: None

static Remove(dataname)

Remove the output data from the list.

Parameters:: dataname (str) – name of the output data to be removed
Returns:: None

static Export(dataname)

Export the current plot as an ASCII file.

Parameters:: dataname (str) – file name to export the data
Returns:: None

static Save(dataname)

Save the current plot as an JSON file, which can be imported later to reproduce the plot.

Parameters:: dataname (str) – file name to save the data
Returns:: None

static ComparativePlot(*datanames)

Create a comparative plot of an item currently selected; more than one data set is retrieved from the specified output data and plotted in the same graph

Parameters:: datanames (variable length list) – names of the output data to be plotted
Returns:: None

Examples

>>> simplex.PostProcess.PlotGainCurve("Pulse Energy") # specify "Pulse Energy" as the target item before creating a comparative plot
>>> simplex.PostProcess.ComparativePlot("sample-1", "sample-2")
# plot the simplex of flux density retrieved from two output data "sample-1" and "sample-2"

static MultiPlot(*datanames)

Create a multiple plot; more than one data set is retrieved from the specified output data and plotted in the same window

Parameters:: datanames (variable length list) – names of the output data to be plotted
Returns:: None

Examples

>>> simplex.PostProcess.PlotGainCurve("Pulse Energy") # specify "Pulse Energy" as the target item before creating a comparative plot
>>> simplex.PostProcess.ComparativePlot("sample-1", "sample-2")
# plot the simplex of flux density retrieved from two output data "sample-1" and "sample-2"

static SetSlide(*slideno)

Set the slide number in the animation plot

Parameters:: slideno (variable length list) – slide number(s) to show
Returns:: None

Examples

>>> simplex.PostProcess.SetSlide(0) # show the 0th slide

static ComparativePlotCols(columns)

Define the number of columns for comparative plot with more than one plot area. This is effective for 2D plots or 1D plots with more than one target items.

Parameters:: columns (integer) – column number of comparative plot areas
Returns:: None

static MultiPlotCols(columns)

Define the number of columns for multiplot.

Parameters:: columns (integer) – column number of multiplot windows
Returns:: None

static PlotScale(**kwargs)

Change the axis scale of the 1D plot.

Parameters:

kwargs["xscale"] (kwargs["x"] or) – select the scale of abscissa, “linear” or “log”
kwargs["yscale"] (kwargs["y"] or) – select the scale of ordinate, “linear” or “log”

Returns:

None

Examples

>>> simplex.PreProcess.PlotScale(x="log",y="log")
# Switch to the log-log plot

NormalizePlot()

Specify if the plot is normalized for each slide.

Parameters:: normalize (bool) – boolean to specify the method of normalization
Returns:: None

static PlotRange(**kwargs)

Specify the plotting range of the 1D or contour plot.

Parameters:

kwargs["xrange"] (kwargs["x"] or) – specify the x range
kwargs["yrange"] (kwargs["y"] or) – specify the y range

Returns:

None

Examples

>>> simplex.PreProcess.PlotRange(x=[1,10],y=[-1,1])
# Specify the x range as [1, 10] and y range as [-1, 1]

static LinePlot(width, size)

Switch to the line plot.

Parameters:

width – width of lines (should be > 0)
size – size of symbols (if 0, simple line plot)

Returns:

None

static SymbolPlot(size)

Switch to the symbol plot.

Parameters:: size – size of symbols (should be > 0)
Returns:: None

static ContourPlot()

Switch to the contour plot.

Parameters:: None
Returns:: None

static SurfacePlot(**kwargs)

Switch to the surface plot.

Parameters:

kwargs["type"] – select the type of the surface plot; “shade” for a shaded surface plot, “color” for a surface plot with a color map
kwargs["wireframe"] – if True, wireframe is drawn on the surface

Returns:

None

Examples

>>> simplex.PreProcess.SurfacePlot(type=shade, wireframe=True)
# Switch to the surface plot with "shading" and "wireframe"

static DuplicatePlot(*titles)

Open a new window to duplicate the current plot with the same configuration.

Parameters:: titles (variable length list) – titles of the plot
Returns:: None

static StartAnimation()

Start an animation with the current plot (if available).

Parameters:: None
Returns:: None

static PlotGainCurve(item)

Plot an item in “Gain Curve” data.

Parameters:: item (str) – name of the target item
Returns:: None

Examples

>>> simplex.PostProcess.PlotGainCurve("Pulse Energy")
# plot "pulse energy vs. undulator length"

static PlotCharacteristics(item)

Plot an item in “Characteristics” data.

Parameters:: item (str) – name of the target item
Returns:: None

Examples

>>> simplex.PostProcess.PlotCharacteristics("Pulse Length")
# plot "pulse length vs. undulator length"

static PlotKTrend()

Plot the K value variation along the undulator line.

Parameters:: None
Returns:: None

static TemporalProfile()

Plot temporal profile of radiation

Parameters:: None
Returns:: None

static SpectralProfile()

Plot spectrum of radiation

Parameters:: None
Returns:: None

static SpatialProfile()

Plot spatial profile of radiation

Parameters:: None
Returns:: None

static AngularProfile()

Plot angular profile of radiation

Parameters:: None
Returns:: None

static SetDataProcessing(label, value)

Set a parameter or an option for “Raw Data Processing”

Parameters:

label (string) – name of the target parameter
value (any) – value to be set

Returns:

None

Examples

>>> simplex.PostProcess.SetDataProcessing("item", "Radiation Power")
# specify "Radiation Power" as a target item for data processing

Note

Refer to the keyword list for the name of the target parameter.

static RunDataProcessing()

Run Raw Data Processing

Parameters:: None
Returns:: None