IscInterface

The IscInterface class is the main interface class used to access all other IPSA objects and functions. It must be created before any other references to IPSA objects. To create an instance from Python the following commands are required when running IPSA with the User Interface:

# Run inside the IPSA User Interface
import ipsa
ipsascript = ipsa.GetScriptInterface()

The GetScriptInterface() returns an IscInterface instance which can then be used to access all other IPSA objects. The following sections provide the syntax for all other IscInterface functions.

Alternatively, the following code returns the IscInterface object when IPSA is running without a User Interface. In IPSA, the GetInterface() function should work as a conduit between both functions:

# Run with No User Interface
import ipsa
ipsascript = ipsa.IscInterface()

The functions IscInterface and GetScriptInterface must only be called once for each running process. Unexpected errors will occur if multiple calls to the above functions are made!

Debugging Options

To aid the development of scripted applications a number of debugging functions have been provided. These functions allow logging and timing of the analysis routines by providing detailed information on the analysis settings and data loaded into the analysis engines. The example below shows the output generated from a DoLoadFlow() function on a small test network.

IlfSetParameters: (100, 100, 0.01, 1,250,250,250,250,0, 0)
IlfSetRunOpts: (0, 1, 1, 1, 1, 0, 1)
IlfAddBusbarWithName: ([1]: <b>Busbar1</b> 0, 1, 0)
IlfAddBusbarWithName: ([2]: <b>Busbar2</b> 0, 1, 2e-005)
IlfAddUniversalMachine: (2, 0, 2, 0, 0)
IlfAddGridInfeed: (1, 0, 1, -2, 4.00037e-005, 0.1, 0.1, 0.1, 0, 0, 0, 0)
IlfAddBranch: (1, 2, 3, 0.0001, 0.001, 0)
IlfSetSlkBus: (1, 1)
IlfDoCalc: (4)
IlfGetBusResults: (1, 1, 0, -0.000529898, -0.00267593)
IlfGetBusResults: (2, 1, 1.99973e-005, 0.000265069, 0)
IlfGetGridInfeedResults: (1, -2.00026, -0.00263594)
IlfGetUMachResults: (1, 2, 0)
IlfGetLineResults: (1, -1.99973, 3.99892e-005, -1.99973, -0)

Database Functionality

Starting with version 2.10.1, the database functionality is now accessible within PyIPSA. The user simply has to open a database and populate an item with a database entry using the string as a reference. There is even added functionality to support item names returned to the user as well.

IscInterface Class

class ipsa.IscInterface

The main interface class used to access all other IPSA objects and functions.

ReadFile(strName: str)

Opens an Ipsa i2f file strName and returns an IscNetwork instance for that file.

Parameters:: strName (str) – The Ipsa i2f file that is going to be opened.
Returns:: The IscNetwork instance for the strName file
Return type:: IscNetwork

ReadIpsa1File(strName: str)

Imports an Ipsa 1 (*.iif) file strName and returns an IscNetwork instance for that file.

Parameters:: strName (str) – The Ipsa i2f file that is going to be imported.
Returns:: The IscNetwork instance for the strName file
Return type:: IscNetwork

GetNetwork()

Returns an IscNetwork instance for the current Ipsa network.

Returns:: The IscNetwork instance of the Ipsa network.
Return type:: IscNetwork

CloseNetwork() → bool

Closes the current network. Returns False if the network can’t be closed, e.g. if there is unsaved data.

Returns:: Boolean denoting whether the network is closed.
Return type:: bool

GetDiagram(network, strName: str)

Returns an IscDiagram instance for the diagram with name strName contained in the network referred to by iscNetwork.

Parameters:

network (IscNetwork) – The IscNetwork instance of the Ipsa network.
strName (str) – The name of the diagram.

Returns:

The diagram of the Ipsa network.

Return type:

IscDiagram

CreateNewNetwork(dSystemBaseMVA: float, dFrequencyHz: float, bWithDiagram: bool, bIsDiagramSingleLine: bool, dGeoSceneScale: float, nSceneMeasurementUnit: int) → bool

Creates a new Ipsa network based on the supplied parameters. Returns False if the network can’t be created.

Parameters:

dSystemBaseMVA (float) – The network base MVA.
dFrequencyHz (float) – The nominal network frequency in hertz.
bWithDiagram (bool) – Denoting whether the diagram is required.
bIsDiagramSingleLine (bool) – True if a normal single line diagram type is required, False if the diagram is a scaled geographic diagram.
dGeoSceneScale (float) – The scaling factor used to locate or size network components on geographic diagrams.
nSceneMeasurementUnit (int) –
The unit used for the geographic scale.
- 0 if Millimetres
- 1 if Centimetres
- 2 if Metres
- 3 if Kilometres
- 4 if Inches
- 5 if Feet
- 6 if Yards
- 7 if Miles

Returns:

Boolean denoting whether a network can be created.

Return type:

bool

MergeFile(sMergeName: str) → bool

Merges the Ipsa I2F file sMergeName into the current network.

Parameters:: sMergeName (str) – The name of the file being merged.
Returns:: Returns True if successful, False on merge failure.
Return type:: bool

ValidatedMergeFile(sMergeName: str) → bool

Performs a consistency check to determine if the Ipsa I2F file sMergeName can be merged into the current network. Use the GetFilingErrors() function to get details of the merge errors.

Parameters:: sMergeName (str) – The name of the file being merged.
Returns:: True if successful, False on merge failure.
Return type:: bool

GetFilingMessages() → List[str]

Returns a list of strings detailing the successful merge operations that occurred as a result of the ValidatedMergeFile function.

Returns:: List of successful merge operations.
Return type:: list(str)

GetFilingErrors() → List[str]

Returns a list of strings detailing the failed merge operations that occurred as a result of the ValidatedMergeFile function.

Returns:: List of failed merge operations.
Return type:: list(str)

WriteFile(strName: str) → bool

Saves the IscNetwork instance as a new Ipsa i2f network file with the file name strName. The file is saved in the current working directory unless the path is defined in the file name. The file name should include the .i2f extension

Parameters:: strName (str) – The name of the output file containing the i2f network.
Returns:: True if successful.
Return type:: bool

WriteArea(nAreaUID: int, strName: str) → bool

Saves the area group specified by the UID, nAreaUID, as a new Ipsa i2f network file with the file name strName. The integer nAreaUID can be obtained using the IscGroup functions. The file is saved in the current working directory unless the path is defined in the file name. The file name should include the .i2f extension

Parameters:

nAreaUID (int) – The area group UID.
strName (str) – The name of the output file containing the i2f network.

Returns:

True if successful.

Return type:

bool

GetAllDiagrams(network)

Returns a tuple of IscDiagram instances for the network referred to by IscNetwork.

Parameters:: network (IscNetwork) – The Ipsa network.
Returns:: The network diagram.
Return type:: tuple(IscDiagram)

GetAllDiagramsNames(network) → List[str]

Returns a list of all the diagram names for the network referred to by IscNetwork.

Parameters:: network (IscNetwork) – The Ipsa network.
Returns:: List of diagram names.
Return type:: list(str)

PrintPDF(diagram, strFileName) → None

Print the IscDiagram instance to a PDF format file with name strFileName.

Parameters:

diagram (IscDiagram) – The diagram of the Ipsa network.
strFileName (str) – The name of the pdf file.

MessageBox(strDialogTitle: str, strMessage: str) → bool

Display a message box with title specified by strDialogTitle and a message specified by strMessage. An OK button is provided for the user to dismiss the dialog.

Parameters:

strDialogTitle (str) – The title of the message box.
strMessage (str) – The message displayed on the message box.

Returns:

Boolean denoting whether a message box is created.

Return type:

bool

AskQuestion(strDialogTitle: str, strQuestion: str) → bool

Display a message box with a title and a question as shown below.

Parameters:

strDialogTitle (str) – The title of the message box.
strQuestion (str) – The question displayed on the message box.

Returns:

True when the user clicks Yes, otherwise False.

Return type:

bool

AllowStackBarUpdates(bAllow: bool) → None

Setting bAllow to True prevents the Ipsa stack bar from updating during script execution. This can provide speed improvements since redrawing the stack bar is prevented.

Parameters:: bAllow (bool) – Deciding whether the Ipsa stack bar can be updated during script execution.

GetDate() → str

Returns the date and time that Ipsa was launched, e.g. 06 Nov 2012 22:53:17.

Returns:: The date in a string format.
Return type:: str

GetUser() → str

Returns the name of the current logged on user.

Returns:: The name of the current logged on user.
Return type:: str

GetHost() → str

Returns the host name of the PC.

Returns:: The host name of the PC.
Return type:: str

GetOrganisation() → str

Returns the company organisation data as set in network properties.

Returns:: The company organisation data.
Return type:: str

GetNetworkTitle() → str

Returns the network title as set in network properties.

Returns:: The network title.
Return type:: str

GetNetworkFileName() → str

Returns the filename of the current network.

Returns:: The filename of the current network.
Return type:: str

GetFileName(strDialogTitle: str, strFileTypes: str) → str

Display the operating system File Open dialog to prompt the user to select a file.

Parameters:

strDialogTitle (str) – The title of the dialog itself.
strFileTypes (str) – The file type filter.

Returns:

String containing the file name and path selected by the user.

Return type:

str

GetDirectoryName(strDialogTitle: str) → str

Display the operating system Folder Selection dialog to prompt the user to select a folder.

Parameters:: strDialogTitle (str) – The title of the dialog itself.
Returns:: String containing the path selected by the user.
Return type:: str

GetVersion() → str

Returns the version number of IPSA software.

Returns:: The version number.
Return type:: str

HasLoadFlow() → bool

Returns True if a load flow license is present.

Returns:: Boolean denoting whether a load flow license is presented.
Return type:: bool

HasFaultLevel() → bool

Returns True if a fault level license is present.

Returns:: Boolean denoting whether a fault level license is presented.
Return type:: bool

HasTransient() → bool

Returns True if a transient stability license is present.

Returns:: Boolean denoting whether a transient stability license is presented.
Return type:: bool

HasProtection() → bool

Returns True if a protection analysis license is present.

Returns:: Boolean denoting whether a protection analysis license is presented.
Return type:: bool

HasHarmonics() → bool

Returns True if a harmonics analysis license is present.

Returns:: Boolean denoting whether a harmonics analysis license is presented.
Return type:: bool

HasUDM() → bool

Returns True if a UDM (User Defined Modelling) license is present.

Returns:: Boolean denoting whether a UDM license is presented.
Return type:: bool

HasDC() → bool

Returns True if a DC component license is present.

Returns:: Boolean denoting whether a DC component license is presented.
Return type:: bool

HasStaticCon() → bool

Returns True if a static converter license is present.

Returns:: Boolean denoting whether a static converter license is presented.
Return type:: bool

HasTandemGen() → bool

Returns True if a tandem generator license is present.

Returns:: Boolean denoting whether a tandem generator license is presented.
Return type:: bool

HasNonLinDevs() → bool

Returns True if a non-linear devices license is present.

Returns:: Boolean denoting whether a non-linear devices license is presented.
Return type:: bool

HasAutomation() → bool

Returns True if an automation analysis license is present.

Returns:: Boolean denoting whether an automation analysis license is presented.
Return type:: bool

IsLimitedSize() → bool

Returns True if the current license imposes a limit on the maximum number of busbars.

Returns:: Boolean denoting whether the current license imposes a limit on the maximum number of busbars.
Return type:: bool

GetMaxBusbars() → int

Returns the maximum number of busbars if it is a limited busbar version, returns 0 if unlimited.

Returns:: The maximum number of busbars if in limited busbar version, else 0.
Return type:: int

DisplayResultsTable(nTableType: int) → None

Displays the Ipsa results table which will contain the results of the last analysis.

Parameters:

nTableType –

Specify the type of table displayed:

ipsa.IscInterface.BusbarLF = busbar load flow results
ipsa.IscInterface.GeneratorLF = generator load flow results
ipsa.IscInterface.GridInfeedLF = grid infeed load flow results
ipsa.IscInterface.LoadLF = load object load flow results
ipsa.IscInterface.IMachineLF = motor load flow results
ipsa.IscInterface.StaticVCLF = SVC load flow results
ipsa.IscInterface.MechSwCapLF = switched capacitor load flow results
ipsa.IscInterface.UMachineLF = universal machine load flow results
ipsa.IscInterface.FilterLF = harmonic filter load flow results
ipsa.IscInterface.LineLF = branch load flow results
ipsa.IscInterface.TransformerLF = transformer load flow results
ipsa.IscInterface.ThreeWindingTransformerLF = 3 winding transformer load flow results
ipsa.IscInterface.BatteryLF = DC battery load flow results
ipsa.IscInterface.DCMachineLF = DC machine load flow results
ipsa.IscInterface.ConverterLF = AC-DC converter load flow results
ipsa.IscInterface.ChopperLF = DC-DC converter load flow results
ipsa.IscInterface.MGSetLF = motor-generator set load flow results
ipsa.IscInterface.BusbarFL = busbar fault level results
ipsa.IscInterface.GeneratorFL = generator fault level results
ipsa.IscInterface.GridInfeedFL = grid infeed fault level results
ipsa.IscInterface.LoadFL = load object fault level results
ipsa.IscInterface.IMachineFL = motor fault level results
ipsa.IscInterface.LineFL = branch fault level results
ipsa.IscInterface.TransformerFL = transformer fault level results
ipsa.IscInterface.ThreeWindingTransformerFL = 3 winding transformer fault level results
ipsa.IscInterface.UniversalMachineFL = universal machine fault level results
ipsa.IscInterface.BusbarHM = busbar harmonic analysis results
ipsa.IscInterface.GeneratorHM = generator harmonic analysis results
ipsa.IscInterface.LoadHM = load object harmonic analysis results
ipsa.IscInterface.IMachineHM = motor harmonic analysis results
ipsa.IscInterface.FilterHM = filter harmonic analysis results
ipsa.IscInterface.LineHM = branch harmonic analysis results
ipsa.IscInterface.TransformerHM = transformer harmonic analysis results
ipsa.IscInterface.ThreeWindingTransformerHM = 3 winding transformer harmonic analysis results

Type:

int

GetResultsTableText(nTableType: int) → str

Returns the data contained in the results’ table as a comma delimited string which can be pasted directly into a spreadsheet.

Parameters:: nTableType (int) – The type defined for the DisplayResultsTable function.
Returns:: Data contained in the results’ table.
Return type:: str

CloseResultsTable(nTableType: int) → None

Closes the results’ table nTableType which is as defined for the DisplayResultsTable function.

Parameters:: nTableType (int) – The type defined for the DisplayResultsTable function.

GetLogFileName() → str

Get the name of log file.

Returns:: The name of the log file.
Return type:: str

DbgSetLogFileName(strName: str) → None

Set the name of the load flow log file to strName. If no file path is specified then the file is created in the Ipsa bin directory.

Parameters:: strName (str) – The name of the load flow log file.

IsLogging() → bool

Checks whether a logging is in progress.

Returns:: Returns True if logging is in progress.
Return type:: bool

DbgStartLogging() → None: Start logging of all analysis engine calls.

DbgStopLogging() → None: Stop logging of all analysis engine calls.

OpenDBFromFile(strFilename: str) → bool

Opens the database from file.

Parameters:: strFilename (str) – The path name of the file to be opened.
Returns:: Returns True if the database is opened successfully.
Return type:: bool

CloseDBFromFile(strFilename: str) → bool

Closes the specified database file.

Parameters:: strFilename (str) – The path name of the file to be closed.
Returns:: Returns True if the database is closed successfully.
Return type:: bool

CloseAllDB() → bool

Close all the databases.

Returns:: Returns True if databases are closed.
Return type:: bool

GetDBNames() → List[str]

Returns all filenames of the databases that have been loaded.

Returns:: Returns list of the databases’ filenames.
Return type:: list(str)

GetDBBranchNames(strFilename: str) → List[str]

Returns all branch names in a database.

Parameters:: strFilename (str) – The path name of the database.
Returns:: Returns list of the branch names.
Return type:: list(str)

GetDBTransformerNames(strFilename: str) → List[str]

Returns all transformer names in a database.

Parameters:: strFilename (str) – The path name of the database.
Returns:: Returns list of the transformer names.
Return type:: list(str)

GetDBGeneratorNames(strFilename: str) → List[str]

Returns all generator names in a database.

Parameters:: strFilename (str) – The path name of the database.
Returns:: Returns list of the generator names.
Return type:: list(str)

GetDBIndMachineNames(strFilename: str) → List[str]

Returns all induction machine names in a database.

Parameters:: strFilename (str) – The path name of the database.
Returns:: Returns list of the induction machine names.
Return type:: list(str)

GetDBCircuitBreakerNames(strFilename: str) → List[str]

Returns all circuit breaker names in a database.

Parameters:: strFilename (str) – The path name of the database.
Returns:: Returns list of the circuit breaker names.
Return type:: list(str)