Introduction

jBEAM provides two methods for executing Python code through the Script component: Jython and Python.

Jython

Jython is an embedded implementation of the Python programming language and is available in jBEAM without needing to install a dedicated Python interpreter. It supports Python 2.7 syntax and provides a subset of Python's standard library. jBEAM functions are also available in Jython through the Script component. Many users will find Jython sufficient for their needs, unless 3rd-party packages or Python 3 syntax are required.

Since Jython is an alternative Python implementation written in Java and Python, it does not share the same set of security vulnerabilities as CPython, the official reference implementation of the language, since Python 2.7 is no longer maintained upstream.

For more information, visit https://github.com/jython/jython.

Open

Python

In addition to providing an embedded Python through Jython, jBEAM is also capable of interfacing with an already installed Python interpreter using the library Jep (Java Embedded Python). The main advantage of this method is the capability to use Python 3 syntax or 3rd-party packages like NumPy. jBEAM functions can also be called the same way as in Jython.

Since Jep is written in Python, C, and Java, its setup is more difficult than for other Python packages. Therefore, this document explains how Jep can be set up for jBEAM.

Open

Dependencies

• Python 3.5, 3.6, 3.7, or 3.8

• JEP == 3.9.0

• JDK >= 8

• Build Tools for Visual Studio 2019 or a full Visual Studio 2019 (Community, Professional, Enterprise)

Setting up Python, Jep, and jBEAM

• The JDK is assumed to be installed, since it is already required for jBEAM. In addition, Jep will use the Java compiler in the JDK to compile parts of itself written in Java.

  • JAVA_HOME must be defined as environment variable. This should usually be done by the default set up of the java version. If this is not the case, you need to add the system variable manually.

  • The javac command must be available on the Command Prompt or on PowerShell; it will print a list of options if it is working properly. If the command is not found, edit the PATH environment variable to include %JAVA_HOME%\bin and open a new Command Prompt or PowerShell.

• Install Python 3.8: https://www.python.org/downloads/windows/

  • Use the recommended setup ("Install Now") to install Python and make sure that the option "Add Python 3.8 to PATH" is checked

• Install the Build Tools or one of the full Visual Studio versions:

  • Build Tools: https://aka.ms/vs/16/release/vs_buildtools.exe

  • Full Version:

    • Community: https://aka.ms/vs/16/release/vs_community.exe

    • Professional: https://aka.ms/vs/16/release/vs_professional.exe

    • Enterprise: https://aka.ms/vs/16/release/vs_enterprise.exe

  • Install the "Desktop development with C++" option. While Visual Studio allows to select individual components like the C++ compiler (MSVC) or the Windows SDK, only this option will install rc.exe. If rc.exe is not present, Jep will fail to compile with the following error message:

Jep uses a special key in the Windows registry to find the Visual Studio installation which is not always present. Create a text file jep.reg with the following content:

jep.reg

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\DevDiv\VCForPython\14.2]

"installdir"="C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\BuildTools\\VC\\Auxiliary\\Build"

• Replace BuildTools with Community, Professional or Enterprise if you have installed a full Visual Studio. Save the file, double click it and confirm the import so that the special key is added to the Windows registry.

• Install Jep through the pip package manager: pip install jep==3.9.0

• If there are problems with the installation:

1. Update the Python setup tools (usually required for older Python versions): python -m pip install --upgrade pip setuptools wheel

2. Have a look at the known Jep issues: https://github.com/ninia/jep/issues

• If the installation was successful there should be a directory:
  %userprofile%\AppData\Local\Programs\Python\Python38\Lib\site-packages\jep

• Add Jep to the Java class path and to the Windows search path to make it available for jBEAM.

1. Find start_jBEAM.bat. If you don’t use this start script directly, follow the link from your jBEAM start icon (there should be a path to the bat file)

2. Edit start_jBEAM.bat with a text editor (e.g. Notepad++)

3. Add the paths to the JEP installation to “CLASSPATH” and “PATH”. Add the following lines to the part of the start script, where the other libraries are added to the class path.
   This should look like this:
   SET CLASSPATH=%jarfile%;%CLASSPATH%;%userprofile%\AppData\Local\Programs\Python\Python38\Lib\site-packages\jep\jep-3.9.0.jar
   SET PATH=%PATH%;%userprofile%\AppData\Local\Programs\Python\Python38\Lib\site-packages\jep

start_jBEAM.bat

...
REM ----------------------------- add all jars of the lib folder to the class path -----------------------------
IF NOT EXIST "%LIBRARY_FOLDER%" SET LIBRARY_FOLDER=.\lib
IF NOT EXIST "%CLASSPATH%" SET CLASSPATH=

FOR /r %LIBRARY_FOLDER% %%j IN (*.jar) DO (
SET CLASSPATH=!CLASSPATH!;%%j
)

SET CLASSPATH=%jarfile%;%CLASSPATH%;%userprofile%\AppData\Local\Programs\Python\Python38\Lib\site-packages\jep\jep-3.9.0.jar
SET PATH=%PATH%;%userprofile%\AppData\Local\Programs\Python\Python38\Lib\site-packages\jep

REM -------------------------------------------- Start jBEAM ---------------------------------------------------
...

Hint for developers: If you want to start jBEAM from your IDE, you have to make sure, that the path to ...\AppData\Local\Programs\Python\Python38\Lib\site-packages\jep is defined in the environment variable for the PATH and that the path is not overwritten in your run configuration.

Check the availability of the library

After starting jBEAM with the batch script, you can check the availability of the library via Help > Resources/Library Usage.

Selecting the entry Resources/Library Usage from the Help menu opens the Resources/Library Overview Dialog. If the list entry for Jep is colored green, the library is available for usage.

API

To use the API in jBEAM, you have to create a Script (Extra > Miscellaneous > Script) and select Python as script language.

Mainly, there are two objects to connect Python scripts with jBEAM (jBEAMInputs and jBEAMResults)

jBEAMInputs

This object is used to get jBEAM Data Objects into the Python script.

Currently there are two methods:

jBEAMInputs.getDoubleArray(ScriptingComponentIF jP, String symbol)

• This method returns a simple Python array

• jP is existing script component within the script

• Symbol is the name of the input configured in the inputs section of the script editor

jBEAMInputs.getNDArray(ScriptingComponentIF jP, String symbol)

• This method returns a ndarray

• jP is existing script component within the script

• Symbol is the name of the input configured in the inputs section of the script editor

jBEAMResults

This object is used to set Python objects as result objects of the scripting component.

jBEAMResults.setResult(String name, Object scriptResult)

• This method adds the given object as result to the scripting component.

• Name is the requested data object name.

• scriptResult is a python object which should be converted and published as jBEAM data object. Currently supported object types:

  • NDArray

  • SingleValues (String, Number)

  • Collections (1D, 2D)

• If the conversion is not possible then the script component publish a script value with the string representation of the python object.

For further information regarding JEP please look at https://github.com/ninia/jep/wiki/Getting-Started