> 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/device.md).

# Device

## Function: activateObservables

| **Section**    | **Description**                                                                                                                                                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Activate a list of observable pins on the device                                                                                                                                                                                                                                 |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – name of the first device<br><strong>observables</strong> (<em>list\[str]</em>) – list of observable names. If list is empty, all observables are removed. Note that it does not append, but is the final list of observables</p> |
| **Returns**    | Error value (int)                                                                                                                                                                                                                                                                |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                                   |

### **Example Usage**

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

```python
HyWorksApi.activateObservables('Imeas1', ['a', 'b'])
HyWorksApi.activateObservables('Imeas1', [])
```

{% endcode %}

## Function: addBus1ph

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Add a 1 phase bus to HYPERSIM model.                                                                                                                                                                                                                                                                                                               |
| **Parameters** | <p><strong>signalName</strong> (<em>str</em>) – signal name<br><strong>points</strong> (<em>list\[list\[int]]</em>) – list of points as X-Y coordinates<br><strong>hitCheck</strong> (<em>bool</em>) – true to check for connections to other signals at both ends of the line<br><strong>subcircuit</strong> (<em>str</em>) – subcircuit path</p> |
| **Returns**    | Unique signal name (str)                                                                                                                                                                                                                                                                                                                           |
| **Raises**     | None                                                                                                                                                                                                                                                                                                                                               |

### **Example Usage**

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

```python
HyWorksApi.addBus1ph('myBus', [[-700, 0], [700, 0]])
```

{% endcode %}

{% hint style="info" %}
until connected to a power pin, a 1 phase bus is considered a control signal
{% endhint %}

## Function: addBus3ph

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Add a 3 phase bus to HYPERSIM model                                                                                                                                                                                                                                                                                                                 |
| **Parameters** | <p><strong>signalName</strong> (<em>str</em>) – signal name<br><strong>points</strong> (<em>list\[list\[int]]</em>) – list of points as X-Y coordinates<br><strong>hitCheck</strong> (<em>bool</em>) – true to check for connections to other signals at both ends of the line.<br><strong>subcircuit</strong> (<em>str</em>) – subcircuit path</p> |
| **Returns**    | Unique signal name (str)                                                                                                                                                                                                                                                                                                                            |
| **Raises**     | None                                                                                                                                                                                                                                                                                                                                                |

### **Example Usage**

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

```python
HyWorksApi.addBus3ph('myBus', [[-700, 0], [700, 0]])
```

{% endcode %}

## Function: addControlSignal

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                     |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Add a control signal to HYPERSIM model                                                                                                                                                                                                                                                                                                              |
| **Parameters** | <p><strong>signalName</strong> (<em>str</em>) – signal name<br><strong>points</strong> (<em>list\[list\[int]]</em>) – list of points as X-Y coordinates<br><strong>hitCheck</strong> (<em>bool</em>) – true to check for connections to other signals at both ends of the line.<br><strong>subcircuit</strong> (<em>str</em>) – subcircuit path</p> |
| **Returns**    | Unique signal name (str)                                                                                                                                                                                                                                                                                                                            |
| **Raises**     | None                                                                                                                                                                                                                                                                                                                                                |

### **Example Usage**

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

```python
HyWorksApi.addControlSignal('signal1', [[-700, 0], [700, 0], [700, 700])
```

{% endcode %}

## Function: addDevice

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Add device to HYPERSIM model                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Parameters** | <p><strong>libName</strong> (<em>str</em>) – device library name<br><strong>blocName</strong> (<em>str</em>) – device name<br><strong>coordX</strong> (<em>int</em>) – X coordinate<br><strong>coordY</strong> (<em>int</em>) – Y coordinate<br><strong>page</strong> (<em>int</em>) – page number<br><strong>subcircuit</strong> (<em>str</em>) – subcircuit path<br><strong>name</strong> (<em>str</em>) – Name to assign to the device. If non, a default name will be assigned<br><strong>rotation</strong> (<em>int</em>) – rotation in degrees.<br><strong>flipHorizontally</strong> (<em>bool</em>) – flip horizontally<br><strong>flipVertically</strong> (<em>bool</em>) – flip vertically</p> |
| **Returns**    | Unique device name, reusable in the other APIs (str)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Raises**     | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### **Example Usage**

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

```python
HyWorksApi.addDevice('Network RLC.clf', 'R grounded', 700, 700)
HyWorksApi.addDevice('Network RLC.clf', 'R grounded', 700, 700, 1, "MySubCircuit", "Resistor1")
```

{% endcode %}

{% hint style="info" %}
The library name must include the .clf for this to work.\
The device will be rotated and then flipped.
{% endhint %}

## Function: addPinsToDevice

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**     | Add pins, bundles, or pins inside bundles on a device                                                                                                                                                                                                                                                                                                                                                                                |
| **Parameters** | <p><strong>name</strong> (<em>str</em>) – device name<br><strong>cardinalPoint</strong> (<em>str</em>) – Location on the symbol of the device<br><strong>function</strong> (<em>str</em>) – The function of the listed pins. Input, Output or Power<br><strong>pins</strong> (<em>list\[str]</em>) – List of pins<br><strong>redraw</strong> (<em>bool</em>) – if True, the symbol will be redrawn with a default representation</p> |
| **Returns**    | Error value (int)                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                                                                                                                                                                                       |

### **Example Usage**

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

```python
HyWorksApi.addPinsToDevice('SubCircuit1', 'N', 'I', ['in1'], True)
HyWorksApi.addPinsToDevice('SubCircuit7', 'S', 'P', ['pow1'], True)
HyWorksApi.addPinsToDevice('SubCircuit1', 'W', 'O', ['Bundle1[o1]', 'Bundle1[o2]', 'Bundle1[o3]'], True)
And to make a sub circuit port connect with the sub circuit pins :
HyWorksApi.addPinsToDevice('SubCircuit1/SubCircuitPort', 'W', 'I', ['PORT[o1]', 'PORT[o2]', 'PORT[o3]')
```

{% endcode %}

## Function: batchConnectDevices

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | <p>Connect multiple device pin pairs in a single batch operation.<br>Each entry in the returned list corresponds (by <code>ConnectDeviceResult.index</code>) to<br>an entry in <em>connections</em>. Inspect <code>ConnectDeviceResult.success</code> to distinguish<br>successes from failures without raising.<br>connections dictionaries should be in the following format:<br>{<br>Required keys:<br>- "fromDev" (string)<br>- "fromPin" (string or list\[str])<br>- "toDev" (string)<br>- "toPin" (string or list\[str])<br>Optional keys:<br>- "three-phase" (boolean)<br>- "signalName" (string)<br>- "design" (string)<br>- "segPath" (string)<br>}</p> |
| **Parameters** | <p><strong>connections</strong> (<em>list\[dict]</em>) – a list of connections to create.<br><strong>interrupt\_on\_error</strong> (<em>bool</em>) – if True, stop processing on the first failure.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Returns**    | One `ConnectDeviceResult` per processed operation. (list\[ConnectDeviceResult])                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Raises**     | **RuntimeError** – If every operation failed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

## Function: connectBundleToBundle

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                             |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Connect two bundle pins together                                                                                                                                                                                                                                                                                                                            |
| **Parameters** | <p><strong>blocA</strong> (<em>str</em>) – name of the first device<br><strong>signalListA</strong> (<em>list\[str]</em>) – list of first bundle signals. ex: \['a','b','c']<br><strong>blocB</strong> (<em>str</em>) – name of the first pin<br><strong>signalListB</strong> (<em>list\[str]</em>) – list of second bundle signals. ex: \['a','b','c']</p> |
| **Returns**    | Error value (int)                                                                                                                                                                                                                                                                                                                                           |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                                                                                                              |

## Function: connectDevices

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Connect two device pins                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **Parameters** | <p><strong>blocA</strong> (<em>str</em>) – name of the first device<br><strong>pinA</strong> (<em>str</em>) – name of the first pin<br><strong>blocB</strong> (<em>str</em>) – name of the second device<br><strong>pinB</strong> (<em>str</em>) – name of the second pin<br><strong>isThreePhaseAndPowerFlexible</strong> (<em>bool</em>) – make the connection 3 phase, for components which can be both 1 phase or 3 phases<br><strong>signalName</strong> (<em>str</em>) – new signal name on the connection</p> |
| **Returns**    | Error value (int)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

### **Example Usage**

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

```python
HyWorksApi.connectDevices('Max1', 'y', 'mySubCircuit', 'a1', False)
HyWorksApi.connectDevices('mySubCircuit/B1', 'a1', 'mySubCircuit/Gain1', 'u', False)
```

{% endcode %}

## Function: connectDeviceToBus1ph

| **Section**    | **Description**                                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Connects a device onto 1 phase bus                                                                                                                                                       |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>pinName</strong> (<em>str</em>) – device pin name<br><strong>signalName</strong> (<em>str</em>) – signal name</p> |
| **Returns**    | Error value (bool)                                                                                                                                                                       |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                           |

### **Example Usage**

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

```python
HyWorksApi.connectDeviceToBus1ph('R1', 'net_1', 'myBus')
HyWorksApi.connectDeviceToBus1ph('SubCC1/SubSubCC1/R3', 'net_1', 'myBus')
```

{% endcode %}

## Function: connectDeviceToBus3ph

| **Section**    | **Description**                                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Connects a device onto 3 phase bus                                                                                                                                                       |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>pinName</strong> (<em>str</em>) – device pin name<br><strong>signalName</strong> (<em>str</em>) – signal name</p> |
| **Returns**    | Error value (bool)                                                                                                                                                                       |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                           |

### **Example Usage**

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

```python
HyWorksApi.connectDeviceToBus3ph('R1', 'net_1', 'myBus')
HyWorksApi.connectDeviceToBus3ph('SubCC1/SubSubCC1/R3', 'net_1', 'myBus')
```

{% endcode %}

## Function: connectDeviceToControlSignal

| **Section**    | **Description**                                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Connects a device onto a control signal                                                                                                                                                  |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>pinName</strong> (<em>str</em>) – device pin name<br><strong>signalName</strong> (<em>str</em>) – signal name</p> |
| **Returns**    | Error value (bool)                                                                                                                                                                       |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                           |

### **Example Usage**

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

```python
HyWorksApi.connectDeviceToControlSignal('Const1', 'y', 's1')
```

{% endcode %}

## Function: connectPinToBundle

| **Section**    | **Description**                                                                                                                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Connect a pin to a bundle's signal                                                                                                                                                                                                                                  |
| **Parameters** | <p><strong>blocA</strong> (<em>str</em>) – name of the first device<br><strong>pinA</strong> (<em>str</em>) – pin name<br><strong>blocB</strong> (<em>str</em>) – name of the second device<br><strong>signalListB</strong> (<em>str</em>) – bundle signal name</p> |
| **Returns**    | Error value (int)                                                                                                                                                                                                                                                   |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                      |

## Function: createSubCircuit

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Create a subcircuit with the specified 'name' and 'subType' at the given coordinates on the specified page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Parameters** | <p><strong>name</strong> (<em>str</em>) – subcircuit definition name<br><strong>subType</strong> (<em>str</em>) – subcircuit type name. This name will show when redrawing the device<br><strong>coordX</strong> (<em>int</em>) – X coordinate<br><strong>coordY</strong> (<em>int</em>) – Y coordinate<br><strong>page</strong> (<em>int</em>) – page number<br><strong>rotation</strong> (<em>int</em>) – rotation in degrees.<br><strong>flipHorizontally</strong> (<em>bool</em>) – flip horizontally<br><strong>flipVertically</strong> (<em>bool</em>) – flip vertically</p> |
| **Returns**    | Unique device name (str)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **Raises**     | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

### **Example Usage**

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

```python
HyWorksApi.createSubCircuit('Subcircuit1', 700, 700, 1)
HyWorksApi.createSubCircuit('Subcircuit1', 'THD', 700, 700,1)
HyWorksApi.createSubCircuit('DEV1/Subsubcircuit1')
```

{% endcode %}

{% hint style="info" %}
The subcircuit will be rotated and then flipped.
{% endhint %}

## Function: disconnectPin

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Disconnects the signal from a pin                                                                                                                                                                                                                                                                              |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>pinName</strong> (<em>str</em>) – pinName<br><strong>removeAllConnections</strong> (<em>bool</em>) – if True, also disconnects the pins of the connected devices, effectively removing completely the line connection of the design</p> |
| **Returns**    | Error value (bool)                                                                                                                                                                                                                                                                                             |
| **Raises**     | None                                                                                                                                                                                                                                                                                                           |

### **Example Usage**

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

```python
HyWorksApi.disconnectPin('Cons1', 'y')
HyWorksApi.disconnectPin('RC1', 'net_1', True)
```

{% endcode %}

## Function: displayComponent

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | <p>Print component information to STDOUT,<br>including tunable parameter values, default values,<br>parameter types and connectors.</p>                                                                                                                                                                                                                                                                 |
| **Parameters** | <p><strong>componentName</strong> (<em>str</em>) – component name<br><strong>printSignals</strong> (<em>bool</em>) – print signals (optional)<br><strong>printConnectors</strong> (<em>bool</em>) – print connectors (optional)<br><strong>printAttributes</strong> (<em>bool</em>) – print attributes (optional)<br><strong>printDefinition</strong> (<em>bool</em>) – print definition (optional)</p> |
| **Returns**    | Error value (str)                                                                                                                                                                                                                                                                                                                                                                                       |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                                                                                                                                                          |

## Function: displayConnections

| **Section**    | **Description**                                      |
| -------------- | ---------------------------------------------------- |
| **Action**     | Print specified component interconnections to STDOUT |
| **Parameters** | **componentName** (*str*) – component name           |
| **Returns**    | Error value (str)                                    |
| **Raises**     | **AssertionError** – Raises exception on error       |

## Function: exportCigre

| **Section**    | **Description**                                                                                          |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| **Action**     | Export a configured CIGRE component to a file                                                            |
| **Parameters** | <p><strong>compName</strong> – cigre component name<br><strong>file\_path</strong> – cigre file path</p> |
| **Returns**    | Success status (bool)                                                                                    |
| **Raises**     | **AssertionError** – Raises exception on error                                                           |

### **Example Usage**

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

```python
Export CIGRE:
HyWorksApi.exportCigre("comp", r"C: emp\my_cigre.cigre")
```

{% endcode %}

## Function: flipHorizontallyDevice

| **Section**    | **Description**                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**     | Flips a device horizontally                                                                                                                                  |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>keepConnections</strong> (<em>bool</em>) – true if pin connections should be kept</p> |
| **Returns**    | Error value (bool)                                                                                                                                           |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                               |

### **Example Usage**

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

```python
HyWorksApi.flipHorizontallyDevice('R1')
```

{% endcode %}

## Function: flipVerticallyDevice

| **Section**    | **Description**                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**     | Flips a device vertically                                                                                                                                    |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>keepConnections</strong> (<em>bool</em>) – true if pin connections should be kept</p> |
| **Returns**    | Error value (bool)                                                                                                                                           |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                               |

### **Example Usage**

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

```python
HyWorksApi.flipVerticallyDevice('R1')
```

{% endcode %}

## Function: getComponentParameter

| **Section**    | **Description**                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Retrieve component parameter value                                                                                                  |
| **Parameters** | <p><strong>compName</strong> (<em>str</em>) – component name<br><strong>compParam</strong> (<em>str</em>) – component parameter</p> |
| **Returns**    | A list of 2 str, the first one being the value and the second one being the unit (list\[str])                                       |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                      |

## Function: getCoordinates

| **Section**    | **Description**                                                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Retrieve the X-Y coordinates of a device or its pin                                                                                                                              |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>pinName</strong> (<em>str</em>) – pin name, can be non if only the position of the device is required</p> |
| **Returns**    | Returns a list of 2 int, representing the (X, Y) coordinates (list\[int])                                                                                                        |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                   |

### **Example Usage**

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

```python
HyWorksApi.getCoordinates('R1')
HyWorksApi.getCoordinates('MTL', 'baseVolt')
```

{% endcode %}

## Function: getDeviceBundleChildPins

| **Section**    | **Description**                                                                                                              |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Retrieve the list of all children pin names in a bundle pin of a device                                                      |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>pinName</strong> (<em>str</em>) – bundle pin name</p> |
| **Returns**    | The list of the sub-pin names (list\[str])                                                                                   |
| **Raises**     | **AssertionError** – Raises exception on error                                                                               |

### **Example Usage**

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

```python
HyWorksApi.getDeviceBundleChildPins('AC1A_1', 'In')
```

{% endcode %}

## Function: getDeviceBundlePins

| **Section**    | **Description**                                               |
| -------------- | ------------------------------------------------------------- |
| **Action**     | Retrieve the list of all pin names of type bundle on a device |
| **Parameters** | **deviceName** (*str*) – device name                          |
| **Returns**    | List of pins of type bundle on a device (list\[str])          |
| **Raises**     | **AssertionError** – Raises exception on error                |

### **Example Usage**

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

```python
HyWorksApi.getDeviceBundlePins('AC1A_1')
```

{% endcode %}

## Function: getDevicePins

| **Section**    | **Description**                                |
| -------------- | ---------------------------------------------- |
| **Action**     | Retrieve the list of all pin on a device       |
| **Parameters** | **deviceName** (*str*) – device name           |
| **Returns**    | List of pins on a device (list\[dict])         |
| **Raises**     | **AssertionError** – Raises exception on error |

### **Example Usage**

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

```python
HyWorksApi.getDevicePins('AC1A_1')
```

{% endcode %}

## Function: getDevicePinTypes

| **Section**    | **Description**                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| **Action**     | Retrieve the type (function) of certain pins on a device                                                     |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>pinNames</strong> – pin names</p>     |
| **Returns**    | List of types in the same order of pins requested. I = Input, O = Output, P = Power, S = Bundle (list\[str]) |
| **Raises**     | **AssertionError** – Raises exception on error                                                               |

### **Example Usage**

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

```python
HyWorksApi.getDevicePinTypes('POW1', ['A', 'P', 'net_1'])
```

{% endcode %}

## Function: getImpedanceMeasurement

| **Section**    | **Description**                                                                                                                                                                                                                                                |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Performs the impedance measurement for a bus                                                                                                                                                                                                                   |
| **Parameters** | <p><strong>busName</strong> (<em>str</em>) – bus name<br><strong>freqMin</strong> (<em>float</em>) – minimum frequency<br><strong>freqMax</strong> (<em>float</em>) – maximum frequency<br><strong>freqInc</strong> (<em>float</em>) – frequency increment</p> |
| **Returns**    | A csv formatted string containing the Z\_mag and Z\_ang for each frequency (str)                                                                                                                                                                               |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                 |

## Function: importCigre

| **Section**    | **Description**                                                                                                                                                                                                                                          |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Import or update a CIGRE component.                                                                                                                                                                                                                      |
| **Parameters** | <p><strong>compName</strong> – cigre component name<br><strong>file\_path</strong> – hypcigre or cigre file path. Ignored if the API is used for update purpose.<br><strong>import\_folder</strong> – directory for the import if using a cigre file</p> |
| **Returns**    | The CIGRE component created or updated (str)                                                                                                                                                                                                             |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                           |

### **Example Usage**

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

```python
Updating an already imported CIGRE:
HyWorksApi.importCigre("comp")
Importing with a hypcigre description
HyWorksApi.importCigre("comp", r"C: emp\my_cigre.hypcigre")
Importing from an exported CIGRE:
HyWorksApi.importCigre("comp", r"C: emp\my_cigre.cigre", r"C:       emp\my_imported_cigre")
```

{% endcode %}

## Function: importUCM

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Import UCM to current HYPERSIM model                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **Parameters** | <p><strong>defFilePath</strong> (<em>str</em>) – path to UCM (. . . py: function: : )<br><strong>coordX</strong> (<em>int</em>) – X coordinate<br><strong>coordY</strong> (<em>int</em>) – Y coordinate<br><strong>page</strong> (<em>int</em>) – page number<br><strong>subcircuit</strong> (<em>str</em>) – subcircuit path<br><strong>name</strong> (<em>str</em>) – Name to assign to the device. If none, a default name will be assigned<br><strong>rotation</strong> (<em>int</em>) – rotation in degrees.<br><strong>flipHorizontally</strong> (<em>bool</em>) – flip horizontally<br><strong>flipVertically</strong> (<em>bool</em>) – flip vertically</p> |
| **Returns**    | Unique device name, reusable in the other APIs (str)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

{% hint style="info" %}
The UCM will be rotated and then flipped.
{% endhint %}

## Function: includeDevice

| **Section**    | **Description**                                                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**     | Include or exclude a device in HYPERSIM model                                                                                                                      |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>include</strong> (<em>bool</em>) – true if device should be included, false if excluded</p> |
| **Returns**    | Error value (bool)                                                                                                                                                 |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                     |

## Function: removeDevice

| **Section**    | **Description**                                |
| -------------- | ---------------------------------------------- |
| **Action**     | Remove device from model                       |
| **Parameters** | **deviceName** (*str*) – device name           |
| **Returns**    | Error value (int)                              |
| **Raises**     | **AssertionError** – Raises exception on error |

## Function: renameDevice

| **Section**    | **Description**                                                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Rename a device inside the model                                                                                                          |
| **Parameters** | <p><strong>oldDeviceName</strong> (<em>str</em>) – old device name<br><strong>newDeviceName</strong> (<em>str</em>) – new device name</p> |
| **Returns**    | Error value (int)                                                                                                                         |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                            |

### **Example Usage**

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

```python
HyWorksApi.renameDevice('DEV1', 'SubCircuit1')
HyWorksApi.renameDevice('SubCircuit1/Gain1', 'SubCircuit1/factor')
```

{% endcode %}

## Function: renameSignal

| **Section**    | **Description**                                                                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Rename all signals sharing a name inside the model                                                                                                                                                                  |
| **Parameters** | <p><strong>oldName</strong> (<em>str</em>) – old signal name<br><strong>newName</strong> (<em>str</em>) – new signal name<br><strong>visible</strong> (<em>bool</em>) – if name should be visible on the design</p> |
| **Returns**    | Error value (bool)                                                                                                                                                                                                  |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                      |

## Function: rotateLeftDevice

| **Section**    | **Description**                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**     | Rotates a device to the left                                                                                                                                 |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>keepConnections</strong> (<em>bool</em>) – true if pin connections should be kept</p> |
| **Returns**    | Error value (bool)                                                                                                                                           |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                               |

### **Example Usage**

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

```python
HyWorksApi.rotateLeftDevice('R1')
```

{% endcode %}

## Function: rotateRightDevice

| **Section**    | **Description**                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**     | Rotates a device to the right                                                                                                                                |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>keepConnections</strong> (<em>bool</em>) – true if pin connections should be kept</p> |
| **Returns**    | Error value (bool)                                                                                                                                           |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                               |

### **Example Usage**

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

```python
HyWorksApi.rotateRightDevice('R1')
```

{% endcode %}

## Function: setComponentParameter

| **Section**    | **Description**                                                                                                                                                                                |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Set a component parameter to a certain value                                                                                                                                                   |
| **Parameters** | <p><strong>compName</strong> (<em>str</em>) – component name<br><strong>compParam</strong> (<em>str</em>) – component parameter<br><strong>value</strong> (<em>str</em>) – component value</p> |
| **Returns**    | Error value (int)                                                                                                                                                                              |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                 |

### **Example Usage**

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

```python
For a single value parameter:
HyWorksApi.setComponentParameter("comp", "param", "value1")
For a 3phase parameter (e.g. voltage source amplitude per phase):
HyWorksApi.setComponentParameter("comp", "Amplitude", "[Va Vb Vc]")
For a matrix parameter (e.g. 3x3 mutual impedance matrix):
HyWorksApi.setComponentParameter("comp", "R", "[Raa Rab Rac Rba Rbb Rbc Rca Rcb Rcc]")
```

{% endcode %}

## Function: setComponentParameters

| **Section**    | **Description**                                                                                                                                                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Set multiple component parameters to specified values                                                                                                                                                                                                |
| **Parameters** | <p><strong>compNames</strong> (<em>list of str</em>) – list of component names<br><strong>compParams</strong> (<em>list of str</em>) – list of component parameters<br><strong>values</strong> (<em>list of str</em>) – list of component values</p> |
| **Returns**    | Error value (int)                                                                                                                                                                                                                                    |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                                                       |

### **Example Usage**

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

```python
HyWorksApi.setComponentParameters(["comp1", "comp2"], ["param1", "param2"], ["value1", "value2"])
```

{% endcode %}

## Function: setDeviceFillColor

| **Section**    | **Description**                                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Set the fill color of the 2D shapes on a device symbol                                                                             |
| **Parameters** | <p><strong>name</strong> (<em>str</em>) – device name<br><strong>colorHexRGB</strong> (<em>str</em>) – RGB color in hex values</p> |
| **Returns**    | Error value (int)                                                                                                                  |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                     |

### **Example Usage**

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

```python
HyWorksApi.setDeviceFillColor('Tr2', 'ff0000')
```

{% endcode %}

## Function: setDeviceLineColor

| **Section**    | **Description**                                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Set the color of the line segments on a device symbol                                                                              |
| **Parameters** | <p><strong>name</strong> (<em>str</em>) – device name<br><strong>colorHexRGB</strong> (<em>str</em>) – RGB color in hex values</p> |
| **Returns**    | Error value (int)                                                                                                                  |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                     |

### **Example Usage**

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

```python
HyWorksApi.setDeviceLineColor('Tr2', 'ff0000')
```

{% endcode %}

## Function: setDevicesAttributeVisibility

| **Section**    | **Description**                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Action**     | Hide/Show devices name in the model.                                                                                                       |
| **Parameters** | <p><strong>deviceList</strong> (<em>list\[str]</em>) – list of devices name<br><strong>isVisible</strong> (<em>bool</em>) – visibility</p> |
| **Returns**    | Error value (int)                                                                                                                          |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                             |

### **Example Usage**

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

```python
HyWorksApi.setDevicesAttributeVisibility(['F18/CB4', 'F19/CB4', 'Dec1', 'Dec2', 'F1'], "Name", False)
HyWorksApi.setDevicesAttributeVisibility(['MyPage'], "PageRef", False)
```

{% endcode %}

## Function: setDevicesNameVisibility

| **Section**    | **Description**                                                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Hide/Show devices name in the model.                                                                                                      |
| **Parameters** | <p><strong>deviceList</strong> (<em>list\[str]</em>) – list of devices name<br><strong>isVisible</strong> (<em>str</em>) – visibility</p> |
| **Returns**    | Error value (int)                                                                                                                         |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                            |

### **Example Usage**

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

```python
HyWorksApi.setDevicesNameVisibility(['F18/CB4', 'F19/CB4', 'Dec1', 'Dec2', 'F1'], False)
```

{% endcode %}

## Function: setPinPhaseNumber

| **Section**    | **Description**                                                                                                                                                                                                            |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | <p>Forces a power flexible pin to take a specific amount of phase.<br>Normally, power flexible pins will use the same amount of phases for each power pin of the device. This call allows to disconnect this behavior.</p> |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – device name<br><strong>pinName</strong> (<em>str</em>) – pin name<br><strong>value</strong> (<em>int</em>) – 1 or 3</p>                                                    |
| **Returns**    | Error value (int)                                                                                                                                                                                                          |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                                                                                                             |

## Function: setSignalLineColor

| **Section**    | **Description**                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Set the line color of a signal                                                                                                           |
| **Parameters** | <p><strong>signalName</strong> (<em>str</em>) – device name<br><strong>colorHexRGB</strong> (<em>str</em>) – RGB color in hex values</p> |
| **Returns**    | Error value (int)                                                                                                                        |
| **Raises**     | **AssertionError** – Raises exception on error                                                                                           |

### **Example Usage**

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

```python
HyWorksApi.setSignalLineColor('WED7', 'ff0000')
```

{% endcode %}

## Function: setSignalLineWidth

| **Section**    | **Description**                                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Action**     | Set the line width of a signal                                                                                   |
| **Parameters** | <p><strong>signalName</strong> (<em>str</em>) – device name<br><strong>width</strong> (<em>int</em>) – width</p> |
| **Returns**    | Error value (int)                                                                                                |
| **Raises**     | **AssertionError** – Raises exception on error                                                                   |

### **Example Usage**

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

```python
HyWorksApi.setSignalLineWidth('WED7', 4)
```

{% endcode %}

## Function: setSubcircuitScripts

| **Section**    | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Configure the scripts of a subcircuit component.                                                                                                                                                                                                                                                                                                                                                                                              |
| **Parameters** | <p><strong>compName</strong> (<em>str</em>) – Subcircuit component name.<br><strong>initialValues</strong> (<em>str</em>) – Initial values script.<br><strong>rules</strong> (<em>str</em>) – Rules script.<br><strong>variablesToTransmit</strong> (<em>list\[str]</em>) – List of variable names to transmit to the subcircuit.<br><strong>evaluateOnly</strong> (<em>bool</em>) – If True, evaluate the scripts without applying them.</p> |
| **Returns**    | Error value. (int)                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Raises**     | None                                                                                                                                                                                                                                                                                                                                                                                                                                          |

## Function: unbindUCMFromLibrary

| **Section**    | **Description**                                                    |
| -------------- | ------------------------------------------------------------------ |
| **Action**     | Unbind a UCM device from its library.                              |
| **Parameters** | **deviceName** (*str*) – UCM device name (as shown in the design). |
| **Returns**    | True if the operation succeeded, False otherwise. (bool)           |
| **Raises**     | None                                                               |

## Function: updateUCM

| **Section**    | **Description**                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Action**     | Update a UCM device.                                                                                                            |
| **Parameters** | <p><strong>deviceName</strong> (<em>str</em>) – UCM device name (as shown in the design)<br><strong>ucmPath</strong> (\*str</p> |
| **Returns**    | True if the update succeeded, False otherwise (bool)                                                                            |
| **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/device.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.
