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