Projects

class mhi.pscad.Project

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)

New in version 2.0.

Project.filename

The project’s file name (read-only)

New in version 2.0.

Project.temp_folder

The project’s compiler-dependent temporary folder (read-only).

New in version 2.1.

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

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
time_duration	float	Duration of run
description	str	Description
MrunType	int	Run config 0=Standalone, 1=Master, 2=Slave
startup_filename	str	Start up snapshot file name
PlotType	int	Save Channels to disk 0=No, 1=Yes
snapshot_filename	str	Save snapshot as text
SnapTime	float	Snapshot time as a real number
SnapType	int	Timed Snapshot: 0=None, 1=Single, 2=Incremental (same file), 3=Incremental (multiple file)
StartType	int	Start simulation: 0=Standard, 1=From Snapshot File
Source	str	Additional Source files
Mruns	int	Number of multiple runs
output_filename	str	Name of data file, with .out extension
sample_step	float	Channel plot step
time_step	float	Solution time step

Project.parameter_range(parameter: str)

Get legal values for a parameter

Example:

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

New in version 2.0.

Management

Load & Save

Project.save() → None

Save changes made to this project

Project.save_as(name: str, ver46: bool = False) → None

Save this project under a new name.

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

The name 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

• name (str) – The name to store project to.

• ver46 (bool) – Set to true to store as a version 4.6 file. (optional)

Notes

The current project is not unloaded from the workspace, and the newly saved project is not loaded into the workspace. These additional actions must be performed manually, if desired.

Changed in version 2.0: Added ver46 parameter.

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.

New in version 2.0.

Project.unload() → None

Unload this project.

The project is unloaded. All unsaved changes are lost.

New in version 2.0.

Navigation

Project.focus() → None

Switch PSCAD’s focus to this project.

Project.canvas(name: str) → Canvas

Retrieve the drawing canvas 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)

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) → 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.

New 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[Optional[str], Optional[int]]

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[mhi.pscad.automation.types.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

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) → Definition

Add a new definition to the project

Parameters

xml (str) – 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.

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.

New 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.

New 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"

New 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.

New 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

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

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)

Global Substitutions

New 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))
['', 'S1', 'S2']

# 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

Layers

Project.layers() → Dict[str, str]

Fetch the state of all of the layers

New in version 2.0.

Project.create_layer(name: str, state: str = 'Enabled') → mhi.pscad.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) → mhi.pscad.Layer

Fetch the given layer

New in version 2.0.

Project.layer_states(name: str) → List[str]

Fetch all valid states for the given layer

New in version 2.0.

Properties

New 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.parameters(parameters: Dict[str, Any] = None, **kwargs) → Optional[Dict[str, Any]]

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

New in version 2.0.

Resources are additional files

Project.resources() → List[mhi.pscad.Resource]

Fetch list of all resources in project

Project.create_resource(name: str) → mhi.pscad.Resource

Add a new resource to the Project’s resource folder

Parameter:

name (str): Filename of the resource

Project.remove_resource(resource: mhi.pscad.Resource)

Remove a resource

Project.resource(name: str) → mhi.pscad.Resource

Find a resource by name

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 name of the this resource

Resource.abspath

The name of the this resource

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

Get/Set Resource parameters