Project#

Project File#

class mhi.xml.pscad.ProjectFile(path: Path | str)#

A PSCAD Project (Library or Case)

property version: str#: The PSCAD project file version

property version_number: tuple[int, ...]#: The PSCAD project file version number tuple (read-only)

Added in version 1.4.0.

property path: Path#: The path of the project’s XML document (read-only)

property namespace: str#

Namespace of the project

Read-only if the project is a case; read-write if the project is a library.

classmethod create(path: Path | str, *, version: str = '5.0.2', overwrite: bool = False) → ProjectFile#: Create a new PSCAD Library (*.pslx) or Project Case (*.pscx)

Changed in version 1.4.0: Added version & overwrite parameters

save()#: Write the updated XML document back to the file it was read from.

save_as(path: Path | str) → None#

Write the project’s XML document to a new location.

Updates the ProjectFile.path property. If written as a .pscx file, the namespace property is updated to keep the filename and namespace in sync.

property definition: DefinitionMapping#

The project’s Definition mapping.

Example:

for defn_name in project.definition:
    print(defn_name)

main_defn = project.definition['Main']

del project.definition['not_needed']

property substitution_set: SubstitutionSetMapping#

The global substitution set mapping.

This is a dictionary of global substitution sets, where each set is a dictionary of substitution variables and the value which will replace them.

Example:

# Create new substitution sets
euro_ss = project.substitution_set.create_set('Euro')
project.substitution_set.create_sets('Asia', 'Africa')

# Set initial (default) global substitutions
default_ss = project.substitution_set['Default']
default_ss['BaseKV'] = '230.0 [kV]'
default_ss['Freq'] = '60.0 [Hz]'

# Override 'Freq' in 'Euro' substitution set
euro['Freq'] = '50.0 [Hz]'

# Set the project's current global substitution set
project.substitution_set.current = 'Euro'

# Delete a global substitution set
del project.substitution_set['Africa']

property layer: LayerMapping#

The project’s Layer mapping.

Examples:

layer_1 = project.layer.create('Layer1')
layer_1.state = 'Invisible'

layer_2 = project.layer.create('Layer2')
layer_2.state = 'Disabled'
layer_2.parameters.disabled_color = 0xAA8866

canvas(name: str) → Schematic#: Canvas lookup.

user_canvases() → list[Schematic]#: List of user canvases

canvases_in_use() → list[Schematic]#: List of canvases in use.

Note

If a module itself has been marked as disabled, the underlying canvas is not in use. If a modules is merely disabled due to being placed on a layer that happens to be disabled, the underlying canvas is still considered to be in use, since the conditions which determine whether or not a layer is disabled are not evaluated here.

components(name, key=value, ...) → Iterable[Component]#

Component search

Find the components within the project identified by the provided arguments. All arguments are optional. The name parameter, if given, must be the first and only positional parameter. All other parameters must be keyword parameters.

Parameters:

name (str) – Name of the component (positional parameter only)
classid (str) – Component class identifier
defn (str) – Definition name
include_defns (set[str]) – Definition names to include in search
exclude_defns (set[str]) – Definition names to exclude from search
canvases_in_use_only (bool) – Ignore non-instanciated canvases (default: False)
with_params (set[str]) – Only components with have the given parameters
key=value – Components with the given parameter key=value pairs

At most one of defn, include_defns or exclude_defns may be provided.

component(name, key=value, ...) → Component | None#

Component search

Find the component within the project identified by the provided arguments. All arguments are optional. The name parameter, if given, must be the first and only positional parameter. All other parameters must be keyword parameters.

Parameters:

name (str) – Name of the component (positional parameter only)
classid (str) – Component class identifier
defn (str) – Definition name
include_defns (set[str]) – Definition names to include in search
exclude_defns (set[str]) – Definition names to exclude from search
canvases_in_use_only (bool) – Ignore non-instanciated canvases (default: False)
raise_if_not_found (bool) – Raise an exception if component isn’t found (default: False)
raise_if_multiple_found (bool) – Raise exception if multiple are found. (default: False)
with_params (set[str]) – Only components with have the given parameters
key=value – Components with the given parameter key=value pairs

At most one of defn, include_defns or exclude_defns may be provided.

named_components(*, classid: str | None = None, defn: str | None = None) → dict[str, list[Component]]#: Find all named components (of a particular class and/or definition), and return a dictionary of name-to-components.

Note

Multiple components can share the same name, so the returned dictionary will contain a list for each name, even if only one component by that name exists.

find_by_id(iid: int) → Component#
find_by_id(iid: int, *, raise_if_not_found: Literal[True]) → Component
find_by_id(iid: int, *, raise_if_not_found: bool) → Component | None: Find a component by its PSCAD id number

Added in version 1.4.0.

remap(old: ProjectFile, new: ProjectFile, *definition: str) → set[str]#

Replace definition references from one namespace with definition references having the same definition name in another namespace.

If definition names are given, each must exist in both namespaces. If no definition names are given, all common definition names will be used.

Returns definition names remapped from old to new.

Raises a ValueError if no common definition names are found, or if any of the given definition names are not common to both old and new.

Added in version 1.2.0.

property parameters: Parameters#: The project parameters structure

Project Parameters#

class Parameters#

Project Parameters

description: str#

creator: str#

revisor: str#

time_duration: float#

time_step: float#

sample_step: float#

StartType: int#

startup_filename: str#

PlotType: int#

output_filename: str#

SnapType: int#

snapshot_filename: str#

SnapTime: float#

MrunType: int#

Mruns: int#

branch_threshold: float#

chatter_threshold: float#

sparsity_threshold: int#

Preprocessor: str#

Source: str#

Advanced: int#

Build: int#

Check: int#

Debug: int#

Options: int#

Warn: int#

property created_by: str#: Return the creator of the project

property created_on: datetime#: Return the date/time the project was created

property revised_by: str#: Return the last revisor of the project

property revised_on: datetime#: Return the date/time the project was last revised

Global Substitutions#

Substitution Set Mapping#

class mhi.xml.pscad.substitution.SubstitutionSetMapping#

The project’s global substitution set dictionary.

Usage:

# Create new substitution sets
euro_ss = project.substitution_set.create_set('Euro')
project.substitution_set.create_sets('Asia', 'Africa')

# Set initial (default) global substitutions
default_ss = project.substitution_set['Default']
default_ss['BaseKV'] = '230.0 [kV]'
default_ss['Freq'] = '60.0 [Hz]'

# Override 'Freq' in 'Euro' substitution set
euro['Freq'] = '50.0 [Hz]'

# Set the project's current global substitution set
project.substitution_set.current = 'Euro'

# Delete a global substitution set
del project.substitution_set['Africa']

property current: str#: The project’s currently active substitution set name

create_set(key: str) → SubstitutionSet#: Create a new global substitution set

create_sets(key: str, *keys: str) → None#: Create one or more new global substitution sets

Schematics#

Schematic#

class mhi.xml.pscad.Schematic#

A canvas which contains a set of components.

property name: str#: Name of the schematic’s definition

property definition: Definition#: Definition the schematic is part of

components(name, key=value, ...) → Iterator[Component]#

Component search

Find the components within the canvas identified by the provided arguments. All arguments are optional. The name parameter, if given, must be the first and only positional parameter. All other parameters must be keyword parameters.

Parameters:

name (str) – Name of the component (positional parameter only)
classid (str) – Component class identifier
defn (str) – Definition name
include_defns (set[str]) – Definition names to include in search
exclude_defns (set[str]) – Definition names to exclude from search
with_params (set[str]) – Only components with have the given parameters
key=value – Components with the given parameter key=value pairs

At most one of defn, include_defns or exclude_defns may be provided.

component(name, key=value, ...) → Component | None#

Component search

Find the component within the canas identified by the provided arguments. All arguments are optional. The name parameter, if given, must be the first and only positional parameter. All other parameters must be keyword parameters.

Parameters:

name (str) – Name of the component (positional parameter only)
classid (str) – Component class identifier
defn (str) – Definition name
include_defns (set[str]) – Definition names to include in search
exclude_defns (set[str]) – Definition names to exclude from search
raise_if_not_found (bool) – Raise an exception if component isn’t found (default: False)
with_params (set[str]) – Only components with have the given parameters
key=value – Components with the given parameter key=value pairs

At most one of defn, include_defns or exclude_defns may be provided.

find_by_id(iid: int) → Component | None#
find_by_id(iid: int, *, raise_if_not_found: Literal[True]) → Component
find_by_id(iid: int, *, raise_if_not_found: bool) → Component | None: Find a component by its PSCAD id number

Changed in version 1.4.0: added raise_if_not_found

page_modules() → Iterator[UserCmp]#: Retrieve the page module components on the canvas

add(component, x, y, orient=None) → None#: Add a component to the schematic at the given XY location. If an orientation is specified, set that as well.

remove(component: Component) → None#: Remove the given components from the schematic

remove_components(component, *components) → None#: Remove listed components from the schematic

property parameters: Parameters#: Retrieve the Schematic’s Parameters

Schematic Parameters#

class Schematic.Parameters#

Schematic parameters

show_grid: int#

size: int#

orient: int#

show_border: int#

show_signal: int#

show_virtual: int#

show_sequence: int#

auto_sequence: int#

monitor_bus_voltage: int#

show_terminals: int#

virtual_filter: str#

animation_freq: int#

Layers#

Layer Map#

class mhi.xml.pscad.layer.LayerMapping#

The project’s Layer dictionary

Examples:

# Create a layer
layer = project.layer.create('Layer1')

# Set layer properties
layer.state = 'Invisible'
layer.parameters.disabled_color = 0xAA8866
layer.parameters.disabled_opacity = 128
layer.parameters.highlight_color = 0x76FF7A
layer.parameters.highlight_opacity = 100

# Delete a layer
del project.layer['Layer1']

create(name: str, *, state: str = 'Enabled', disabled_color: int = 13616578, disabled_opacity: int = 128, highlight_color: int = 7798650, highlight_opacity: int = 100) → Layer#: Create a new layer

Layer#

class mhi.xml.pscad.layer.Layer#

A project layer

property name: str#: The value of the name attribute

property state: str#

The layer’s state.

Possible values are ‘Enabled’, ‘Disabled’, ‘Visible’, or a custom user state.

property enabled: bool#: True if the layer’s state is ‘Enabled’ (read-only)

property disabled: bool#: True if the layer’s state is ‘Disabled’ (read-only)

property ids: set[int]#: Return the set of ids which belong to the layer.

custom_states() → set[str]#: Custom states for the layer

Added in version 1.4.0.

add_state(name: str)#: Add a new custom state

Added in version 1.4.0.

remove_state(name: str)#: Remove a custom state

Added in version 1.4.0.

set_custom_state(cmp: Component, state_name: str, state: CustomLayerState)#: Set the custom state for the component

Added in version 1.4.0.

components() → Iterator[Component]#: Return all components which belong to the layer.

Added in version 1.2.0.

delete_components() → None#: Remove all components on the layer

Added in version 1.2.0.

property parameters: Parameters#: Retrieve the Layer Parameters object

Layer Parameters#

class Layer.Parameters#

Layer Parameters

disabled_color: str#

disabled_opacity: int#

highlight_color: str#

highlight_opacity: int#

Table of Contents

Previous topic

Next topic

Project#

Project File#

Project File#

Project Parameters#

Global Substitutions#

Substitution Set Mapping#

Schematics#

Schematic#

Schematic Parameters#

Layers#

Layer Map#

Layer#

Layer Parameters#