Injection Module
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 methodsTEracsInjectionEasy.AddInjection()
andTEracsInjectionEasy.RemoveInjection()
to change the harmonic current injection sources we use for the study, or useTEracsInjectionEasy.ClearInjections()
to clear all current injection sources from the study. Start the Harmonic Injection study the standard way by calling theCalculations.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.