Page Contents

1 Python Version Compatibility
2 Requirements
3 Using the Python HYPERSIM® API via Command Line Prompt
4 Installing a Python IDE
5 Importing the HYPERSIM API Package
6 Migrating scripts from Python 2

Python Version Compatibility

Please refer to the Software Compatibility page to know which version of Python is supported in each HYPERSIM version.

Requirements

The HYPERSIM API requires a few Python modules, notably around the gRPC technology used by the API. The Python requirements associated to the version of interest are located at the path below and must be installed:

C:\OPAL-RT\HYPERSIM\{hypersim_version}\Windows\HyApi\python\HyApiUtils\requirements.txt

For HYPERSIM versions < 2026.2

In addition to the requirements above, a specific version of setuptools needs to be used in your Python environment due to a dependency on pkg_resources

python -m pip install "setuptools<82.0.0"

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

The HYPERSIM API only supports the 64-bit versions of Python.

Using the Python HYPERSIM® API via Command Line Prompt

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

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 documentation to set it up in your environment.

Importing the HYPERSIM API Package

The HYPERSIM® API package, named HyWorksApi, allows you to control many parts of a simulator, from configuration to execution. All available functions are described in the next section. 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.path.join(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 migrate 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.