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

The database functionality is 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 i3f/i2f file strName and returns an IscNetwork instance for that file.

Parameters:

strName (str) – The IPSA i3f 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 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)
GetDiagram(network, nUID: int)

Returns an IscDiagram instance for the diagram with name strName or ID nUID contained in the identified network.

Parameters:

  • network (IscNetwork) – The IscNetwork instance of the IPSA network.

  • strName (str) – The name of the diagram.

  • nUID (int) – The diagram ID.

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 i3f/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 i3f/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 i3f 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 .i3f extension

Parameters:

strName (str) – The name of the output file containing the i3f extension and path.

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 i3f 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 .i3f extension

Parameters:

  • nAreaUID (int) – The area group UID.

  • strName (str) – The name of the output file containing the i3f extension and path.

Returns:

True if successful.

Return type:

bool

GetAllDiagrams(network)

Returns a tuple of IscDiagram instances for the identified network.

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 identified network.

Parameters:

network (IscNetwork) – The IPSA network.

Returns:

List of diagram names.

Return type:

list(str)

GetAllDiagramsUIDs(network)

Returns a dictionary of diagrams for the identified network. The keys are the Diagram IDs.

Parameters:

network (IscNetwork) – The IPSA network.

Returns:

Dictionary of diagrams for the network.

Return type:

dict(int, IscDiagram)

AddDiagram(network, strSceneTitle: str, bIsDiagramSingleLine: bool, dGeoSceneScale: float, nSceneMeasurementUnit: int) → int
AddDiagram(network, strSceneTitle: str, bIsDiagramSingleLine: bool, dGeoSceneScale: float, nSceneMeasurementUnit: int, nCopyWhat: int, nDiagramToCopy: int) → int

Creates a new diagram for the identified network based on the supplied parameters. Returns the diagram UID corresponding to the new diagram. Note that this function causes IPSA to rebuild the IscDiagram data maps.

If nCopy what and nDiagramToCopy are provided, they provide a reference diagram and determine what is copied from that diagram into the new diagram. If nDiagramToCopy is provided and doesn’t refer to an existing diagram, no new diagram will be created.

Parameters:

  • network (IscNetwork) – The IPSA network.

  • strSceneTitle (str) – The name of the new diagram.

  • 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

  • nCopyWhat (int) –

    Determines what is copied from the provided diagram pDiagramToCopy

    • 0 if copy nothing

    • 1 if copy the busbars as they are

    • 2 if copy the busbars as junctions

    • 3 if copy everything

  • nDiagramToCopy (int) – The UID of the diagram that any components may be copied from.

Returns:

The diagram UID for the newly created diagram.

Return type:

int

AddSLDiagram(network, strSceneTitle: str) → int

Creates a new single line diagram for the identified network. Returns the diagram UID corresponding to the new diagram. Note that this function causes IPSA to rebuild the IscDiagram data maps. This is equivalent to calling AddDiagram with bIsDiagramSingleLine = True.

Parameters:

  • network (IscNetwork) – The IPSA network.

  • strSceneTitle (str) – The name of the new diagram.

Returns:

The diagram UID for the newly created diagram.

Return type:

int

DeleteDiagram(network, pDiagram: IscDiagram) → bool
DeleteDiagram(network, nUID: int) → bool
DeleteDiagram(network, strName: str) → bool

Deletes the diagram identified by name strName, ID nUID or IscDiagram pDiagram from the identified network.

Parameters:

  • network (IscNetwork) – The IPSA network.

  • strName (str) – The name of the diagram to be deleted.

  • nUID (int) – The diagram ID to be deleted.

  • pDiagram (IscDiagram) – The diagram to be deleted.

Returns:

True if the diagram is deleted.

Return type:

bool

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 IPSA preferences.

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

Return type:

bool

HasFaultLevel() → bool

Returns True if a fault level license is present.

Returns:

Boolean denoting whether a fault level license is present.

Return type:

bool

HasTransient() → bool

Returns True if a transient stability license is present.

Returns:

Boolean denoting whether a transient stability license is present.

Return type:

bool

HasProtection() → bool

Returns True if a protection analysis license is present.

Returns:

Boolean denoting whether a protection analysis license is present.

Return type:

bool

HasHarmonics() → bool

Returns True if a harmonics analysis license is present.

Returns:

Boolean denoting whether a harmonics analysis license is present.

Return type:

bool

HasNetworkReduction() → bool

Returns True if a network reduction license is present.

Returns:

Boolean denoting whether a network reduction license is present.

Return type:

bool

HasUDM() → bool

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

Returns:

Boolean denoting whether a UDM license is present.

Return type:

bool

HasDC() → bool

Returns True if a DC component license is present.

Returns:

Boolean denoting whether a DC component license is present.

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)

GetReportType() → int

The nReport type of the most recently generated report, matching those in e.g., IscNetwork.GetStudies(nReportType)().

Automation studies:

  • 100 = All studies in the order run

  • 101 = All solved studies in the order run

  • 102 = All solved studies listed by severity of overload

  • 103 = All solved studies listed by the number of items exceeding limits

  • 104 = All studies that failed to solve

Contingency studies:

  • 120 = All studies in the order run

  • 121 = All solved studies in the order run

  • 122 = All solved studies listed by severity of overload

  • 123 = All solved studies listed by the number of items exceeding limits

  • 124 = All studies that failed to solve

Note this number only updates if a report has been generated from the IPSA UI.

Returns:

The nReport type of the most recently generated report.

Return type:

int

GetUndoActive() → bool

Returns a boolean determining whether Undo is currently active.

Note Undo will act on a complete PyIPSA script as a single action.

Returns:

Returns True if Undo is active.

Return type:

bool

SetUndoActive(bSetActive: bool)

Sets the boolean determining whether Undo is currently active.

This will determine the state of Undo following the completion of the script.

Parameters:

bSetActive (bool) – True if undo should be active.

HasPSSEIO() → bool

Deprecated. Returns True if a PSSE analysis license is present.

Returns:

Boolean denoting whether a PSSE analysis license is presented.

Return type:

bool

GetIpsa1Mode() → bool

Deprecated. Returns the IPSA 1 mode - note, this is currently not used anywhere so does nothing.

Returns:

The boolean of the Ipsa1 mode.

Return type:

bool

SetIpsa1Mode(bIpsa1) → bool

Deprecated. Sets the IPSA 1 mode - note, this is currently not used anywhere so does nothing.

Parameters:

bIpsa1 (bool) – The boolean of the Ipsa1 mode.

WriteJsonFile(strName: str) → bool

Deprecated. Saves the graphical information, name and UID for every component in the network as a json file. The file is saved in the current working directory unless the path is defined in the file name. The file name should include the .json extension

Parameters:

strName (str) – The name of the output file.

Returns:

True if successful.

Return type:

bool

WriteCSVItemFile(strName: str) → bool

Deprecated. Saves the UID, component type and name for every component in the network as a csv file. The file is saved in the current working directory unless the path is defined in the file name. The file name should include the .csv extension

Parameters:

strName (str) – The name of the output file.

Returns:

True if successful.

Return type:

bool