MultiFault Module

Inheritance diagram of MultiFault

The easiest way to run a Multi-Fault study is by creating CSV files (comma-separated values) to define parameters for each study and result selection. Below, the expected file structures are documented.

Note

As well as using CSV files with the ReadStudiesAndTargetResultsFromCSV method, you can also use the AddStudy and AddTargetResult methods for adding studies and result selection programmatically. All methods are documented in the API section below.

File Structure

There are two input files and one output file, each with specific structures. The Study Parameters CSV file defines each study to perform, with appropriate setup parameters for each study. The Result Selection CSV file defines results you want outputted for every study. The Results CSV file includes the results defined in the Result Selection file.

Study Parameters CSV file

The following table demonstrates an example Study Parameters CSV file structure. CSV files can be worked with easily in spreadsheet programs (like Excel), as these programs tend to interpret the comma-separators as column dividers.

Study Parameters Structure

StudyTitle

Typecode

SeqNum

ReactOption

FaultType

FaultPos

Rph

Xph

Rgrnd

Xgrnd

IncMotor

Testing Study A

1

1

1

4

0

0

0

0

0

1

Testing Study B

1

2

1

4

0

0

0

0

0

1

The CSV file representation of the above table would in fact look like this in a simple text editor:

StudyTitle,Typecode,SeqNum,ReactOption,FaultType,FaultPos,Rph,Xph,Rgrnd,Xgrnd,IncMotor
Testing Study A,1,1,1,4,0,0,0,0,0,1
Testing Study B,1,2,1,4,0,0,0,0,0,1

The example shows us two Fault Studies, entitled “Testing Study A” and “Testing Study B” respectively. The first row in the table is a headings row and is ignored when passed to the Multi-Fault class. It’s advised to use a template like the example above to minimise the chance of mistakes. In the second row, the respective columns are as follows:

  1. Study title

  2. Element typecode

  3. Element sequence number

  4. Reactance option

  5. Fault type

  6. Fault position

  7. Phase resistance

  8. Phase reactance

  9. Ground resistance

  10. Ground reactance

  11. Include motor contribution

See the Glossary for a full list of possible values.

Result Selection CSV file

The following table demonstrates an example Result Selection CSV file structure. It’s a similar structure to result selection for MultiLoadflow Module.

Result Selection Structure

Element Type

Summary

Busbar

Transformer

Element ID

f1

RU_Pmp1

TX_PH_ab

Result Label

f1

vip

winding1.il1

The CSV file would actually look like this in a text format:

Element Type,Summary,Busbar,Transformer
Element ID,f1,RU_Pmp1,TX_PH_ab
Result Label,f1,vip,winding1.il1

Unlike the Study Parameters CSV file, the Result Selection CSV file grows horizontally rather than vertically, meaning the first column acts as the heading and is therefore ignored by the Multi-Fault module. The first row contains the type of element, second row contains the element ID, and the third row contains the specific result to extract from the study results. The Element Type (first row) is a way of defining which result list to access. By typing “Summary” it tells the Interface to use Summary Results to find the f1 result. Since there’s no elements in summary results, the Element ID field is ignored.

See the Glossary for lists of possible results to select.

As seen in the example above, some results are nested. The transformer results are nested by windings, so to access the red phase fault current for winding 1 you need to input winding1.il1 as the result label.

Result Output CSV file

The example Result Selection CSV file above will give the following results as output.

Result Output Structure

Summary

Busbar

Transformer

f1

RU_Pmp1

TX_PH_ab

Study Name

f1

vip

winding1.il1

Testing Study A

5.63174963

0.626973152

0.055039357

Testing Study B

10.36097336

0.042896558

0.085246384

The CSV file would look like this in a text format:

,Summary,Busbar,Transformer
,f1,RU_Pmp1,TX_PH_ab
Study Name,f1,vip,winding1.il1
Testing Study A,5.631749629974365,0.6269731521606445,0.055039357393980026
Testing Study B,10.360973358154297,0.04289655759930611,0.08524638414382935

The output structure is very similar to result selection. Note how results are given per row for each study that was performed. The bold heading “Study Name” is always written into the CSV output as a heading for showing what the first column is. Being in this format makes the results easy to parse with any programming language that supports the CSV file format (Python being the recommended choice).


API

Module for running multiple fault studies easily defined programmatically or using CSV files.

class TEracsMultiFault(progressCallback=<function TEracsMultiFault.<lambda>>)

Multi-Fault class provided as the driving point for all multi-fault studies. With this class it’s very easy to run multiple fault studies. Target results and study parameters can be defined either with a CSV file or by calling the appropriate methods.

property Results

List of all results.

Type

list.

Writable

False.

LoadXml(AXmlFileName)

Loads the XML file for the network to perform the fault studies on.

Parameters

AXmlFileName (str) – The target ERACS XML file.

ReadStudiesAndTargetResultsFromCSV(AStudyParamPath, ATargetResultsPath)

Loads up two CSV files, one containing all study parameters (for each study to perform), and the other containing all target results to output.

Parameters
  • AStudyParamPath (str) – Path and file name of study parameters CSV file.

  • ATargetResultsPath (str) – Path and file name of target results CSV file.

AddTargetResult(ElementId, ElementType, ResultLabel)

Add a target result to the list of desired results to output to the results file. This method can be used in conjunction with a pre-loaded CSV file, for any additional target results not already included.

Parameters
  • ElementId (str) – The element identifier to output results for.

  • ElementType (str) – The element typecode, e.g. ‘Busbar’ for busbars.

  • ResultLabel (str) – The result identifier to output, such as ‘vin’ for busbars.

AddStudy(StudyTitle, Typecode, SeqNum, ReactOption=None, FaultType=None, FaultPos=None, Rph=None, Xph=None, Rgrnd=None, Xgrnd=None, IncMotor=None)

Adds a set of study parameters to the list of studies to perform. This is an alternative to loading a list of studies from CSV, but can be used in conjunction. If the optional parameters are not filled, defaults within the Fault module are used.

Parameters
  • StudyTitle (str) – A title of the study.

  • Typecode (int) – The typecode of the target element to apply the fault across.

  • SeqNum (int) – The sequence number of the target element to apply the fault across.

  • ReactOption (int) – (Optional) Reactance selection. Positive sequence if empty.

  • FaultType (int) – (Optional) Fault type. Single phase to earth if empty.

  • FaultPos (float) – (Optional) Fault position along a target cable/line element. 0 if empty.

  • Rph (float) – (Optional) Fault’s phase resistance. 0 if empty.

  • Xph (float) – (Optional) Fault’s phase reactance. 0 if empty.

  • Rgrnd (float) – (Optional) Fault’s ground resistance. 0 if empty.

  • Xgrnd (float) – (Optional) Fault’s ground reactance. 0 if empty.

  • IncMotor (int) – (Optional) Include motor contribution. Yes if empty.

RunStudies()

Start the multiple fault studies. This fills a local list with results. This should be called after loading all target results and study parameters from CSV.

WriteResultsToCSV(APath='MultiFaultStudyResults.csv')

Writes all internal results out to a CSV file. This should be called after running the studies with RunStudies method.

Parameters

APath (str) – (Optional) The path to the CSV file to write results to.