Projects#

class mhi.pscad.Project(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#: PSCAD Project

In PSCAD, a Project may refer to a Library (.pslx) or a Case (.pscx). A Library will contain component definitions and/or code which may be used in other libraries and cases. A Case is a runnable simulation that may reference other libraries.

The Master Library is a library which is automatically loaded into every workspace.

Properties#

Project.name#: The name of the project (read-only)

Added in version 2.0.

Project.filename#: The project’s file name (read-only)

Added in version 2.0.

Project.temp_folder#: The project’s compiler-dependent temporary folder (read-only).

Added in version 2.1.

Project.parameters() → Dict[str, Any]#

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

Get or set project parameters

Parameters:

parameters (dict) – A dictionary of name=value parameters
**kwargs – Zero or more name=value keyword parameters

Returns:

A dictionary of current parameters, if no parameters were given.

Project Parameters#
Param Name	Type	Description
description	str	Description
time_step	float	Solution time step
time_duration	float	Duration of run
sample_step	float	Channel plot step
PlotType	choice	Save to: “NONE”, “OUT”, “PSOUT”
output_filename	str	Name of data file, with .out extension
StartType	int	Start simulation: 0=Standard, 1=From Snapshot File
startup_filename	str	Start up snapshot file name
SnapType	int	Timed Snapshot: 0=None, 1=Single, 2=Incremental (same file), 3=Incremental (multiple file)
SnapTime	float	Snapshot time as a real number
snapshot_filename	str	Save snapshot as text
MrunType	int	Run config 0=Standalone, 1=Master, 2=Slave
Mruns	int	Number of multiple runs

Project.parameter_range(parameter: str) → Tuple | Set | range | None#

Get legal values for a parameter

Example:

>>> vdiv.parameter_range('SnapType')
frozenset({'ONLY_ONCE', 'NONE', 'INCREMENTAL_SAME_FILE', 'INCREMENTAL_MANY_FILES'})

Added in version 2.0.

Management#

Load & Save#

Project.save() → None#: Save changes made to this project

Project.save_as(filename: str | PureWindowsPath, ver46: bool = False, folder: str | PureWindowsPath | None = None) → Project#

Save this project under a new name.

The project will be saved using the appropriate extension depending on whether the project is a case (.pscx) or library (.pslx).

The filename must conform to PSCAD naming convensions:

it must start with a letter,
remaining characters must be alphanumeric or the underscore _,
cannot exceed 30 characters.

Parameters:

filename (str) – The name or filename to store project to.
ver46 (bool) – Set to true to store as a version 4.6 file. (optional)
folder (str) – If provided, the path to the filename is resolved relative to this folder. (optional)

Notes

When the project name is changed, all existing Python handles to the project and anything within it become invalid and must not be used.

Changed in version 2.0: Added ver46 parameter.

Changed in version 2.7.2: Added folder parameter; returns the new project object.

Project.is_dirty() → bool#

Check if the project contains unsaved changes

Returns:: True, if unsaved changes exist, False otherwise.

Project.reload() → None#

Reload this project.

The project is unloaded, without saving any unsaved modifications, and then immediately reloaded. This returns the project to the state it was in when it was last saved.

Added in version 2.0.

Project.unload() → None#

Unload this project.

The project is unloaded. All unsaved changes are lost.

Added in version 2.0.

Navigation#

Project.focus() → None#: Switch PSCAD’s focus to this project.

Project.canvas(name: str) → Canvas#

Retrieve the drawing canvas of a component definition.

Only T-Lines, Cables, and module-type user components have a canvas.

Parameters:: name (str) – Definition name of the component.
Returns:: The corresponding canvas proxy object.

Getting the main page of a project:

main = project.canvas('Main')

Changed in version 2.0: Was Project.user_canvas(name)

Project.create_bookmark(name: str, mouse_x: int, mouse_y: int, *callstack: Component) → int#: Create a bookmark to a particular location of particular instance of a component in a call stack.

Added in version 3.1.1: Renamed from Project.bookmark(name, mouse_x, mouse_y, callstack)

Search#

Project.branch_search(subsystem_id: int = 0, node_id: int = 0) → Tuple[Component, ...]#

Perform a ‘Branch Search’ in this project

Project must be compiled for the search to return useful results.

Added in version 2.9.6.

Project.node_search(subsystem_id: int, node_id: int, look_in: LookIn, global_flag: bool) → Tuple[Component, ...]#

Perform a ‘Node Search’ with this project

Project must be compiled for the search to return useful results.

Added in version 2.9.6.

Scenarios#

Project.scenarios() → List[str]#

List the scenarios which exist in the project.

Returns:: List of scenario names.
Return type:: List[str]

Changed in version 2.0: Was ProjectCommands.list_scenarios()

Project.scenario(name: str | None = None) → str#

Get or set the current scenario.

Parameters:: name (str) – Name of scenario to switch to (optional).
Returns:: The name of the (now) current scenario.
Return type:: str

Project.save_scenario() → None#: Save the current scenario.

Added in version 2.0.

Project.save_as_scenario(name: str) → None#

Save the current configuration under the given scenario name.

Parameters:: name (str) – Name of scenario to create or overwrite.

Project.delete_scenario(name: str) → None#

Delete the named scenario.

Parameters:: name (str) – Name of scenario to delete.

Build & Run#

Project.build() → None#: Clean & Build this project, and any dependencies

Project.run(consumer=None) → None#

Build and run this project.

Parameters:: consumer – handler for events generated by the build/run (optional).

Note

A library cannot be run; only a case can be run.

Project.run_status() → Tuple[str | None, int | None]#

Get the run status of the project

Returns:: Returns (“Build”, None) if building, (“Run”, percent) if running, or (None, None) otherwise.

Changed in version 2.0: Was ProjectCommands.get_run_status()

Project.pause() → None#: Pause the currently running projects.

Note

All projects being run will be paused, not just this project.

Project.stop() → None#: Terminate a running execution of this project.

Project.messages() → List[Message]#

Retrieve the load/build messages

Returns:: A list of messages associated with the project.
Return type:: List[Message]

Each message is a named tuple composed of:

text	The message text
label	Kind of message, such as build or load
status	Type of messages, such as normal, warning, or error.
scope	Project to which the message applies
name	Component which caused the message
link	Id of the component which caused the message
group	Group id of the message

Example:

pscad.load('tutorial/vdiv.pscx', folder=pscad.examples_folder)
vdiv = pscad.project('vdiv')
vdiv.build()
for msg in vdiv.messages():
    print(msg.text)

Project.output() → str#

Retrieve the output (run messages) for the project

Returns:: The output messages
Return type:: str

Example:

pscad.load('tutorial/vdiv.pscx', folder=pscad.examples_folder)
vdiv = pscad.project('vdiv')
vdiv.run()
print(vdiv.output())

Changed in version 2.0: Was ProjectCommands.get_output_text()

Project.clean() → None#: Clean the project

Project.compile_library()#: Compile all resources linked in this library into a single compiled *.lib file.

Added in version 2.8.

Definitions#

Project.definitions() → List[str]#

Retrieve a list of all definitions contained in the project.

Returns:: A list of all of the Definition names.
Return type:: List[str]

Changed in version 2.0: Was ProjectCommands.list_definitions()

Project.definition(name: str) → Definition#

Retrieve the given named definition from the project.

Parameters:: name (str) – The name of the definition.
Returns:: The named Definition.

Changed in version 2.0: Was ProjectCommands.get_definition()

Project.create_definition(xml: str | ET.Element) → Definition#

Add a new definition to the project

Parameters:: xml (Union[str, ET.Element]) – The definition XML
Returns:: The newly created Definition

Project.delete_definition(name: str) → None#

Delete the given named Definition.

Parameters:: name (str) – The name of the definition to delete.

Project.delete_definition_instances(name: str) → None#

Delete the given named Definition, along with all instances of the that definition.

Parameters:: name (str) – The name of the Definition whose definition and instances are to be deleted.

PSCAD.copy_definitions(*defns: Definition) → None#: Copy a definition to the clipboard

Project.paste_definitions() → None#: Paste definitions from the clipboard into this project.

Added in version 2.9.

Project.paste_definitions_with_dependents() → None#: Paste definitions and their dependents from the clipboard into this project.

Added in version 2.9.

Project.remap_definitions(old: Project, new: Project, *definitions: str) → None#: Remap definitions from one namespace to another namespace.

Added in version 3.0.2.

Components#

Finding#

Project.find([[definition,] name,] [layer=name,] [key=value, ...])#: Find the (singular) component that matches the given criteria, or None if no matching component can be found. Raises an exception if more than one component matches the given criteria.

Added in version 2.0.

Project.find_first([[definition,] name,] [layer=name,] [key=value, ...])#: Find the first component that matches the given criteria, or None if no matching component can be found.

Added in version 2.0.

Project.find_all([[definition,] name,] [layer=name,] [key=value, ...])#

Find all components that match the given criteria.

Parameters:

definition (str) – One of “Bus”, “TLine”, “Cable”, “GraphFrame”, “Sticky”, or a colon-seperated definition name, such as “master:source3” (optional)
name (str) – the component’s name, as given by a parameter called “name”, “Name”, or “NAME”. If no definition was given, and if the provided name is “Bus”, “TLine”, “Cable”, “GraphFrame”, “Sticky”, or contains a colon, it is treated as the definition name. (optional)
layer (str) – only return components on the given layer (optional)
key=value – A keyword list specifying additional parameters which must be matched. Parameter names and values must match exactly. For example, Voltage=”230 [kV]” will not match components with a Voltage parameter value of “230.0 [kV]”. (optional)

Returns:

The list of matching components, or an empty list if no matching components are found.

Return type:

List[ZComponent]

Examples:

c = find_all('Bus'                # all Bus components
c = find_all('Bus10')             # all components named "Bus10"
c = find_all('Bus', 'Bus10')      # all Bus component named "Bus10"
c = find_all('Bus', BaseKV='138') # all Buses with BaseKV="138"
c = find_all(BaseKV='138')        # all components with BaseKV="138"

Added in version 2.0.

Finding By Id#

Project.component(iid: int) → Component#

Retrieve a component by ID.

Parameters:: iid (int) – The ID attribute of the component.

Added in version 2.0: This command replaces all of the type specific versions.

Note

It is often easier to use Project.find(), Project.find_first() or Project.find_all() methods (or the Canvas variants Canvas.find(), Canvas.find_first() or Canvas.find_all()) to find a component of interest, rather than using a component Id for locating the component.

For example, in pm_machine.pscx case:

# Compare finding a component by name ...
pm = prj.canvas('main').find('PMMachine')

# with finding a component by ID.
pm = prj.component(1551087554)

Parameter Grid#

Project.export_parameter_grid(filename: str, folder: str | None = None) → None#

Export parameters 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)

Project.import_parameter_grid(filename: str, folder: str | None = None) → None#

Import parameters from a CSV file.

Parameters:

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

Names In Use#

Project.names_in_use(defn: str | None = None, **params) → Set[str]#: Return the set of “Name” parameter values, for all components on the canvas that have a “Name” parameter.

Global Substitutions#

Added in version 2.0.

Project.global_substitution#

The global substitution container for the project. Can be referenced as a dictionary of dictionaries. Dict[SetName, Dict[VariableName, Value]]

Examples:

prj.global_substitution.create_sets('Set1', 'Set2')
prj.global_substitution.create('freq', 'VBase')
prj.global_substitution['']['freq'] = "60.0 [Hz]"      # Default set
prj.global_substitution['Set1']['freq'] = "50.0 [Hz]"
prj.global_substitution['Set2'] = { 'freq': "60.0 [Hz]", 'VBase': '13.8 [kV]' }
prj.global_substitution.active_set = "Set1"

# List all global substitution sets
>>> list(prj.global_substitution))
['', 'Set1', 'Set2']

# Print active global substitutions:
>>> gs = prj.global_substitution
>>> for name, value in gs[gs.active_set].items():
        print(name, "=", value)


freq = 50.0 [Hz]
VBase =

Sets#

GlobalSubstitution.active_set#

The currently active global substitution set.

Returns the name of the currently active substitution set, or None for the default set

Set to the desired global substitution set name to change the active global substitution set. Setting this to "" or None reverts to the default set.

GlobalSubstitution.create_sets(*set_names: str) → None#

Creates 1 or more named global substitution sets

Parameters:: *set_names (str) – One or more names for the new sets

GlobalSubstitution.remove_sets(*set_names: str) → None#

Removes 1 or more named global substitution sets

Parameters:: *set_names (str) – One or more names of sets to be deleted

GlobalSubstitution.rename_set(old_name: str, new_name: str) → bool#

Rename a global substitution set

Parameters:

old_name (str) – Current name of the substitution set
new_name (str) – Desired name of the substitution set

Variables#

GlobalSubstitution.create(*val_names: str) → None#

Creates 1 or more named global substitution variables.

Parameters:: *val_names (str) – One or more new variable names

GlobalSubstitution.remove(*val_names: str) → None#

Removes 1 or more named global substitution variables

Parameters:: *val_names (str) – One or more names of variables to be deleted

GlobalSubstitution.rename(old_name: str, new_name: str) → bool#

Rename a global substitution variable

Parameters:

old_name (str) – Current name of the substitution variable
new_name (str) – Desired name of the substitution variable

Load / Save#

GlobalSubstitution.save_set(filename: str, set_name: str | None = None) → None#

Save global substitution set to a CSV file.

Parameters:

filename (str) – Filename for the CSV file
set_name (str) – Set name to save (default is currently active set)

Added in version 2.8.1.

GlobalSubstitution.load_set(filename: str, set_name: str | None = None) → None#

Load global substitution set from a CSV file, replacing current values

Parameters:

filename (str) – Filename of the CSV file
set_name (str) – Set name to load (default is currently active set)

Added in version 2.8.1.

GlobalSubstitution.append_set(filename: str, set_name: str | None = None) → None#

Load global substitution set from a CSV file, without clear old values

Parameters:

filename (str) – Filename of the CSV file
set_name (str) – Set name to load (default is currently active set)

Added in version 2.8.1.

GlobalSubstitution.save_all_sets(filename: str) → None#

Save all global substitution sets to a CSV file.

Parameters:: filename (str) – Filename for the CSV file

Added in version 2.8.1.

GlobalSubstitution.load_all_sets(filename: str) → None#

Load all global substitution sets from a CSV file, replacing all current values.

Parameters:: filename (str) – Filename of the CSV file

Added in version 2.8.1.

GlobalSubstitution.append_all_sets(filename: str) → None#

Load global substitution sets from a CSV file, creating new sets when a set name already exists.

Parameters:: filename (str) – Filename of the CSV file

Added in version 2.8.1.

Layers#

Project.layers() → Dict[str, str]#: Fetch the state of all of the layers

Added in version 2.0.

Project.create_layer(name: str, state: str = 'Enabled') → Layer#

Create a new layer

Parameters:

name (str) – Name of the layer to create.
state (str) – Initial state of layer (optional, default=’Enabled’)

Project.set_layer_state(name: str, state: str) → None#

Set the state of a layer

Parameters:

name (str) – Name of the layer to alter.
state (str) – “Enabled”, “Disabled”, “Invisible” or a custom state.

Changed in version 2.0: Renamed from .set_layer(state)

Project.delete_layer(name: str) → None#

Delete an existing layer

Parameters:: name (str) – Name of the layer to delete.

Project.layer(name: str) → Layer#: Fetch the given layer

Added in version 2.0.

Project.layer_states(name: str) → List[str]#: Fetch all valid states for the given layer

Added in version 2.0.

Properties#

Added in version 2.0.

After a layer has been retrieved with Project.layer(), the following attributes and methods may be accessed:

Layer.project#: The project this layer belongs to (read-only)

Layer.id#: The ID of this layer (read-only)

Layer.name#: The name of this layer

Layer.state#: The current state of this layer

Layer.parameters() → Dict[str, Any]#

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

Get or set layer parameters

Parameters:

parameters (dict) – A dictionary of name=value parameters
**kwargs – Zero or more name=value keyword parameters

Returns:

A dictionary of current parameters, if no parameters were given.

Layer Properties#
Param Name	Type	Description
disabled_color	Color	Disabled Colour
disabled_opacity	int	Diabled Opacity
highlight_color	Color	Highlight Colour
highlight_opacity	int	Highlight Opacity

Layer.add_state(new_name: str) → None#

Create a new custom configuration name for list layer

Parameters:: new_name (str) – Name of the new configuration to create.

Layer.remove_state(state_name: str) → None#

Remove an existing custom state from this layer

Parameters:: state_name (str) – The name of the custom configuration state to remove.

Layer.rename_state(old_name: str, new_name: str) → None#

Rename an existing custom state in this layer

Parameters:

old_name (str) – The name of the custom configuration state to rename.
new_name (str) – The new name to rename the custom configuration state to.

Layer.set_custom_state(state_name: str, component: Component, component_state: str) → None#

Set the state of a component when the layer is set to the state name provided.

Parameters:

state_name (str) – The name of the custom configuration state to configure.
component (Component) – The component to set the state to
component_state (str) – One of the strings (‘Enabled’, ‘Disabled’, ‘Invisible’) for the state of the provided component when the provided state is set.

Layer.move_up(delta: int = 1) → None#: Move the layer up the list by 1

Layer.move_down(delta: int = 1) → None#: Move the layer down the list by 1

Layer.to_top() → None#: Move the layer to top of list

Layer.to_bottom() → None#: Move the layer to bottom of list

Resources#

Added in version 2.0.

Resources are additional files

Project.resources() → List[Resource]#: Fetch list of all resources in project

Project.create_resource(path: str) → Resource#

Add a new resource to the Project’s resource folder

Parameter:: path (str): Pathname of the resource

Project.remove_resource(resource: Resource)#: Remove a resource

Project.resource(path: str) → Resource#: Find a resource by path

Properties#

After a resource has been retrieved with Project.resource(), the following attributes and methods may be accessed:

Resource.project#: The project this resource belongs to (read-only)

Resource.id#: The ID of this resource (read-only)

Resource.name#: The name of the this resource.

Resource.path#: The path of the this resource, relative to the project.

Resource.abspath#: The absolute path of the this resource.

Resource.parameters() → Dict[str, Any]#
Resource.parameters(parameters: Dict[str, Any] | None = None, **kwargs) → None: Get/Set Resource parameters

Table of Contents

Previous topic

Next topic

Projects#

Properties#

Management#

Load & Save#

Navigation#

Search#

Scenarios#

Build & Run#

Definitions#

Components#

Finding#

Finding By Id#

Parameter Grid#

Names In Use#

Global Substitutions#

Sets#

Variables#

Load / Save#

Layers#

Properties#

Resources#

Properties#