Using Python HYPERSIM® API

To start Python from a Windows command line prompt:

python

Make sure the HYPERSIM® installation directory is part of the Python path:

import sys

sys.path.append(r'C:\OPAL-RT\HYPERSIM\hypersim_version\Windows\HyApi\python')

Where hypersim_version is the folder corresponding to the version to use.

You can then import the Python module to be able to communicate with HYPERSIM®:

import HyWorksApiGRPC as HyWorksApi

Please refer to the Software Compatibility page to know which version of Python is supported in each version. The HYPERSIM API requires a few python modules (notably around the gRPC technology used by the API). If some packages are missing, the previous import will return an error, and a message explaining the command to install the required packages.

Note: HYPERSIM packages its own python version which is compatible with the API. It can be found at C:\OPAL-RT\HYPERSIM\hypersim_version\Windows\PythonHS. 

Installing a Python IDE

The second way to use Python is to install Eclipse with the PyDev module to get an interactive python environment.

The most comfortable way of developing with Python is to use an Integrated Developer Environment (IDE). Here are some popular Python IDE :

• Pycharm
• VS Code
• Eclipse IDE  with the PyDev Eclipse Module

Please follow their own documentation to set it up on your environment.

Importing the API

The HYPERSIM® API module, named HyWorksApi, allows you to control many parts of a simulator, from configuration to execution. All available functions are described in the next section. In order to use this module, it is necessary to import it. There are several ways to enable its import :

• Just like in the example above, appending the exact path directly in the code, by calling :

sys.path.append(r'C:\OPAL-RT\HYPERSIM\hypersim_version\Windows\HyApi\python')

• By adjusting the PYTHONPATH environment variable so that it contains the python API folder, before you run your script.

PYTHONPATH=C:\OPAL-RT\HYPERSIM\hypersim_version\Windows\HyApi\python

• By mixing the 2 previous approaches, setting an environment variable called HYPERSIM_DIR=C:\OPAL-RT\HYPERSIM\hypersim_version . Then, in your script, you can do

import os
import sys
sys.path.append(os.environ['HYPERSIM_DIR'], 'Windows', 'HyApi', 'python')

In all cases, you can then import the HYPERSIM API via the following line.

import HyWorksApiGRPC as HyWorksApi

Using the API through the Interactive Python Console is a good way to test some commands that would be later integrated to a Python script and thus creating a fully automated sequence.

See the examples at the end of this document for useful command examples.

Migrating scripts from Python 2

If you used a previous version of HYPERSIM, you might have some python scripts that were written in Python 2.7. As of HYPERSIM 2023.1, you will need to migrate from python 2 to python 3 to be able to continue using these scripts.

Luckily, a community python module exists to help users migrating their scripts. Please consult the documentation of py2to3 to get familiar with the procedure.

Additionally, with this migration, the folder which contained the API has been changed, from :

• before : C:\OPAL-RT\HYPERSIM\hypersim_version\Windows\HyApi\c\py
• after : C:\OPAL-RT\HYPERSIM\hypersim_version\Windows\HyApi\python

This change centralizes the HYPERSIM, ScopeView and Datalogger APIs in the same location.

Please note that while your script will still currently work using the C\py folder import, it may be removed in a future version. It is encouraged to update that import path and name as well.