Python API / Sequencer does not work when a HYPERSIM model is already open

Q&A
, , ,
1

Hello Team,

I am using HYPERSIM 2025.2.1 and trying to use the Python API / Sequencer functionality.

Initially, I thought the issue was related to the Python version because I was testing with Python 3.14. After further investigation, I found that the API works correctly when using the PythonHS environment provided with HYPERSIM.

The actual issue appears to be related to HYPERSIM session behavior.

Observation:

  • Python API can successfully connect when no model is currently open.
  • If a model is already open in HYPERSIM, the Python API / Sequencer does not behave as expected.
  • Closing the currently open model allows the Python script to work again.

Environment:

  • HYPERSIM Version: 2025.2.1
  • Python Environment: Windows\PythonHS\python.exe
  • API: HyWorksApiGRPC

Typical workflow:

  1. Launch PythonHS
  2. Import HyWorksApiGRPC
  3. Start and connect to HYPERSIM
  4. Open a design using openDesign()

Question:

Is it an expected limitation that the Python API or Sequencer requires no model to be open before executing scripts?

If a design is already open, what is the recommended workflow?

  • Should we close the existing design first?
  • Should we use connectToHyWorks() instead of startAndConnectHypersim()?
  • Is there a supported way to attach to an already open design?

Any clarification on the expected behavior would be appreciated.

Thank you.

2

Hi Ravi,
Thanks for joining OPAL-RT community.
The issue you report seems to be a known bug. It will most likely be fixed in a newer release.
Will check and keep you posted.

3

Yes, this is expected behavior — but it’s not a limitation, it’s a workflow distinction. The key is choosing the correct connection method depending on your scenario.

Understanding
Understanding463×520 45.4 KB

The problem occurs because startAndConnectHypersim() launches a fresh HYPERSIM process. If HYPERSIM is already running with a model open, you now have two instances competing, which causes unexpected behavior.
HyWorksApi Commands

Recommended Workflows
Scenario 1: HYPERSIM is NOT running → Launch + open model

Scenario1
Scenario1483×334 32.5 KB

Scenario 2: HYPERSIM is ALREADY running (model may or may not be open) → Attach to it

Scenario2
Scenario2478×471 48.3 KB

Scenario 3: You need to switch models via the API

Scenario3
Scenario3481×337 34.8 KB

The Sequencer (Built-In GUI) vs. External Python Scripts
There’s an important distinction:

Sequencer (executed from within the HYPERSIM GUI via the Play button): requires the design to already be open. The documentation explicitly states: “execute the script by clicking the Play button; make sure the design is already open.”
Sequencer | Quick Start Guide

External Python scripts (launched from PythonHS command line): must explicitly manage the connection using either startAndConnectHypersim() or connectToHyWorks() depending on context.

Additional Notes
Multi-user sessions are not supported — only one API session can control HYPERSIM at a time.
Known Issues & Limitations

Python 3.14 compatibility — Confirm the supported Python version on the
Software Compatibility page. For HYPERSIM 2025.2.x, use the bundled PythonHS environment to avoid dependency issues (setuptools < 82.0.0 is required for versions < 2026.2).
Python API | Setup

id parameter in connectToHyWorks() — If you have multiple HYPERSIM instances (advanced use case), you can specify which one to connect to using the id parameter.

4

Hi Ravi,

Without any logs or python script, we can only speculate as to what the issue really is.

For your 3 questions:

  • In older versions of HYPERSIM, there was indeed a bug in the Sequencer, where the Sequencer UI would not open if a design was already opened. This issue is fixed in 2026.2, where we did a big rework of the Sequencer (notably, much more stable auto completion feature). In the older versions, the workaround was to open HYPERSIM, then open the sequencer, then open the model.
  • startAndConnectHypersim first tries to connect to an existing session (calling connectToHyWorks under the hood). If that fails, then it starts a new session. You can force a second HYPERSIM session with a flag forceNew=True, but the support for multi HYPERSIM via API is currently limited. So startAndConnectHypersim is always safer, unless you want in your script to detect first that HYPERSIM was not running to flag any issue in your environment.
  • You do not need to close other designs to switch the focus on another one. The API openDesign() should be enough , but currently only switches part of the focus : The UI also should be focused on the model, which is required for certain operations. To make sure you have really fully switched the focus to the other model, you can use this workaround:
import HyWorksApiGRPC as HyWorksApi
HyWorksApi.connectToHyWorks()

model_1 = r"C:\Users\MaximeJosse\Documents\HYPERSIM\HVAC_500kV_6Bus\HVAC_500kV_6Bus.ecf"
model_2 = r"C:\Users\MaximeJosse\Documents\HYPERSIM\HVAC_230kV_16Bus\HVAC_230kV_16Bus.ecf"
while True:
    HyWorksApi.openDesign(model_1)
    HyWorksApi._execute("selectDesign", ['-D', model_1])
    print(HyWorksApi.getComponentParameter("WES7", "baseVolt"))
    HyWorksApi.openDesign(model_2)
    HyWorksApi._execute("selectDesign", ['-D', model_2])
    print(HyWorksApi.getComponentParameter("Bus9", "baseVolt"))