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

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