Documentation Home Page ◇ HYPERSIM Home Page
Pour la documentation en FRANÇAIS, utilisez l'outil de traduction de votre navigateur Chrome, Edge ou Safari. Voir un exemple.

HyWorksApi Commands

Owned by Victoria Bruny
Last updated: Nov 06, 2024 by Maxime Josse

General

closeHyperWorks():

HyWorksApiGRPC.closeHyperWorks()

Close HyperWorks

Examples:

  • HyWorksApi.closeHyperWorks()

closeLibrary(libraryPath):

HyWorksApiGRPC.closeLibrary(libraryPath)

close a CLF library located at the specified ‘libraryPath’.

Parameters:

libraryPath (str) – The path to the CLF library to be closed.
Returns:

True if the library was successfully closed; False otherwise.
Return type:

bool

connectToHyWorks(host=socket.gethostname(), register=getpass.getuser(), timeout=120000, id=None):

HyWorksApiGRPC.connectToHyWorks(host=socket.gethostname(), register=getpass.getuser(), timeout=120000, id=None)

Connect HyJavaApi to HYPERSIM

Parameters:

  • host (str) – computer name

  • register (str) – user name

  • timeout (int) – timeout for function

  • id (int) – Hyworks index to register to
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

disableHyWorksApiExceptions():

HyWorksApiGRPC.disableHyWorksApiExceptions()

Disable HyWorksApi from returning ScopeView exceptions through Python

enableHyWorksApiExceptions():

HyWorksApiGRPC.enableHyWorksApiExceptions()

Enable HyWorksApi to return HYPERSIM exceptions through Python

getCurrentDesign():

HyWorksApiGRPC.getCurrentDesign()

getProperties():

HyWorksApiGRPC.getProperties()

Get current HYPERSIM general properties

Returns:

HYPERSIM general properties
Return type:

str

getProperty(key):

HyWorksApiGRPC.getProperty(key)

Get HYPERSIM property Refer to the following page of the documentation to find the properties names:

Parameters:

key (str) – property key
Returns:

HYPERSIM property
Return type:

str
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.getProperty(“hyworks.hysim.extraTimeout”)

getVersion(long=False) :

HyWorksApiGRPC.getVersion(long=False)

Get the current HYPERSIM version name

Parameters:

long (bool) – Add ‘’ prefix, which is necessary for certain compatibility usage
Returns:

HYPERSIM version
Return type:

str

openLibrary(libraryPath, visible=True):

HyWorksApiGRPC.openLibrary(libraryPath, visible=True)

opens a CLF library located at the specified ‘libraryPath’.

Parameters:

  • libraryPath (str) – The path to the CLF library to be opened.

  • visible (bool) – (Optional) A boolean indicating whether the library should be opened in a visible state (default is True).
Returns:

True if the library was successfully opened; False otherwise.
Return type:

bool

setProperty(key, value, save=False):

HyWorksApiGRPC.setProperty(key, value, save=False)

Set HYPERSIM general property Refer to the following page of the documentation to find the properties names:

Parameters:

  • key (str) – property key

  • value (str) – property value

  • save (bool) – save preferences for the next session
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.setProperty(“hyworks.hysim.extraTimeout”, “1200000”)

  • HyWorksApi.setProperty(“hyworks.hysim.extraTimeout”, “1800000”, True)

startAndConnectHypersim(host=socket.gethostname(), register=getpass.getuser(), stdout=None, stderr=None:

startHyperWorks(stdout=None, stderr=None):

HyWorksApiGRPC.startHyperWorks(stdout=None, stderr=None)

Start HYPERSIM

Parameters:

  • stdout – standard output

  • stderr – standard error

Examples:

  • HyWorksApi.startHyperWorks()

Design

closeDesign(designPath):

HyWorksApiGRPC.closeDesign(designPath)

Close design

Parameters:

designPath (str) – path to the HYPERSIM model (.ecf)
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

disconnectDesign(designPath):

HyWorksApiGRPC.disconnectDesign(designPath)

Disconnect HyWorksApi from the HYPERSIM model

Parameters:

designPath (str) – path to the HYPERSIM model (.ecf)
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

findMinimalStepSize(timeout, overrunsThreshold: int, nCores=100, startingTimeStep=1e-6, jump=1e-6):

HyWorksApiGRPC.findMinimalStepSize(timeout, overrunsThreshold: int, nCores=100, startingTimeStep=1e-6, jump=1e-6)

Determines the smallest possible time step that prevents exceeding a specified number of overruns. This function requires Dashboards to be enabled beforehand. It attempts to start and stop the simulation in each iteration while staying within the overrun limit, ensuring the number of overruns does not reach the threshold. If the simulation completes before reaching the specified timeout, the time step is incremented by the given jump value. The minimal time step is identified when the simulation completes without timing out.

Parameters:

  • timeout (float) – Maximum allowed simulation iteration time in seconds.

  • overrunsThreshold – The maximum number of overruns per iteration that must not be reached, for example,

setting it to 1 means the program will iterate if the current simulation iteration experiences at least one overrun. Note that the threshold must be greater than 0. :type overrunsThreshold: int :param nCores: Number of processor cores to use (Default: 100). If the specified number exceeds available hardware cores, all available cores will be used. A value of 0 enables automatic core assignment. :type nCores: int :param startingTimeStep: Initial time step in seconds (Default: 1 microsecond) :type startingTimeStep: float :param jump: Increment for the time step in seconds (Default: 1 microsecond) :type jump: float :return: The minimal time step in seconds, or None if unsuccessful :rtype: float :raises AssertionError: raises exception on error

getAllComponentDescriptions():

HyWorksApiGRPC.getAllComponentDescriptions()

getAllComponentParameters(compName):

HyWorksApiGRPC.getAllComponentParameters(compName)

getAllComponentSensors(compName):

HyWorksApiGRPC.getAllComponentSensors(compName)

getAllDevicesNames():

HyWorksApiGRPC.getAllDevicesNames()

Gets the list of all devices names

Returns:

the list of all visible devices
Return type:

list
Raises:

AssertionError – raises exception on error

This call requires an analyze call before to function properly

getDesignPrefs():

HyWorksApiGRPC.getDesignPrefs()

Get current model preferences

Returns:

model preferences
Return type:

str

importEDD(eddFilePath, doConnections):

HyWorksApiGRPC.importEDD(eddFilePath, doConnections)

Import EDD to current HYPERSIM model

Parameters:

  • eddFilePath (str) – path to EDD (.edd)

  • doConnections (bool) – connect imported devices
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

importPSCAD(filePath, onlyDll, removeNotConnectedBuses=False):

HyWorksApiGRPC.importPSCAD(filePath, onlyDll, removeNotConnectedBuses=False)

importPSSE(filePath, replaceMachines=False, groupMachinesWithControls=True):

HyWorksApiGRPC.importPSSE(filePath, replaceMachines=False, groupMachinesWithControls=True)

importPowerFactory(filePath, mode=0):

HyWorksApiGRPC.importPowerFactory(filePath, mode=0)

Import PowerFactory

Parameters:

  • filePath (str) – path to PowerFactory file (.xml)

  • mode (int) – select switch import mode (Default: 0): 0 (All switches are removed), 1 (All switches are added), 2 (Only switches with events are added)
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

newDesign(designFilePath=None):

HyWorksApiGRPC.newDesign(designFilePath=None)

Create new HYPERSIM model

Parameters:

designFilePath (str) – path to the HYPERSIM model (.ecf)
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

openDesign(designPath):

HyWorksApiGRPC.openDesign(designPath)

Open HYPERSIM model

Parameters:

designPath (str) – path to HYPERSIM model (.ecf)
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

recheckPorts():

HyWorksApiGRPC.recheckPorts()

Check connections by page connectors Recommended after build circuits involving page connectors via API

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

saveDesign():

HyWorksApiGRPC.saveDesign()

Save current HYPERSIM model

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

saveDesignAs(fileName):

HyWorksApiGRPC.saveDesignAs(fileName)

Save current HYPERSIM model

Parameters:

fileName (str) – desired model path
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

updateEDD(eddFilePath, doConnections):

HyWorksApiGRPC.updateEDD(eddFilePath, doConnections)

Update EDD

Parameters:

  • eddFilePath (str) – path to EDD (.edd)

  • doConnections (bool) – connect imported devices
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Device

activateObservables(deviceName, observables):

HyWorksApiGRPC.activateObservables(deviceName, observables)

Activate a list of observable pins on the device

Parameters:

  • deviceName (str) – name of the first device

  • observables (list[str]) – 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
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.activateObservables(‘Imeas1’, [‘a’, ‘b’])

  • HyWorksApi.activateObservables(‘Imeas1’, [])

addBus1ph(signalName, points, hitCheck=False, subcircuit=None):

HyWorksApiGRPC.addBus1ph(signalName, points, hitCheck=False, subcircuit=None)

Add a 1 phase bus to HYPERSIM model.

Parameters:

  • signalName (str) – signal name

  • points (list[list[int]]) – list of points as X-Y coordinates

  • hitCheck (bool) – true to check for connections to other signals at both ends of the line

  • subcircuit (str) – subcircuit path
Returns:

unique signal name
Return type:

str

Examples:

  • HyWorksApi.addBus1ph(‘myBus’, [[-700, 0], [700, 0]])

until connected to a power pin, a 1 phase bus is considered a control signal

addBus3ph(signalName, points, hitCheck=False, subcircuit=None):

HyWorksApiGRPC.addBus3ph(signalName, points, hitCheck=False, subcircuit=None)

Add a 3 phase bus to HYPERSIM model

Parameters:

  • signalName (str) – signal name

  • points (list[list[int]]) – list of points as X-Y coordinates

  • hitCheck (bool) – true to check for connections to other signals at both ends of the line.

  • subcircuit (str) – subcircuit path
Returns:

unique signal name
Return type:

str

Examples:

  • HyWorksApi.addBus3ph(‘myBus’, [[-700, 0], [700, 0]])

addControlSignal(signalName, points, hitCheck=False, subcircuit=None):

HyWorksApiGRPC.addControlSignal(signalName, points, hitCheck=False, subcircuit=None)

Add a control signal to HYPERSIM model

Parameters:

  • signalName (str) – signal name

  • points (list[list[int]]) – list of points as X-Y coordinates

  • hitCheck (bool) – true to check for connections to other signals at both ends of the line.

  • subcircuit (str) – subcircuit path
Returns:

unique signal name
Return type:

str

Examples:

  • HyWorksApi.addControlSignal(‘signal1’, [[-700, 0], [700, 0], [700, 700])

addDevice(libName, blocName, coordX=0, coordY=0, page=1, subcircuit=None, name=None):

HyWorksApiGRPC.addDevice(libName, blocName, coordX=0, coordY=0, page=1, subcircuit=None, name=None)

Add device to HYPERSIM model

Parameters:

  • libName (str) – device library name

  • blocName (str) – device name

  • coordX (int) – X coordinate

  • coordY (int) – Y coordinate

  • page (int) – page number

  • subcircuit (str) – subcircuit path

  • name (str) – Name to assign to the device. If non, a default name will be assigned
Returns:

unique device name, reusable in the other APIs
Return type:

str

Examples:

  • HyWorksApi.addDevice(‘Network RLC.clf’, ‘R grounded’, 700, 700)

  • HyWorksApi.addDevice(‘Network RLC.clf’, ‘R grounded’, 700, 700, 1, “MySubCircuit”, “Resistor1”)

The library name must include the .clf for this to work.

addPinsToDevice(name, cardinalPoint, function, pins, redraw=False):

HyWorksApiGRPC.addPinsToDevice(name, cardinalPoint, function, pins, redraw=False)

Add pins, bundles, or pins inside bundles on a device

Parameters:

  • name (str) – device name

  • cardinalPoint (str) – Location on the symbol of the device

  • function (str) – The function of the listed pins. Input, Output or Power

  • pins (list[str]) – List of pins

  • redraw (bool) – if True, the symbol will be redrawn with a default representation
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • 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]’)

connectBundleToBundle(blocA, signalListA, blocB, signalListB):

HyWorksApiGRPC.connectBundleToBundle(blocA, signalListA, blocB, signalListB)

Connect two bundle pins together

Parameters:

  • blocA (str) – name of the first device

  • signalListA (list[str]) – list of first bundle signals. ex: [‘a’,’b’,’c’]

  • blocB (str) – name of the first pin

  • signalListB (list[str]) – list of second bundle signals. ex: [‘a’,’b’,’c’]
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

connectDeviceToBus1ph(deviceName, pinName, signalName):

HyWorksApiGRPC.connectDeviceToBus1ph(deviceName, pinName, signalName)

Connects a device onto 1 phase bus

Parameters:

  • deviceName (str) – device name

  • pinName (str) – device pin name

  • signalName (str) – signal name
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.connectDeviceToBus1ph(‘R1’, ‘net_1’, ‘myBus’)

  • HyWorksApi.connectDeviceToBus1ph(‘SubCC1/SubSubCC1/R3’, ‘net_1’, ‘myBus’)

connectDeviceToBus3ph(deviceName, pinName, signalName):

HyWorksApiGRPC.connectDeviceToBus3ph(deviceName, pinName, signalName)

Connects a device onto 3 phase bus

Parameters:

  • deviceName (str) – device name

  • pinName (str) – device pin name

  • signalName (str) – signal name
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.connectDeviceToBus3ph(‘R1’, ‘net_1’, ‘myBus’)

  • HyWorksApi.connectDeviceToBus3ph(‘SubCC1/SubSubCC1/R3’, ‘net_1’, ‘myBus’)

connectDeviceToControlSignal(deviceName, pinName, signalName):

HyWorksApiGRPC.connectDeviceToControlSignal(deviceName, pinName, signalName)

Connects a device onto a control signal

Parameters:

  • deviceName (str) – device name

  • pinName (str) – device pin name

  • signalName (str) – signal name
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.connectDeviceToControlSignal(‘Const1’, ‘y’, ‘s1’)

connectDevices(blocA, pinA, blocB, pinB, isThreePhaseAndPowerFlexible, signalName=None):

HyWorksApiGRPC.connectDevices(blocA, pinA, blocB, pinB, isThreePhaseAndPowerFlexible, signalName=None)

Connect two device pins

Parameters:

  • blocA (str) – name of the first device

  • pinA (str) – name of the first pin

  • blocB (str) – name of the second device

  • pinB (str) – name of the second pin

  • isThreePhaseAndPowerFlexible (bool) – make the connection 3 phase, for components which can be both 1 phase or 3 phases

  • signalName (str) – new signal name on the connection
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.connectDevices(‘Max1’, ‘y’, ‘mySubCircuit’, ‘a1’, False)

  • HyWorksApi.connectDevices(‘mySubCircuit/B1’, ‘a1’, ‘mySubCircuit/Gain1’, ‘u’, False)

connectPinToBundle(blocA, pinA, blocB, signalListB):

HyWorksApiGRPC.connectPinToBundle(blocA, pinA, blocB, signalListB)

Connect a pin to a bundle’s signal

Parameters:

  • blocA (str) – name of the first device

  • pinA (str) – pin name

  • blocB (str) – name of the second device

  • signalListB (str) – bundle signal name
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

createSubCircuit(name, subType, coordX=0, coordY=0, page=1):

HyWorksApiGRPC.createSubCircuit(name, subType, coordX=0, coordY=0, page=1)

Create a subcircuit with the specified ‘name’ and ‘subType’ at the given coordinates on the specified page.

Parameters:

  • name (str) – subcircuit definition name

  • subType (str) – subcircuit type name. This name will show when redrawing the device

  • coordX (int) – X coordinate

  • coordY (int) – Y coordinate

  • page (int) – page number
Returns:

unique device name
Return type:

str

Examples:

  • HyWorksApi.createSubCircuit(‘Subcircuit1’, 700, 700, 1)

  • HyWorksApi.createSubCircuit(‘Subcircuit1’, ‘THD’, 700, 700,1)

  • HyWorksApi.createSubCircuit(‘DEV1/Subsubcircuit1’)

disconnectPin(deviceName, pinName, removeAllConnections=False):

HyWorksApiGRPC.disconnectPin(deviceName, pinName, removeAllConnections=False)

Disconnects the signal from a pin

Parameters:

  • deviceName (str) – device name

  • pinName (str) – pinName

  • removeAllConnections (bool) – if True, also disconnects the pins of the connected devices, effectively removing completely the line connection of the design
Returns:

error value
Return type:

bool

Examples:

  • HyWorksApi.disconnectPin(‘Cons1’, ‘y’)

  • HyWorksApi.disconnectPin(‘RC1’, ‘net_1’, True)

displayComponent(componentName, printAttributes=True, printSignals=True, printConnectors=True:

displayConnections(componentName):

HyWorksApiGRPC.displayConnections(componentName)

Print specified component interconnections to STDOUT

Parameters:

componentName (str) – component name
Returns:

error value
Return type:

str
Raises:

AssertionError – raises exception on error

flipHorizontallyDevice(deviceName, keepConnections=True):

HyWorksApiGRPC.flipHorizontallyDevice(deviceName, keepConnections=True)

Flips a device horizontally

Parameters:

  • deviceName (str) – device name

  • keepConnections (bool) – true if pin connections should be kept
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.flipHorizontallyDevice(‘R1’)

flipVerticallyDevice(deviceName, keepConnections=True):

HyWorksApiGRPC.flipVerticallyDevice(deviceName, keepConnections=True)

Flips a device vertically

Parameters:

  • deviceName (str) – device name

  • keepConnections (bool) – true if pin connections should be kept
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.flipVerticallyDevice(‘R1’)

getComponentParameter(compName, compParam):

HyWorksApiGRPC.getComponentParameter(compName, compParam)

Retrieve component parameter value

Parameters:

  • compName (str) – component name

  • compParam (str) – component parameter
Returns:

a list of 2 str, the first one being the value and the second one being the unit
Return type:

list[str]
Raises:

AssertionError – raises exception on error

getCoordinates(deviceName, pinName=None):

HyWorksApiGRPC.getCoordinates(deviceName, pinName=None)

Retrieve the X-Y coordinates of a device or its pin

Parameters:

  • deviceName (str) – device name

  • pinName (str) – pin name, can be non if only the position of the device is required
Returns:

Returns a list of 2 int, representing the (X, Y) coordinates
Return type:

list[int]
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.getCoordinates(‘R1’)

  • HyWorksApi.getCoordinates(‘MTL’, ‘baseVolt’)

getDeviceBundleChildPins(deviceName, pinName):

HyWorksApiGRPC.getDeviceBundleChildPins(deviceName, pinName)

Retrieve the list of all children pin names in a bundle pin of a device

Parameters:

  • deviceName (str) – device name

  • pinName (str) – bundle pin name
Returns:

the list of the sub-pin names
Return type:

list[str]
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.getDeviceBundleChildPins(‘AC1A_1’, ‘In’)

getDeviceBundlePins(deviceName):

HyWorksApiGRPC.getDeviceBundlePins(deviceName)

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
Return type:

list[str]
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.getDeviceBundlePins(‘AC1A_1’)

getDevicePinTypes(deviceName: str, pinNames: list):

HyWorksApiGRPC.getDevicePinTypes(deviceName: str, pinNames: list)

Retrieve the type (function) of certain pins on a device

Parameters:

  • deviceName (list<str>) – device name

  • pinNames – pin names
Returns:

list of types in the same order of pins requested. I = Input, O = Output, P = Power, S = Bundle
Return type:

list[str]
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.getDevicePinTypes(‘POW1’, [‘A’, ‘P’, ‘net_1’])

importUCM(defFilePath):

HyWorksApiGRPC.importUCM(defFilePath)

Import UCM to current HYPERSIM model

Parameters:

defFilePath (str) – path to UCM (… py: function: : )
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

includeDevice(deviceName, include):

HyWorksApiGRPC.includeDevice(deviceName, include)

Include or exclude a device in HYPERSIM model

Parameters:

  • deviceName (str) – device name

  • include (bool) – true if device should be included, false if excluded
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

removeDevice(deviceName):

HyWorksApiGRPC.removeDevice(deviceName)

Remove device from model

Parameters:

deviceName (str) – device name
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

renameDevice(oldDeviceName, newDeviceName):

HyWorksApiGRPC.renameDevice(oldDeviceName, newDeviceName)

Rename a device inside the model

Parameters:

  • oldDeviceName (str) – old device name

  • newDeviceName (str) – new device name
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.renameDevice(‘DEV1’, ‘SubCircuit1’)

  • HyWorksApi.renameDevice(‘SubCircuit1/Gain1’, ‘SubCircuit1/factor’)

renameSignal(oldName, newName, visible=True):

HyWorksApiGRPC.renameSignal(oldName, newName, visible=True)

Rename all signals sharing a name inside the model

Parameters:

  • oldName (str) – old signal name

  • newName (str) – new signal name

  • visible (bool) – if name should be visible on the design
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

rotateLeftDevice(deviceName, keepConnections=True):

HyWorksApiGRPC.rotateLeftDevice(deviceName, keepConnections=True)

Rotates a device to the left

Parameters:

  • deviceName (str) – device name

  • keepConnections (bool) – true if pin connections should be kept
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.rotateLeftDevice(‘R1’)

rotateRightDevice(deviceName, keepConnections=True):

HyWorksApiGRPC.rotateRightDevice(deviceName, keepConnections=True)

Rotates a device to the right

Parameters:

  • deviceName (str) – device name

  • keepConnections (bool) – true if pin connections should be kept
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.rotateRightDevice(‘R1’)

setComponentParameter(compName, compParam, value):

HyWorksApiGRPC.setComponentParameter(compName, compParam, value)

Set a component parameter to a certain value

Parameters:

  • compName (str) – component name

  • compParam (str) – component parameter

  • value (str) – component value
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

setComponentParameters(compNames, compParams, values):

HyWorksApiGRPC.setComponentParameters(compNames, compParams, values)

Set multiple component parameters to specified values

Parameters:

  • compNames (list of str) – list of component names

  • compParams (list of str) – list of component parameters

  • values (list of str) – list of component values
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.setComponentParameters([“comp1”, “comp2”], [“param1”, “param2”], [“value1”, “value2”])

setDeviceFillColor(name, colorHexRGB):

HyWorksApiGRPC.setDeviceFillColor(name, colorHexRGB)

Set the fill color of the 2D shapes on a device symbol

Parameters:

  • name (str) – device name

  • colorHexRGB (str) – RGB color in hex values
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.setDeviceFillColor(‘Tr2’, ‘ff0000’)

setDeviceLineColor(name, colorHexRGB):

HyWorksApiGRPC.setDeviceLineColor(name, colorHexRGB)

Set the color of the line segments on a device symbol

Parameters:

  • name (str) – device name

  • colorHexRGB (str) – RGB color in hex values
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.setDeviceLineColor(‘Tr2’, ‘ff0000’)

setDevicesNameVisibility(deviceList, isVisible):

HyWorksApiGRPC.setDevicesNameVisibility(deviceList, isVisible)

Hide/Show devices name in the model.

Parameters:

  • deviceList (list[str]) – list of devices name

  • isVisible (str) – visibility
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.setDevicesNameVisibility([‘F18/CB4’, ‘F19/CB4’, ‘Dec1’, ‘Dec2’, ‘F1’], False)

setPinPhaseNumber(deviceName, pinName, value):

HyWorksApiGRPC.setPinPhaseNumber(deviceName, pinName, value)

Forces a power flexible pin to take a specific amount of phase. 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.

Parameters:

  • deviceName (str) – device name

  • pinName (str) – pin name

  • value (int) – 1 or 3
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

setSignalLineColor(signalName, colorHexRGB):

HyWorksApiGRPC.setSignalLineColor(signalName, colorHexRGB)

Set the line color of a signal

Parameters:

  • signalName (str) – device name

  • colorHexRGB (str) – RGB color in hex values
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.setSignalLineColor(‘WED7’, ‘ff0000’)

setSignalLineWidth(signalName, width):

HyWorksApiGRPC.setSignalLineWidth(signalName, width)

Set the line width of a signal

Parameters:

  • signalName (str) – device name

  • width (int) – width
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.setSignalLineWidth(‘WED7’, 4)

setSubcircuitScripts(compName, initialValues, rules, variablesToTransmit, evaluateOnly=False):

HyWorksApiGRPC.setSubcircuitScripts(compName, initialValues, rules, variablesToTransmit, evaluateOnly=False)

unbindUCMFromLibrary(deviceName):

HyWorksApiGRPC.unbindUCMFromLibrary(deviceName)

updateUCM(deviceName, ucmPath=None):

HyWorksApiGRPC.updateUCM(deviceName, ucmPath=None)

Update UCM

Parameters:

deviceName (str) – UCM name
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Sensor

editSensor(blocName, sensorName, IOType=None, IONumber=None, base=None, unit=None):

HyWorksApiGRPC.editSensor(blocName, sensorName, IOType=None, IONumber=None, base=None, unit=None)

Edit device sensor

Parameters:

  • blocName (str) – device name

  • sensorName (str) – sensor name

  • IOType (str) – IO Type. ex: AD, DA, DI or DO

  • IONumber (int) – IO number

  • base (float) – base value

  • unit (str) – unit value
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.editSensor(‘R1’, ‘Ia’, 1.0, ‘pu’, ‘DA’, 1001)

  • HyWorksApi.editSensor(‘R1’, ‘Ia’, base = 1.0, unit = ‘pu’)

  • HyWorksApi.editSensor(‘R1’, ‘Ia’, IOType = ‘DA’, IONumber = 1001)

getLastSensorValues(sensorNames):

HyWorksApiGRPC.getLastSensorValues(sensorNames)

Gets the last current value of a list of sensors while simulation is running

Parameters:

sensorNames (list[str]) – list of sensor names as string
Returns:

values in the same order as the sensor names
Return type:

list[float]
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.getLastSensorValues([‘Const1.y’, ‘Subcircuit1/Gain1.u’, “/Subcircuit1/R15.Ia”])

getSensorInfo(blocName, sensorName, key):

HyWorksApiGRPC.getSensorInfo(blocName, sensorName, key)

Get value for the specified key on the specified sensor

Parameters:

  • blocName (str) – device name

  • sensorName (str) – sensor name

  • key (str) – key in sensor inf.
Supported keys:

  • ‘selected’

  • ‘userName’

  • ‘userUnit’

  • ‘iotype’

  • ‘ionum’

  • ‘iofactor’

  • ‘base’

  • ‘dataLoggerRecord’

  • ‘dataLoggerGroup’

  • ‘dataLoggerTrigger’

  • ‘exchangerTag’

  • ‘dataPointName’

  • ‘dataPointIndex’

Returns:

value of the specified key
Return type:

str

getSensorsValues(sensorNames: List[str], timeLength, timeStart=0, acquisitionRate=Non:

loadSensors(filePath):

HyWorksApiGRPC.loadSensors(filePath)

Load sensor file to current model

Parameters:

filePath (str) – path to sensor file (.sig, .csv)
Returns:

error value
Return type:

bool
Raises:

AssertionError – raises exception on error

selectAllSensors(blocName):

HyWorksApiGRPC.selectAllSensors(blocName)

Select all sensors for device

Parameters:

blocName (str) – device name
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

selectSensor(blocName, sensorName, selected=True):

HyWorksApiGRPC.selectSensor(blocName, sensorName, selected=True)

Select device sensor

Parameters:

  • blocName (str) – device name

  • sensorName (str) – sensor name

  • selected (bool) – selected
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

setSensorDataLogger(blocName, sensorName, record, groupName, trigger):

HyWorksApiGRPC.setSensorDataLogger(blocName, sensorName, record, groupName, trigger)

Set sensor parameter through datapoints

Parameters:

  • blocName (str) – device name

  • sensorName (str) – sensor name

  • record (bool) – record signal

  • groupName (str) – signal group name

  • trigger (bool) – set signal as trigger for the group
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.setSensorDataLogger(‘sine1’, ‘y’, True, ‘SIGNAL_GROUP_1’, False)

  • HyWorksApi.setSensorDataLogger(‘sine2’, ‘y’, True, ‘SIGNAL_GROUP_2’, True)

  • HyWorksApi.setSensorDataLogger(‘sine3’, ‘y’, False, ‘SIGNAL_GROUP_3’, False)

setSensorDataPoint(blocName, sensorName, exchangerTag, dataPointName, dataPointIdx):

HyWorksApiGRPC.setSensorDataPoint(blocName, sensorName, exchangerTag, dataPointName, dataPointIdx)

Set sensor parameter through datapoints

Parameters:

  • blocName (str) – device name

  • sensorName (str) – sensor name

  • exchangerTag (str) – exchanger tag

  • dataPointName (str) – data point name

  • dataPointIdx (str) – data point index
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.setSensorDataPoint(‘Const_Amplitude’, ‘y’, ‘Signal Generator’, ‘Sine Waves/Sine Wave 1/Amplitude’, ‘0’)

  • HyWorksApi.setSensorDataPoint(‘Const_Frequency’, ‘y’, ‘Signal Generator’, ‘Sine Waves/Sine Wave 1/Frequency’, ‘0’)

  • HyWorksApi.setSensorDataPoint(‘Gain’, ‘u’, ‘Signal Generator’, ‘Sine Waves/Sine Wave 1/Output’, ‘0’)

Settings

analyze():

HyWorksApiGRPC.analyze()

Analyse

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

buildTopology():

HyWorksApiGRPC.buildTopology()

Build topology

Returns:

error value
Return type:

int

clearCodeDir():

HyWorksApiGRPC.clearCodeDir()

Clear code directory

Returns:

error value
Return type:

int

genCode():

HyWorksApiGRPC.genCode()

Generate code

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

getLoadFlowReport() :

HyWorksApiGRPC.getLoadFlowReport()

Get the load-flow report (BETA: this feature is subject to improvements in the upcoming versions)

Returns:

HYPERSIM load-flow report
Return type:

LoadflowReport

getPreference(prefName):

HyWorksApiGRPC.getPreference(prefName)

Retrieve a model preference Refer to the following pages of the documentation to find the preference names:

Parameters:

prefName (str) – preference name
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

mapTask():

HyWorksApiGRPC.mapTask()

Map tasks

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

setPreference(prefName, value):

HyWorksApiGRPC.setPreference(prefName, value)

Set a model preference to a specific value Refer to the following pages of the documentation to find the preference names:

Parameters:

  • prefName (str) – preference name

  • value (str) – preference value
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

setTarget(hostname, mode=None):

HyWorksApiGRPC.setTarget(hostname, mode=None)

Set simulation target

Parameters:

  • hostname (str) – target IP

  • mode (str) – simulation mode. Options: - Offline (RTA): nrt_optimized - Offline (PMI) : nrt_mpi - Real-time : rt
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

startLoadFlow():

HyWorksApiGRPC.startLoadFlow()

Load flow

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Simulation

getMonitoringAllValues():

HyWorksApiGRPC.getMonitoringAllValues()

Get the current value of all monitors during simulation

Returns:

a dictionary where the key is the monitor name, and the value is the current value
Return type:

dict[str, str]
Raises:

AssertionError – raises exception on error

getMonitoringValue(monitorName):

HyWorksApiGRPC.getMonitoringValue(monitorName)

Get the current value of a monitor during simulation

Parameters:

monitorName (str) – Name of the monitor
Returns:

value
Return type:

str
Raises:

AssertionError – raises exception on error

Examples:

  • HyWorksApi.getMonitoringValue(‘MyMonitor1’)

getPreparationTimings(modelPath: str = None) :

HyWorksApiGRPC.getPreparationTimings(modelPath: str = None)

Get the timings of the preparation phase of the current or provided model. The preparation phase includes the topology build, analysis, load flow, task mapping, code generation, simulation start and simulation stop.

Parameters:

modelPath (str) – path to the model file (Default: Currently opened model)
Returns:

An object containing the performance information
Return type:

SimulationPreparationTimingsInfo

getSimulationCoreTimings(modelPath: str = None) :

HyWorksApiGRPC.getSimulationCoreTimings(modelPath: str = None)

Get the core timings of the current or provided model. This function gives the timings of the steps that occur during the simulation for each core.

Parameters:

modelPath (str) – path to the model file (Default: Currently opened model)
Returns:

A list of objects containing the core timings
Return type:

list[SimulationCoreTimingsInfo]

getSimulationTime():

HyWorksApiGRPC.getSimulationTime()

Get the current simulation time, in the unit of the Point-On-Wave

Returns:

value
Return type:

float
Raises:

AssertionError – raises exception on error

getSimulationTimings(modelPath: str = None) :

HyWorksApiGRPC.getSimulationTimings(modelPath: str = None)

Get the simulation timings of the current or provided model. This function provides the timings for the steps that occur at the start of the simulation and during each subsequent iteration.

Parameters:

modelPath (str) – path to the model file (Default: Currently opened model)
Returns:

An object containing the simulation timings
Return type:

SimulationTimings

loadSnapshot():

HyWorksApiGRPC.loadSnapshot()

Loads a snapshot in the simulation

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

resetMonitoring(cpuList):

HyWorksApiGRPC.resetMonitoring(cpuList)

Reset performance indicators and timings for simulation

Parameters:

cpuList (list[int]) – list of cpu cores to reset. ex: [1, 2, 3, 4] Returns error value
Return type:

int
Raises:

AssertionError – raises exception on error

resetPerfIndic(cpuList):

HyWorksApiGRPC.resetPerfIndic(cpuList)

Reset performance indicators for simulation

Parameters:

cpuList (list[int]) – list of cpu cores to reset. ex: [1, 2, 3, 4] Returns error value
Raises:

AssertionError – raises exception on error

resetTiming(cpuList):

HyWorksApiGRPC.resetTiming(cpuList)

Reset performance timing for simulation

Parameters:

cpuList (list[int]) – list of cpu cores to reset. ex: [1, 2, 3, 4] Returns error value
Return type:

int
Raises:

AssertionError – raises exception on error

simtrig(sync):

HyWorksApiGRPC.simtrig(sync)

Trig the programmable devices in the simulation

Parameters:

sync (bool) – synchronize with POW
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

startMonitoring():

HyWorksApiGRPC.startMonitoring()

Start monitoring

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

startSim():

HyWorksApiGRPC.startSim()

Start simulation

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

stopMonitoring():

HyWorksApiGRPC.stopMonitoring()

Stop monitoring

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

stopSim():

HyWorksApiGRPC.stopSim()

Stop simulation

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

takeSnapshot():

HyWorksApiGRPC.takeSnapshot()

Takes a snapshot of the simulation

Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

Target

addTargetToManager(targetHostName):

HyWorksApiGRPC.addTargetToManager(targetHostName)

Add target to HYPERSIM target manager

Parameters:

targetHostName (str) – target IP
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

diagnosticTarget(targetHostName):

HyWorksApiGRPC.diagnosticTarget(targetHostName)

Prints a diagnostic report of the target configuration.

Parameters:

targetHostName (str) – target IP
Returns:

diagnostic report on the target
Return type:

str

getAllTargetsName():

HyWorksApiGRPC.getAllTargetsName()

Get all known targets by HYPERSIM target manager

Returns:

list of all known targets
Return type:

str

getCurrentVersionOnTarget(targetHostName):

HyWorksApiGRPC.getCurrentVersionOnTarget(targetHostName)

Get current HYPERSIM version on target

Parameters:

targetHostName (str) – target IP
Returns:

HYPERSIM version
Return type:

str

getInstalledVersionOnTarget(targetHostName):

HyWorksApiGRPC.getInstalledVersionOnTarget(targetHostName)

Get all HYPERSIM versions installed on target

Parameters:

targetHostName (str) – target IP
Returns:

list of all HYPERSIM versions
Return type:

str

installHypersimOnTarget(targetHostName):

HyWorksApiGRPC.installHypersimOnTarget(targetHostName)

Install HYPERSIM version on target

Parameters:

targetHostName (str) – target IP
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

isTargetReady(targetHostName):

HyWorksApiGRPC.isTargetReady(targetHostName)

Determine if target is ready for simulation

Parameters:

targetHostName (str) – target IP
Returns:

ready status
Return type:

bool

removeTargetFromManager(targetHostName):

HyWorksApiGRPC.removeTargetFromManager(targetHostName)

Remove target from HYPERSIM target manager

Parameters:

targetHostName (str) – target IP
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

switchVersionOnTarget(targetHostName, switchToVersion):

HyWorksApiGRPC.switchVersionOnTarget(targetHostName, switchToVersion)

Switch HYPERSIM versions on target

Parameters:

  • targetHostName (str) – target IP

  • switchToVersion (str) – HYPERSIM version to switch to
Returns:

error value
Return type:

int
Raises:

AssertionError – raises exception on error

OPAL-RT TECHNOLOGIES, Inc. | 1751, rue Richardson, bureau 1060 | Montréal, Québec Canada H3K 1G6 | opal-rt.com | +1 514-935-2323
Follow OPAL-RT: LinkedIn | Facebook | YouTube | X/Twitter