> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-with-python-script.md).

# Automate with Python script

The [**HYPERSIM Python API**](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/hypersim-api-references.md) provides programmatic control over the full simulation lifecycle — from model configuration and preparation, through execution and acquisition, to post-processing. It communicates with HYPERSIM via gRPC, enabling automation of repetitive tasks and integration into scripted workflows.

Leverage additional APIs such as the [**Datalogger API**](https://github.com/Opal-RT-Technologies/product-docs-hypersim/tree/release-2026.4/automation-api-and-scripting/datalogger-api.md)**,** [**Dashboard API**](https://github.com/Opal-RT-Technologies/product-docs-hypersim/tree/release-2026.4/automation-api-and-scripting/dashboard-api/README.md) or [**ScopeView API**](https://www.opal-rt.com/docs/scopeview/automation-api-and-scripting/use-python-scopeview-api) enhance functionality and integration capabilities.

## Requirements

Please refer to the [Software Compatibilities](https://www.opal-rt.com/docs/hypersim/overview/workstation-requirements/software-compatibilities.md) page to know which **version of Python** is supported in this HYPERSIM version. The HYPERSIM API only supports the **64-bit versions** of Python.

The HYPERSIM API relies on several Python modules, particularly those related to 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

## Use the Python HYPERSIM API

HYPERSIM includes a **bundled Python installation** that is fully compatible with the HYPERSIM API. It is located in C:\OPAL-RT\HYPERSIM\\\<hypersim\_version>\Windows\PythonHS.

{% hint style="info" %}
Using the **Python distribution** is recommended when developing or running scripts that interact with the HYPERSIM API.
{% endhint %}

There are three different ways to use the **HYPERSIM Python API**:

* Using the [**Sequencer tool**](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-with-python-script/use-the-sequencer-tool.md), a small Python Integrated Development Environment (IDE) integrated in HYPERSIM to write simple python scripts.
* Using the **Windows command prompt**
* Using a **Python Integrated Development Environment (IDE)**, such as [PyCharm](https://www.jetbrains.com/pycharm/download/?section=windows#section=windows), [Visual Studio Code](https://code.visualstudio.com/download), or [Eclipse](https://www.eclipse.org/downloads/download.php?file=/oomph/epp/photon/R/eclipse-inst-win64.exe) with the PyDev module

### Use the W**indows command prompt**

To use the **HYPERSIM API Package**, you must **first** import the module into your Python script.

#### **From the PowerShell**

To start **Python** from a Windows command line prompt:

{% code lineNumbers="true" %}

```shellscript
python
```

{% endcode %}

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

{% code overflow="wrap" lineNumbers="true" %}

```shellscript
import sys
sys.path.append(r'C:\OPAL-RT\HYPERSIM\<hypersim_version>\Windows\HyApi\python')
```

{% endcode %}

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 (required **gRPC** must be installed):

{% code overflow="wrap" lineNumbers="true" %}

```shellscript
import HyWorksApiGRPC as HyWorksApi
```

{% endcode %}

#### From the **Python distribution (recomanded)**

Open a Windows Command Prompt from the Python distribution by navigating to the Python installation folder and double-clicking **python.exe**.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-f73be69c8794d2d557e43b5c98023355ef86fe93%2Fpython-distribution-console.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
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.
{% endhint %}

### Use a Python IDE

There are several ways to enable its import the package.

1. Just like in the example above, appending the exact path directly in the code, by calling

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

2. By adjusting the **PYTHONPATH** environment variable so that it contains the Python API folder, before you run your script.

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

3. By mixing the 2 previous approaches, setting an environment variable called **HYPERSIM\_DIR**. Then, in your script, you can do:

{% code overflow="wrap" lineNumbers="true" %}

```python
import os
import sys
HYPERSIM_DIR=C:\OPAL-RT\HYPERSIM\<hypersim_version>
sys.path.append(os.path.join(os.environ['HYPERSIM_DIR'], 'Windows', 'HyApi', 'python'))
```

{% endcode %}

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

{% code overflow="wrap" lineNumbers="true" %}

```python
import HyWorksApiGRPC as HyWorksApi
```

{% endcode %}

## Examples code

<details>

<summary><strong>Example to start HYPERSIM, load a network and interact with HYPERSIM</strong></summary>

{% code overflow="wrap" lineNumbers="true" %}

```python
import os
import sys
sys.path.append(r'C:\OPAL-RT\HYPERSIM\<hypersim-version>\Windows\HyApi\python')
# Replace hypersim-version by the version you want to test

import HyWorksApiGRPC as HyWorksApi
import time

HyWorksApi.startAndConnectHypersim()
# This script finds the model next to it, when we launch python from the same directory
designPath = os.path.join(os.getcwd(), 'HVAC_735kV_38Bus.ecf')
HyWorksApi.openDesign(designPath)

HyWorksApi.setPreference('simulation.calculationStep', '50e-6')
calcStep = HyWorksApi.getPreference('simulation.calculationStep')

print('calcStep = ' + calcStep)

print('code directory : ' + HyWorksApi.getPreference('simulation.codeDirectory'))

print('mode : ' + HyWorksApi.getPreference('simulation.architecture'))

HyWorksApi.mapTask()
HyWorksApi.genCode()
HyWorksApi.startLoadFlow()
HyWorksApi.startSim()
print('startSim done')

volt = HyWorksApi.getComponentParameter('Ge7', 'baseVolt')
print(('baseVolt = ' + volt[0] + volt[1]))

HyWorksApi.setComponentParameter('Ge7', 'baseVolt', str(float(volt[0]) + 2.75))

volt2 = HyWorksApi.getComponentParameter('Ge7', 'baseVolt')

print(('baseVolt = ' + volt2[0] + volt2[1]))

if( abs( float(volt2[0]) - float(volt[0]) - 2.75) > 0.0001 ):
    print('SET_COMP ERROR')
else:
    print('SET_COMP SUCCESS')

time.sleep(5)

HyWorksApi.stopSim()
HyWorksApi.closeDesign(designPath)
HyWorksApi.closeHyperWorks()
```

{% endcode %}

This example is available at C:\OPAL-RT\HYPERSIM\\\<hypersim-version>\Windows\HyApi\C\py\example\_Windows\_Api.py

</details>

<details>

<summary><strong>Example to control ScopeView</strong></summary>

This example starts ScopeView, loads a template and data source, starts an acquisition, saves graphs as a pdf file and saves data to a text file. The output from ScopeView can be read from the stdout.txt and stderr.txt files generated in the same directory as the example.

To run this script, you must have an "**exampleFiles**" folder that contains the files template.xml, datasource.cfg and datasource.dat

{% code overflow="wrap" lineNumbers="true" %}

```python
import os
import sys
import time

#Modify this line to set-up your HYPERSIM version folder
#Example : hypersim_dir = "C:\\OPAL-RT\\HYPERSIM\\hypersim_2020.3.0.o97"
hypersim_dir =  " "

python_path = os.path.join(hypersim_dir, 'Windows', 'HyApi', 'python')
sys.path.insert(1, python_path)
import HyWorksApiGRPC as HyWorksApi
import ScopeViewApiGRPC as ScopeViewApi

currentPath = os.path.abspath(os.path.dirname( file ))
exportPath = os.path.join(currentPath, 'ExportData')

scopeViewProcess = ScopeViewApi.openScopeView()
ScopeViewApi.loadTemplate(os.path.join(currentPath, 'exampleFiles', 'template.xml'))
ScopeViewApi.replaceDataSource("COM1", "{file=" + os.path.abspath(os.path.join(currentPath, 'exampleFiles', 'datasource.cfg')) + "}")
ScopeViewApi.startAcquisition()

ScopeViewApi.exportToPDF(os.path.join(currentPath, 'exportPDF.pdf'))
ScopeViewApi.exportToFile(os.path.join(currentPath, 'exportTXT.txt'))

ScopeViewApi.close()
```

{% endcode %}

This example is available at C:\OPAL-RT\HYPERSIM\\\<hypersim-version>\Windows\ScopeView\lib\ScopeViewApi\example.py

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-with-python-script.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
