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
- 1 General
- 1.1 closeHyperWorks():
- 1.2 closeLibrary(libraryPath):
- 1.3 connectToHyWorks(host=socket.gethostname(), register=getpass.getuser():
- 1.4 disableHyWorksApiExceptions():
- 1.5 enableHyWorksApiExceptions():
- 1.6 getApiSession():
- 1.7 getCurrentDesign():
- 1.8 getProperties():
- 1.9 getProperty(key):
- 1.10 getVersion(long=False) :
- 1.11 newApiSession():
- 1.12 openLibrary(libraryPath, visible=True):
- 1.13 setApiSession(session):
- 1.14 setProperty(key, value, save=False):
- 1.15 startAndConnectHypersim(host=socket.gethostname(), register=getpass.getuser(), stdout=None, stderr=None:
- 1.16 startHyperWorks(stdout=None, stderr=None):
- 2 Design
- 2.1 batchAddDevices(devices, interrupt_on_error=False):
- 2.2 closeDesign(designPath):
- 2.3 disconnectDesign(designPath):
- 2.4 findMinimalStepSize(timeout, overrunsThreshold: int, nCores=100, startingTimeStep=1e-6, jump=1e-6):
- 2.5 getAllComponentDescriptions():
- 2.6 getAllComponentParameters(compName):
- 2.7 getAllComponentSensors(compName):
- 2.8 getAllDevicesNames():
- 2.9 getAllSelectedSensors():
- 2.10 getDesignPrefs():
- 2.11 importEDD(eddFilePath, doConnections):
- 2.12 importPSCAD(filePath, onlyDll, removeNotConnectedBuses=False):
- 2.13 importPSSE(filePath, replaceMachines=False, groupMachinesWithControls=True):
- 2.14 importPowerFactory(filePath, mode=0):
- 2.15 importProject(zipFilePath, destinationPath=None, isUI=False, overwrite=False):
- 2.16 newDesign(designFilePath=None):
- 2.17 openDesign(designPath):
- 2.18 recheckPorts():
- 2.19 saveDesign():
- 2.20 saveDesignAs(fileName):
- 2.21 updateEDD(eddFilePath, doConnections):
- 3 Device
- 3.1 activateObservables(deviceName, observables):
- 3.2 addBus1ph(signalName, points, hitCheck=False, subcircuit=None):
- 3.3 addBus3ph(signalName, points, hitCheck=False, subcircuit=None):
- 3.4 addControlSignal(signalName, points, hitCheck=False, subcircuit=None):
- 3.5 addDevice(libName, blocName, coordX=0, coordY=0, page=1, subcircuit=None, name=None, rotation=0:
- 3.6 addPinsToDevice(name, cardinalPoint, function, pins, redraw=False):
- 3.7 batchConnectDevices(connections, interrupt_on_error=False):
- 3.8 connectBundleToBundle(blocA, signalListA, blocB, signalListB):
- 3.9 connectDeviceToBus1ph(deviceName, pinName, signalName):
- 3.10 connectDeviceToBus3ph(deviceName, pinName, signalName):
- 3.11 connectDeviceToControlSignal(deviceName, pinName, signalName):
- 3.12 connectDevices(blocA, pinA, blocB, pinB, isThreePhaseAndPowerFlexible, signalName=None):
- 3.13 connectPinToBundle(blocA, pinA, blocB, signalListB):
- 3.14 createSubCircuit(name, subType, coordX=0, coordY=0, page=1, rotation=0, flipHorizontally=False:
- 3.15 disconnectPin(deviceName, pinName, removeAllConnections=False):
- 3.16 displayComponent(componentName, printAttributes=True, printSignals=True, printConnectors=True:
- 3.17 displayConnections(componentName):
- 3.18 exportCigre(compName: str, file_path: str):
- 3.19 flipHorizontallyDevice(deviceName, keepConnections=True):
- 3.20 flipVerticallyDevice(deviceName, keepConnections=True):
- 3.21 getComponentParameter(compName, compParam):
- 3.22 getCoordinates(deviceName, pinName=None):
- 3.23 getDeviceBundleChildPins(deviceName, pinName):
- 3.24 getDeviceBundlePins(deviceName):
- 3.25 getDevicePinTypes(deviceName: str, pinNames: list):
- 3.26 getDevicePins(deviceName):
- 3.27 getImpedanceMeasurement(busName: str, freqMin: float, freqMax: float, freqInc: float):
- 3.28 importCigre(compName: str, file_path: str=None, import_folder: str=None):
- 3.29 importUCM(defFilePath, coordX=0, coordY=0, page=1, subcircuit=None, name=None, rotation=0, flipHorizontally=False:
- 3.30 includeDevice(deviceName, include):
- 3.31 removeDevice(deviceName):
- 3.32 renameDevice(oldDeviceName, newDeviceName):
- 3.33 renameSignal(oldName, newName, visible=True):
- 3.34 rotateLeftDevice(deviceName, keepConnections=True):
- 3.35 rotateRightDevice(deviceName, keepConnections=True):
- 3.36 setComponentParameter(compName, compParam, value):
- 3.37 setComponentParameters(compNames, compParams, values):
- 3.38 setDeviceFillColor(name, colorHexRGB):
- 3.39 setDeviceLineColor(name, colorHexRGB):
- 3.40 setDevicesAttributeVisibility(deviceList, attributeName, isVisible):
- 3.41 setDevicesNameVisibility(deviceList, isVisible):
- 3.42 setPinPhaseNumber(deviceName, pinName, value):
- 3.43 setSignalLineColor(signalName, colorHexRGB):
- 3.44 setSignalLineWidth(signalName, width):
- 3.45 setSubcircuitScripts(compName, initialValues, rules, variablesToTransmit, evaluateOnly=False):
- 3.46 unbindUCMFromLibrary(deviceName):
- 3.47 updateUCM(deviceName, ucmPath=None, forced=False):
- 4 Graphic
- 4.1 drawArc(left, top, right, bottom, start, extent, posX=0, posY=0, page=1, subcircuit=None, lineWidth=None, foreColor=None):
- 4.2 drawEllipse(left, top, right, bottom, posX=0, posY=0, page=1, subcircuit=None, lineWidth=None, foreColor=None, backColor=None):
- 4.3 drawLine(x1, y1, x2, y2, posX=0, posY=0, page=1, subcircuit=None, lineWidth=None, foreColor=None):
- 4.4 drawRectangle(left, top, right, bottom, posX=0, posY=0, page=1, subcircuit=None, lineWidth=None, foreColor=None, backColor=None):
- 4.5 drawText(text, posX=0, posY=0, textX=0, textY=0, page=1, subcircuit=None, just=None, textSize=None, foreColor=None, bold=False, italic=False, font=None, rotation=None):
- 5 Sensor
- 5.1 editSensor(blocName, sensorName, IOType=None, IONumber=None, base=None, unit=None):
- 5.2 getLastSensorValues(sensorNames):
- 5.3 getSensorInfo(blocName, sensorName, key):
- 5.4 getSensorsValues(sensorNames: List[str], timeLength, timeStart=0, acquisitionRate=Non:
- 5.5 loadSensors(filePath):
- 5.6 selectAllSensors(blocName):
- 5.7 selectSensor(blocName, sensorName, selected=True):
- 5.8 setSensorDataLogger(blocName, sensorName, record, groupName, trigger):
- 5.9 setSensorDataPoint(blocName, sensorName, exchangerTag, dataPointName, dataPointIdx):
- 6 Settings
- 6.1 analyze():
- 6.2 buildTopology():
- 6.3 clearCodeDir():
- 6.4 genCode():
- 6.5 getLoadFlowReport() :
- 6.6 getModelTasks(file_name=””) :
- 6.7 getPreference(prefName):
- 6.8 loadModelTasks(file_name=””) :
- 6.9 mapTask():
- 6.10 setModelTasks(mapping: TaskMapping, file_name=””) :
- 6.11 setPreference(prefName, value):
- 6.12 setTarget(hostname, mode=None):
- 6.13 startLoadFlow():
- 7 Simulation
- 7.1 getMonitoringAllValues():
- 7.2 getMonitoringValue(monitorName):
- 7.3 getPreparationTimings(modelPath: str = None) :
- 7.4 getReservedProcessorCount() :
- 7.5 getSimulatingProcessorCount() :
- 7.6 getSimulationCoreTimings(modelPath: str = None) :
- 7.7 getSimulationOverruns():
- 7.8 getSimulationPerformanceTimings(mode: MonitoringMode = MonitoringMode.ALL:
- 7.9 getSimulationTime():
- 7.10 getSimulationTimings(modelPath: str = None) :
- 7.11 loadSnapshot():
- 7.12 resetMonitoring(cpuList):
- 7.13 resetPerfIndic(cpuList):
- 7.14 resetSimulationPerformanceTimings(mode: MonitoringMode = MonitoringMode.ALL, procs: List[int] = None) :
- 7.15 resetTiming(cpuList):
- 7.16 simtrig(sync):
- 7.17 startMonitoring():
- 7.18 startSim():
- 7.19 stopMonitoring():
- 7.20 stopSim():
- 7.21 takeSnapshot():
- 8 Target
- 8.1 addTargetToManager(targetHostName):
- 8.2 diagnosticTarget(targetHostName):
- 8.3 getAllTargetsName():
- 8.4 getCurrentVersionOnTarget(targetHostName):
- 8.5 getInstalledVersionOnTarget(targetHostName):
- 8.6 installHypersimOnTarget(targetHostName):
- 8.7 isTargetReady(targetHostName):
- 8.8 removeTargetFromManager(targetHostName):
- 8.9 switchVersionOnTarget(targetHostName, switchToVersion):
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():
HyWorksApiGRPC.connectToHyWorks(host=socket.gethostname(), register=getpass.getuser()
Connect HyJavaApi to HYPERSIM
Parameters: |
|
Returns: | error value |
Return type: | int |
Raises: | AssertionError – raises exception on error |
disableHyWorksApiExceptions():
HyWorksApiGRPC.disableHyWorksApiExceptions()
Disable HyWorksApi from returning HYPERSIM exceptions through Python
enableHyWorksApiExceptions():
HyWorksApiGRPC.enableHyWorksApiExceptions()
Enable HyWorksApi to return HYPERSIM exceptions through Python
getApiSession():
HyWorksApiGRPC.getApiSession()
Retrieve the currently active API session with HyWorks Note : To be used only when multiple HYPERSIM instances are required at the same time
getCurrentDesign():
HyWorksApiGRPC.getCurrentDesign()
Get the currently focused HYPERSIM design.
Returns: | path to the currently active HYPERSIM design |
Return type: | str |
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 |
newApiSession():
HyWorksApiGRPC.newApiSession()
Create a new API disconnected API session for HyWorks
openLibrary(libraryPath, visible=True):
HyWorksApiGRPC.openLibrary(libraryPath, visible=True)
opens a CLF library located at the specified ‘libraryPath’.
Parameters: |
|
Returns: | True if the library was successfully opened; False otherwise. |
Return type: | bool |
setApiSession(session):
HyWorksApiGRPC.setApiSession(session)
Activates a previously save API session retrieved by getApiSession
Parameters: | session (HyWorksGRPCSession) – gRPC Session |
Returns: | the currently active session |
Return type: | HyWorksGRPCSession |
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: |
|
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: |
|
Examples:
HyWorksApi.startHyperWorks()
Design
batchAddDevices(devices, interrupt_on_error=False):
HyWorksApiGRPC.batchAddDevices(devices, interrupt_on_error=False)
Add multiple devices to a design in a single batch operation.
Each entry in the returned list corresponds (by AddDeviceResult.index) to an entry in devices. Inspect AddDeviceResult.success to distinguish successes from failures without raising.
devices dictionaries should be in the following format: {
Required keys:
library (string)
type (string)
Optional keys:
x (int)
y (int)
page (int)
subcircuit (string)
name (string)
rotation (int)
flipVertically (bool)
flipHorizontally (bool)
}
Parameters: |
|
Returns: | one |
Return type: | list[AddDeviceResult] |
Raises: | RuntimeError – if every operation failed. |
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: |
|
Returns: | The minimal time step in seconds, or None if unsuccessful |
Return type: | float |
Raises: | AssertionError – raises exception on error |
getAllComponentDescriptions():
HyWorksApiGRPC.getAllComponentDescriptions()
Gets the descriptions of all components available in the current design, including their parameters and signals.
Returns: | a list of component descriptions |
Return type: | list |
getAllComponentParameters(compName):
HyWorksApiGRPC.getAllComponentParameters(compName)
Gets the list of parameters for a given component.
Parameters: | compName (str) – Component Name |
Returns: | a list of parameter descriptions, for the ‘compName’ |
Return type: | list |
getAllComponentSensors(compName):
HyWorksApiGRPC.getAllComponentSensors(compName)
Gets the list of sensors available for a given component type.
Parameters: | compName (str) – Component Name |
Returns: | a list of sensor descriptions for the component. |
Return type: | list |
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
getAllSelectedSensors():
HyWorksApiGRPC.getAllSelectedSensors()
Gets the list of selected sensors in the current design, including their runtime I/O connections. The returned value is a CSV string; it is the caller’s responsibility to decode it with the appropriate CSV parsing tool.
Returns: | csv string of selected sensor descriptions |
Return type: | str |
getDesignPrefs():
HyWorksApiGRPC.getDesignPrefs()
Get current model preferences