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

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.

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

class Parameters#

Project Parameters

description: str#: Data descriptor for known parameters

creator: str#: Data descriptor for known parameters

revisor: str#: Data descriptor for known parameters

time_duration: float#: Data descriptor for known parameters

time_step: float#: Data descriptor for known parameters

sample_step: float#: Data descriptor for known parameters

StartType: int#: Data descriptor for known parameters

startup_filename: str#: Data descriptor for known parameters

PlotType: int#: Data descriptor for known parameters

output_filename: str#: Data descriptor for known parameters

SnapType: int#: Data descriptor for known parameters

snapshot_filename: str#: Data descriptor for known parameters

SnapTime: float#: Data descriptor for known parameters

MrunType: int#: Data descriptor for known parameters

Mruns: int#: Data descriptor for known parameters

branch_threshold: float#: Data descriptor for known parameters

chatter_threshold: float#: Data descriptor for known parameters

sparsity_threshold: int#: Data descriptor for known parameters

Preprocessor: str#: Data descriptor for known parameters

Source: str#: Data descriptor for known parameters

Advanced: int#: Data descriptor for known parameters

Build: int#: Data descriptor for known parameters

Check: int#: Data descriptor for known parameters

Debug: int#: Data descriptor for known parameters

Options: int#: Data descriptor for known parameters

Warn: int#: Data descriptor for known parameters

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#

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

Definitions#

Definition Map#

class mhi.xml.pscad.definitions.DefinitionMapping#

The project’s Definition dictionary.

Example:

for defn_name in project.definition:
    print(defn_name)

main_defn = project.definition['Main']

del project.definition['not_needed']

create(name: str) → UserCmpDefn#: Create a new UserCmp Definition

create_tline(name: str) → RowDefn#: Create a new TLine

create_cable(name: str) → RowDefn#: Create a new TLine

Definition#

class mhi.xml.pscad.Definition#

Definition node

property group: str#

A comma separated list of groups this definition belongs to.

Examples:

'(null)'
'Miscellaneous,I/O Devices'
'Meters,Breakers Faults,Machines,Miscellaneous'

property groups: list[str]#

The list of groups this definition belongs to.

Examples:

['(null)']
['Miscellaneous', 'I/O Devices']
['Meters', 'Breakers Faults', 'Machines', 'Miscellaneous']

property description: str#: Description of the definition

delete() → None#: Remove this definition from its parent project

class mhi.xml.pscad.UserCmpDefn#

User Component Definition node

property form: Form#: The Parameter Form for the definition

property schematic: Schematic | None#: The Schematic of the definition, if it is a module definition

property script: ScriptSegmentMapping#

The script dictionary for the definition

This contains ‘Computations’, ‘Checks’, ‘Fortran’, ‘Branch’ sections (etc).

property graphics: Graphics#: The Graphics of the definition

Form#

class mhi.xml.pscad.Form#

A collection of categories of parameters, along with their descriptions and validity constraints.

Examples:

form = definition.form

# Create a "Extra" category, add 'Author', 'Version' parameters.
extra = form.category.create("Extra")
extra.add_text('Author', "Creator")
extra.add_integer('Version', "Revision number", min=1, default=1)

# Remove the "Extra" category
del form.category["Extra"]

property w: int#

Width of the dialog form, in pixels.

Does not include additional width added by dynamic help.

property h: int#: Height of the dialog form, in pixels

property splitter: int#: The “Description <–> Value” splitter position, in percent

property commentlines: int#: Number of lines at the bottom of the form for help text.

property category: KeyMapping[Category]#: Form category dictionary

property parameter: KeyMapping[Parameter]#: Form parameter dictionary

Form Category#

class mhi.xml.pscad.Category#

A form category

Contains 1 or more parameters, and a condition for when the category is enabled.

property cond#: Category enabled condition expression (read/write)

property parameter: KeyMapping[Parameter]#: Category parameter dictionary

add_text(name: str, description: str, default: str = '', empty_allowed=True, **kwargs) → Parameter#: Create a text parameter.

add_integer(name: str, description: str, default: int = 0, min: int | None = None, max: int | None = None, animate: bool = False, **kwargs) → Parameter#: Create an Integer parameter.

add_real(name: str, description: str, default: int = 0, min: int | None = None, max: int | None = None, animate: bool = False, unit: str | None = None, **kwargs) → Parameter#: Create a Real parameter.

Form Parameter#

class mhi.xml.pscad.Parameter#

A parameter definition.

Gives the parameter a symbol name, description, type, units, default value, validation attributes (minimum and/or maximum limits, regex), and help attributes.

property description: str#: Parameter description

property group: str#: Parameter group (set of related parameters in one category)

property type: str#: Parameter type (Text, Complex, Real, Integer, Choice, Boolean, Table)

property min: int | float | None#: Minimum allowed value (Integer / Real) or length (Text)

property max: int | float | None#: Maximum allowed value (Integer / Real) or length (Text)

property unit: str#: Parameter unit (kV, kA, ohm, MVA, rad/s, …)

property empty_allowed: bool#: Can this Text field be empty?

property animate: bool#: Is this parameter animated?

property help_mode: str#: Help mode (Append, Overwrite)

property default: str#: Default value for the parameter

property help: str#: Brief help message to Append/Overwrite help panel with

property regex: str#: A reg-ex validation pattern for Text input parameters

property cond: str#: Enable condition for this parameter.

property error_msg: str#: The message to display if a issue exists with the entered parameter value.

property choices: dict[int, str]#: The options for a Choice parameter

Graphics#

class mhi.xml.pscad.Graphics#

A <graphics/> container node

add_text(*coords, text: str, color: str = 'Black', full_font: str = 'Tahoma, 12world', font_size: int = 0, align: str | Align | int = Align.CENTER, angle: int = 0, cond: str = 'true')#: Add a line of text to the definition graphics

add_line(*coords, color: str = 'Black', line_style: str | LineStyle | int = LineStyle.SOLID, thickness: int = 0, port: str = '', cond: str = 'true')#: Add a line to the definition graphics

add_rect(*coords, color: str = 'Black', line_style: str | LineStyle | int = LineStyle.SOLID, thickness: int = 0, port: str = '', fill_style: str | FillStyle | int = FillStyle.HOLLOW, fill_fg: str = 'Black', fill_bg: str = 'White', cond: str = 'true')#: Add a rectangle to the definition graphics

add_ellipse(*coords, color: str = 'Black', line_style: str | LineStyle | int = LineStyle.SOLID, thickness: int = 0, port: str = '', fill_style: str | FillStyle | int = FillStyle.HOLLOW, fill_fg: str = 'Black', fill_bg: str = 'White', cond: str = 'true')#: Add an ellipse to the definition graphics

add_circle(*coords, color: str = 'Black', line_style: str | LineStyle | int = LineStyle.SOLID, thickness: int = 0, port: str = '', fill_style: str | FillStyle | int = FillStyle.HOLLOW, fill_fg: str = 'Black', fill_bg: str = 'White', cond: str = 'true')#: Add a circle to the definition graphics

ports(name: str | None = None) → list[Port]#: Retrieve the list of ports defined in the component graphics

add_input(x: int, y: int, name: str, *, dim: int = 1, cond: str = 'true', internal: bool = False, datatype: SignalType | str | int = SignalType.REAL) → Port#: Add an input port to the graphic definition

add_output(x: int, y: int, name: str, *, dim: int = 1, cond: str = 'true', internal: bool = False, datatype: SignalType | str | int = SignalType.REAL) → Port#: Add an output port to the graphic definition

add_electrical(x: int, y: int, name: str, *, dim: int = 1, cond: str = 'true', internal: bool = False, electype: ElectricalType | str | int = ElectricalType.FIXED) → Port#: Add an electical port to the graphic definition

Graphic Elements#

class mhi.xml.pscad.GfxText#

Gfx Text

property color: Colour#: The ‘color’ property of a visible Gfx item

property value: str#: The ‘message’ of a Graphics.Text item

property full_font: str#: The ‘font’ used to draw a Graphics.Text item

property font_size: int#: The ‘size of font’ used to draw a Graphics.Text item

property anchor: Align#: The ‘text anchor’ (Left/Centre/Right) of a Graphics.Text item

property angle: int#: The ‘angle’ (in degrees) to draw the Graphic.Text message at

class mhi.xml.pscad.GfxLine#

Gfx Line

property color: Colour#: The ‘color’ property of a visible Gfx item

property dasharray: LineStyle#: The ‘Line Style’ of a stroked Gfx item

property thickness: int#: The ‘Line Thickness’ of a stroked Gfx item

vertices() → list[Vertex]#: The list <vertex> elements of a Graphics.Line

Changed in version 1.2.0.

class mhi.xml.pscad.GfxRectangle#

Gfx Rectangle

property color: Colour#: The ‘color’ property of a visible Gfx item

property dasharray: LineStyle#: The ‘Line Style’ of a stroked Gfx item

property thickness: int#: The ‘Line Thickness’ of a stroked Gfx item

property fill_style: FillStyle#: The ‘Fill Style’ of a painted Gfx item

property fill_fg: Colour#: The ‘Foreground color’ of a painted Gfx item

property fill_bg: Colour#: The ‘Background Color’ of a painted Gfx item

class mhi.xml.pscad.GfxEllipse#

Gfx Ellipse

property color: Colour#: The ‘color’ property of a visible Gfx item

property dasharray: LineStyle#: The ‘Line Style’ of a stroked Gfx item

property thickness: int#: The ‘Line Thickness’ of a stroked Gfx item

property fill_style: FillStyle#: The ‘Fill Style’ of a painted Gfx item

property fill_fg: Colour#: The ‘Foreground color’ of a painted Gfx item

property fill_bg: Colour#: The ‘Background Color’ of a painted Gfx item

class mhi.xml.pscad.Port#

Graphics Port

property name: str#: The ‘name’ of the connection point

property dim: int#: The ‘dimension’ of the connection point

property mode: NodeType#: The ‘mode’ of the connection point (Input, Output, Electrical, …)

property datatype: SignalType#: The ‘data type’ of input/output Port (Logical, Integer, Real, …)

property electype: ElectricalType#: The ‘type’ of an Electrical Port (Fixed, Removable, Ground, …)

property internal: bool#: An electrical port’s ‘internal’ nature (not connected externally)

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.

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

Data descriptor for known parameters

size: int#

Data descriptor for known parameters

orient: int#

Data descriptor for known parameters

show_border: int#

Data descriptor for known parameters

show_signal: int#

Data descriptor for known parameters

show_virtual: int#

Data descriptor for known parameters

show_sequence: int#

Data descriptor for known parameters

auto_sequence: int#

Data descriptor for known parameters

monitor_bus_voltage: int#

Data descriptor for known parameters

show_terminals: int#

Data descriptor for known parameters

virtual_filter: str#

Data descriptor for known parameters

animation_freq: int#

Data descriptor for known parameters

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.

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#

Data descriptor for known parameters

disabled_opacity: int#

Data descriptor for known parameters

highlight_color: str#

Data descriptor for known parameters

highlight_opacity: int#

Data descriptor for known parameters

Components#

Component#

class mhi.xml.pscad.Component#

A Component

property classid: str#

The classid of the component.

Typically “UserCmp” but other possibilities include “WireOthogonal”, “Sticky”, “GraphFrame”, “ControlFrame”, and so on.

property location: XY#: The (X, Y) location of the component.

property canvas: Schematic#: The canvas the component is on.

property size: XY#: The size (width & height) of the component.

property defn: str | None#: The component’s definition.

property scope_and_defn: tuple[str, str]#: Returns the component definitions’s scope and definition names.

property name: str | None#

Returns the component’s assigned name value.

The name must be stored in a parameter called name, `Name or NAME.

property layer: Layer | None#: The Layer the component is on, or None if not on any layer.

property params: ParamListNode | None#

The parameter list node of the component

Individual parameters can be set and retrieved using index notation:

name = cmp['Name']
cmp['BaseKV'] = '230.0 [kV]'

property enabled: bool#: Is this component enabled.

Note

This does not check if the component is on a disabled layer.

enable(state=True) → None#: Enable this component

Note

This does not affect whether the component is on a disabled layer.

disable() → None#: Disable this component

delete() → None#: Remove this component from the canvas.

UserCmp#

class mhi.xml.pscad.UserCmp#

A component with a definition defined in a ‘.pslx’ file

property defn: str#: The definition of the component

property subcanvas: 'Schematic' | None#: The component’s definition’s schematic, in one exists

is_module() → bool#: Does this component’s definition contain a schematic?

Wires#

class mhi.xml.pscad.Wire#

Base class for all multi-vertex Wires

vertices() → list[Vertex]#

The list <vertex> elements of a Wire

These are the raw <vertex> elements, relative to the component’s origin. Use Wire.vertex[i] to retrieve the actual canvas vertex locations.

Changed in version 1.2.0.

Utility Classes#

Vertex#

class mhi.xml.pscad.Vertex#

A <vertex/> node

Added in version 1.2.0.

property x: int#

property y: int#

XY#

class mhi.xml.pscad.XY(x: int, y: int)#

Two dimensional position or size, used to specify Component locations on a Schematic canvas.

property x: int#

property y: int#

mhi.xml.pscad.UP#: An XY vector representing one grid unit “up” on a Schematic canvas.

mhi.xml.pscad.DOWN#: An XY vector representing one grid unit “down” on a Schematic canvas.

mhi.xml.pscad.LEFT#: An XY vector representing one grid unit to the “left” on a Schematic canvas.

mhi.xml.pscad.RIGHT#: An XY vector representing one grid unit to the “right” on a Schematic canvas.

Enum Types#

Resources#

class mhi.xml.pscad.ResourceType(*values)#

Types of Resource for a PSCAD Project

UNKNOWN = '0'#

TEXT = '1'#

BINARY = '2'#

Ports#

class mhi.xml.pscad.NodeType(*values)#

Node Input/Output/Electrical Type

UNKNOWN = '0'#

INPUT = '1'#

OUTPUT = '2'#

ELECTRICAL = '3'#

SHORT = '4'#

class mhi.xml.pscad.SignalType(*values)#

Signal Types

ELECTRICAL = '0'#

LOGICAL = '1'#

INTEGER = '2'#

REAL = '3'#

COMPLEX = '4'#

UNKNOWN = '15'#

class mhi.xml.pscad.ElectricalType(*values)#

Electrical Node Types

FIXED = '0'#

REMOVABLE = '1'#

SWITCHED = '2'#

GROUND = '3'#

Graphics#

class mhi.xml.pscad.Align(*values)#

Text Alignment

LEFT = '0'#

CENTER = '1'#

RIGHT = '2'#

class mhi.xml.pscad.LineStyle(*values)#

Line Styles

SOLID = '0'#

DASH = '1'#

DOT = '2'#

DASHDOT = '3'#

class mhi.xml.pscad.FillStyle(*values)#

Fill Styles

HOLLOW = '0'#

SOLID = '1'#

BACKWARD_DIAGONAL = '2'#

FORWARD_DIAGONAL = '3'#

CROSS = '4'#

DIAGONAL_CROSS = '5'#

HORIZONTAL = '6'#

VERTICAL = '7'#

GRADIENT_HORZ = '8'#

GRADIENT_VERT = '9'#

GRADIENT_BACK_DIAG = '10'#

GRADIENT_FORE_DIAG = '11'#

GRADIENT_RADIAL = '12'#

Table of Contents

Previous topic

Next topic

Project#

Project File#

Global Substitutions#

Definitions#

Definition Map#

Definition#

Form#

Form Category#

Form Parameter#

Graphics#

Graphic Elements#

Schematics#

Schematic#

Schematic Parameters#

Layers#

Layer Map#

Layer#

Layer Parameters#

Components#

Component#

UserCmp#

Wires#

Utility Classes#

Vertex#

XY#

Enum Types#

Resources#

Ports#

Graphics#