Overview of simplex-ui

The python package simplex-ui is to operate the FEL simulation code SIMPLEX from the python script.

How it works?

To save the effort of the software development as much as possible, simplex-ui takes advantage of the resource for the desktop version; the diagram shown below explains how simplex-ui works as a python script.

Diagram of how simplex-ui communicates with other software components.

As a GUI, simplex-ui opens the remote repository for the source file with a web browser and communicates with it through Selenium WebDriver, a well-known framework to automate the operation in the web brwoser. When necessary, simplex-ui invokes the solver (simplex_solver or simplex_solver_nompi) as a child process and communicates with it (sends a command or receives the status of progress). Upon completion of the child process, simplex-ui loads the result and sends it to the browser to be plotted in the Pre-Processing or Post-Processing tabbled panel. In case the user is offline, the source files, which are downloaded and stored in the local repository when simplex-ui is installed, can be used instead. Refer to Launch Options about how to enable this option.

Installation

simplex-ui is available from the Python Package Index (PyPI), and thus can be installed by a standard pip command,

pip install simplex-ui [--user]

or

pip3 install simplex-ui [--user]

on some platforms.

The [–user] option may be needed when global installation is not allowed. Note that binary packages are available for Windows and Mac OS platforms, but not for Linux distributions because of the too diverse versions of core libraries (glibc). Thus in Linux platforms, the source codes are downloaded and compiled during the installation process. This means that the user should arrange the enviroment for software development before installation, such as the C/C++ compiler, CMake, and MPI (optional), and the installation process may need a bit long time.

Parallel Computing

simplex-ui supports parallel computing based on MPI. To enable this option, MPI library should be installed depending on the platform as follows.

Windows

Install MS-MPI; other MPI libraries are not supported.

Mac OS

Install MPICH; if you already have OpenMPI installed in your system (and like to continue to use it), comiplation of the source files with the OpenMPI library is needed in the installation process; this can be done by running pip command with –no-binary option as follows,

pip install simplex-ui --no-binary simplex-ui [--user]

which avoids the installation of binary package and tries to compile the source files with the installed MPI library.

Linux

Install MPICH or OpenMPI. The pip command tries to find the installed MPI and compile the source files accordingly.

Getting Started

The simplest way to get started with simplex-ui is to run as a module. If you have “Chrome” browser installed in your environment, try,

python -m simplex

or,

python3 -m simplex

to launch simplex-ui as a GUI mode, in which most of the functions available in the desktop version are supported.

If you prefer another browser, add an option (for example -e for Edge) to specify it. Refer to Launch Options for details of how to launch simplex-ui using a preferred browser. Note that “Chrome” (or “Edge”) is recommended because of several issues encountered in other brwosers as summarized below.

Web browsers supported in *simplex-ui* and known issues.
Browser	Remarks/Issues
Chrome	Fully tested and most recommended.
Edge	Recommended as well as Chrome.
Firefox	Loading source files from the local repository may fail. In such a case, the user is requested to move them to another location.
Safari	GUI cannot be operated, or it is not editable because frozen by the OS; it just shows the parameters and configurations, and plots the pre- and post-processed results.

Operation Mode

There are three operation modes in simplex-ui: GUI, CLI, and interactive ones.

The GUI mode mimics the desktop version, and all the operations are done in the GUI (web browser). This mode has been prepared as an alternative to the desktop version in Linux distributions.
The CLI (command line interface, or CUI = console user interface) mode is dedicated to the utilization of SIMPLEX for a batch job. It can be operated only through the python script, and the GUI is not shown. In this mode, the output file is not imported by the post-processor for visualization, but the data is stored in memory buffer to be processed later on.
The interactive mode has both of the capabilities available in the GUI and CLI modes. Namely, it can be operated through the GUI (web browser) and receives commands from the python script. Note that several menu commands (File-Exit, Run-Start Calculation, etc.) are disabled in the GUI; this is to avoid an unintended conflict between commands from the GUI and CLI.

To enable each operation mode, refer to the instruction of the function Start().

Launch Options

Option	Alternative	Contents
–chrome	-c	Specify Chrome (default) as the browser for GUI.
–edge	-e	Specify Edge as the browser for GUI.
–firefox	-f	Specify Firefox as the browser for GUI.
–remote	-r	Use remote repository for the source file.
–local	-l	Use local repository (/path-to-python/site-packages/simplex/src/indx.html) for the source file.