22)

About

These web pages describe the ERACS Python Interface which can be used to run ERACS calculations programmatically using the Python programming language.

Authors

Dominic Edhouse, Clive Wickham, Kevin Davey

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.
- Additional constants…
  
  New STR_TYPECODE_TO_XML_ELEMENT in Constants.
  
  New CALC_PROGRESS_STEPS, and CALC_PROGRESS_DESC constants in Constants.
- 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 to Mapping and the import uses the new collections.abc namespace.
  
  Winding selection for Fault has been corrected.
- Better progress reporting…
  
  Fault, Impedance, and Injection now call all progress listeners for better progress reporting.
  
  Progress listeners should now include two arguments, an integer for the step number, and a string for the step description.
- 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 raises Global.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() and Dict.TEracsDict.SetValue() new helper methods for individual element data.
  
  New Global.TEracsEvent class which is used in Collection.TEracsDataCollection. Events are raised when data is cleared or modified within the collection, and Calculations.TEracsEasy listens to these events and handles them by called Calculations.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 as Result.TEracsResultVisibility.Show() and Result.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.