MultiLoadflow Module

To run a Multi-Loadflow study you must create two CSV files. A Study Parameters CSV file for defining each study, and a Results Selection CSV file for defining the output. Unlike MultiFault Module, Multi-Loadflow does not provide methods for adding studies and result selection programmatically, and must be defined in CSV files. Below, the expected file structures are documented.

File Structure

There are two input files and one output file, each with specific structures.

Inputs:
- Study Parameters CSV file
- Result Selection CSV file
Outputs:
- Result Output CSV file

Study Parameters CSV file

The following table demonstrates an example Study Parameters CSV file structure for Multi-Loadflow. CSV files can be worked with like tables in Excel and similar spreadsheet tools.

Study Parameters Structure
NumLoadflow	2
ElementType	BusSection	Switch	LoadflowParam
ElementID	BS_PH2	CB_TxLE1	PMult
ItemID	swstate	swstate	PMult
ParameterValues	1	1	1
ParameterValues	0	1	0.5
ParameterValues	0	0	1

The CSV file looks like this in a text format:

NumLoadflow,2
ElementType,BusSection,Switch,LoadflowParam
ElementID,BS_PH2,CB_TxLE1,PMult
ItemID,swstate,swstate,PMult
ParameterValues,1,1,1
ParameterValues,0,1,0.5
ParameterValues,0,0,1

From the example above we can observe a number of things about the Study Parameters definition.

The first row defines the number of Loadflow studies to perform. In our example we’ve specified that 2 studies should be performed, yet we listed 3 Parameter Values rows. The last row will therefore be ignored.
The file will grow horizontally when adding more parameters to each study, and will grow vertically with each new study we define. The first column acts as the heading.
Headings are compulsory. However, the headings are not case senstitive. We recommend using camelCasing or PascalCasing to make the headings more readable.
The second row defines which type of element to change the parameters for. If specified as “LoadflowParam” then it will set a Loadflow parameter rather than a specific element value. This makes Parameter definitions very flexible since Loadflow and Element data can be modified before each study. See the Glossary for a list of element types.
The third row defines the element ID we want to act upon. For example, you can see that we’re changing data for a BusSection with an ID of BS_PH2. Since Loadflow parameters do not relate to a specific element, the element ID should match the item ID described below.
The fourth row defines what data we want to change. For bus section BS_Ph2 we’re changing the switch state, and for the Loadflow Parameter we’re changing P multiplier. See Glossary for possible item IDs.
From the fifth row onwards we will be specifying the data to use for each study. For the first study In our example, we close both switches (allowing power to run through them) and set the P Multiplier to 1. On the second study, we open the bus section switch to cut off power flow, and halve the P Multiplier.

Example of changing data

It’s possible to modify all sorts of setup data with the parameter input file. This includes internal data. Here are two examples of changing data, one of which is just changing top level data as a means of comparing with the second example which changes internal data. The ‘.’ (dot) notation can be used to drill down into all sorts of internal data for any element type.

Top level data change: This example changes the length of a transmission line from 10 for the first study to 20 for the second study. The example has headers omitted.

Transmission line data change
Line
line_0001
length
10
20

The CSV file might look like this in a text format, with headers included:

NumLoadflow,2
ElementType,Line
ElementID,line_0001
ItemID,length
ParameterValues,10
ParameterValues,20

Internal data change: This example changes the per unit voltage value for the minimum fault level of a grid infeed. On the first study we use a per unit value of 1, and on the second study we’re using a per unit value of 1.5. The example has headers omitted.

Grid infeed data change
Grid
grid_0001
min_fault_level.vpu
1
1.5

The CSV file might look like this in a text format, with headers included:

NumLoadflow,2
ElementType,Grid
ElementID,grid_0001
ItemID,min_fault_level.vpu
ParameterValues,1
ParameterValues,1.5

Result Selection CSV file

The following table is an example of the Result Selection CSV structure for Multi-Loadflow.

Result Selection Structure
Element Type	Busbar	Summary
Element ID	SB_PH1b	pg
Item ID	posdrvz	pg

The CSV file looks like this in text format:

Element Type,Busbar,Summary
Element ID,SB_PH1b,pg
Item ID,posdrvz,pg

The Result Selection structure is very simple, and is identical to that of the MultiFault Module. In our example, we’re grabbing the Positive Sequence Driving-Point Impedance for the SB_PH1b busbar, and the Total Real Power Generated from the overall summary results. Like with Study Parameter selection, the first column is treated as a heading and therefore ignored by Multi-Loadflow.

See the Glossary for lists of result selections.

Result Output CSV file

Using the example above for result selection, the following results will be outputted in the same structure.

Result Output Structure
Element Type	Busbar	Summary
Element ID	SB_PH1b	pg
Item ID	posdrvz	pg
Study 1	1.699686289	2.077662945
Study 2	1.700982451	1.800819635

The CSV file will look like this in text format:

Element Type,Busbar,Summary
Element ID,SB_PH1b,pg
Item ID,posdrvz,pg
Study 1,1.6996862888336182,2.077662944793701
Study 2,1.7009824514389038,1.8008196353912354

Loadflow studies don’t have names, so a default name of “Study X” is used. The structure is identical to result selection apart from the actual results are listed below the headings. Being in an easy-to-read CSV format split by rows makes it easy to parse the results using any programming language (preferably Python).

API

Module for running multiple loadflow studies easily using CSV definition files.

class TEracsMLFEventType(value)

This Enum is used to define an event type for MultiLoadflow. The ‘before’ event type is fired before each Loadflow study is performed and the ‘after’ event type is fired after each Loadflow study is performed. The MultiLoadflow instance object is passed into each event handler.

Inherits: Enum - Enumeration type.

BEFORE_EACH_LOADFLOW = 1

AFTER_EACH_LOADFLOW = 2

exception TEracsMLFError: Exception/Error class for multi-loadflow specific exceptions.

class TEracsMultiLoadflow

This is the main class for running multiple Loadflow studies. This class instantiates an object of type data manager and another of type results manager. This class is instantiated directly by importing this module. Commence the multiple Loadflow studies using RunStudies.

property Loadflow

The calculation object used to perform the multiple Loadflow studies.

Type: TEracsLoadflowEasy.
Writable: False.

property Data

The data object used to load up the XML data.

Type: TEracsData.
Writable: False.

property Silent

If MultiLoadflow is silent, it will not output anything (no progress reports), but it will still generate result files. Also, if exceptions are raised and unhandled they will also output to the stderr pipe.

Type: bool.
Writable: True.

property ResultsFilename

The filename and path of the results from the multiple loadflow studies.

Type: str.
Writable: True.

AddListener(AEvent: MultiLoadflow.TEracsMLFEventType, AHandler)

Add an event listener to one of the event types for each Loadflow study.

Parameters

AEvent (TEracsMLFEventType) – The event type we want to add a listener to.
AHandler (Callable[[], None]) – The callback function used for the event handler.

Returns

None.

RemoveListener(AEvent: MultiLoadflow.TEracsMLFEventType, AHandler)

Remove an event listener from one of the event types for each Loadflow study.

Parameters

AEvent (TEracsMLFEventType) – The event type we want to remove a listener from.
AHandler – The callback function used for the event handler.

Returns

None.

RunStudies(ADataFile, AParamListFile, AResultsListFile, AOutputFileDir=None, AIncludeMonitorMessages=False)

Start the multiple Loadflow studies, passing in paths to data, study parameter, results and output files.

Parameters

ADataFile (str) – The location of the ERACS data file containing the network which will be used in the studies.
AParamListFile (str) – The location of the CSV file containing Loadflow parameters for each study to be performed.
AResultsListFile (str) – The location of the CSV file containing all target results to output.
AOutputFileDir (str) – (Optional) The location of the output file which will contain all results. If empty, current working directory will be used.
AIncludeMonitorMessages (bool) – (Optional) Whether to include monitor messages from Loadflow. If not provided it’s false by default. If true, the monitor messages are included as a separate text file.

Returns

None.