Tutorial¶

Requirements¶

Applications¶

The PSCAD Automation Library requires the following tools are installed:

PSCAD 4.6.3
Python 3.x (such as Python 3.7.1)
- PIP - Python’s package manager (included with Python 3.4 and later)
- PyWin32 - Python extensions for Microsoft Windows

Installation of the above programs is beyond the scope of this tutorial.

Automation Library¶

You can check which version of the Automation Library is installed by executing:

py -m mhrc.automation

If multiple versions of Python have been installed, each installation will need its own copy of the Automation Library, so you may want specify the Python version being queried:

py -3.7 -m mhrc.automation

PSCAD’s “Update Client” will automatically install the Automation Library into the latest Python 3.x installation. If you wish to add the Automation Library to a different Python 3.x installation, you would execute a PIP install command similar to the following from the C:\Program Files (x86)\PSCAD\AutomationLibrary\463\Installs\PyAL directory:

py -3.4 -m pip install mhrc_automation-1.2.4-py3-none-any.whl

My First Automation Script¶

Running the Tutorial¶

The following script is the “simplest” PSCAD automation script that does something useful. It:

launches PSCAD,

loads the “Tutorial” workspace,

runs all simulation sets in the “Tutorial” workspace, and

quits PSCAD.

To keep this first example simple, no error checking of any kind is done. Also, no feedback from the simulation is retrieved for the same reason.

#! python3
import mhrc.automation

# Launch PSCAD
pscad = mhrc.automation.launch_pscad()

# Load the tutorial workspace
pscad.load(r"C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\Tutorial.pswx")

# Run all the simulation sets in the workspace
pscad.run_all_simulation_sets()

# Exit PSCAD
pscad.quit()

Many assumptions are being made here.

Certificate licensing is used, and a license certificate can be automatically acquired.

Ensure “Retain certificate” is selected under “Certificate Licensing ➭ Termination Behaviour” and ensure you hold a valid certificate when you exit PSCAD before running the above script.
The “Public Documents” directory is located at C:\Users\Public\Documents.
The 64-bit version PSCAD 4.6.3 is installed.

Finding the Tutorial¶

We can relax the last two restrictions by retrieving the correct location of the “Public Documents” directory from PyWin, and searching inside that directory for the “Tutorial” workspace. Doing so will allow the scripts in this tutorial to be downloaded and executed without modification by the reader.

Alter the import statements at the top of the script to read:

import mhrc.automation, os
from win32com.shell import shell, shellcon

To retrieve the “Public Documents” folder, add the following statement below the imports:

# Find "Public Documents" folder
#   Probably "C:\Users\Public\Documents"
public_dir = shell.SHGetFolderPath(0, shellcon.CSIDL_COMMON_DOCUMENTS, None, 0)

Beneath this statement, add another which will search inside the “PSCAD” folder for a subdirectory which contains the desired Tutorial.pswx file:

# Find the "Tutorial" workspace
#   Probably "<Public Documents>\PSCAD\4.6.3\Examples\tutorial\Tutorial.pswx"
tutorial_dir = next(root for root, _, files in os.walk(
    os.path.join(public_dir, "PSCAD") ) if "Tutorial.pswx" in files)

Finally, change the pscad.load() statement to load the Tutorial.pscx workspace from that directory:

# Load the tutorial workspace
pscad.load(os.path.join(tutorial_dir, "Tutorial.pswx"))

See the resulting script.

Logging¶

Add logging to the current imports, and add the logging.basicConfig statement below:

import mhrc.automation, os, logging
from win32com.shell import shell, shellcon

# Log 'INFO' messages & above.  Include level & module name.
logging.basicConfig(level=logging.INFO,
                    format="%(levelname)-8s %(name)-26s %(message)s")

If you now run the script, you should see something similar to following output. The paths, port numbers, and process ID’s may be different:

INFO     mhrc.automation.controller Launching PSCAD 4.6.3 (x64): C:\Program Files (x86)\PSCAD463 x64 Testing\bin\win64\Pscad.exe
INFO     mhrc.automation.pscad      Server socket bound to 0.0.0.0 port 51312
INFO     mhrc.automation.pscad      Process ID = 3836
INFO     mhrc.automation.pscad      Waiting for connection on ('0.0.0.0', 51312)
INFO     mhrc.automation.pscad      Connected to ('127.0.0.1', 51313)
INFO     mhrc.automation.pscad      Loading ('C:\\Users\\Public\\Documents\\PSCAD\\4.6.3\\Examples x64\\tutorial\\Tutorial.pswx',)
INFO     mhrc.automation.pscad      Run all simulation sets
INFO     mhrc.automation.pscad      Quiting PSCAD

In the next steps, we’ll be adding additional logging to our script. The logging already built into the automation library can be squelched to warnings and above, so it is easier to see our own log messages. After the logging.basicConfig( … ) line, add the following:

# Ignore INFO msgs from automation (eg, mhrc.automation.controller, ...)
logging.getLogger('mhrc.automation').setLevel(logging.WARNING)

LOG = logging.getLogger('main')

Next, add logging lines to print out the location of the “Public Documents” and “tutorial” directories:

LOG.info("Public Documents  : %s", public_dir)
LOG.info("Tutorial directory: %s", tutorial_dir)

If you now run the script, you should see something similar to following output. Again, the paths may be different, which is of course the whole point of this exercise:

INFO     main                       Public Documents  : C:\Users\Public\Documents
INFO     main                       Tutorial directory: C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial

Error Handling¶

If the automation controller cannot launch PSCAD, it will log the reason why to the console and return the value None. Other problems may be signalled by an “Exception” being raised. A well behaved script must catch these exceptions, and properly clean up. This cleanup should include closing PSCAD.

Replace the final 3 commands in the script with the following:

if pscad:

    try:
        # Load the tutorial workspace
        pscad.load(os.path.join(tutorial_dir, "Tutorial.pswx"))

        # Run all the simulation sets in the workspace
        pscad.run_all_simulation_sets()

    finally:
        # Exit PSCAD
        pscad.quit()

else:
    LOG.error("Failed to launch PSCAD")

Whether or not an exception occurs during the loading of the workspace or running all simulation sets, due to the try: ... finally: ... block, PSCAD will always be terminated before the script terminates.

Launch Options¶

Minimize PSCAD¶

When PSCAD is started, it normally opens the PSCAD window. During automation, it is sometimes desirable to launch PSCAD with its window “minimized”, reducing the amount “screen flickering”, as well as the chance a stray mouse click could “poison” a running automation.

Add minimized=True to the launch_pscad() call:

# Launch PSCAD
pscad = mhrc.automation.launch_pscad(minimize=True)

Run this new script. You should still see log messages in the Python Shell, and PSCAD appear in the Task Bar, but no PSCAD window should open.

Note

PSCAD remembers where it is on the screen, including whether or not it is “maximized”. When it is launched, it restores itself to that position and, if required, maximized state. The automation library cannot override the remembered “maximized” state. If PSCAD remembers that it was last “maximized”, it will maximize itself, regardless of whether it was launched in a “minimized” state by the automation library. Manually launching PSCAD, de-maximizing it, and quitting it will fix this issue.

PSCAD Version¶

The launch_pscad() method does a bit of work behind the scenes. If more than one version of PSCAD is installed, it tries to pick the best version to run. “Best” in this context means:

not an “Alpha” version, if other choices exist, then
not a “Beta” version, if other choices exist, then
not a 32-bit version, if other choices exist, finally
the “lexically largest” version of the choices that remain.

Instead of letting launch_pscad() choose the version, the script can specify the exact version to use with the pscad_version=... parameter. For example, to launch the 64-bit version of PSCAD 4.6.3, use:

pscad = mhrc.automation.launch_pscad(pscad_version='PSCAD 4.6.3 (x64)')

A controller object may be queried to determine which versions of PSCAD are installed. Replacing the launch_pscad() statement with the following will mimic its selection process:

controller = mhrc.automation.controller()
versions = controller.get_paramlist_names('pscad')
LOG.info("PSCAD Versions: %s", versions)

# Skip any 'Alpha' versions, if other choices exist
vers = [ver for ver in versions if 'Alpha' not in ver]
if len(vers) > 0:
    versions = vers

# Skip any 'Beta' versions, if other choices exist
vers = [ver for ver in versions if 'Beta' not in ver]
if len(vers) > 0:
    versions = vers

# Skip any 32-bit versions, if other choices exist
vers = [ver for ver in versions if 'x86' not in ver]
if len(vers) > 0:
    versions = vers

LOG.info("   After filtering: %s", versions)

# Of any remaining versions, choose the "lexically largest" one.
version = sorted(versions)[-1]
LOG.info("   Selected PSCAD version: %s", version)

# Launch PSCAD
LOG.info("Launching: %s", version)
pscad = mhrc.automation.launch_pscad(pscad_version=version, minimize=True)

With the above changes to the script, the output may be:

INFO     main                       Public Documents  : C:\Users\Public\Documents
INFO     main                       Tutorial directory: C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial
INFO     main                       PSCAD Versions: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)', 'PSCAD Beta (x64)']
INFO     main                          After filtering: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)']
INFO     main                          Selected PSCAD version: PSCAD 4.6.3 (x64)
INFO     main                       Launching: PSCAD 4.6.3 (x64)

Fortran Version¶

In a similar fashion, the controller object may be queried for which versions of FORTRAN are installed.

Before the launch_pscad() line, add the following:

# Get all installed FORTRAN compiler versions
fortrans = controller.get_paramlist_names('fortran')
LOG.info("FORTRAN Versions: %s", fortrans)

# Skip 'GFortran' compilers, if other choices exist
vers = [ver for ver in fortrans if 'GFortran' not in ver]
if len(vers) > 0:
    fortrans = vers

LOG.info("   After filtering: %s", fortrans)

# Order the remaining compilers, choose the last one (highest revision)
fortran = sorted(fortrans)[-1]
LOG.info("   Selected FORTRAN version: %s", fortran)

Add the , fortran_version=fortran parameter to the launch_pscad() call:

# Launch PSCAD
LOG.info("Launching: %s  FORTRAN=%r", version, fortran)
pscad = mhrc.automation.launch_pscad(pscad_version=version, minimize=True,
                                     fortran_version=fortran)

With the above changes to the script, the output may be:

INFO     main                       Public Documents  : C:\Users\Public\Documents
INFO     main                       Tutorial directory: C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial
INFO     main                       PSCAD Versions: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)', 'PSCAD Beta (x64)']
INFO     main                          After filtering: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)']
INFO     main                          Selected PSCAD version: PSCAD 4.6.3 (x64)
INFO     main                       FORTRAN Versions: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          After filtering: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          Selected FORTRAN version: GFortran 4.6.2
INFO     main                       Launching: PSCAD 4.6.3 (x64)  FORTRAN='GFortran 4.6.2'

Matlab Version¶

In a similar fashion, the controller object may be queried for which versions of Matlab are installed. Matlab, unlike FORTRAN, is not required for PSCAD to run, so there may be no versions of Matlab installed.

Before the launch_pscad() line, add the following:

# Get all installed Matlab versions
matlabs = controller.get_paramlist_names('matlab')
LOG.info("Matlab Versions: %s", matlabs)

# Get the highest installed version of Matlab:
matlab = sorted(matlabs)[-1] if matlabs else None
LOG.info("   Selected Matlab version: %s", matlab)

Add the , matlab_version=matlab parameter to the launch_pscad() call:

# Launch PSCAD
LOG.info("Launching: %s  FORTRAN=%r   Matlab=%r", version, fortran, matlab)
pscad = mhrc.automation.launch_pscad(pscad_version=version, minimize=True,
                                     fortran_version=fortran,
                                     matlab_version=matlab)

With the above changes to the script, the output may be:

INFO     main                       Public Documents  : C:\Users\Public\Documents
INFO     main                       Tutorial directory: C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial
INFO     main                       PSCAD Versions: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)', 'PSCAD Beta (x64)']
INFO     main                          After filtering: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)']
INFO     main                          Selected PSCAD version: PSCAD 4.6.3 (x64)
INFO     main                       FORTRAN Versions: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          After filtering: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          Selected FORTRAN version: GFortran 4.6.2
INFO     main                       Matlab Versions: []
INFO     main                          Selected Matlab version: None
INFO     main                       Launching: PSCAD 4.6.3 (x64)  FORTRAN='GFortran 4.6.2'   Matlab=None

PSCAD Settings¶

To ensure reliable, repeatable tests, the automation library instructs PSCAD to use the default settings, ignoring any stored user settings.

The pscad.settings() method must be used to change any application settings to the desired value.

The following script may be used to determine what settings exist, and their current values:

#! python3
import mhrc.automation

pscad = mhrc.automation.launch_pscad(minimize=True)

for key, value in sorted(pscad.settings().items()):
    print("%33s: %s" % (key, value))

pscad.quit()

And produces output similar to:

                   AvoidLocalExec: 1
                DetectedCoreCount: 
                    EMTDC_Version: 
                           Folder: 
            LCP_MaxConcurrentExec: 8
                      LCP_Version: 
                    MEDIC_Version: 
                 MaxConcurrentSim: 8
                      VersionText: Not installed
                  active_graphics: 2
                       agent_show: true
                    backup_enable: true
                    backup_folder: $(LocalDir)\FileBackups
                      backup_freq: 60
⋮               ⋮               ⋮               ⋮

To change settings from their defaults, pass one or more key=value arguments to the pscad.settings() method:

pscad.settings(MaxConcurrentSim=8, LCP_MaxConcurrentExec=8)

Note

All settings are automatically converted to strings before passing to PSCAD. There is no functional difference between pscad.settings(MaxConcurrentSim=8) and pscad.settings(MaxConcurrentSim="8").

PSCAD returns all settings as strings. If a numeric setting is expected, the Python script is responsible for converting the string into an integer. Booleans may be returned as "true" or "false", without the first letter capitalized; again the Python script must accept responsibility for converting the strings into Python boolean values True and False if required.

Projects¶

To run all loaded projects, one at a time, we first obtain a list of all projects. From this list, we filter out any libraries, which are not runnable. Then, we retrieve a Project controller for each project, and call Project.run() on each one, in turn.

Replace the pscad.run_all_simulation_sets() line with the following:

        # Get a list of all projects
        projects = pscad.list_projects()

        # Filter out libraries; only keep cases.
        cases = [prj for prj in projects if prj['type'] == 'Case']

        # For each case ...
        for case in cases:
            project = pscad.project(case['name'])

            LOG.info("Running '%s' (%s)", case['name'], case['description'])
            project.run();
            LOG.info("Run '%s' complete", case['name'])

This script would produce:

INFO     main                       Public Documents  : C:\Users\Public\Documents
INFO     main                       Tutorial directory: C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial
INFO     main                       PSCAD Versions: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)', 'PSCAD Beta (x64)']
INFO     main                          After filtering: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)']
INFO     main                          Selected PSCAD version: PSCAD 4.6.3 (x64)
INFO     main                       FORTRAN Versions: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          After filtering: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          Selected FORTRAN version: GFortran 4.6.2
INFO     main                       Matlab Versions: []
INFO     main                          Selected Matlab version: None
INFO     main                       Launching: PSCAD 4.6.3 (x64)  FORTRAN='GFortran 4.6.2'   Matlab=None
INFO     main                       Running 'chatter' (Simple case with chatter elimination)
INFO     main                       Run 'chatter' complete
INFO     main                       Running 'fft' (Harmonic Impedance and FFT)
INFO     main                       Run 'fft' complete
INFO     main                       Running 'inputctrl' (Input Control Components)
INFO     main                       Run 'inputctrl' complete
INFO     main                       Running 'interpolation' (Simple case illustrating interpolation)
INFO     main                       Run 'interpolation' complete
INFO     main                       Running 'legend' (Use of macros)
INFO     main                       Run 'legend' complete
INFO     main                       Running 'vdiv' (Single Phase Voltage Divider)
INFO     main                       Run 'vdiv' complete
INFO     main                       Running 'simpleac' (A Simple AC Power System)
INFO     main                       Run 'simpleac' complete
INFO     main                       Running 'multirun' (A Simple Multiple Run Example)
INFO     main                       Run 'multirun' complete
INFO     main                       Running 'pagearray' (Page Inside a Page, Arrays)
INFO     main                       Run 'pagearray' complete

Simulation Sets¶

When a workspace contains multiple projects, they may be required to run together or in a particular sequence. A simulation set is often used to control the collection of projects.

Instead of blindly running all projects in the workspace, or simply all simulation sets, we may retrieve the list of simulations sets and run each simulation set individually, under the control of our script. If no simulation sets are found, we can fall back to running each project separately.

Replace the code we just added, with this code instead:

        workspace = pscad.workspace()

        # Get the list of simulation sets in the workspace
        sim_sets = workspace.list_simulation_sets()
        if len(sim_sets) > 0:
            LOG.info("Simulation sets: %s", sim_sets)

            # For each simulation set ...
            for sim_set_name in sim_sets:
                # ... run it
                LOG.info("Running simulation set '%s'", sim_set_name)
                sim_set = workspace.simulation_set(sim_set_name)
                sim_set.run()
                LOG.info("Simulation set '%s' complete", sim_set_name)
        else:
            # Get a list of all projects
            projects = pscad.list_projects()

            # Filter out libraries; only keep cases.
            cases = [prj for prj in projects if prj['type'] == 'Case']

            # For each case ...
            for case in cases:
                project = pscad.project(case['name'])

                LOG.info("Running '%s' (%s)", case['name'], case['description'])
                project.run();
                LOG.info("Run '%s' complete", case['name'])

This version of the script runs all projects simultaneously, producing the following output:

INFO     main                       Public Documents  : C:\Users\Public\Documents
INFO     main                       Tutorial directory: C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial
INFO     main                       PSCAD Versions: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)', 'PSCAD Beta (x64)']
INFO     main                          After filtering: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)']
INFO     main                          Selected PSCAD version: PSCAD 4.6.3 (x64)
INFO     main                       FORTRAN Versions: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          After filtering: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          Selected FORTRAN version: GFortran 4.6.2
INFO     main                       Matlab Versions: []
INFO     main                          Selected Matlab version: None
INFO     main                       Launching: PSCAD 4.6.3 (x64)  FORTRAN='GFortran 4.6.2'   Matlab=None
INFO     main                       Simulation sets: ['default']
INFO     main                       Running simulation set 'default'
INFO     main                       Simulation set 'default' complete

If, instead of loading Tutorial.pswx, we just loaded vdiv.pscx project:

        # Load only the 'voltage divider' project
        pscad.load(os.path.join(tutorial_dir, "vdiv.pscx"))

there are no simulation sets, so the else: path is taken in our script, and the vdiv project is run:

INFO     main                       Public Documents  : C:\Users\Public\Documents
INFO     main                       Tutorial directory: C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial
INFO     main                       PSCAD Versions: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)', 'PSCAD Beta (x64)']
INFO     main                          After filtering: ['PSCAD 4.6.2 (x64)', 'PSCAD 4.6.3 (x64)']
INFO     main                          Selected PSCAD version: PSCAD 4.6.3 (x64)
INFO     main                       FORTRAN Versions: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          After filtering: ['GFortran 4.2.1', 'GFortran 4.6.2']
INFO     main                          Selected FORTRAN version: GFortran 4.6.2
INFO     main                       Matlab Versions: []
INFO     main                          Selected Matlab version: None
INFO     main                       Launching: PSCAD 4.6.3 (x64)  FORTRAN='GFortran 4.6.2'   Matlab=None
INFO     main                       Running 'vdiv' (Single Phase Voltage Divider)
INFO     main                       Run 'vdiv' complete

Event Monitoring¶

Event Handlers¶

The Automation Library will allow you to observe the communications between the automation library and the PSCAD process.

At the top of the file, add the following “Handler” class:

import xml.etree.ElementTree as ET

class Handler:

    def send(self, msg):
        if msg is None:
            LOG.info("Tick")
        else:
            event = msg.find('event')
            if event is not None:
                detail = str(ET.tostring(event), 'utf-8')
                LOG.info("%s", detail)

    def close(self):
        pass

Following the successful launch of PSCAD, we can create an instance of our Handler class, and attach it to the PSCAD instance. After the if pscad:, add the following two lines:

if pscad:

    handler = Handler()
    pscad.add_handler(handler)

After downgrading some of the earlier LOG.info(...) messages to LOG.debug(...) message, if we run this script, we might see:

INFO     main                       Launching: PSCAD 4.6.3 (x64)  FORTRAN='GFortran 4.6.2'   Matlab=None
INFO     main                       <event type="LoadEvent"><type Task="1662" file-type="files" status="BEGIN" /></event>
INFO     main                       <event type="LoadEvent"><type Task="1688" file-type="workspace" status="BEGIN" /><file>C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.pscx</file></event>
INFO     main                       <event type="LoadEvent"><type Task="1688" file-type="workspace" status="END" /><file>C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.pscx</file><project Description="Single Phase Voltage Divider" name="vdiv" type="Case" /></event>
INFO     main                       <event type="LoadEvent"><type Task="1662" file-type="files" status="END" /></event>
INFO     main                       Running 'vdiv' (Single Phase Voltage Divider)
INFO     main                       <event type="BuildEvent"><type Task="1765" name="Workspace" status="BEGIN" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="1767" name="Project Builder" status="BEGIN" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="1768" name="Project Compile" status="BEGIN" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="1768" name="Project Compile" status="END" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="9288" name="EMTDC MAKE" status="BEGIN" /></event>
INFO     main                       Tick
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="9288" name="EMTDC MAKE" status="END" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="1767" name="Project Builder" status="END" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="1787" name="Project Solver" status="BEGIN" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="1787" name="Project Solver" status="END" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><rank value="1" /><type Task="1788" name="Mediator" status="BEGIN" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="14008" name="EMTDC RUN" status="BEGIN" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><rank value="1" /><type Task="1788" name="Mediator" status="END" /></event>
INFO     main                       <event type="BuildEvent"><project name="vdiv" /><type Task="14008" name="EMTDC RUN" status="END" /></event>
INFO     main                       Run 'vdiv' complete

As messages are received from PSCAD, the automation library sends the message to each registered handler, by calling handler.send(msg). The handler can do pretty much whatever it wants with the message. If it consumes the message, and doesn’t want any subsequent handler from seeing it, the handler should return True.

After a period of time when no messages have been sent back from PSCAD, the automation library also sends a blank message to the handler, by calling handler.send(None). This allows the handler a chance to do additional processing. For instance, the Automated Test Suite’s ProgressHandler uses those opportunities to send a get-run-status command to the various projects, in order to track % complete.

Removing Handlers¶

If the script decides a certain handler is no longer required, the script can remove it by calling pscad.remove_handler( handler ).

Automatic Removal¶

Since the handler is receiving messages from PSCAD, it is usually in the best position to determine when a particular process is complete. The handler can indicate this to the automation library, by returning the special value StopIteration, or by raising the StopIteration exception. When this happens, the automation library will automatically remove the handler.

For example, the Load process is complete when a load event is found with a file-type of files and a status of END. Change the Handler’s send() method to the following code:

    def send(self, msg):
        if msg is not None:
            event = msg.find('event')
            if event is not None:
                detail = str(ET.tostring(event), 'utf-8')
                LOG.info("%s ...", detail[:70])
                event_type = event.find('type')
                file_type = event_type.get('file-type')
                status = event_type.get('status')
                if file_type == 'files'  and  status == 'END':
                    LOG.info("Load must be complete.")
                    return StopIteration

When this new script is run, this much shorter output results:

INFO     main                       Launching: PSCAD 4.6.3 (x64)  FORTRAN='GFortran 4.6.2'   Matlab=None
INFO     main                       <event type="LoadEvent"><type Task="1662" file-type="files" status="BE ...
INFO     main                       <event type="LoadEvent"><type Task="1688" file-type="workspace" status ...
INFO     main                       <event type="LoadEvent"><type Task="1688" file-type="workspace" status ...
INFO     main                       <event type="LoadEvent"><type Task="1662" file-type="files" status="EN ...
INFO     main                       Load must be complete.
INFO     main                       Running 'vdiv' (Single Phase Voltage Divider)
INFO     main                       Run 'vdiv' complete

Build Events¶

Build Events are generated when PSCAD builds and runs cases. A build event handler might be installed just before executing the run command, and removed just after the run command finished. Code to do thing might look like this:

handler = BuildEventHandler()
pscad.add_handler(handler)
project.run()
pscad.remove_handler(handler)

This is a lot of boiler-plate code. As a convenience, the automation library will perform the add_handler and remove_handler calls itself, if the handler is passed to the run( ) command directly:

project.run( BuildEventHandler() )

Note

When used this way, it is the handler’s auto-termination that indicates the run( ) command is complete. The handler must properly detect the completion of the run task.

Add an import for mhrc.automation.handler:

from win32com.shell import shell, shellcon
import mhrc.automation, os, logging
import mhrc.automation.handler
import xml.etree.ElementTree as ET

Replace the Handler code from the previous section with the following:

class BuildEventHandler(mhrc.automation.handler.BuildEvent):

    def _build_event(self, msg, event):
        elapsed = int(msg.get('elapsed'))
        etype = event.find('type')
        phase = etype.get('name')
        status = etype.get('status')
        project = event.find('project')
        prj_name = project.get('name') if project is not None else None

        LOG.info("BuildEvt: [%s] %s/%s %d", prj_name, phase, status, elapsed)

        return super()._build_event(msg, event)

Here, we are extending a standard BuildEvent handler. Its send() method already looks for build event messages, and forwards them to the _build_event() method. Its _build_event() method looks for matching BEGIN and END messages, and returns StopIteration when the final END message is found. This standard BuildEvent handler in turn extends an AbstractHandler, which implements the required do-nothing close() method. As such, most of the required work has already been done for us. We just need to override _build_event(), and add return super()._build_event(msg, event) at the end.

Remove the previous pscad.add_handler( ) call, and replace the project.run() call with:

                project.run( BuildEventHandler() )

When this script is run, the following output is produced:

INFO     main                       Launching: PSCAD 4.6.3 (x64)  FORTRAN='GFortran 4.6.2'   Matlab=None
INFO     main                       Running 'vdiv' (Single Phase Voltage Divider)
INFO     main                       BuildEvt: [None] Workspace/BEGIN 1
INFO     main                       BuildEvt: [vdiv] Project Builder/BEGIN 4
INFO     main                       BuildEvt: [vdiv] Project Compile/BEGIN 4
INFO     main                       BuildEvt: [vdiv] Project Compile/END 71
INFO     main                       BuildEvt: [vdiv] EMTDC MAKE/BEGIN 81
INFO     main                       BuildEvt: [vdiv] EMTDC MAKE/END 388
INFO     main                       BuildEvt: [vdiv] Project Builder/END 397
INFO     main                       BuildEvt: [vdiv] Project Solver/BEGIN 428
INFO     main                       BuildEvt: [vdiv] Project Solver/END 447
INFO     main                       BuildEvt: [vdiv] Mediator/BEGIN 468
INFO     main                       BuildEvt: [vdiv] EMTDC RUN/BEGIN 475
INFO     main                       BuildEvt: [vdiv] Mediator/END 598
INFO     main                       BuildEvt: [vdiv] EMTDC RUN/END 729
INFO     main                       BuildEvt: [None] Workspace/END 729
INFO     main                       Run 'vdiv' complete

Our handler is just displaying the events as they occur. It could do more interesting things. For instance, when it receives a BEGIN message, it could record the elapsed time; when it receives a matching END message, it could subtract the elapsed time from the time it recorded earlier, giving the time required for each task:

class BuildEventHandler(mhrc.automation.handler.BuildEvent):

    def __init__(self):
        super().__init__()
        self._start = {}

    def _build_event(self, msg, event):
        elapsed = int(msg.get('elapsed'))
        etype = event.find('type')
        phase = etype.get('name')
        project = event.find('project')
        prj_name = project.get('name') if project is not None else "[All]"

        key = "{} {}".format(prj_name, phase)
        if etype.get('status') == 'BEGIN':
            self._start[key] = elapsed
        else:
            msec = elapsed - self._start[key]
            LOG.info("%s: %d ms", key, msec)

        return super()._build_event(msg, event)

Running this revised script script would produce:

INFO     main                       Launching: PSCAD 4.6.3 (x64)  FORTRAN='GFortran 4.6.2'   Matlab=None
INFO     main                       Running 'vdiv' (Single Phase Voltage Divider)
INFO     main                       vdiv Project Compile: 72 ms
INFO     main                       vdiv EMTDC MAKE: 293 ms
INFO     main                       vdiv Project Builder: 395 ms
INFO     main                       vdiv Project Solver: 50 ms
INFO     main                       vdiv Mediator: 128 ms
INFO     main                       vdiv EMTDC RUN: 249 ms
INFO     main                       [All] Workspace: 772 ms
INFO     main                       Run 'vdiv' complete

The handler can store information collected during the run, that may be accessed afterwards. Of course, to do so, you would need to hold onto a reference to the handler:

handler = BuildEventHandler()
project.run( handler )
info = handler.get_interesting_data()

Build & Run Messages¶

Build Messages¶

When PSCAD builds a project, the build messages are recorded. The script can retrieve these build messages as an XML document.

After the project.run(…) line, add the following:

                project.run( BuildEventHandler() )
                LOG.info("Run '%s' complete", case['name'])

                messages = project.messages()
                for msg in messages:
                    print("%s  %s  %s" % (msg.scope, msg.status, msg.text))

This script would produce:

⋮               ⋮               ⋮               ⋮
INFO     main                       vdiv EMTDC RUN: 249 ms
INFO     main                       [All] Workspace: 772 ms
INFO     main                       Run 'vdiv' complete
vdiv  normal  Generating network and source code 'C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.gf46\Station.f'.
vdiv  normal  Generating network and source code 'C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.gf46\Main.f'.
vdiv  normal  Generating 'C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.gf46\vdiv.map'.
vdiv  normal  The total number of live nodes: 1
vdiv  normal  Time for Compile: 46ms  Make: 0ms
vdiv  normal  Will execute (1): call C:\Program Files (x86)\GFortran\4.6\bin\gf46vars.bat
vdiv  normal  Will execute (1): call "C:\Program Files (x86)\GFortran\4.6\bin\gf46vars.bat"
vdiv  normal  Will execute (2): make -f vdiv.mak
vdiv  normal  Will execute (2): "C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.gf46\vdiv.mak.bat"
vdiv  normal  Creating EMTDC executable...
vdiv  normal  C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.gf46>call "C:\Program Files (x86)\GFortran\4.6\bin\gf46vars.bat" 
vdiv  normal  Compiling 'Station.f' into object code.
vdiv  normal  Compiling 'Main.f' into object code.
vdiv  normal  Linking objects and libraries into binary 'vdiv.exe'
vdiv  normal  Solve Time = 47ms

Here, we are just extracting the scope, status, and text of the messages. Other fields, such as label and component references could also be extracted.

Run Messages¶

After EMTDC has run the project, the run messages may also be retrieved. Unlike the build messages, the run messages are returned as an unstructured blob of text.

Immediately after the above code, add the following lines:

                print("-"*60)
                output = project.get_output_text()
                print(output)

When run, this change to the script adds the run messages to the output:

⋮               ⋮               ⋮               ⋮
vdiv  normal  C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.gf46>call "C:\Program Files (x86)\GFortran\4.6\bin\gf46vars.bat" 
vdiv  normal  Linking objects and libraries into binary 'vdiv.exe'
vdiv  normal  Solve Time = 47ms
------------------------------------------------------------
Initializing Simulation Run
Executing > "C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.gf46\\vdiv.30065.bat"
C:\Users\Public\Documents\PSCAD\4.6.3\Examples x64\tutorial\vdiv.gf46>call "C:\Program Files (x86)\GFortran\4.6\bin\gf46vars.bat" 
Communications: Connection established.
EMTDC(tm) Version 4.60 R#93051001
Current locale = C
Requested locale = english-us
Current locale = English_United States.1252
 ****
 * EMTDC for PSCAD 4.6: Build# 20180314                 
 ****
Time Summary: Start Date: 10-16-2018
Time Summary: Start Time: 13:10:06
The actual plot step: '250.000000' 
Number of Matrix Switchings in SS#   1 is:        1
         Input file: vdiv.map                          
Time Summary: Stop Time: 13:10:06
Time Summary: Total CPU Time: 47ms.
Terminating connection.
EMTDC run completed.
Simulation has ended. Status code = 0

Tutorial¶

Requirements¶

Applications¶

Automation Library¶

My First Automation Script¶

Running the Tutorial¶

Finding the Tutorial¶

Logging¶

Error Handling¶

Launch Options¶

Minimize PSCAD¶

PSCAD Version¶

Fortran Version¶

Matlab Version¶

PSCAD Settings¶

Projects¶

Simulation Sets¶

Event Monitoring¶

Event Handlers¶

Removing Handlers¶

Automatic Removal¶

Build Events¶

Build & Run Messages¶

Build Messages¶

Run Messages¶

Table of Contents

Previous topic

Next topic

This Page