Workspace#

The PSCAD Workspace file is an XML document which contains:

  • the workspace parameters,

  • the workspace project files:

    • libraries,

    • cases,

  • the workspace simulations sets.

Workspace File#

class mhi.xml.pscad.workspace.WorkspaceFile(path: Path | str | None = None)#

A PSCAD Workspace XML File

An existing workspace is read by specifying an existing workspace file in the constructor:

from mhi.xml.pscad import WorkspaceFile

ws = WorkspaceFile(r"C:\Workspace\Path\TheWorkspace.pswx")

Since project files are located relative to the workspace, to create a new workspace the directory of the new workspace is required. Specifying a directory, instead of a file, creates an empty workspace:

from mhi.xml.pscad import WorkspaceFile

ws = WorkspaceFile(r"C:\Workspace\Path")

...

ws.save_as("TheWorkspace.pswx")
classmethod create(path: Path | str, *, version: str = '5.0.2', overwrite: bool = False) → WorkspaceFile#

Create a new PSCAD Workspace file (*.pswx)

Added in version 1.4.0.

property name: str#

Name of the workspace (read-only)

property path: Path | None#

The path of the XML document (read-only)

Note

The path is None if it has not been read from an actual file.

property folder: Path#

The workspace directory (read-only)

property version: str#

PSCAD version used to create the workspace.

property version_number: tuple[int, ...]#

The PSCAD workspace file version number tuple (read-only)

Added in version 1.4.0.

save()#

Write the updated XML document back to the file it was read from.

save_as(path: Path | str) → None#

Write the workspace XML document to a new location.

Note

This updates the “read-only” name, path, and folder properties.

all_exist() → bool#

Verify that all projects in the workspace exist.

add_project(project_or_path: ProjectFile | PathLike | str) → None#

Add a project to the workspace

property project: ProjectMapping#

The workspace’s “Project” dictionary.

It is used to find the workspace’s projects:

from mhi.xml.pscad import WorkspaceFile

examples_folder = r"C:\Users\Public\Documents\PSCAD\5.0.2\Examples"
ws = WorkspaceFile(rf"{examples_folder}\tutorial\Tutorial.pswx")

vdiv = ws.project["vdiv"].open()

Note

A ProjectNode must be ‘opened’ to access the corresponding Project.

property simulation_set: SimulationSetMapping#

The workspace’s simulation set dictionary.

It is used to access the workspace’s simulation sets:

from mhi.xml.pscad import WorkspaceFile

workspace = ...

default_simset = workspace.simulation_set["default"]
base_simset = workspace.simulation_set.create("base")

Projects#

class mhi.xml.pscad.workspace.ProjectMapping(workspace_file: WorkspaceFile)#

The workspace’s ProjectNode dictionary.

The ProjectNode dictionary contains the libraries and cases in the workspace (excluding the Master Library). The dictionary may be iterated over to obtain each ProjectNode within, or it may be indexed by namespace to obtain a specific one:

workspace = ...
for prj_name, prj_node in workspace.project.items():
    print(prj_name, prj_node.path)

tutorial_ws = ...
vdiv_node = tutorial_ws.project['vdiv']

A project may be added to the workspace by assigning a path to a new namespace, or removed by deleting the entry:

del workspace.project['old_library']
workspace.project['new_library'] = Path(r"C:\Path\to\new_library.pslx")

Project#

class mhi.xml.pscad.workspace.ProjectNode#

A project within a workspace.

Note

This ProjectNode only represents an entry within the WorkspaceFile. It must be opened to obtain the actual ProjectFile.

static validate_name(name: str) → None#

Ensure the name is a legal PSCAD project identifier

static validate_type(kind: str) → None#

Ensure the type is a legal PSCAD project type

property type: str#

Type of the project (read-only)

Either ‘library’ or ‘project’

property is_library: bool#

True if the project represents a PSCAD Library. (read-only)

property is_case: bool#

True if the project represents a PSCAD Project Case. (read-only)

property filepath: str#

The project’s filepath attribute string. (read-only)

property path: Path#

The project’s filepath, resolved relative to the workspace file. (read-only)

open() → ProjectFile#

Open the project’s XML file

delete() → None#

Remove this project from the workspace.

Simulation Sets#

class mhi.xml.pscad.workspace.SimulationSetMapping(workspace_file: WorkspaceFile)#

The workspace’s SimulationSetNode dictionary.

The dictionary contains the simulation sets in the workspace. The dictionary may be iterated over to obtain each SimulationSetNode within, or it may be indexed by name to obtain a specific one:

workspace = ...
for simset in workspace.simulation_set.values():
    print(simset.name)

default_ss = workspace.simulation_set['default']

New simulation sets may be created using the create() method:

simset1 = workspace.simulation_set.create('simset1')

A simulation set may be removed from the workspace by deleting the entry:

del workspace.simulation_set['simset1']
create(name: str) → SimulationSetNode#

Create a new simulation set

Simulation Set#

class mhi.xml.pscad.workspace.SimulationSetNode#

A simulation set element.

property task: TaskMapping#

The simulation set’s task dictionary.

property depends_on: str#

Simultaion set dependency.

namespaces() → list[str]#

The project names that are part of this simulation set.

delete() → None#

Remove this simulation set from the workspace

parameters(name='Default') → Parameters#

The simultaion set’s parameters structure.

Changed in version 1.4.0: Returns a Parameters51 if the workspace version is 5.1 or higher

class Parameters#

The simulation set’s parameters (read/write)

enabled: bool#
before_run: str#
before_block: bool#
after_run: str#
after_block: bool#
class Parameters51#

Additional simulation set’s parameters for PSCAD 5.1+ (read/write)

Added in version 1.4.0.

pmr_enabled: bool#
ammunition: int#
volley: int#
on_crash: bool#
after_block: bool#
after_run: str#
before_block: bool#
before_run: str#
enabled: bool#

Simulation Set Tasks#

class mhi.xml.pscad.workspace.TaskMapping(simset: SimulationSetNode)#

A simulation set’s task dictionary.

namespaces() → list[str]#

List the namespaces of the tasks in the simulation set.

create(namespace: str, **kwargs) → SimulationTaskNode#

Create a new simulation set task

Added in version 1.4.0.

Simulation Set Task#

class mhi.xml.pscad.workspace.SimulationTaskNode#

A simulation set’s task element.

property namespace: str#

The namespace of this simulation set task.

delete() → None#

Remove this simulation task from the simulation set.

parameters(name='Options') → Parameters#

The simulation set task’s parameters structure.

class Parameters#

Parameters of a simulation set’s task (read/write).

Changed in version 1.4.0: Removed simulationset & namespace parameters

name: str#
ammunition: int#
volley: int#
affinity_type: int#
affinity: int#
rank_snap: bool#
substitutions: str#
clean: bool#
property overrides: Overrides#

The simulation set task’s project overrides accessor

Added in version 1.4.0.

class Overrides#

Project overrides for a simulation set’s task (read/write).

Each attribute has a corresponding override_{name} boolean attribute. Assigning a value to any of the base attributes will simultaneously set the corresponding override attribute to True, where as assigning None to the attribute will set the override to False instead.

When an override attribute is set to False, the corresponding base attribute will return None.

Added in version 1.4.0.

remove_snapshot_offset: bool#
only_in_use_channels: bool#
state_animation: bool#
manual_start: bool#
run_config: int#
run_count: int#
save_channels_file: str#
save_channels: int#
timed_snapshots: int#
snapshot_file: str#
snap_time: float#
start_method: int#
startup_inputfile: str#
duration: float#
time_step: float#
plot_step: float#
override_duration#
override_manual_start#
override_only_in_use_channels#
override_plot_step#
override_remove_snapshot_offset#
override_run_config#
override_run_count#
override_save_channels#
override_save_channels_file#
override_snap_time#
override_snapshot_file#
override_start_method#
override_startup_inputfile#
override_state_animation#
override_time_step#
override_timed_snapshots#
property layer_overrides: MutableMapping[str, str]#

The simulation set task’s layer overrides.

The layer overrides behave as a dictionary of layer name and layer states.

Note

The layer overrides are part of the workspace, and are accessed without referencing the project file. Layer names and custom layer states are not verified to exist.

Examples:

# Get an existing simulation set task
simset1 = workspace.simulation_set['simset1']
task = simset1.task.create['prj1']

# Add or alter existing layer overrides
task.layer_overrides['Layer1'] = 'Enabled'
task.layer_overrides['Layer2'] = 'Disabled'
task.layer_overrides['Layer3'] = 'Invisible'
task.layer_overrides['Layer4'] = 'MyCustomState'

# Remove an existing override
if 'Layer5' in task.layer_overrides:
    del task.layer_overrides['Layer5']

Added in version 1.4.0.

On this page