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 afrozenset
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 byCertificate.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
anddescription
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
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.