Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Below is the list of commands for the HYPERSIM® API (windows).

...

Close HYPERSIM

...

Connect HyJavaApi to HYPERSIM

Parameters

  • host (str): computer name
  • register (str): user name
  • timeout (int timeout for function
  • index (int): Hyworks index to register to

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Disable HyWorksApi from returning HYPERSIM exceptions through Python

...

Disable HyWorksApi from returning ScopeView exceptions through Python

Enable HyWorksApi to return HYPERSIM exceptions through Python

enableScopeViewscopeview_ApiExceptions():

Enable HyWorksApi to return ScopeView exceptions through Python

...

Get HYPERSIM property

Parameters :

Returns HYPERSIM property

Return type str

Raises AssertionError: raises exception on error

Examples:

  • HyWorksApi.getProperty("hyworks.hysim.extraTimeout")

...

Returns HYPERSIM properties

Return type str

Set HYPERSIM general property

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)

...

...

Open and connect HyJavaApi to HYPERSIM

Parameters

  • host (str computer name
  • register (str): user name
  • stdout: standard output
  • stderr: standard error
  • timeout (int): timeout for function

Returns error value

Return type int

Raises AssertionError: raises exception on error

startHyperWorks(stdout=None, stderr=None):

Start HYPERSIM

Parameters

  • stdout: standard output
  • stderr: standard error

...

Close design

...

...

...

Returns error value

Return type int

...

...

...

Disconnect HyWorksApi from the HYPERSIM model

...

...

...

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Print component interconnections to STDOUT

Returns error value

Return type int

...

...

...

Get current model preferences

...

Return type str

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

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

Open HYPERSIM model

Parameters designPath (str): path to HYPERSIM model (.ecf)

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Check connections by page connectors

Recommended after build circuits involving page connectors via API

Returns error value

Return type int

...

...

Save current HYPERSIM model

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Save current HYPERSIM model

...

...

Returns error value

Return type int

...

...

...

Parameters

  • eddFilePath (str): path to EDD (.edd)
  • doConnections (bool): connect imported devices

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Activate a list of observable pins on the device

Parameters

  • blocA (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

...

Add a control signal to HYPERSIM model

Parameters

  • signalName(str): signal name
  • points(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

Example :

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

...

Add a 1 phase bus to HYPERSIM model.

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

Parameters

  • signalName(str): signal name
  • points(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

Example :

...

Add a bus to HYPERSIM model

Parameters

  • signalName(str): signal name
  • points(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

Example :

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

...

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

...

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('SubCircuit7', 'S', 'P', ['pow1'], TrueHyWorksApi.addPinsToDevice('SubCircuit1', 'W', 'O', ['Bundle1[o1]', 'Bundle1[o2]', 'Bundle1[o3]'], True)

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

...

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)

...

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

...

Connects a device onto 1 phase bus

...

  • 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')

...

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

...

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

Returns error value

Return type int

...

...

Add device to HYPERSIM model

Parameters

  • name (str): subcircuit definition name
  • type(str): subcircuit type name. This name will show when redrawing the device
  • blocName (str): device name
  • coordX (int): X coordinate
  • coordY (int): Y coordinate
  • page (int): page number

Returns unique device name

Return type str

Examples

...

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)

...

(warning) This call requires an analyze call before to function properly

Print component information to STDOUT, including tunable parameter values, default values, parameter types and connectors By default shows all model components, but a specific component can be given as an argument

Parameters componentName (str): component name

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

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')

...

Flips a device vertically

Parameters

  • deviceName (str): device name
  • keepConnections(bool): true if pin connections should be kept

Returns error value

Return type bool

...

...

Examples

  • HyWorksApi.flipVerticallyDevice('R1')

(warning) This call requires an analyze call before to function properly

Gets the list of all devices names

Returns the list of all visible devices

Return type list

Raises AssertionError: raises exception on error

...

Retrieve a device or its pin X-Y coordinates

Parameters

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

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

Return type list

Raises AssertionError: raises exception on error

Examples

...

(warning) This call requires an analyze call before to function properly

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

...

...

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 of strings

Raises AssertionError: raises exception on error

Examples

  • HyWorksApi.getDeviceBundleChildPins('AC1A_1', 'In')

Retrieve the list of all pin names of type bundle on a device

Parameters

  • deviceName (str): device name

Returns error value

Return type list of strings

Raises AssertionError: raises exception on error

Examples

  • HyWorksApi.getDeviceBundlePins('AC1A_1')

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

...

Include or exclude a device in HYPERSIM model

Parameters

  • deviceName (str): device name
  • (bool true if device should be included, false if excluded

Returns error value

Return type bool

Raises AssertionError: raises exception on error

...

Remove device from model

...

...

...

Return type int

Raises AssertionError: raises exception on error

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')

...

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

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')

...

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')

...

...

...

(warning) This call requires an analyze call before to function properly

Set a component parameter to a certain value

Parameters

  • compName (str): component name
  • compParam (str): component parameter

Returns error value

Return type int

Note : Please refer to Variables and Expressions to see how to set certain expressions via API.

Raises AssertionError: raises exception on error

...

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

Parameters

Returns error value

Return type int

Raises AssertionError: raises exception on error

Examples

  • HyWorksApi.setDeviceFillColor('Tr2', 'ff0000')

...

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')

...

Set the line color of a signal

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.setSignalLineColor('WED7', 'ff0000')

...

Set the line width of a signal

Parameters

  • name(str) device name
  • width(int): width

Returns error value

Return type int

Raises AssertionError: raises exception on error

Examples

...

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)

...

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 behaviour.

Parameters

  • deviceName(str): device name
  • pinName(str): pin name
  • value(int 1 or 3

Returns error value

...

Raises AssertionError: raises exception on error

Update UCM

Parameters deviceName (str): UCM name

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

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)

...

...

Parameters

  • blocName (str device name
  • sensorName (str): sensor name
  • blocName (str): key in sensor info. Supported keys :
    • 'selected'
    • 'userName'
    • 'userUnit'
    • 'iotype'
    • 'ionum'
    • 'iofactor'
    • 'base'
    • 'dataLoggerRecord'
    • 'dataLoggerGroup'
    • 'dataLoggerTrigger'
    • 'exchangerTag'
    • 'dataPointName'
    • 'dataPointIndex'

Return type str

...

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

Returns error value

Return type bool

Raises AssertionError: raises exception on error

Select all sensors for device

Parameters blocName (str): device name

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Set sensor parameter through datapoints

Parameters

  • blocName (str): device name
  • sensorName (str): sensor name
  • exchangerTag (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)

...

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')

...

Select all sensors for device

Parameters blocName (str): device name

Returns error value

Return type int

Raises AssertionError: raises exception on error

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

...

Analyse

Returns error value

Return type int

...

...

Build topology

Returns error value

Return type int

...

Clear code directory

...

Return type int

...

Generate code

Returns error value

Return type int

...

...

Retrieve a model preference

Parameters prefName (str): preference name

Returns error value

Return type int

Raises AssertionError: raises exception on error

Map tasks

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Set a model preference to a specific value

Parameters

  • prefName (str): preference name

Returns error value

Return type int

Raises AssertionError: raises exception on error

Set simulation target

Parameters

...

...

...

...

...

Returns error value

Return type int

Raises AssertionError: raises exception on error

startLoadFlow():

Load flow

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

...

Get the current value of all monitors during simulation

Returns dictionary where the key is the monitor name, and the value is the current value

Return dict[str, str]

...

...

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')

...

Get the last values of the list of sensors during simulation

Parameters

  • sensorNames (list[str]): Names of the sensors

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"])

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

Returns value

Return type float

Raises AssertionError: raises exception on error

...

Loads a snapshot in the simulation

Returns error value

Return type int

...

...

...

Reset performance indicators and timings for simulation

...

...

...

...

Return type int

Raises AssertionError: raises exception on error

...

Reset performance indicators for simulation

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

Return type int

...

...

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

...

...

Trig the programmable devices in the simulation

Parameters sync (bool): synchronize with POW

Returns error value

Return type bool

Raises AssertionError: raises exception on error

...

Start monitoring

Returns error value

Return type int

...

...

...

Start simulation

Returns error value

Return type int

...

...

...

Stop monitoring

Returns error value

Return type int

...

...

...

Returns error value

Return type int

Raises AssertionError: raises exception on error

Takes a snapshot of the simulation

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Add target to HYPERSIM target manager

...

...

...

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Prints a diagnostic report of the target configuration. More information on Target Manager

...

...

...

Returns diagnostic report on the target

Return type str

Get all known targets by HYPERSIM target manager : return: list of all known targets : rtype: str

...

Get current HYPERSIM version on target

...

...

...

Return type str

...

Get all HYPERSIM versions installed on target

Parameters targetHostName (str): target IP

Returns list of all HYPERSIM versions

Return type str

...

...

Install HYPERSIM version on target

Parameters

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Install HYPERSIM version on target

...

...

...

Returns error value

Return type int

...

...

Determine if target is ready for simulation

Parameters targetHostName (str): target IP

Returns ready status

Return type bool

...

Remove target from HYPERSIM target manager

...

...

...

Return type int

Raises AssertionError: raises exception on error

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

ScopeView Commands

The following commands are used to interact with ScopeView and are accessible through HyJavaApi.”command”.

ScopeViewApi can also be accessed without HyWorksApi, ScopeViewApi python module is located in C: \OPAL-RT\HYPERSIM\hypersim-version\Windows\ScopeView\lib

To use ScopeViewApi without HyWorksApi, add the path above to System PythonPath and use the following command:

...

General

...

Close ScopeView

Returns error value

Return type int

Raises AssertionError: raises exception on error

...

Connect to the first instance of ScopeView

Returns error value

Return type int

Raises AssertionError: raises exception on error

ScopeView.disableScopeViewApiExceptions():

Disable ScopeViewApi from returning ScopeView exceptions through Python

ScopeView.enableScopeViewApiExceptions():

Enable ScopeViewApi to return ScopeView exceptions through Python

ScopeView.initScopeViewApi():

Initializes ScopeView VM with necessary arguments

...

Open ScopeView note: ScopeView location is relative to HYPERSIM_DIR variable

Returns process ID

Return type int