Injection Module

Inheritance diagram of Injection

Added in version 1.1.0 of the ERACS Python Interface, it’s possible to run Harmonic Injection studies using the high-level TEracsInjectionEasy class.

Adding injections

Once the Injection.TEracsInjectionEasy class has been instantiated and data passed to it, you must add injections to the study using the Injection.TEracsInjectionEasy.AddInjection() method. The method takes one argument which is a dictionary, the expected structure of the dictionary is defined in the glossary.

If you’re running multiple studies with the same Injection instance, and desire different injections per study, you can either remove an injection with Injection.TEracsInjectionEasy.RemoveInjection() or clear all injections with Injection.TEracsInjectionEasy.ClearInjections().

Example

Below is an example snippet of adding an injection source and running a Harmonic Injection study, then printing out the injection results.

 1"""
 2This example script demonstrates running a very simple injection study
 3on the Springfield Road network ("Generation On" data state) with a single
 4injection source.
 5"""
 6
 7import os
 8
 9from Eracs.Data import TEracsData
10from Eracs.Injection import TEracsInjectionEasy
11from Eracs.Global import TEracsInformation
12from Eracs.Constants import *
13
14# Constants
15# Springfield Road network ("Generation On" data state)
16XML_FILE_LOCATION = os.path.abspath(TEracsInformation().ExamplesFolder + "SpringfieldRoad_GenerationOn.xml")
17
18if __name__ == "__main__":
19    # Load data
20    data = TEracsData()
21    data.Load(XML_FILE_LOCATION)
22    # Pass to Harmonic Injection module
23    injection = TEracsInjectionEasy()
24    injection.SetData(data)
25    # Configure study setup
26    injection.StudyTitle = "Example of injection in Python"
27    injection.TripInd = HI_TRIP_IND_POS
28    injection.OutputOption = oloFULL
29    injection.TIFInd = HI_TIFIND_CCITT
30    injection.HarmOff = DEF_HARM_OFF
31    injection.cLimit = DEF_C_LIMIT
32    injection.vLimit = DEF_V_LIMIT
33    # Add one injection source
34    injection.AddInjection({
35        "seqnum": 3,
36        "typecode": tcINDUCTION,
37        "id": "6_pulse_VSD",
38        "description": "Sample data",
39        "units": IUNITS_RELATIVE,
40        "scalefact": 2.0,
41        "harmvalues": [
42            {"n": 5.0, "mag": 13.0, "angle": 120.0},
43            {"n": 7.0, "mag": 8.0, "angle": 68.0},
44            {"n": 11.0, "mag": 3.0, "angle": 140.0},
45            {"n": 13.0, "mag": 3.0, "angle": 40.0}
46        ]
47    })
48    # Run the study
49    injection.RunCalc()
50    # Print results
51    print(injection.InjectionResults)

The example loads up data from the predefined XML location, sets up the injection data by using default values from the ERACS constants module, adds an injection source on an induction machine and provides 4 different harmonic values. It then simply calls RunCalc (the same method for every calculation) and prints out the InjectionResults. This demonstrates how easy it is to setup study data, add a harmonic current injection source, and print out results after the calculation has run.


API

Injection calculation module for interfacing with the ERACS Harmonic Injection engine and running studies. To run an Injection study you should instantiate an object of the TEracsInjectionEasy class, pass in the TEracsData object, and configure injections via the AddInjection method. Once setup is complete the study can simply be performed by calling the RunCalc method.

class TEracsInjection

The low-level ERACS Injection calculation module. Use this to run Harmonic Injection studies, or use the TEracsInjectionEasy class for a simplified approach. The methods exposed by this class require structured records to be used, which are located in the InjectionRecords module.

Inherits

Harmonic.TEracsHarmonic - This module is dependent on Loadflow.

property VersionNumber

Version number of the calculation module.

Type

str.

Writable

False.

property ProgramNumber

Program number of the calculation.

Type

int.

Writable

False.

Example

1 = Loadflow

property NumberOfHarmonics

The number of harmonics returned after running an injection study.

Type

int.

Writable

False.

property HarmonicNumbers

The harmonic numbers in a list of floats after running an injection study.

Type

list of float.

Writable

False.

SetupCalculation(ASetupSimple: Eracs.InjectionRecords.THISetupData)

The second method to call in the Injection DLL after PassTDFBlock. It passes all required calculation parameters needed to run Harmonic Injection.

Parameters

ASetupSimple (THISetupData) – Object which contains a record structure holding all of the setup information and is passed to Injection.

Raises

TEracsDataError – If the number of injection sources isn’t set or if the study type is incorrectly set.

LoadTxData(ATxData: Eracs.InjectionRecords.THITxData)

Pass the data for a transformer into the Harmonic Injection module.

Parameters

ATxData (THITxData) – Object which contains a TX record structure of information.

LoadInjection(AInjection: Eracs.InjectionRecords.THIInjectionData)

Pass the data for a harmonic current injection source into the Harmonic Injection module.

Parameters

AInjection (THIInjectionData) – The harmonic current injection source data to pass to the Harmonic Injection module.

GetHarmonicNumbers()

This method call may not be strictly necessary since we could work out the number of harmonic values ourselves, but to follow what the GUI does exactly we still call this procedure. It returns back the number of harmonic values injected into the system.

Note, this is one of the few methods which doesn’t use a return code. So no return code error will be raised if something goes wrong.

class TEracsInjectionEasy

The easy way of running Harmonic Injection studies. This class contains an instance of TEracsInjection which it uses to pass in data and extract results. The results can be accessed via properties. Also, setup data is exposed via properties, apart from InjectionRecords.THISetupData.NInjections which doesn’t need to be exposed because it’ll be calculated from the injections list. Use the methods TEracsInjectionEasy.AddInjection() and TEracsInjectionEasy.RemoveInjection() to change the harmonic current injection sources we use for the study, or use TEracsInjectionEasy.ClearInjections() to clear all current injection sources from the study. Start the Harmonic Injection study the standard way by calling the Calculations.TEracsEasy.RunCalc() method.

Inherits

Harmonic.TEracsHarmonicEasy - All Loadflow-dependent harmonic easy calculation modules should inherit from this class.

property NumpyAvailable

Is the NumPy library present and available? This is an optional dependency, but IFFT results for Harmonic Injection will be null without NumPy.

Type

bool.

Writable

False.

property FundamentalFrequency

Fundamental frequency of the Injection study.

Type

float.

Writable

False.

property TimeRange

The time range used to display waveform charts in the Complex GUI example. It’s in milliseconds, and spans one frequency cycle. For a 50Hz sytem it would span 20ms.

Type

ndarray (NumPy).

Writable

False.

property NumberOfHarmonics

The number of harmonics used in the low-level API.

Type

int.

Writable

False.

property HarmonicNumbers

A list of each harmonic number used in the Injection study, grabbed from the low-level API.

Type

list of float.

Writable

False.

property HarmOff

Harmonic offset in the setup data.

Type

float.

Writable

True.

property TripInd

Triplen indicator in the study setup data.

Type

int.

Writable

True.

property OutputOption

Output option in the study setup data.

Type

int.

Writable

True.

property cLimit

Current threshold in the study setup data.

Type

float.

Writable

True.

property vLimit

Voltage threshold in the study setup data.

Type

float.

Writable

True.

property TIFInd

TIF weighting factors in the study setup data.

Type

int.

Writable

True.

property StudyType

You cannot set the study type, only Injection is supported at this moment in time.

Type

int.

Writable

False.

property InjectionResults

The injection results for the Harmonic Injection study.

Type

list.

Writable

False.

property BusbarResults

The busbar results for the Harmonic Injection study.

Type

list.

Writable

False.

property LineResults

The transmission line results for the Harmonic Injection study.

Type

list.

Writable

False.

property CableResults

The cable results for the Harmonic Injection study.

Type

list.

Writable

False.

property SeriesElementResults

The series element results for the Harmonic Injection study.

Type

list.

Writable

False.

property TransformerResults

The transformer results for the Harmonic Injection study.

Type

list.

Writable

False.

property InductionMachineResults

The induction machine results for the Harmonic Injection study.

Type

list.

Writable

False.

property SynchronousMachineResults

The synchronous machine results for the Harmonic Injection study.

Type

list.

Writable

False.

property GridInfeedResults

The grid infeed results for the Harmonic Injection study.

Type

list.

Writable

False.

property ShuntResults

The shunt results for the Harmonic Injection study.

Type

list.

Writable

False.

property Injections

The injection sources as a list of dictionaries. Expected keys include “seqnum”, “typecode”, “id”, “description”, “units”, “scalefact” and “harmvalues”. You may also provide a “keyname” key-value pair if the data already exists from the library data.

AddInjection(AInjection: dict)

Add a harmonic current injection source to the injections list. This injection source should be a dictionary (see above Injections property for a list of the expected keys). If a “keyname” key-value pair is present, the harmonic current data and element data will be located from the loaded locally referenced data, otherwise it’s assumed all necessary data is provided in the dictionary. If “keyname” is specified the injection source library elements will be searched for a match with the “keyname”.

Parameters

AInjection (dict) – The injection data to append to the injections list.

Raises
  • TEracsArgumentError – If the injection dictionary is missing expected keys or containing incorrect data such as an unsupported typecode.

  • TEracsDataError – If the injection contains too many harmonic values or the harmonic value is greater than permitted.

Returns

The index of the new item.

RemoveInjection(AIndex: int)

Remove a harmonic current injection source from the list by its index value. This will remove the injection source from the study.

Parameters

AIndex (int) – The index we should delete from the list of injections.

Returns

None.

ClearInjections()

Clear all harmonic current injection sources from the list. This will remove all injection sources from the underlying study.

Returns

None.

ClearResults()

Clears all Harmonic Injection results (usually called in the parent class RunCalc method to clear all previous results to prevent polluting the new results with the old ones).

OpenResultsInExcel(AFilePath=None, AFileName=None, ASeparateSheets=True, AOpen=True)

We are overriding the OpenResultsInExcel method from TEracsEasy because we need to process the results slightly differently so that it outputs results for each harmonic in turn.

Required

XlsxWriter Python library.

Parameters
  • AFilePath (str) – (Optional) File path to Excel file.

  • AFileName (str) – (Optional) File name to Excel file.

  • ASeparateSheets (bool) – (Optional) Ignored for Harmonic Injection.

  • AOpen (bool) – (Optional) Opens the file after writing.

Returns

Full file path as string.

Raises

TEracsError – If XlsxWriter Python Library isn’t installed.