The PSCAD Application

class mhi.pscad.PSCAD

The PSCAD Application

This proxy is used to communicate with a running PSCAD Application, and may only be created via one of the following methods:

Configuration

Application Settings

PSCAD.settings(settings: Dict[str, Any] = None, **kwargs) → Optional[Dict[str, Any]]

Set or retrieve PSCAD’s settings.

Parameters
  • settings (dict) – A dictionary of setting key-values pairs

  • **kwargs – individual setting key-value pairs

If called without providing any key-value pairs, the current settings are returned. Otherwise, the given key-value pairs are set in the application’s settings.

Any unknown keys are silently ignored. The effect of setting an known key to an invalid value is undefined.

PSCAD.setting_range(setting: str)

Get legal values for a setting.

The function may return:

  • a tuple or a frozenset of legal values,

  • a range() of legal values (integer settings),

  • a Tuple[float, float] representing minimum and maximum values (real & complex settings),

  • an exception if the setting does not have a defined range

Parameters

setting (str) – A PSCAD setting name

Returns

The valid values or range the setting may take on.

Examples:

>>> pscad.setting_range('agent_show')
(False, True)

>>> pscad.settings_range('backup_freq')
(10, 15, 20, 30, 60)

>>> pscad.settings_range('active_graphics')
frozenset({'2_SEC', '5_SEC', '10_SEC'})

>>> pscad.settings_range('backup_folder')
    ...
ValueError: No defined range for setting

New in version 2.1.

Application Flags

The following flags are supported:

Flag Name

Description

silence

Suppress popup dialogs which may interfere with automation.

load-meta-files

Controls loading of additional project state information, such as build messages from a previous session.

PSCAD.flags(flags: Dict[str, bool] = None, **kwargs) → Optional[Dict[str, bool]]

Retrieve or set application flags

If no flags are given, the value of all flags is returned. Otherwise, the specified flags are set or cleared.

Parameters
  • flags (dict) – The flags to set or clear (optional).

  • **kwargs – Flags to set or clear as key=value pairs (optional)

Examples:

pscad.flags({"silence": True, "load-meta-files": False})
pscad.flags(silence=True, load_meta_files=False)
PSCAD.substitute(value: str) → str

Substitute PSCAD workspace and environment variables in the given string

Returns

The string with known variables substituted.

Return type

str

Example:

>>> pscad.substitute('Running PSCAD version $(Version)')
'Running PSCAD version 5.0'

Properties

New in version 2.0.

PSCAD.version

The PSCAD version string. (Read-only)

PSCAD.examples_folder

The PSCAD “Examples Directory”. (Read-only)

PSCAD.is_busy() → bool

Determine whether the PSCAD application is “busy” or not.

Returns

True if the application is presently busy, False otherwise.

Licensing

PSCAD.login(username: str, password: str, remember: bool = False)

Attempt to log in to a My Center account, for licensing.

Parameters
  • username (str) – The account’s My Center user name

  • password (str) – The account’s My Center password

  • remember (bool) – Set to True to check the “Remember me” checkbox

PSCAD.logout() → None

Log out of the My Center account

PSCAD.logged_in() → bool

Returns whether or not the user is “Logged in”

Returns

True if the user is logged in, False otherwise.

Example

>>> pscad.logged_in()
True
PSCAD.licensed() → bool

Determine whether a valid license is being held.

Returns

True if the a license is held, False otherwise.

Example

>>> pscad.licensed()
True
PSCAD.get_available_certificates(*, refresh: bool = False) → Dict[int, mhi.pscad.Certificate]

Retrieve a list of license certificates available to the user.

Returns

A dictionary of certificates, keyed by Certificate.id().

PSCAD.get_current_certificate() → Optional[mhi.pscad.Certificate]

Retrieve the Certificate currently being held.

Returns

The Certificate being held, or None

PSCAD.get_certificate(certificate: mhi.pscad.Certificate) → int

Attempt to acquire the given license certificate.

Parameters

certificate – the Certificate to be acquired.

PSCAD.release_certificate() → None

Releases the currently held certificate.

PSCAD.release_all_certificates() → None

Releases all currently held certificates.

New in version 2.1.1.

Workspace Commands

Changed in version 2.0: These methods used to be under the Workspace object

PSCAD.new_workspace(filename: str = '~\\Documents\\NewWorkspace.pswx', folder: str = None) → None

Unload the current workspace, and create a new one.

Parameters
  • filename (str) – filename of new workspace

  • folder (str) – If provided, the path to the filename is resolved relative to this folder.

Warning

If popup dialogs are being silenced, all unsaved changes will be unconditionally lost.

Changed in version 2.0: Added filename & folder parameters.

PSCAD.save_workspace(filename: str = None, folder: str = None, save_projects: bool = True) → None

Save the current workspace, possibly as a new workspace.

PSCAD.workspace_dir

Return the current workspace directory

PSCAD.workspace_name

Return the current workspace name

PSCAD.workspace_path

Return the current workspace path

PSCAD.is_dirty() → bool

Determine whether the workspace has been modified since the last time it was saved.

Returns

True if the workspace has unsaved changes, False otherwise.

PSCAD.load(*filenames: str, handler=None, folder: str = None) → None

Load a workspace, or one or more projects into the current workspace.

Parameters
  • *filenames (str) – a list of filenames to load.

  • folder (str) – If provided, the path to the filenames are resolved relative to this folder.

  • handler – If provided, the given handler is automatically added for the duration of the load operation. Defaults to None.

If a workspace file (*.pswx) is given, it must be the only file. Otherwise, more than one library (*.pslx) and/or case (*.pscx) may be given.

>>> pscad.load(os.path.join(pscad.examples_folder, r'tutorial\vdiv.pscx'))
>>> vdiv = pscad.project('vdiv')
>>> vdiv.parameters()['description']
'Single Phase Voltage Divider'

Changed in version 2.0: Added folder parameter.

PSCAD.projects() → List[Dict[str, str]]

List all currently loaded libraries and cases.

Returns

The name, type and description of each project in the workspace.

Return type

List[dict]

With only the master library loaded:

>>> pscad.new_workspace()
>>> pscad.projects()
[{'name': 'master', 'type': 'Library', 'description': 'Master Library'}]

Changed in version 2.0: Was PSCAD.list_projects().

PSCAD.project(name: str)mhi.pscad.Project

Retrieve a controller for a named project in the workspace.

Parameters

name (str) – The name of the library or case. The directory and filename extension must not be included.

Returns

A project controller.

>>> master = pscad.project('master')
>>> master.parameters()['description']
'Master Library'
PSCAD.create_library(filename: str, folder: str = None)mhi.pscad.Project

Create a new library project in the workspace.

Parameters
  • filename (str) – Name or filename of the library.

  • folder (str) – Folder where library will be stored. (optional)

Returns

The newly created library.

New in version 2.0: Replaces PSCAD.create_project(2, name, folder)

PSCAD.create_case(filename: str, folder: str = None)mhi.pscad.Project

Create a new project case in the workspace.

Parameters
  • filename (str) – Name or filename of the project.

  • folder (str) – Folder where project will be stored. (optional)

Returns

The newly created project case.

New in version 2.0: Replaces PSCAD.create_project(1, name, folder)

Build & Run Commands

Changed in version 2.0: These methods used to be under the Workspace object

PSCAD.build_all(handler=None) → None

Build all projects

PSCAD.build_modified(handler=None) → None

Build any modified projects

PSCAD.build_current(handler=None) → None

Build only the current project

PSCAD.pause_run() → None

Pause the currently running projects.

PSCAD.stop_run() → None

End the currently running projects.

PSCAD.clean_all() → None

Remove all temporary files used to build the case.

Simulation Sets

Changed in version 2.0: These methods used to be under the Workspace object

PSCAD.simulation_sets() → List[str]

List all simulations set names.

Returns

A names of all simulation sets in the workspace.

Return type

List[str]

Changed in version 2.0: Replaces Workspace.list_simulation_sets()

PSCAD.create_simulation_set(set_name: str)mhi.pscad.SimulationSet

Create a new simulation set.

Parameters

set_name (str) – Name of the new simulation set.

PSCAD.simulation_set(set_name: str)mhi.pscad.SimulationSet

Retrieve a controller proxy for the given simulation set.

Parameters

set_name (str) – Name of the simulation set.

Returns

The named simulation set.

Return type

SimulationSet

Changed in version 2.0: Replaces Workspace.simulation_set(set_name)

PSCAD.remove_simulation_set(set_name: str) → None

Remove an existing simulation set.

Parameters

set_name (str) – Name of the simulation set to remove.

PSCAD.run_all_simulation_sets(handler=None) → None

Run all simulations sets.

Any modified projects will be built as necessary.

Subscriptions

These methods are used to get asynchronous events from the PSCAD application.

PSCAD.subscriptions() → Set[str]

Returns the set of event-names which can be subscribed to.

Returns

Event names which can be subscribed to.

Return type

Set[str]

New in version 2.0.

PSCAD.subscribed(name: str) → bool

Determine if the given event is being subscribed to.

Returns

True if the given event is subscribed to, False otherwise.

PSCAD.subscribe(name: str, handler=None) → None

Start receiving name events.

Parameters
  • name (str) – Name of event being subscribed to, such as “load-events” or “build-events”

  • handler – Function to call when event is received.

PSCAD.unsubscribe(name: str) → bool

Stop receiving and processing name events.

Parameters

name (str) – Name of event being unsubscribed from.

PSCAD.unsubscribe_all() → None

Stop receiving all events

New in version 2.0.

PSCAD.subscription(name: str, handler)

Subscription context manager

Usage:

with pscad.subscription(event_name, handler):
    # subscription is active in this "with-statement"

# handler is auto-unsubscribed when "with-statement" exits

New in version 2.0.

Keys & Mouse

Keystroke Events

Changed in version 2.0: These methods used to be under the KeyStrokes object

PSCAD.key_down(vkcode: int)

Simulate keyboard key press

PSCAD.key_up(vkcode: int)

Simulate keyboard key release

PSCAD.stroke(vkcode: int)

Simulate keyboard keystroke

PSCAD.keystrokes(*strokes: Union[str, int])

Type a series of strings and/or virtual key strokes.

PSCAD.typing(data: str, cooked: bool = False)

Send a series of keystrokes to type in the application.

Since pressing and holding certain keys will change the meaning of other keypresses, modifier prefixes are used to indicate which keys must be pressed and released around another key: ‘!’ is for SHIFT, ‘@’ is for ALT, and ‘#’ is for CTRL.

By default, this method will “cook” strings, adding the appropriate modifiers to turn a character into a series of modified keypress. If cooked=True is specified, the given string must already contain the required modifiers.

Raw

Cooked

He said, ‘How & why?’

!he said, ‘!how !7 why!/’

Mouse Events

Changed in version 2.0: These methods used to be under the MouseEvents object

PSCAD.move(x: int, y: int)

Simulate mouse movement

PSCAD.leftdown(x: int, y: int)

Simulate left mouse button press

PSCAD.leftup(x: int, y: int)

Simulate left mouse button release

PSCAD.leftclick(x: int, y: int)

Simulate left mouse button click

PSCAD.middledown(x: int, y: int)

Simulate middle mouse button press

PSCAD.middleup(x: int, y: int)

Simulate middle mouse button release

PSCAD.middleclick(x: int, y: int)

Simulate middle mouse button click

PSCAD.rightdown(x: int, y: int)

Simulate right mouse button press

PSCAD.rightup(x: int, y: int)

Simulate right mouse button release

PSCAD.rightclick(x: int, y: int)

Simulate right mouse button click

PSCAD.wheel(delta: int)

Simulate mouse scroll wheel movement

Termination

PSCAD.quit() → None

Terminate the remote application.

Note: The local side of the socket connection to the remote application is not explicitly closed. The client is responsible for explicitly closing the connection:

application.quit()
application.close_connection()

or by using a context manager:

with ... as application:
    # interact with the application
    #
    # application.close_connection() is automatically called
    # when the `with` statement block exits.