ERACS Python Interface 1.1.5 (08/03/22)
About
These web pages describe the ERACS Python Interface which can be used to run ERACS calculations programmatically using the Python programming language.
Abbreviations
Various abbreviations are used throughout the ERACS Python Interface and its documentation. The list below is a brief summary of the most commonly used abbreviations.
Abbreviation |
Description |
---|---|
int |
Integer - the Python data type representing integer numbers |
float |
Float - the Python data type representing floating point (decimal) numbers |
str |
String - the Python data type representing a string of characters |
bool |
Boolean - the Python data type representing true or false |
list |
List - the Python data type representing an array of various values |
dict |
Dictionary - the Python data type representing key-value pairs |
DLL |
Dynamic-link library |
API |
Application programming interface |
GUI |
Graphical User Interface |
Prerequisites
In order to use the ERACS Python Interface effectively, you should ensure you have the following…
ERACS installed
Python (32-bit) installed
Knowledge of ERACS and power systems
Knowledge of the Python programming language
An IDE (for example: ERACS Python Editor) for writing and executing Python scripts
ERACS Version
This version of the ERACS Python Interface (1.1.5) was built for the following ERACS and calculation module versions…
ERACS 3.12.0
Loadflow 3.12.0
Fault 3.10.0
Harmonic Injection 3.11.0
Harmonic Impedance 3.10.1
Note
It is likely the Python Interface will work with other versions of ERACS and the calculation modules, but for best compatibility it’s recommended to use the same versions.
Supported Python Versions
Python 3.7.* 32-bit
Python 3.8.* 32-bit
Python 3.9.* 32-bit (recommended)
Python 3.10.* 32-bit (limited support - some dependencies do not yet support this version).
Important
The 32-bit version of Python is required for the ERACS Python Interface to work.
Note
The ERACS Python Interface is actively developed and tested with the Python versions listed above. The Interface may work with older versions of Python, but for best reliability we advise using one of the Python versions listed. For more information on setting up Python and the Interface, view Python Setup.
Note
Some example scripts require extra Python dependencies which have Python version requirements of their own. For best reliability, it’s advised to use more recent versions of Python.
Supported Virtual Environment Versions
Python 3.7+ 32-bit
The ERACS Python Interface supports the use of virtual Python environments in order to use an isolated Python installation specially configured for using the ERACS Python Interface. The Python Interface setup wizard uses venv to create the virtual environment. Venv differs between Python versions, and Python 3.7+ is recommended to ensure the virtual environment works with the ERACS Python Editor.
Notable Changes From Previous Interface Version
- Documentation improvements…
A new Prerequisites section is included in this index page.
Data.TEracsData.OpenInBrowserAsSvg()
docstring now describes the latest changes.Extensive changes elsewhere in the documentation to describe all the changes summarised below.
Rewording the important notice in the introduction.
- General improvements…
Testing the interface in the latest Python versions (3.9 and 3.10)
Copyright notices in script headings have been updated.
- Various bug fixes…
Result selection was lost when re-running studies, resolved by using
Result.TEracsResultVisibility.ApplyVisibility()
.All calculation modules are now correctly reporting their study progress.
collections.Mapping
changed toMapping
and the import uses the newcollections.abc
namespace.Winding selection for Fault has been corrected.
Added X and Y properties to element data. This is used by calculation modules with summary boxes and arrows (such as
Fault
) to position the summary box arrow between the summary box and the results.Data.TEracsData.OpenInBrowserAsSvg()
now returns a Thread object. The method is multi-threaded because it’s a long running operation. Standard multi-threading techniques can be used to join or poll the thread progress.Data.TEracsData.OpenInBrowserAsSvg()
now raisesGlobal.TEracsMissingModuleError
if the lxml dependency is missing.Result.TEracsResultVisibility.ApplyVisibility()
method ensures the interface can maintain result visibility for individual element results when re-running studies.- Improved integrity for study results…
Calculations.TEracsEasy.Invalidate()
method invalidates results when a new data object is assigned to the calculation module.Data.TEracsData.SetValue()
helper method is provided to easily change data for a given typecode and element ID. This method also invalidates results to ensure accuracy of results in relation to the latest data.When changing the data without using the helper method, it’s recommended that the user call
Calculations.TEracsEasy.Invalidate()
.Dict.TEracsDict.GetValue()
Dict.TEracsDict.TryGetValue()
andDict.TEracsDict.SetValue()
new helper methods for individual element data.New
Global.TEracsEvent
class which is used inCollection.TEracsDataCollection
. Events are raised when data is cleared or modified within the collection, andCalculations.TEracsEasy
listens to these events and handles them by calledCalculations.TEracsEasy.Invalidate()
.
- Vast improvements to results…
Exporting results to SVG from Loadflow now uses the most up-to-date format.
Exporting results to SVG from Fault is now supported.
The most up-to-date result definitions used by ERACS are exported with the results.
A new
Result.TEracsResultVisibility
class has been implemented. All individual element results inherit from this class, along with the overall results lists. This means that result Visibility can be individually managed, or managed for an entire element type. Use key methods such asResult.TEracsResultVisibility.Show()
andResult.TEracsResultVisibility.Hide()
to manage visibility.A new
Result.TEracsResultDefinitions
class has been implemented. The result definitions reside in an XML file in the ERACS template folder, and this class preprocesses them to determine the default visibility for the results.Fault now comes with a Fault arrow in the summary results.
- Extensive improvements to examples…
The Loadflow Complex GUI now supports switch group management and result visibility management. The management GUI windows have also been improved/implemented.
The Loadflow Complex GUI progress bar has been improved, it now displays for long running operations such as SVG transformations.
The Fault Complex GUI now comes with an “Open in SVG” button that exports the results to an SVG network diagram.
The Fault Complex GUI now has a progress bar to present progress of the calculation and SVG export.
The Fault Complex GUI now has a built-in window similar to Loadflow Complex GUI for managing result selection for the SVG.
Enhanced UX, such as additional scrollbars on memo fields and realigning buttons in the GUI.
- External tool improvements (ERACS Python Editor)…
Resolved a bug whereby Python 3.10 installations weren’t being detected.