Global Module

Global ERACS Python module contains all constants and core functions. Also contains classes for basic operation of running ERACS studies.

exception TEracsError

Parent class of all ERACS related exceptions.

Inherits: Exception.

exception TEracsMissingModuleError

This exception class is raised whenever ERACS tries to use a third-party module which it depends on, but cannot find it. For example; LXML.

Inherits: TEracsError.

exception TEracsArgumentError

This exception class is raised when an error is detected relating to one of the arguments passed into a method within the ERACS Python Interface.

Inherits: TEracsError.

exception TEracsDllError

This exception class is raised when an error is detected relating to a DLL in use, such as one of the calculation modules.

Inherits: TEracsError.

exception TEracsReturnCodeError(AProgramNumber, AMethodName, code)

This exception class is raised when a non-zero return code is returned from a DLL call. Each return code can have a different meaning, so this exception class uses lookup tables to include a more useful description inside the exception message to explain the reason for the return code.

Inherits: TEracsDllError.

property ReturnCode

The return code which was returned from an ERACS DLL.

Type: int.
Writable: False.
Example: 1501 (Loadflow - Bad busbar sequence number)

CompareReturnCode(AValue)

This method can be used to compare the argument against two possible values. Arguments of 1001 and 1 both refer to an EGeneralError; the 1000 signifies that it’s a Loadflow error number, so really the error code is just 1. This method takes the module prefix into account.

Returns: True if the argument matches the return code.

exception TEracsDataError

This exception class is raised when an error is detected relating to the data within a network. For example, when a mandatory key is missing from a data dictionary.

Inherits: TEracsError.

exception TEracsEventTypeError

This exception class is raised when an event type error occurs. Commonly, it is used to indicate that an event is unknown.

Inherits: TEracsError.

class TEracsWeakList(iterable=(), /)

This specially designed class holds weak references in a list, and ensures the weak references are cleared from the list when the object is garbage collected. Weak references don’t prevent garbage collection of items that have no remaining strong references.

Inherit: list.

AddObj(AItem)

Add a weak reference to an object.

Parameters: AItem (Object) – An object to weak reference in the list.
Returns: The weak reference object, this shouldn’t need to be stored to remove again, a new weakref will be created instead (inside RemoveObj).

AddMethod(AItem)

Add a weak reference to a method.

Parameters: AItem (Callable) – A method to provide a weak reference to in the list.
Returns: The weak reference object, this shouldn’t need to be stored to remove again, a new weakref will be created instead (inside RemoveMethod).

RemoveObj(AItem)

Remove a weak reference object from the list.

Parameters: AItem (Object) – An object to remove from the weak reference list.
Returns: None.

RemoveMethod(AItem)

Remove a weak reference method from the list.

Parameters: AItem (Callable) – A method to remove from the weak reference list.
Returns: None.

class TEracsEventEnum(value): This enum is used specifically to define event types raised by a class.

class TEracsEvent

This class can be inherited from by classes in the ERACS PI that require events to be exposed. An enum of possible events should be provided in the overrideable EventEnum() method. The enum will be iterated and an event dictionary will be built up internally.

EventEnum() → Global.TEracsEventEnum: Returns the event enum used by the implementing events class. This can be called from anywhere to find out what events are exposed.

AddListener(AEventType, AHandler) → None

Associate a listener to an event type exposed by this class. When the event occurs, the listener will be called.

Parameters

AEventType (Enum) – The event type of concern.
AHandler (Callable) – The listener which should be associated with the event.

Returns

None.

RemoveListener(AEventType, AHandler) → None

Remove an associated listener to an event type. The listener will no longer be called when the event occurs.

Parameters

AEventType (Enum) – The event type of concern.
AHandler (Callable) – The listener which should have its association removed.

Returns

None.

ToBytes(AStringObject)

This function was created to fix the difference in bytes() between Python versions 2 and 3.

Parameters: AStringObject (str) – A string object to be converted to a bytes object.
Returns: The bytes object.

ToString(ABytesObject)

This function was created to fix the difference in bytes() between Python versions 2 and 3.

Parameters: ABytesObject (bytes) – A bytes object, to be converted to a string object.
Returns: The string object.

DictToXml(AXmlParentElem, AKey, ADictionary)

This method takes the dictionaries containing all of the element data, and puts the dictionary data into an XML object. The method is passed a parent XML element, and the data to put into the XML element, then it goes through the data, determines if it’s a dict or list, and constructs accordingly.

Parameters

AXmlParentElem (xml) – A parent XML element that will contain all of the data e.g. <busbar><id>example</id></busbar>
AKey (str) – The key for the next element to be created e.g. “id”
ADictionary (dict) – The dictionary the data belongs to (so the value for the key can be accessed).

Returns

None (it puts the results into an instance variable ‘XmlObject’ - AXmlParentElem is the child of it).

CastToType(AKey, AValue)

Since data is read in from a file, data starts off as a string. Cast to relevant data type (such as int) to avoid confusion and possible bugs when doing conditional statements on the dictionary data.

Parameters

AKey (str/None) – The key which is used in the uploaded data, it’s used to determine whether a certain key needs to be cast or not.
AValue – A value can be any type, but it’s likely to be either a str, dict, or list. This method will recursively call itself to cast all nested elements within dicts and lists.

Returns

The cast value, might be a str, int, dict, list, or any other type.

Doctest

>>> # Import
>>> from Eracs.Global import CastToType
>>> # Test basic call with int
>>> CastToType(None, '1')
1

>>> # Test list
>>> CastToType(None, ['1', '2'])
[1, 2]

>>> # Test dictionary and nesting
>>> CastToType(None, {'k': '1', 'e': ['2']})
{'k': 1, 'e': [2]}

>>> # Test key which should remain str
>>> CastToType('id', 'bus1')
'bus1'

PIVersion(AbsPath=False)

This function returns the ERACS Python Interface version.

Returns: A string of the semantic version number x.y.z.b where x is major, y is minor, z is release/patch, and b is build.

CompareSemanticVersionString(AActualVersion, AExpectedVersion)

Compares semantic version strings and returns an integer. If the first semantic version string is higher than the second, 1 is returned. If both semantic version strings are equal, 0 is returned. If the first semantic version string is lower than the second, -1 is returned.

Parameters

AActualVersion (int) – The first parameter is considered the actual version number.
AExpectedVersion (int) – The second parameter is considered the expected version number.

Example

CompareSemanticVersionString(“3.11.0”, “3.10.0”) = 1.

Returns

An integer in [-1, 0, 1] to determine which semantic version is newer.

DocsVersion(AbsPath=False)

This function returns the ERACS Python Interface version number but only as 3 segments (it gets rid of the build number) because the documentation doesn’t need to know or display build number.

Returns: A string of the semantic version number x.y.z where x is major, y is minor, and z is release/patch.

ListOfDicts(AList)

This method ensures the dictionary is in a list, so when append is called it can call this method to always treat it as a list of dictionaries, regardless of whether a dictionary is passed into append, or a list of dictionaries.

Parameters

AList (list/dict) – The list or dict which should be a list.

Returns

The dictionary in a single-item list, or the original list.

Doctest

>>> # Import
>>> from Eracs.Global import ListOfDicts
>>> # Test basic call with dict
>>> ListOfDicts({'test': 2})
[{'test': 2}]

>>> # Test basic call with list
>>> ListOfDicts(['test'])
['test']

class TEracsInformation

This class can be used to get important information about ERACS. For example it has properties for all important directories relating to ERACS.

property DongleSolution

Specifies whether the user is using a dongle solution.

Type: int.
Writable: False.

property ConfigurationFolder

Points to the Configuration folder within the ERACS installation.

Type: str.
Writable: False.

property InstallationFolder

Points to the main installation folder for ERACS.

Type: str.
Writable: False.

property PythonFolder

Points to the Python folder within the ERACS installation.

Type: str.
Writable: False.

property InterfaceFolder

Points to the Interface folder residing in the Python folder of the ERACS installation.

Type: str.
Writable: False.

property ExamplesFolder

Points to the Examples folder residing in the Python folder of the ERACS installation.

Type: str.
Writable: False.

property TemplateFolder

Points to the Template folder within the ERACS installation.

Type: str.
Writable: False.

property NetworksFolder

Points to the Networks folder within the ERACS installation.

Type: str.
Writable: False.

property IsInstalled

Checks whether ERACS is installed, returns 0 = true, any other value false.

Type: int.
Writable: False.

property SilentSecurity

Whether silent security is enabled.

Type: bool.
Writable: False.

property ERACSVersionNumber

The version number for the ERACS installation.

Type: str.
Writable: False.

property LoadflowVersionNumber

The version number for the Loadflow calculation module.

Type: str.
Writable: False.

property FaultVersionNumber

The version number for the Loadflow calculation module.

Type: str.
Writable: False.

property ImpedanceVersionNumber

The version number for the Loadflow calculation module.

Type: str.
Writable: False.

property InjectionVersionNumber

The version number for the Loadflow calculation module.

Type: str.
Writable: False.

class TEracsDllLoader

Class used to load a DLL. This class is used extensively throughout the ERACS Python Interface for loading up each calculation module and all other dependent DLLs.

property Dll

The loaded DLL reference.

Type: WinDLL
Writable: False.

property Loaded

Is the DLL loaded?

Type: bool.
Writable: False.

property RunRecommendedCheck

The recommended check will check to see whether any recommended (optional) dependencies are available. This property determines whether that check is performed. It’s advised to keep this enabled, unless you know it can be disabled.

Type: bool.
Writable: True.

property DependencyList

List of all dependent DLLs.

Type: list.
Writable: False.

property RecommendedList

List of all recommended DLLs.

Type: list.
Writable: False.

UnloadDLL()

Unload any loaded DLL, freeing up any resources associated with it. Unload DLLs once their use is finished.

Raises: TEracsDllError – If the DLL could not be freed (perhaps it wasn’t loaded in the first place?).

LoadDLL(ADllFile)

This function can be used to load a DLL from the main ERACS installation folder,

Parameters

ADllFile (str) – The full path of the DLL, or just the DLL file name (with or without the .dll extension). If a path is provided, that path will be used, otherwise it will look through the Python system paths.

Use

example: LoadDLL(self._DllName())

Raises

TEracsError – If using a 64-bit version of Python which isn’t supported.
TEracsDllError – If the DLL didn’t load successfully, possibly due to the path being wrong, DLL not existing, etc.

class TEracsEnviron

This class sets up the environment such as loading the security DLL and setting global variables. This class can be used to toggle silent security and other core features.

property XlsxWriterAvailable

Is the XlsxWriter library present and available?

Type: bool.
Writable: False.

property LxmlAvailable

Is the lxml library present and available?

Type: bool.
Writable: False.

property EracsInformation

An object of the TEracsInformation class.

Type: TEracsInformation.
Writable: False.

property LoadflowEnabled

Is the Loadflow calculation available to the user?

Type: bool.
Writable: False.

property ImpedanceEnabled

Is the Harmonic Impedance calculation available to the user?

Type: bool.
Writable: False.

property FaultEnabled

Is the Fault calculation available to the user?

Type: bool.
Writable: False.

property InjectionEnabled

Is the Injection calculation available to the user?

Type: bool.
Writable: False.

property SilentSecurity

Silent security will authenticate the user behind-the-scenes if possible.

Type: bool.
Writable: True.

EndSession()

class TEracsEngineInterface(*args)

The engine interface classes are designed to assist with interacting with calculation engines, and are the main driving points when running a calculation. These classes hold an object reference to a complex (lower-level) class underneath, so for example, when loading a busbar into a Loadflow study, you should use this class to modify any attributes, which will in turn be reflected in the underlying low-level object which is passed straight to Loadflow.

property Object

The complex/low-level object which is passed to the calculation engine as a record structure.

Type: Varies, depending on the type of the descendant class. For example, LoadflowRecords.TLFBusData has an object of type _TLFBusDataComplex.
Writable: False.

class TEracsEngineInterfaceResult(*args)

This class is used to represent result information. The underlying object is passed to Loadflow and populated, the results are then available within the ERACS Python Interface.

Inherits: TEracsEngineInterface.

StoreIntoDictionary(AOutputDictionary: dict)

Store all information from the underlying object into a dictionary.

Parameters: AOutputDictionary (dict) – The dictionary to populate with field data.
Raises: TEracsArgumentError – If first argument is not a dict.

class TEracsEngineInterfaceResultElement(*args)

The results for a specific element type are represented with this class. For example, FaultRecords.TFBusbarResult inherits from this class, with the busbar being the element the results are for. This class stores common information for all element results, such as sequence numbers.

Inherits: TEracsEngineInterfaceResult.

property SequenceNumber

The sequence number of the element result.

Type: int.
Writable: False.

class TEracsEngineInterfaceData(*args)

This class should be inherited and used for all data being passed into the calculation engines. It provides common methods for all descendants which will represent data passed to the calculation engines, such as SetDefaults, WriteBytes, and ClearBytes (for writing and clearing identifier strings).

Inherits: TEracsEngineInterface.

SetDefaults()

This method should be called to set the default values before loading up the next set of data. This class’s object is re-used for all elements, so restoring default values beforehand is important to avoid bugs.

Raises: TEracsDataError – If any of the keys are missing.

WriteBytes(ABuffer, AString)

Writes a string to the bytes object buffer. This is used to populate fields which are strings, such as the element identifier.

Parameters

ABuffer (int) – The size of the bytes array.
AString (str) – The string to populate into the bytes array.

Raises

TEracsDataError – If it fails to write bytes. Was a string passed in?

ClearBytes(ABuffer)

Clears the bytes object buffer so that it contains empty characters. This helps prevent bugs, otherwise characters won’t be cleared from the buffer and may appear in other element data.

Parameters: ABuffer (int) – The size of the bytes buffer to clear.

ReadBytes(ABuffer)

Read the string contained within the bytes object buffer. This is a method provided for simplifying access, this way the element identifiers can be easily read.

Parameters: ABuffer (int) – The size of the bytes buffer to read from.
Returns: The string read from the bytes buffer.

class TEracsEngineInterfaceSetupData(*args)

This class is specifically for containing setup data for the calculation engine. It contains setup specific data such as network name and data state name.

Inherits: TEracsEngineInterfaceData.

property NetworkName

Name of the network being used in the study.

Type: str.
Writable: True.

property StateName

Name of the data state being used in the study.

Type: str.
Writable: True.

property UserID

Name of the original user who created the network.

Type: str.
Writable: True.

property ChangeID

Name of the user who last modified the network (and is likely running this study).

Type: str.
Writable: True.

property SysDate

System date of the study being performed.

Type: str.
Writable: False.

SetDefaults()

This method should be called to set the default values before loading up the next set of data. This class’s object is re-used for all elements, so restoring default values beforehand is important to avoid bugs.

Raises: TEracsDataError – If any of the keys are missing.

LoadHeaders(AHeaderDictionary)

Loads headers into the setup data, which includes network and data state names.

Parameters: AHeaderDictionary (dict) – This dictionary contains header specific information.
Raises: TEracsDataError – If expected keys are missing from the given dictionary.

class TEracsEngineInterfaceDataElement(*args)

This class holds data for an element. This class should be inherited from for more specific data shared between all elements of a particular type. This class contains properties, such as sequence number, which are common to all ERACS elements.

Inherits: TEracsEngineInterfaceData.

property SequenceNumber

The sequence number of the element being passed to the calculation engine.

Type: int.
Writable: True.

property SeqNum

Alternative to SequenceNumber property.

Type: int.
Writable: True.

property ID

The Identifier of the element.

Type: str.
Writable: True.

property TypeCode

The Typecode which identifies the element type.

Type: int.
Writable: True.

SetDefaults()

This method should be called to set the default values before loading up the next set of data. This class’s object is re-used for all elements, so restoring default values beforehand is important to avoid bugs.

Raises: TEracsDataError – If any of the keys are missing.

class TEracsEngineInterfaceDataElementWithLibrary(*args)

This class should be inherited from classes which represent element data containing library information. For example, this class is inherited from TLFLineCableData and TLFSeriesElementData. This class provides the library key property, so it doesn’t have to be redefined in descendants.

Inherits: TEracsEngineInterfaceDataElement.

property LibraryKey

The library key for the element (in the ERACS database).

Type: str.
Writable: True.

SetDefaults()

This method should be called to set the default values before loading up the next set of data. This class’s object is re-used for all elements, so restoring default values beforehand is important to avoid bugs.

Raises: TEracsDataError – If any of the keys are missing.