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

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(filename: str, ver46: bool = False, folder: str = 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.

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

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

New 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: Union[str, 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.

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

Load / Save

GlobalSubstitution.save_set(filename: str, set_name: str = 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)

New in version 2.8.1.

GlobalSubstitution.load_set(filename: str, set_name: str = 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)

New in version 2.8.1.

GlobalSubstitution.append_set(filename: str, set_name: str = 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)

New 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

New 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

New 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

New in version 2.8.1.

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

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

The name of this layer

Layer.state

The current state of this layer

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[Resource]

Fetch list of all resources in project

Project.create_resource(name: str) → Resource

Add a new resource to the Project’s resource folder

Parameter:

name (str): Filename of the resource

Project.remove_resource(resource: Resource)

Remove a resource

Project.resource(name: str) → 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