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() → Dict[str, Any]#

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

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) → Tuple | Set | range | None#

Get legal values for a setting.

The function may return:

a tuple, set, 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),
None if the setting does not have a defined range
an exception if no such setting exists

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.setting_range('autosave_interval')
{'15_MINUTES', '1_HOUR', 'NO_ACTION', '5_MINUTES'}

>>> pscad.setting_range('SocketPortBase')
range(30000, 40000, 1000)

>>> pscad.setting_range('backup_folder')

>>> pscad.setting_range('python_version')
Traceback (most recent call last):
    ...
ValueError: No such setting

Added 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() → Dict[str, bool]#

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

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#

Added 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#

Certificate#

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

Attempt to log in to a MyCentre account, for licensing.

Parameters:

username (str) – The account’s MyCentre user name
password (str) – The account’s MyCentre password
remember (bool) – Set to True to check the “Remember me” checkbox

PSCAD.logout() → None#: Log out of the MyCentre 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, Certificate]#

Retrieve a list of license certificates available to the user.

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

PSCAD.get_current_certificate() → Certificate | None#

Retrieve the Certificate currently being held.

Returns:: The Certificate being held, or None

PSCAD.get_certificate(certificate: 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.

Added in version 2.1.1.

PSCAD.set_license_host(host: str) → None#: Set license host

Legacy#

PSCAD.activate_edu_license() → bool#: Activate Educational Legacy License

PSCAD.activate_pro_license() → bool#: Activate Professional Legacy License

Workspace Commands#

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

PSCAD.new_workspace(filename: str | PurePath = '~\\Documents\\NewWorkspace.pswx', folder: str | PurePath | None = 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 = None, folder: str | None = 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) → 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(r'tutorial\vdiv.pscx', folder=pscad.examples_folder)
>>> vdiv = pscad.project('vdiv')
>>> vdiv.parameters()['description']
'Single Phase Voltage Divider'

Note

In the common case of loading a workspace immediately after launching PSCAD, it is better to pass that workspace to the launch() command:

pscad = mhi.pscad.launch(load=r'c:\path\to\workspace.pswx')

This avoids restoring a previous workspace, which then must be unloaded prior to loading the desired one.

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.projects()
[{'name': 'master', 'type': 'Library', 'description': 'Master Library'}]

Instead of a name, type, and description dictionary, cases() may be used to retrieve all the case projects, and libraries() to retrieve all the library projects.

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

PSCAD.project_names() → List[str]#

List all currently loaded library and case names.

Returns:: The name of each project in the workspace.
Return type:: List[str]

With only the master library loaded:

>>> pscad.project_names()
['master']

Added in version 2.9.6.

PSCAD.cases() → List[Project]#

List all currently loaded cases.

Returns:: A list of case projects.
Return type:: List[Project]

Added in version 2.6.

PSCAD.libraries() → List[Project]#

List all currently loaded libraries.

Returns:: A list of library projects.
Return type:: List[Project]

Added in version 2.6.

PSCAD.project(name: str) → 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 = None) → 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.

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

PSCAD.create_case(filename: str, folder: str | None = None) → 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.

Added 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) → SimulationSet#

Create a new simulation set.

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

PSCAD.simulation_set(set_name: str) → 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.

Parameter Grid#

Added in version 2.8.1.

PSCAD.parameter_grid#

The Parameter Grid interface object.

Example:

# Load simulations sets into parameter grid, & export the grid to a file
pscad.parameter_grid.view_simulation_sets()
pscad.parameter_grid.save("sim_sets.csv")

The following methods are defined on the interface object

ParameterGrid.view(subject: Component | Definition | Project) → None#

Load subject into the parameter grid.

The property grid is able to view and modify several components at once.

If the subject is a component or component definition, all of the instances of that component are loaded into the parameter grid.

If the subject is a project, all of the corresponding project types (libraries or cases) are loaded into the parameter grid.

ParameterGrid.view_cases() → None#: Load all project cases into the parameter grid.

ParameterGrid.view_libraries() → None#

Load all libraries into the parameter grid.

Note: The ‘master’ library is always omitted.

ParameterGrid.view_simulation_sets() → None#

Load all simulation sets into the property grid.

This allows for viewing / editing multiple simulation sets in the workspace at once.

ParameterGrid.view_simulation_tasks() → None#

Load all simulation tasks into the property grid.

This allows for viewing / editing multiple simulation tasks in the workspace at once.

ParameterGrid.view_simulation_task_overrides() → None#

Load simulation tasks’ project overrides into the property grid.

This allows for viewing / editing multiple sets of project overrides in the workspace at once.

ParameterGrid.view_simulation_task_layers(scope: Project | str) → None#

Load simulation tasks’ layers configurations into the property grid.

This allows for viewing / editing multiple sets of layers configurations in the workspace at once.

Parameters:: scope – The project object or a project name

ParameterGrid.save(filename: str, folder: str | None = None) → None#

Write parameter grid to a CSV file.

Parameters:

filename (str) – Filename of the CSV file to write.
folder (str) – Directory where the CSV file will be stored (optional)

ParameterGrid.load(filename: str, folder: str | None = None) → None#

Load parameter grid from a CSV file.

Parameters:

filename (str) – Filename of the CSV file to read.
folder (str) – Directory to read the CSV file from (optional)

Search Results#

PSCAD.search_results() → Tuple[Component, ...]#

Retrieve components in PSCAD’s search result pane

Presently, only Node Search and Branch Search results are supported.

Added in version 2.9.6.

Navigation#

PSCAD.navigate(msg: Message) → bool#

Navigate to a component, highlight it, and show a message next to it.

Parameters:: msg – A message returned from Project.messages()

PSCAD.navigate_to(scope: str, name: str, link: int, text: str = '', status: str = 'normal') → bool#

Navigate to a component, highlight it, and show a message next to it.

Parameters:

scope (str) – The project component is in.
name (str) – The canvas the component is on.
link (int) – The component Id number
text (str) – Message to display
status (str) – ‘normal’, ‘warning’, or ‘error’

PSCAD.navigate_up() → None#: Return to the page which contains the object currently being viewed.

PSCAD.navigate_dismiss() → bool#: Dismiss a popup message shown for a previous navigate command

PSCAD.focused() → Project#: Return the currently focused project

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]

Added 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

Added 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

Added 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: 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()#: Terminate the PSCAD application

Table of Contents

Previous topic

Next topic

The PSCAD Application#

Configuration#

Application Settings#

Application Flags#

Properties#

Licensing#

Certificate#

Legacy#

Workspace Commands#

Build & Run Commands#

Simulation Sets#

Parameter Grid#

Search Results#

Navigation#

Subscriptions#

Keys & Mouse#

Keystroke Events#

Mouse Events#

Termination#