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.

_images/simplexui.png

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. For Linux platforms, any MPI library is available, because the source files are compiled/liked with the library installed in the system during the installation process. For other platforms, default MPI library is supposed: MS-MPI for Windows and MPICH for Mac OS. If other MPI library is preferred for these platforms, comiplation of the source files with the preferred MPI 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 MPI library if installed.

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.