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