Python Setup

The ERACS calculation modules are provided in the form of 32-bit DLLs. For that reason, the ERACS Python Interface will only work with the 32-bit edition of Python. Download Python from here.

The ERACS Python Interface is actively developed using 32-bit Python, versions 3.7, 3.8 and 3.9. To guarantee compatibility, it is recommended that you use one of those versions, but it will likely work with other versions of Python (new and old).

ERACS Python Interface Setup Wizard

The ERACS Python Interface comes with a setup wizard for installing the Interface into any existing Python installations. The benefit of this being simpler imports in your Python scripts. The installer can be explicitly launched from within ERACS via the Tools menu and Python sub-menu. Alternatively, the installer will automatically run if you open the ERACS Python Editor without having the Interface previously installed. Python is required to be installed before running the setup wizard.

The setup wizard will present you with two options…

Global - This option installs the ERACS Python Interface in all Python installations. It also runs a pip install to grab Python libraries that the interface depends on (pip is Python’s package manager). For a list of the dependencies, view the requirements.txt file in the ERACS Python folder (typically C:\Program Files (x86)\ERACS\Python\).
Virtual Environment - This option installs the ERACS Python Interface into a virtual Python environment which isolates the Interface from any other Python installations. Virtual environments are good for isolating different Python projects from each other. Also, the environment is minimal and only contains what it needs, so it’s portable. The virtual environment option should only be used if you’re experienced with Python programming and know how the virtual environment works. Further information about virtual environments can be viewed here.

Importing ERACS Modules

To use the ERACS Python Interface, import one of the modules into your script using the built-in Python import statement. There are a number of modules which make up the ERACS Python Interface; the ones listed below are of particular interest:

Data Module - For loading data from a file containing ERACS network (i.e. single-line diagram) data.
Loadflow Module - For running Loadflow studies and extracting relevant results.
Fault Module - For running Fault studies and extracting relevant results.
Impedance Module - For running Harmonic Impedance studies and extracting relevant results.
Injection Module - For running Harmonic Injection studies and extracting relevant results.

Below is an example snippet of importing some ERACS modules and using them.

"""
Importing Data and Loadflow to find out the Loadflow convergence
error of the 'SpringfieldRoad' network
"""

## System imports #############################################################
import os
## ERACS Imports ##############################################################
from Eracs import Data, Loadflow, Global
## Other Imports ##############################################################
# Nothing

if __name__ == "__main__":
   # Create the data object and load the SpringfieldRoad example network
   data = Data.TEracsData()
   data.Load(TEracsInformation().ExamplesFolder + "SpringfieldRoad.xml")

   # Create the Loadflow easy object, give it the data, and run Loadflow
   loadflow = Loadflow.TEracsLoadflowEasy()
   loadflow.SetData(data)
   loadflow.RunCalc()
   print(loadflow.SummaryResults['conv'])

The code above imports the Data Module and the Loadflow Module, opens up the ‘SpringfieldRoad’ network from the Examples folder (typically C:\Program Files (x86)\ERACS\Python\Examples\), passes the data object to Loadflow, runs Loadflow, and prints the resulting convergence error. The imports imply that namespaces are required, thus to use TEracsData you must prepend the name of the module that contains it (Data), like so…

data = Data.TEracsData()

To remove the namespaces (which isn’t advised, read the caution below) you can use the from keyword to import only the TEracsData class as follows…

from Eracs.Data import TEracsData

…or import everything from the Data module…

from Eracs.Data import *

Using either of the above from statements would change the example snippet to…

data = TEracsData()

Caution

Removing namespaces is considered an anti-pattern because it can cause complications due to naming clashes of functions and classes from multiple imports. Only remove namespaces if you know it won’t cause issues.

Dependent Modules

The ERACS Python Interface is dependent on a few modules, some of which are bundled with Python, whilst others are not but can be installed by using pip (Python’s package manager). The modules which need to be installed using pip are optional. Without the optional dependencies, the Interface will work but with limited functionality.

Optional Dependencies (installed via `pip`)

The optional dependencies are listed below, the list has been extracted from the requirements.txt file…

# ERACS Python Interface dependencies
lxml>=4.4.0
XlsxWriter>=1.1.8
numpy>=1.19.0
# ERACS Python Editor dependencies
pylint>=2.3.1

Note

All optional dependencies for the Python Interface are listed above, however, optional dependencies used by the example scripts are not listed. These dependencies are grabbed at run-time when executing an example script that is missing dependencies. Such example script dependencies are: (Matplotlib, Pillow, OpenPyXL)

Bundled Dependencies

Listed below are just some of the core dependencies provided by Python and used by the Interface.

os (and sys/path) - Operating system operations
ctypes - For loading and interacting with DLLs
xml.etree.ElementTree - For loading XML data
winreg - For accessing the Windows registry
venv - For creating a virtual environment containing the Python Interface

Note

All dependent modules should already be installed via the ERACS Python Interface Setup Wizard. Use pip list to check whether the modules are already installed. The modules are listed in the requirements.txt file in the ERACS Python folder (typically C:\Program Files (x86)\ERACS\Python\).

Python Scripts Folder

ERACS Projects is a folder inside the Documents area on your computer which acts as a default location for all ERACS projects. As of ERACS v3.10.0, the ERACS Projects folder includes a Python Scripts sub-folder. The Python Scripts sub-folder is the default location for scripts which use the ERACS Python Interface, though scripts can be saved and executed anywhere. The ERACS Python Editor automatically points to this folder so it’s recommended to store your scripts here, as they won’t be overwritten by future ERACS updates.

Caution

Do not put scripts inside the ERACS installation directory (typically C:\Program Files (x86)\ERACS\) because the scripts may be lost if overwritten by an ERACS update. The Python folder within the ERACS installation directory is only intended to house example scripts and the ERACS Python Interface itself.