> 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/hypersim-api-references/design.md).

# Design

## Function: batchAddDevices

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | <p>Add multiple devices to a design in a single batch operation.<br>Each entry in the returned list corresponds (by <code>AddDeviceResult.index</code>) to an<br>entry in <em>devices</em>. Inspect <code>AddDeviceResult.success</code> to distinguish successes<br>from failures without raising.<br>devices dictionaries should be in the following format:<br>{<br>Required keys:<br>- library (string)<br>- type (string)<br>Optional keys:<br>- x (int)<br>- y (int)<br>- page (int)<br>- subcircuit (string)<br>- name (string)<br>- rotation (int)<br>- flipVertically (bool)<br>- flipHorizontally (bool)<br>}</p> |
| **Parameters** | <p><strong>devices</strong> (<em>list\[dict]</em>) – a list of devices to be added.<br><strong>interrupt\_on\_error</strong> (<em>bool</em>) – if True, stop processing on the first failure.</p>                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **Returns**    | One `AddDeviceResult` per processed operation. (list\[AddDeviceResult])                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Raises**     | **RuntimeError** – If every operation failed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

## Function: closeDesign

| **Section**    | **Description**                                            |
| -------------- | ---------------------------------------------------------- |
| **Action**     | Close design                                               |
| **Parameters** | **designPath** (*str*) – path to the HYPERSIM model (.ecf) |
| **Returns**    | Error value (int)                                          |
| **Raises**     | **AssertionError** – Raises exception on error             |

## Function: disconnectDesign

| **Section**    | **Description**                                            |
| -------------- | ---------------------------------------------------------- |
| **Action**     | Disconnect HyWorksApi from the HYPERSIM model              |
| **Parameters** | **designPath** (*str*) – path to the HYPERSIM model (.ecf) |
| **Returns**    | Error value (int)                                          |
| **Raises**     | **AssertionError** – Raises exception on error             |

## Function: findMinimalStepSize

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | <p>Determines the smallest possible time step that prevents exceeding a specified number of overruns.<br>This function requires Dashboards to be enabled beforehand.<br>It attempts to start and stop the simulation in each iteration while staying within the overrun limit,<br>ensuring the number of overruns does not reach the threshold.<br>If the simulation completes before reaching the specified timeout, the time step is incremented by the given jump value.<br>The minimal time step is identified when the simulation completes without timing out.</p>                                                                                                                                                                                                                                                                                                                             |
| **Parameters** | <p><strong>timeout</strong> (<em>float</em>) – Maximum allowed simulation iteration time in seconds.<br><strong>overrunsThreshold</strong> (<em>int</em>) – The maximum number of overruns per iteration that must not be reached, for example,<br>setting it to 1 means the program will iterate if the current simulation iteration experiences at least one overrun.<br>Note that the threshold must be greater than 0.<br><strong>nCores</strong> (<em>int</em>) – Number of processor cores to use (Default: 100). If the specified number exceeds available hardware<br>cores, all available cores will be used. A value of 0 enables automatic core assignment.<br><strong>startingTimeStep</strong> (<em>float</em>) – Initial time step in seconds (Default: 1 microsecond)<br><strong>jump</strong> (<em>float</em>) – Increment for the time step in seconds (Default: 1 microsecond)</p> |
| **Returns**    | The minimal time step in seconds, or None if unsuccessful (float)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

## Function: getAllComponentDescriptions

| **Section**    | **Description**                                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Action**     | Gets the descriptions of all components available in the current design, including their parameters and signals. |
| **Parameters** | None                                                                                                             |
| **Returns**    | A list of component descriptions (list)                                                                          |
| **Raises**     | None                                                                                                             |

## Function: getAllComponentParameters

| **Section**    | **Description**                                             |
| -------------- | ----------------------------------------------------------- |
| **Action**     | Gets the list of parameters for a given component.          |
| **Parameters** | **compName** (*str*) – Component Name                       |
| **Returns**    | A list of parameter descriptions, for the 'compName' (list) |
| **Raises**     | None                                                        |

## Function: getAllComponentSensors

| **Section**    | **Description**                                                |
| -------------- | -------------------------------------------------------------- |
| **Action**     | Gets the list of sensors available for a given component type. |
| **Parameters** | **compName** (*str*) – Component Name                          |
| **Returns**    | A list of sensor descriptions for the component. (list)        |
| **Raises**     | None                                                           |

## Function: getAllDevicesNames

| **Section**    | **Description**                                |
| -------------- | ---------------------------------------------- |
| **Action**     | Gets the list of all devices names             |
| **Parameters** | None                                           |
| **Returns**    | The list of all visible devices (list)         |
| **Raises**     | **AssertionError** – Raises exception on error |

{% hint style="info" %}
This call requires an analyze call before to function properly
{% endhint %}

\## Function: getAllSelectedSensors

| **Section**    | **Description**                                                                                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | <p>Gets the list of selected sensors in the current design, including their runtime I/O connections.<br>The returned value is a CSV string; it is the caller's responsibility to decode it with the<br>appropriate CSV parsing tool.</p> |
| **Parameters** | None                                                                                                                                                                                                                                     |
| **Returns**    | Csv string of selected sensor descriptions (str)                                                                                                                                                                                         |
| **Raises**     | None                                                                                                                                                                                                                                     |

## Function: getDesignPrefs

| **Section**    | **Description**               |
| -------------- | ----------------------------- |
| **Action**     | Get current model preferences |
| **Parameters** | None                          |
| **Returns**    | Model preferences (str)       |
| **Raises**     | None                          |

## Function: importEDD

| **Section**    | **Description**                                                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Import EDD to current HYPERSIM model                                                                                                                 |
| **Parameters** | <p><strong>eddFilePath</strong> (<em>str</em>) – path to EDD (.edd)<br><strong>doConnections</strong> (<em>bool</em>) – connect imported devices</p> |
| **Returns**    | Error value (int)                                                                                                                                    |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                       |

## Function: importPowerFactory

| **Section**    | **Description**                                                                                                                                                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Import PowerFactory                                                                                                                                                                                                                                                    |
| **Parameters** | <p><strong>filePath</strong> (<em>str</em>) – path to PowerFactory file (.xml)<br><strong>mode</strong> (<em>int</em>) – select switch import mode (Default: 0): 0 (All switches are removed), 1 (All switches are added), 2 (Only switches with events are added)</p> |
| **Returns**    | Error value (int)                                                                                                                                                                                                                                                      |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                         |

## Function: importProject

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Import HYPERSIM project                                                                                                                                                                                                                                                                                                                                                                  |
| **Parameters** | <p><strong>zipFilePath</strong> (<em>str</em>) – path to HYPERSIM project (.zip)<br><strong>destinationPath</strong> (<em>str</em>) – destination path for the imported project<br><strong>isUI</strong> (<em>bool</em>) – true if import is for UI, false otherwise<br><strong>overwrite</strong> (<em>bool</em>) – true if existing project should be overwritten, false otherwise</p> |
| **Returns**    | Error value (int)                                                                                                                                                                                                                                                                                                                                                                        |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                                                                                                                                           |

## Function: importPSCAD

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**     | Imports a PSCAD project into the current HYPERSIM model.                                                                                                                                                                                                                                                                                   |
| **Parameters** | <p><strong>filePath</strong> (<em>str</em>) – path to the PSCAD project file (.pscx)<br><strong>onlyDll</strong> (<em>bool</em>) – if True, import only the compiled DLL instead of the full circuit<br><strong>removeNotConnectedBuses</strong> (<em>bool</em>) – remove buses left without connections after import (Default: False)</p> |
| **Returns**    | A string detailing the conversion and import steps (str)                                                                                                                                                                                                                                                                                   |
| **Raises**     | **HyWorksApiException** – Raised on failure                                                                                                                                                                                                                                                                                                |

## Function: importPSSE

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**     | Imports a PSSE case file into the current HYPERSIM model.                                                                                                                                                                                                                                                                                                                                                                |
| **Parameters** | <p><strong>filePath</strong> (<em>str</em>) – path to the PSSE project file (.dyr)<br><strong>replaceMachines</strong> (<em>bool</em>) – Replaces machines in the model to save by voltage sources and removes the associated control blocks (Default: False)<br><strong>groupMachinesWithControls</strong> (<em>bool</em>) – group imported machines together with their associated control systems (Default: True)</p> |
| **Returns**    | A string detailing the conversion and import steps (str)                                                                                                                                                                                                                                                                                                                                                                 |
| **Raises**     | **HyWorksApiException** – Raised on failure                                                                                                                                                                                                                                                                                                                                                                              |

## Function: newDesign

| **Section**    | **Description**                                                |
| -------------- | -------------------------------------------------------------- |
| **Action**     | Create new HYPERSIM model                                      |
| **Parameters** | **designFilePath** (*str*) – path to the HYPERSIM model (.ecf) |
| **Returns**    | Error value (int)                                              |
| **Raises**     | **AssertionError** – Raises exception on error                 |

## Function: openDesign

| **Section**    | **Description**                                        |
| -------------- | ------------------------------------------------------ |
| **Action**     | Open HYPERSIM model                                    |
| **Parameters** | **designPath** (*str*) – path to HYPERSIM model (.ecf) |
| **Returns**    | Error value (int)                                      |
| **Raises**     | **AssertionError** – Raises exception on error         |

## Function: recheckPorts

| **Section**    | **Description**                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Action**     | <p>Check connections by page connectors<br>Recommended after build circuits involving page connectors via API</p> |
| **Parameters** | None                                                                                                              |
| **Returns**    | Error value (int)                                                                                                 |
| **Raises**     | **AssertionError** – Raises exception on error                                                                    |

## Function: saveDesign

| **Section**    | **Description**                                |
| -------------- | ---------------------------------------------- |
| **Action**     | Save current HYPERSIM model                    |
| **Parameters** | None                                           |
| **Returns**    | Error value (int)                              |
| **Raises**     | **AssertionError** – Raises exception on error |

## Function: saveDesignAs

| **Section**    | **Description**                                |
| -------------- | ---------------------------------------------- |
| **Action**     | Save current HYPERSIM model                    |
| **Parameters** | **fileName** (*str*) – desired model path      |
| **Returns**    | Error value (int)                              |
| **Raises**     | **AssertionError** – Raises exception on error |

## Function: updateEDD

| **Section**    | **Description**                                                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Update EDD                                                                                                                                           |
| **Parameters** | <p><strong>eddFilePath</strong> (<em>str</em>) – path to EDD (.edd)<br><strong>doConnections</strong> (<em>bool</em>) – connect imported devices</p> |
| **Returns**    | Error value (int)                                                                                                                                    |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                       |


---

# 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/hypersim-api-references/design.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.
