Components#

Common#

class mhi.pscad.Component(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#: Components which can be moved & rotated on a Canvas. They might also be modules.

Properties#

Component.project_name#

The name of the project this component exists in (read-only)

Type:: str

Component.iid#

The id of the component in the project (read-only)

Type:: int

Component.defn_name#: The name of the definition (read-only)

Changed in version 3.0.2: Return type changed from Union[str, Tuple[str, str]] to str. For a three-phased voltage source for instance, the return value changed from 'master', 'source3' to 'master:source3'

Component.parameters(*, parameters: Dict[str, Any] | None = None, **kwargs) → Dict[str, Any] | None#

Set or get the component’s parameters.

Parameters:

parameters (dict) – A dictionary of parameter values. (optional)
**kwargs – name=value keyword parameters.

Returns:

A dictionary of parameter values (if no parameters are being set), or None.

Component.range(parameter: str) → Tuple | Set | range | None#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

Component.view_parameter_grid() → bool#: View the parameter grid for this component

Component.import_parameters(csvfile: str) → None#

Import component parameters from a CSV file

Read component parameters from a two-line CSV file, where the first row contains the parameter names and the second row contains the parameter values. The first column represents the component identifier and the parameter name must be blank.

Component.export_parameters(csvfile: str) → None#

Export component parameters to a CSV file

Write component parameters to a two-line CSV file. The first row will contains the parameter names and the second row will contain the parameter values. The first column contains the component identifier and the parameter name will be blank.

Location#

Component.parent#

Canvas this component is located on (read-only)

Type:: Canvas

Component.location#

Component (X, Y) location, in grid units

When this property is retrieved, it will be cached for 5.0 seconds, and if retrieved again within that time the cached value will be returned.

Component.get_location()#

Get this component’s (x,y) location

Returns:: The x,y location of the component, in grid units
Return type:: Tuple[int, int]

Component.set_location(x, y)#

Set the component’s (x,y) location

Parameters:

x (int) – The new x location for this component
y (int) – The new y location for this component

Component.bounds#

The left, top, right and bottom bounds of the component, in grid units (read only)

Type:: Rect

When this property is retrieved, it will be cached for 5.0 seconds, and if retrieved again within that time the cached value will be returned.

Layers#

Component.layer#: The layer the component is on

Component.add_to_layer(name: str) → None#

Add this component to the given layer.

The layer must exist, but need not be enabled or visible.

Parameters:: name (str) – The layer to add the component to.

Component.remove_from_layer(name: str) → None#

Remove this component from the given layer.

The layer must exist, but need not be enabled or visible.

Parameters:: name (str) – The layer to remove the component from.

Component.custom_state(state_name: str, state: str) → None#

Set a custom layer state for this component.

The component must already be part of a layer, and that layer must already have the named custom state added to it. This component will be set to the given state when the component’s layer is set to the given custom state name.

Parameters:

state_name (str) – The component’s layer’s custom state name
state (str) – One of ‘Enabled’, ‘Disabled’ or ‘Invisible’

Component.enable(enable: bool = True) → None#

Enable this component.

With no argument, or if given a True value, this will enable a disabled component. If the component is disabled via layers it will remain disabled.

Parameters:: enable (bool) – If set to False, disables the component (optional)

Component.disable() → None#

Disable this component.

This component will be disabled regardless of the layer states. To re-enable this component use the enable() function.

Component.enabled#

The component’s enable/disable status.

This is independent of whether the component is on a layer that is enabled or disabled.

Added in version 2.8.1.

Modules#

Component.is_module() → bool#

Check to see if this component has its own canvas, with in turn, can contain additional components.

Transmission lines, cables, and some user components are modules with their own canvas.

Returns:: True if the component has an internal canvas, False otherwise.
Return type:: bool

Clipboard#

Component.copy() → bool#: Copy this component to the clipboard.

Component.cut() → bool#: Cut this component to the clipboard

Component.delete() → bool#: Delete this component.

Component.clone(x: int, y: int) → Component#

Copy this component and place the copy at the given location.

Parameters:

x (int) – x-coordinate for the cloned component (in grid units)
y (int) – y-coordinate for the cloned component (in grid units)

Returns:

the cloned component

Return type:

Component

Z-Ordering#

Component.to_front() → bool#: Put at the front (end) of the Z-Order on the canvas.

Component.to_back() → bool#: Put at the start (back) of the Z-Order on the canvas.

Component.to_next() → bool#: Move the component one position forward in the Z-Order relative to the current Z-Order position.

Component.to_prev() → bool#: Move the component one position backward in the Z-Order relative to the current current Z-Order position.

User Components#

class mhi.pscad.UserCmp(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#: Non-builtin components (a.k.a User Components)

Properties#

UserCmp.definition#: The User Component’s definition

UserCmp.parameters(scenario: str | None = None) → Dict[str, Any]#

UserCmp.parameters(scenario: str | None = None, *, parameters: Dict[str, Any] | None = None, **kwargs) → None

Set or get the component’s parameters.

Parameters:

scenario (str) – Name of scenario to set parameters for. (optional)
parameters (dict) – A dictionary of parameter values. (optional)
**kwargs – name=value keyword parameters.

Returns:

A dictionary of parameter values (if no parameters are being set), or None.

UserCmp.range(parameter: str) → Tuple | Set | range | None#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

UserCmp.view_parameter_grid() → bool#: View the parameter grid for this component

Ports#

UserCmp.ports() → Dict[str, Port]#

Retrieve the active ports of a component.

Returns:: A dictionary of ports, by port name.
Return type:: Dict[str, Port]

UserCmp.port(name: str) → Port | None#

Based on the location of this component, taking into account any any rotation and/or mirroring, return the location and type of the named component port.

Returns:: The x, y location, name, dimension and type of the port.
Return type:: tuple

Modules#

UserCmp.canvas() → Canvas#

Get the module’s canvas

Returns:: The canvas containing this module’s subcomponents
Return type:: Canvas

UserCmp.navigate_in() → Canvas#: Navigate into a page module or definition

UserCmp.compile() → None#: Compile this component page

UserCmp.blackbox(x: int | None = None, y: int | None = None, sub_prefix: str | None = None, instance_data: bool | None = None) → Component#: Convert this component page into a blackboxed module

Changed in version 2.7: Added x, y, sub_prefix & instance_data parameters.

UserCmp.blackbox_defn() → Definition#: Convert this component page into a blackboxed module definition

Added in version 2.7.

Connections#

Wires, sticky wires, buses, and transmission-lines & cables are formed from one or more line segments. The line segments are specified by vertices. The entire component may be moved by changing the component’s location, or by changing the location of the vertices.

Wire.vertices([vertices])#

Set or get the vertices of the wire

Parameters:: vertices (List[x,y]) – a list of (x,y) coordinates (optional)
Returns:: A list of (x,y) coordinates.
Return type:: List[x,y]

Wire.endpoints() → Tuple[Point, Point]#

Get the end-points of the wire. Internal vertices are not returned.

Returns:: The wire’s end-points
Return type:: List[Point]

Wires#

class mhi.pscad.Wire(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

An electrical wire or control signal.

Wires are continuous lines which connect 2 or more vertices. Each segment must be horizontal or vertical.

To construct a new wire, use UserCanvas.create_wire().

Sticky Wire#

class mhi.pscad.StickyWire(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

A “Sticky Wire” is an electrical wire or control signal, which stretches to maintain connection to a component it is attached to.

Unlike all other wires, a “Sticky Wire” may have more than two end-points. Each pair of vertices form a horizontal or vertical line segment, which is then attached to a central point by diagonal line segments.

To construct a new sticky wire, use UserCanvas.create_sticky_wire().

Bus#

class mhi.pscad.Bus(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

Bus Component

A Bus is a 3-phase electrical wire. It addition to vertices, it has parameters which can be set and retrieved.

To construct a new bus, use UserCanvas.create_bus().

Bus Parameters#
Parameter	Type	Description
Name	str	Name of the Bus
BaseKV	float	Bus Base Voltage, in kV. May be zero.
VA	float	Bus Base Angle, in degrees
VM	float	Bus Base Magnitude, in degrees
type	int	0=Auto, 1=Load, 2=Generator or 3=Swing

T-Line#

class mhi.pscad.TLine(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

Transmission Line Component

A Transmission Line component is defined by 4 vertices, which form a 3 line segments. The first and last segments must be horizontal or vertical segments; the middle segment may be diagonal.

It addition to vertices, a transmission line will also have a collection of parameters as well as a canvas containing additional components defining the transmission line.

Cable#

class mhi.pscad.Cable(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

Cable Component

A Cable component is defined by 4 vertices, which form a 3 line segments. The first and last segments must be horizontal or vertical segments; the middle segment may be diagonal.

It addition to vertices, a cable will also have a collection of parameters as well as a canvas containing additional components defining the cable.

Output Channels#

Graph Frame#

class mhi.pscad.GraphFrame(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

A container for holding one or more overlay graphs.

The Graph Frame parameters holds a set of properties for the frame itself.

Graph Frame Properties#
Param Name	Type	Description
title	str	Caption of Graph Frame
markers	bool	Show Markers
lockmarkers	bool	Lock distance between X & O markers
deltareadout	bool	Show “Delta T” readout
xmarker	float	The X-Marker position
omarker	float	The O-Marker position
pan_enable	bool	Auto Pan X-Axis enabled
pan_amount	int	Auto Pan X-Axis percentage
xtitle	str	Title of the x-axis
xgrid	float	X-Axis grid line spacing
xfont	str	X-Axis font
xangle	int	X-Axis label angle (in degrees)

property markers: Any#: Show/hide X/O markers

property auto_sizing: Any#: Enable/disable vertical auto sizing

property follow_run: Any#: Enable/disable auto pan (follow end of run)

zoom(xmin: float | None = None, xmax: float | None = None, *, compute_x_grid: bool = True) → None#: Alter the graph’s X-Axis extents

pan(left: float | None = None, right: float | None = None, *, width: float | None = None) → None#: Set the location of the graph’s panning bar.

add_overlay_graph(*sources: Curve | PGB) → Tuple[OverlayGraph, List[Curve]]#

Add a new Overlay Graph

Parameters:: *sources – pgbs or curves to add to newly created graph (optional)
Returns:: The new Overlay Graph & its curves
Return type:: Tuple[OverlayGraph,List[Curve]]

add_poly_graph(*sources: Curve | PGB, digital: bool = False) → Tuple[PolyGraph, List[Curve]]#

Add a new Stacked PolyGraph

Parameters:

*sources – pgbs or curves to add to newly created graph (Optional)
digital – Whether curve should be displayed as a digital signal. Defaults to False. (Optional)

Returns:

The new PolyGraph & its curves Newly added Stacked Polygraph

Return type:

Tuple[PolyGraph,List[Curve]]

remove(*panels: GraphPanel) → None#: Remove one or more graph panels from the Graph Frame

toggle_auto_pan() → None#: Toggle auto-pan on or off.

set_auto_pan(enable: bool = True) → None#: Set auto-pan on or off.

toggle_markers() → None#: Toggle the markers on or off.

show_markers(show: bool = True) → None#: Set the marker visibility to on or off.

toggle_auto_sizing() → None#: Toggle auto-sizing on or off.

set_auto_sizing(enable: bool = True) → None#: Set auto-sizing on or off.

minimize(flag: bool = True) → None#: Minimize the frame.

restore()#: Restore the frame from its minimized state.

toggle_minimize() → None#: Toggle minimized/restored state

synchronize_channel_limits() → None#: Set the limits of each channel in the frame to the limits of its graph.

copy(*graphs)#: Copy this component to the clipboard.

cut(*graphs)#: Cut this component to the clipboard

Overlay Graph#

class mhi.pscad.OverlayGraph#

Parameters#

OverlayGraph.parameters() → Dict[str, Any]#

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

Get/set Overlay Graph Settings

Overlay Graph Settings#
Param Name	Type	Description
glyphs	bool	Glyphs
grid	bool	Grids
grid_color	Color	Grid Line Colour
curve_colours	Colors	Curve Colour Pattern
curve_colours2	Colors	Curve Inverted Colour Pattern
ticks	bool	Ticks
yinter	bool	Y-Intercept
xinter	bool	X-Intercept
crosshair	bool	Crosshair
manualscale	bool	Manual Scalling Only
invertcolor	bool	Invert Colours
title	Text	Y-Axis Title
gridvalue	Real	Grid Size
ymin	Real	Minimum Value
ymax	Real	Maximum Value
yintervalue	Real	Intercept Value
autoframe	Real	Padding

OverlayGraph.range(parameter: str) → Tuple | Set | range | None#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

Properties#

property OverlayGraph.crosshair: Any#: Show / hide crosshair

property OverlayGraph.glyphs: Any#: Show / hide curve glyphs

property OverlayGraph.grid: Any#: Show / hide grid

property OverlayGraph.height: Any#: Manual graph height

property OverlayGraph.ticks: Any#: Show / hide axis tick marks

property OverlayGraph.x_intercept: Any#: Show / hide x-intercept

property OverlayGraph.y_intercept: Any#: Show / hide y-intercept

OverlayGraph.show_glyphs(show: bool = True) → None#

Set the curve glyph visibility.

Parameters:: show (bool) – Set to False to turn off the curve glyphs.

OverlayGraph.show_grid(show: bool = True) → None#

Set the grid visibility

Parameters:: show (bool) – Set to False to turn off the grid.

OverlayGraph.show_ticks(show: bool = True) → None#

Set the tick visibility.

Parameters:: show (bool) – Set to False to turn off the tick markers.

OverlayGraph.show_x_intercept(show: bool = True)#: Set the X intercept visibility on or off

OverlayGraph.show_y_intercept(show: bool = True) → None#: Set the Y intercept visibility on or off

OverlayGraph.toggle_curve_glyphs() → None#: Toggle curve glyphs on or off

OverlayGraph.toggle_grid_lines() → None#: Toggle grid lines on or off

OverlayGraph.toggle_tick_marks() → None#: Toggle tick marks on or off

OverlayGraph.toggle_x_intercept() → None#: Toggle X intercept on or off

OverlayGraph.toggle_y_intercept() → None#: Toggle Y intercept on or off

Position#

OverlayGraph.move_up() → None#: Move the graph one position up in the graph frame.

OverlayGraph.move_down() → None#: Move the graph one position down in the graph frame.

OverlayGraph.to_top() → None#: Put at the top of the graph frame.

OverlayGraph.to_bottom() → None#: Put at the bottom of the graph frame.

Zoom#

OverlayGraph.zoom(xmin: float | None = None, xmax: float | None = None, ymin: float | None = None, ymax: float | None = None, *, compute_x_grid: bool = True, compute_y_grid: bool = True) → None#

Set the horizontal and/or vertical limits of the overlay graph.

All parameters are optional.

Parameters:

xmin (float) – Lower X-Axis limit
xmax (float) – Upper X-Axis limit
ymin (float) – Lower Y-Axis limit
ymax (float) – Upper Y-Axis limit
compute_x_grid (bool) – Recompute x-grid spacing
compute_x_grid – Recompute y-grid spacing

OverlayGraph.zoom_extents(x_extents: bool = True, y_extents: bool = True) → None#

Reset the graph’s zoom to the X and/or Y extents. By default, both X and Y axis zoom is affected.

Parameters:

x_extents (bool) – set to False to not affect X-axis
y_extents (bool) – set to False to not affect Y-axis

OverlayGraph.zoom_limits(x_limits: bool = True, y_limits: bool = True) → None#

Reset the graph’s zoom to the X and/or Y limits. By default, both X and Y axis zoom is affected.

Parameters:

x_limits (bool) – set to False to not affect X-axis
y_limits (bool) – set to False to not affect Y-axis

OverlayGraph.zoom_in() → None#: Increase the graph’s zoom level.

OverlayGraph.zoom_out() → None#: Decrease the graph’s zoom level.

OverlayGraph.zoom_previous() → None#: Undo zoom.

OverlayGraph.zoom_next() → None#: Redo zoom.

OverlayGraph.zoom_x_extents() → None#: Reset the graph’s zoom for the X-axis to the X extents.

OverlayGraph.zoom_x_limits() → None#: Reset the graph’s zoom for the X-axis to the X limits.

OverlayGraph.zoom_y_extents() → None#: Reset the graph’s zoom for the Y-axis to the Y extents.

OverlayGraph.zoom_y_limits() → None#: Reset the graph’s zoom for the Y-axis to the Y limits.

OverlayGraph.reset_extents() → None#: Reset the graph’s extents

OverlayGraph.reset_limits() → None#: Reset the graph’s limits

OverlayGraph.synchronize_channel_limits() → None#: Set the limits of each channel to the limits of the graph.

Curves#

OverlayGraph.curve(index: int) → Curve#

Retrieve a curve that belongs to this graph panel.

Parameters:: index (int) – The curve index, starting from 0
Returns:: the indexed curve in this panel
Return type:: Curve

OverlayGraph.curves() → List[Curve]#

Retrieve the curves that belong to this graph panel.

Returns:: the curves in this panel
Return type:: List[Curve]

OverlayGraph.create_curve(source: PGB | Curve, index: int = -1) → Curve#

Create a new curve on this graph from the given source.

If the source is another curve, that curve is cloned.

Parameters:

source – The signal source (pgb or a curve)
index – Position in graph (optional)

Returns:

The created curve

Return type:

Curve

OverlayGraph.move_curve(curve: Curve, index: int = -1)#

Move a curve to a given position on this graph.

If a curve is on a different graph, it is removed from that graph, and added to this one.

Parameters:

curve – The curve to move.
index – Position in graph (Optional)

Clipboard#

OverlayGraph.copy_data_all() → None#: Copy all data in the graph to the clipboard.

OverlayGraph.copy_data_between_markers() → None#: Copy data between the markers in the graph to the clipboard.

OverlayGraph.copy_data_visible() → None#: Copy visible data in the graph to the clipboard.

Polygraph#

class mhi.pscad.PolyGraph#

Parameters#

PolyGraph.parameters(*, parameters: Dict[str, Any] | None = None, **kwargs) → Dict[str, Any] | None#

Set or get the component’s parameters.

Parameters:

parameters (dict) – A dictionary of parameter values. (optional)
**kwargs – name=value keyword parameters.

Returns:

A dictionary of parameter values (if no parameters are being set), or None.

PolyGraph.range(parameter: str) → Tuple | Set | range | None#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

Properties#

property PolyGraph.crosshair: Any#: Show / hide crosshair

property PolyGraph.glyphs: Any#: Show / hide curve glyphs

property PolyGraph.grid: Any#: Show / hide grid

property PolyGraph.ticks: Any#: Show / hide axis tick marks

property PolyGraph.x_intercept: Any#: Show / hide x-intercept

property PolyGraph.y_intercept: Any#: Show / hide y-intercept

PolyGraph.show_glyphs(show: bool = True) → None#

Set the curve glyph visibility.

Parameters:: show (bool) – Set to False to turn off the curve glyphs.

PolyGraph.show_grid(show: bool = True) → None#

Set the grid visibility

Parameters:: show (bool) – Set to False to turn off the grid.

PolyGraph.show_ticks(show: bool = True) → None#

Set the tick visibility.

Parameters:: show (bool) – Set to False to turn off the tick markers.

PolyGraph.show_x_intercept(show: bool = True)#: Set the X intercept visibility on or off

PolyGraph.show_y_intercept(show: bool = True) → None#: Set the Y intercept visibility on or off

PolyGraph.toggle_curve_glyphs() → None#: Toggle curve glyphs on or off

PolyGraph.toggle_grid_lines() → None#: Toggle grid lines on or off

PolyGraph.toggle_tick_marks() → None#: Toggle tick marks on or off

PolyGraph.toggle_x_intercept() → None#: Toggle X intercept on or off

PolyGraph.toggle_y_intercept() → None#: Toggle Y intercept on or off

Position#

PolyGraph.move_up() → None#: Move the graph one position up in the graph frame.

PolyGraph.move_down() → None#: Move the graph one position down in the graph frame.

PolyGraph.to_top() → None#: Put at the top of the graph frame.

PolyGraph.to_bottom() → None#: Put at the bottom of the graph frame.

Zoom#

PolyGraph.zoom(xmin: float | None = None, xmax: float | None = None, ymin: float | None = None, ymax: float | None = None, *, compute_x_grid: bool = True, compute_y_grid: bool = True) → None#

Set the horizontal and/or vertical limits of the overlay graph.

All parameters are optional.

Parameters:

xmin (float) – Lower X-Axis limit
xmax (float) – Upper X-Axis limit
ymin (float) – Lower Y-Axis limit
ymax (float) – Upper Y-Axis limit
compute_x_grid (bool) – Recompute x-grid spacing
compute_x_grid – Recompute y-grid spacing

PolyGraph.zoom_extents(x_extents: bool = True, y_extents: bool = True) → None#

Reset the graph’s zoom to the X and/or Y extents. By default, both X and Y axis zoom is affected.

Parameters:

x_extents (bool) – set to False to not affect X-axis
y_extents (bool) – set to False to not affect Y-axis

PolyGraph.zoom_limits(x_limits: bool = True, y_limits: bool = True) → None#

Reset the graph’s zoom to the X and/or Y limits. By default, both X and Y axis zoom is affected.

Parameters:

x_limits (bool) – set to False to not affect X-axis
y_limits (bool) – set to False to not affect Y-axis

PolyGraph.zoom_in() → None#: Increase the graph’s zoom level.

PolyGraph.zoom_out() → None#: Decrease the graph’s zoom level.

PolyGraph.zoom_previous() → None#: Undo zoom.

PolyGraph.zoom_next() → None#: Redo zoom.

PolyGraph.zoom_x_extents() → None#: Reset the graph’s zoom for the X-axis to the X extents.

PolyGraph.zoom_x_limits() → None#: Reset the graph’s zoom for the X-axis to the X limits.

PolyGraph.zoom_y_extents() → None#: Reset the graph’s zoom for the Y-axis to the Y extents.

PolyGraph.zoom_y_limits() → None#: Reset the graph’s zoom for the Y-axis to the Y limits.

PolyGraph.reset_extents() → None#: Reset the graph’s extents

PolyGraph.reset_limits() → None#: Reset the graph’s limits

Curves#

PolyGraph.curve(index: int) → Curve#

Retrieve a curve that belongs to this graph panel.

Parameters:: index (int) – The curve index, starting from 0
Returns:: the indexed curve in this panel
Return type:: Curve

PolyGraph.curves() → List[Curve]#

Retrieve the curves that belong to this graph panel.

Returns:: the curves in this panel
Return type:: List[Curve]

PolyGraph.create_curve(source: PGB | Curve, index: int = -1, digital: bool = False) → Curve#

Create a new curve on this polygraph from the given source.

If the source is another curve, that curve is cloned.

Parameters:

source – The signal source (pgb or a curve)
index – Position in graph (optional)
digital – Whether curve should be displayed as a digital signal (optional)

Returns:

The created curve

Return type:

Curve

PolyGraph.move_curve(curve: Curve, index: int = -1)#

Move a curve to a given position on this graph.

If a curve is on a different graph, it is removed from that graph, and added to this one.

Parameters:

curve – The curve to move.
index – Position in graph (Optional)

Clipboard#

PolyGraph.copy_data_all() → None#: Copy all data in the graph to the clipboard.

PolyGraph.copy_data_between_markers() → None#: Copy data between the markers in the graph to the clipboard.

PolyGraph.copy_data_visible() → None#: Copy visible data in the graph to the clipboard.

XY Plot Frame#

class mhi.pscad.PlotFrame(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

X-Y Plot Frame

A Graph Frame that displays an X-Y curves where both X and Y values are dependent on another quantity, such as time.

Parameters#

PlotFrame.parameters() → Dict[str, Any]#

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

parameters(parameter=value, …) Get/set Plot Frame Settings

Plot Frame Settings#
Param Name	Type	Description
title	Text	Caption
glyphs	Bool	Show Glyphs
ticks	Bool	Show Ticks
grid	Bool	Show Grid
grid_color	Color	Grid Line Colour
curve_colours	Colors	Curve Colour Pattern
curve_colours2	Colors	Curve Inverted Colour Pattern
yinter	Bool	Show Y-Intercept
xinter	Bool	Show X-Intercept
markers	Choice	Show Markers: HIDE, SHOW
xmarker	Real	X Marker
omarker	Real	O Marker

PlotFrame.range(parameter: str) → Tuple | Set | range | None#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

Properties#

property PlotFrame.crosshair: Any#: Show/hide crosshair

property PlotFrame.glyphs: Any#: Show/hide curve glyphs

property PlotFrame.grid: Any#: Show/hide grid

property PlotFrame.ticks: Any#: Show/hide axis tick marks

property PlotFrame.markers: Any#: Show/hide X/O markers

property PlotFrame.x_intercept: Any#: Show/hide x-intercept

property PlotFrame.y_intercept: Any#: Show/hide y-intercept

PlotFrame.show_glyphs(show: bool = True) → None#

Set the curve glyph visibility.

Parameters:: show (bool) – Set to False to turn off the curve glyphs.

PlotFrame.show_grid(show: bool = True) → None#

Set the grid visibility

Parameters:: show (bool) – Set to False to turn off the grid.

PlotFrame.show_ticks(show: bool = True) → None#

Set the tick visibility.

Parameters:: show (bool) – Set to False to turn off the tick markers.

PlotFrame.show_x_intercept(show: bool = True)#: Set the X intercept visibility on or off

PlotFrame.show_y_intercept(show: bool = True) → None#: Set the Y intercept visibility on or off

PlotFrame.toggle_curve_glyphs() → None#: Toggle curve glyphs on or off

PlotFrame.toggle_grid_lines() → None#: Toggle grid lines on or off

PlotFrame.toggle_tick_marks() → None#: Toggle tick marks on or off

PlotFrame.toggle_x_intercept() → None#: Toggle X intercept on or off

PlotFrame.toggle_y_intercept() → None#: Toggle Y intercept on or off

Appearence#

property PlotFrame.title: str#: The title displayed on the frame

PlotFrame.minimize(flag: bool = True) → None#: Minimize the frame.

PlotFrame.restore() → None#: Restore the frame from its minimized state.

PlotFrame.toggle_minimize() → None#: Toggle minimized/restored state

Zoom#

Set the horizontal, vertical, and/or aperture limits of the XY Plot.

All parameters are optional.

Parameters:

xmin (float) – Lower X-Axis limit
xmax (float) – Upper X-Axis limit
ymin (float) – Lower Y-Axis limit
ymax (float) – Upper Y-Axis limit
start (float) – Aperture start
end (float) – Aperture end

PlotFrame.zoom_extents(x_extents: bool = True, y_extents: bool = True) → None#

Reset the graph’s zoom to the X and/or Y extents. By default, both X and Y axis zoom is affected.

Parameters:

x_extents (bool) – set to False to not affect X-axis
y_extents (bool) – set to False to not affect Y-axis

PlotFrame.zoom_limits(x_limits: bool = True, y_limits: bool = True) → None#

Reset the graph’s zoom to the X and/or Y limits. By default, both X and Y axis zoom is affected.

Parameters:

x_limits (bool) – set to False to not affect X-axis
y_limits (bool) – set to False to not affect Y-axis

PlotFrame.zoom_in() → None#: Increase the graph’s zoom level.

PlotFrame.zoom_out() → None#: Decrease the graph’s zoom level.

PlotFrame.zoom_previous() → None#: Undo zoom.

PlotFrame.zoom_next() → None#: Redo zoom.

PlotFrame.zoom_x_extents() → None#: Reset the graph’s zoom for the X-axis to the X extents.

PlotFrame.zoom_x_limits() → None#: Reset the graph’s zoom for the X-axis to the X limits.

PlotFrame.zoom_y_extents() → None#: Reset the graph’s zoom for the Y-axis to the Y extents.

PlotFrame.zoom_y_limits() → None#: Reset the graph’s zoom for the Y-axis to the Y limits.

PlotFrame.reset_extents() → None#: Reset the graph’s extents

PlotFrame.reset_limits() → None#: Reset the graph’s limits

PlotFrame.aperture(start: float | None = None, end: float | None = None)#

Set/Get the aperture limits of the XY Plot.

All parameters are optional.

Parameters:

start (float) – Aperture start
end (float) – Aperture end

Returns:

The plot aperture

Return type:

Tuple[float, float]

Curves#

PlotFrame.curves() → List[Tuple[Curve, Curve]]#

Retrieve the curves that belong to this XY Plot.

Returns:: the curve pairs in this plot
Return type:: List[Tuple[Curve,Curve]]

PlotFrame.curve(index: int) → Tuple[Curve, Curve]#

Retrieve a curve pair that belongs to this XY Plot.

Parameters:: index (int) – The curve pair index, starting from 0
Returns:: the indexed curve pair in this plot
Return type:: Tuple[Curve,Curve]

PlotFrame.create_curve(*, x: PGB | Curve) → Curve#

PlotFrame.create_curve(*, y: PGB | Curve) → Curve

PlotFrame.create_curve(x: PGB | Curve, y: PGB | Curve) → Tuple[Curve, Curve]

Add a curve to the XY plot.

Parameters:

x – The signal source for the X-axis (pgb or a curve)
y – The signal source for the Y-axis (pgb or a curve)

Returns:

The created curve(s)

Return type:

Union[Curve, Tuple[Curve,Curve]]

Note

To plot a curve in an XY plot, both the X & Y signal sources are required. Using drag-and-drop, the X & Y signals sources are added separately, one at a time; to faciliate script recording, an x= or y= keyword argument is used to add the individual halves of the X & Y pairs separately. However, it is recommended to add both signal sources at once.

Added in version 2.1.1.

PlotFrame.create_curves(*xy: Tuple[PGB | Curve, PGB | Curve]) → List[Tuple[Curve, Curve]]#

Add one or more curves to the XY plot.

Parameters:: *xy (Tuple[X,Y]) – Tuples of X/Y signal sources
Returns:: The created curve tuples
Return type:: List[Tuple[Curve,Curve]]

Added in version 2.1.1.

Clipboard#

PlotFrame.copy_data_all() → None#: Copy all data in the XY plot to the clipboard.

PlotFrame.copy_data_visible() → None#: Copy all data inside the XY plot’s view aperature to the clipboard.

Curve#

class mhi.pscad.Curve(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#: A Curve on a graph

Properties#

property Curve.traces: int#

The number of traces in the curve. This will be zero until the project has been run. (Read-only)

Type:: int

property Curve.samples: int#

The number of sample points in the curve. This will be zero until the project has been run. (Read-only)

Type:: int

Curve.active#

The “active” trace in the set of curve traces.

The active trace will be the default focus in tracking cross-hair mode. It may be displayed in a custom style.

Type:: int

Curve.bold#

A list of “Bold” flags, one per trace.

Analog curve traces are drawn with thicker lines when bold; digital curve traces are drawn thick when True and thin when False, instead of as a square-wave.

Type:: List[bool]

Examples:

curve.bold = [True, False, False]   # Set the A-phase of a 3-phase curve to bold
curve.bold[0] = True                # Set the A-phase to bold, other traces unaffected
curve.bold = True                   # Set all traces in curve to bold

Curve.digital#

A list of “Digital” flags, one per trace.

In a polygraph, when this flag is True, the trace is drawn as two-state signal, either as a square-wave (bold=False) or a thick/thin trace (bold=True).

Type:: List[bool]

Curve.visible#

Visibility flags, one per trace

When False, the trace is hidden.

Type:: List[bool]

Methods#

Curve.to_start() → None#: Put first in the list of curves in the graph.

Curve.to_end() → None#: Put last in the list of curves in the graph.

Curve.domain() → array#

The domain of the curve.

Returns:: the domain axis values
Return type:: array.array(‘d’)

Curve.trace(trace_num: int = 0) → array#

An array of sample values for the indexed trace in the curve.

Parameters:: trace_num (int) – The trace index, starting at 0
Returns:: the trace’s sample values
Return type:: array.array(‘d’)

Instruments#

class mhi.pscad.Instrument(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

Output controls allowing the user to observe quantities changing during a simulation.

Includes Oscilloscopes, Phasor Meters and Poly Meters.

Added in version 2.1.1.

Instrument.link_id#: Related / linked component id

Instrument.linked#: Component which this control component is linked to.

Instrument.title#: The title displayed on the frame

Instrument.parameters() → Parameters#

Instrument.parameters(*, parameters: Parameters | None = None, **kwargs) → None

Set or get the component’s parameters.

Parameters:

parameters (dict) – A dictionary of parameter values. (optional)
**kwargs – name=value keyword parameters.

Returns:

A dictionary of parameter values (if no parameters are being set), or None.

Instrument.range(parameter: str) → ParameterRange#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

Oscilloscope#

class mhi.pscad.Oscilloscope(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#: An Oscilloscope is a special runtime object that is used to mimic the triggering effects of a real-world oscilloscope on a time varying, cyclical signal like an AC voltage or current. Given a base frequency, the oscilloscope will follow the signal during a simulation (like a moving window), refreshing its display at the rate given by the base frequency. This gives the illusion that the oscilloscope is transfixed on the signals being displayed, resulting in a triggering effect.

Oscilloscope.frequency#: Base frequency

Oscilloscope.cycles#: Number of cycles to display

Phasor Meter#

class mhi.pscad.PhasorMeter(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#: A PhasorMeter is a special runtime object that can be used to display up to six, separate phasor quantities. The phasormeter displays phasors in a polar graph, where the magnitude and phase of each phasor responds dynamically during a simulation run. This device is perfect for visually representing phasor quantities, such as output from the Fast Fourier Transform (FFT) component.

PhasorMeter.degrees#: True if Phasor Meter angle input is in degrees

PhasorMeter.radians#: True if Phasor Meter angle input is in radians

PhasorMeter.index#

Active phasor index (read-only)

Type:: int

Poly Meter#

class mhi.pscad.PolyMeter(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#: A polymeter is a special runtime object used specifically for monitoring a single, multiple-trace curve. The polymeter dynamically displays the magnitude of each trace in bar type format (called gauges), which results in an overall appearance similar to a spectrum analyzer. The power of this device lies in its ability to compress a large amount of data into a small viewing area, which is particularly helpful when viewing harmonic spectrums such as data output from the Fast Fourier Transform (FFT) component.

PolyMeter.labels#: Meter labels visible?

PolyMeter.scrollable#: Scroll view enabled?

PolyMeter.colour#: Colour of bars in Poly Meter

Input Controls#

Control Frame#

class mhi.pscad.ControlFrame(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#: A container for holding buttons, switches, and dials

ControlFrame.create_control(control_component: Component) → Control#

Create control in the control frame connected to the given control component.

The control component must be one of the following:

master:var,
master:var_button,
master:var_switch, or a
master:var_dial

Parameters:: control_component (Component) – the control component
Returns:: the created control
Return type:: Control

ControlFrame.create_controls(*control_components: Component) → List[Control]#

Create several controls in the control frame connected to the given control components.

The control components must each be one of:

master:var,
master:var_button,
master:var_switch, or a
master:var_dial

Parameters:: *control_components (Component) – A list of control components
Returns:: the created controls
Return type:: List[Control]

ControlFrame.reset() → None#: Reset all controls in the control frame

General#

class mhi.pscad.Control(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

Input controls allow the user to make changes to a simulation before or during a run, by varying set-points, or switching inputs on or off.

All controls share some common parameters, to identify the control to the user. The control subclasses will add additional parameters specific to each:

Common Control Properties#
Param Name	Type	Description
Name	str	Name of input
Group	str	Name of logical group input belongs to
Display	bool	Show the Name on the control

property link_id: int#: Related / linked component id

property linked: Component#: Component which this control component is linked to.

property order: Any#: Position in Control Panel

parameters() → Parameters#

parameters(*, parameters: Parameters | None = None, **kwargs) → None

Set or get the component’s parameters.

Parameters:

parameters (dict) – A dictionary of parameter values. (optional)
**kwargs – name=value keyword parameters.

Returns:

A dictionary of parameter values (if no parameters are being set), or None.

range(parameter: str) → ParameterRange#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

reset() → None#: Reset the control component

Button#

class mhi.pscad.Button(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

A momentary contact control.

A button will output the Min value until the user clicks the button, at which point it will output Max for one time-step, and then resume outputing Min:

Button-specific Properties#
Param Name	Type	Description
Min	float	Button’s output value when not pressed
Max	float	Button’s output value when pressed

press() → None#: Press the button

release() → None#: Release the button

click() → None#: Press and release the button

Switch#

class mhi.pscad.Switch(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

A switch will output one of two values, depending on the position of the switch control:

Switch-specific Properties#
Param Name	Type	Description
Max	float	Output value in the “On” position
Min	float	Output value in the “Off” position
Ton	str	Text label for the “On” position
Toff	str	Text label for the “Off” position
Value	str	Initial State (`"ON"` or `"OFF"`)
conv	str	Convert output to the nearest integer (`"YES"` or `"NO"`)

on() → None#: Turn the switch to the On state

off() → None#: Turn the switch to the Off state

set_state(state: bool) → None#

Set the switch to the indicated state

Parameters:: state (bool) – True = On, False = Off

Selector#

class mhi.pscad.Selector(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

A multi-state switch having between 3 and 10 states. Also known as a “Dial” or a “Rotary Switch”.

Selector-specific Properties#
Param Name	Type	Description
NDP	int	# of dial positions (3 - 10)
Value	int	Initial dial position (1 - NDP)
conv	str	Convert output to the nearest integer (`"YES"` or `"NO"`)
LabelType	str	Appearence. `"INDEX"`, `"INDEX_AND_VALUE"` or `"VALUE"`
F1	float	Output value for position #1
F2	float	Output value for position #2
F3	float	Output value for position #3
F4	float	Output value for position #4
F5	float	Output value for position #5
F6	float	Output value for position #6
F7	float	Output value for position #7
F8	float	Output value for position #8
F9	float	Output value for position #9
F10	float	Output value for position #10

position(position: int) → None#

Set the selector to the given position

Parameters:: position (int) – Desired dial position (1 to NDP)

Slider#

class mhi.pscad.Slider(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

A variable input between minumum & maximum values.

Button-specific Properties#
Param Name	Type	Description
Max	float	Slider’s maximum value
Min	float	Slider’s minimum value
Value	float	Slider’s initial value
Units	str	Units to display on slider control
Collect	str	Data collection (`"CONTINUOUS"` or `"ON_RELEASE"`)

value(value: float) → None#

Set the slider to the given value

Parameters:: value (float) – Slider position value

limits(lower: float, upper: float) → None#

Set slider minumum and maximum limits

Parameters:

lower (float) – Lower limit for slider
upper (float) – Upper limit for slider

Annotations#

Sticky#

class mhi.pscad.Sticky(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

A text note which may be placed on a user canvas, and which can have arrows pointing in up to 8 directions from the sides/corners of the Sticky note.

Sticky Note Parameters#
Param Name	Type	Description
full_font	Font	Font
align	Choice	Alignment: LEFT, CENTRE, RIGHT
fg_color_adv	Color	Text Colour
bg_color_adv	Color	Background Colour
bdr_color_adv	Color	Border Colour

Sticky.parameters(*, parameters: Dict[str, Any] | None = None, **kwargs) → Dict[str, Any] | None#

Set or get the component’s parameters.

Parameters:

parameters (dict) – A dictionary of parameter values. (optional)
**kwargs – name=value keyword parameters.

Returns:

A dictionary of parameter values (if no parameters are being set), or None.

Sticky.range(parameter: str) → Tuple | Set | range | None#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

Sticky.arrows(*args: str, add: int | str | Sequence[str] = (), remove: int | str | Sequence[str] = ()) → str#

Get or set the arrows on the Text Area.

With no arguments, the current arrows are returned as a string.

If any positional arguments are given, the arrows are set to the indicated directions only.

If the add keyword argument is specified, these arrows are added on the text area, joining any existing arrows.

If the remove keyword argument is specified, these arrows are removed from the text area.

The direction arrows may be given as iterable group of strings, or as a space-separated string.

Parameters:

*args – arrow directions to set on the Text Area
add – arrow directions to add to the Text Area
remove – arrow directions to remove from the Text Area

Returns:

a string describing the current arrow configuration

Examples:

note.arrows("N", "NE")  # Set North & North-East arrows only.
note.arrows("N NE")     # Set North & North-East arrows only.
note.arrows(add="N NE") # Add the North & North-East arrows.
note.arrows(remove=("N", "NE")) # Remove those arrows.

Divider#

class mhi.pscad.Divider(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

A variable length horizontal or vertical divider that can be added to a user canvas.

Divider Settings#
Param Name	Type	Description
state	Choice	Display: 2D, 3D
true-color	Color	Colour
style	Choice	Line Style: SOLID, DASH, DOT, DASHDOT
weight	Choice	Line Weight: 02_PT, 04_PT, 06_PT, 08_PT, 10_PT, 12_PT, 14_PT

Divider.parameters(*, parameters: Dict[str, Any] | None = None, **kwargs) → Dict[str, Any] | None#

Set or get the component’s parameters.

Parameters:

parameters (dict) – A dictionary of parameter values. (optional)
**kwargs – name=value keyword parameters.

Returns:

A dictionary of parameter values (if no parameters are being set), or None.

Divider.range(parameter: str) → Tuple | Set | range | None#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

Divider.horizontal(width: int)#

Set the divider to horizontal orientation with the given width.

Parameters:: width (int) – the width of the divider, in grid units.

Divider.vertical(height: int)#

Set the divider to vertical orientation with the given height.

Parameters:: height (int) – the height of the divider, in grid units.

Set the divider to a non-3D appearence. Optionally, change the line style, weight and colour.

Parameters:

style (str) – SOLID, DASH, DOT, or DASHDOT. (optional)
weight – the divider’s line weight. (optional)
colour (str) – The divider’s line colour. (optional)

The weight can be given as a floating point number, between 0.2 and 1.4, and integer between 0 and 7, or a string such as "02_PT".

Divider.solid(weight: str | int | float | None = None, colour: str | None = None)#

Set the divider to a non-3D appearence, with a solid line style. Optionally, change the line weight and colour.

Parameters:

weight – the divider’s line weight. (optional)
colour (str) – The divider’s line colour. (optional)

Divider.dashed(weight: str | int | float | None = None, colour: str | None = None)#

Set the divider to a non-3D appearence, with a dashed line style. Optionally, change the line weight and colour.

Parameters:

weight – the divider’s line weight. (optional)
colour (str) – The divider’s line colour. (optional)

Divider.dotted(weight: str | int | float | None = None, colour: str | None = None)#

Set the divider to a non-3D appearence, with a dotted line style. Optionally, change the line weight and colour.

Parameters:

weight – the divider’s line weight. (optional)
colour (str) – The divider’s line colour. (optional)

Divider.dot_dash(weight: str | int | float | None = None, colour: str | None = None)#

Set the divider to a non-3D appearence, with a dot-dash line style. Optionally, change the line weight and colour.

Parameters:

weight – the divider’s line weight. (optional)
colour (str) – The divider’s line colour. (optional)

Divider.raised(colour: str | None = None)#

Set the divider to a 3D appearence. Optionally, change the colour.

Parameters:: colour (str) – The divider’s line colour. (optional)

Group Box#

class mhi.pscad.GroupBox(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)#

A group box which may be placed on a user canvas, to visually show components which are related to each other.

Group Box Parameters#
Param Name	Type	Description
name	str	Name of the group box
show_name	bool	Show or Hide the group name
font	Font	Font
line_style	int	Border style: SOLID, DASH, DOT, DASHDOT
line_weight	int	Border Weight: 02_PT, 04_PT, 06_PT, 08_PT, 10_PT, 12_PT, 14_PT
line_colour	Color	Colour of the group box border
fill_style	int	Fill style of the group box interior
fill_fg	Color	Colour of foreground fill
fill_bg	Color	Colour of background fill

Added in version 2.9.

GroupBox.parameters(*, parameters: Dict[str, Any] | None = None, **kwargs) → Dict[str, Any] | None#

Set or get the component’s parameters.

Parameters:

parameters (dict) – A dictionary of parameter values. (optional)
**kwargs – name=value keyword parameters.

Returns:

A dictionary of parameter values (if no parameters are being set), or None.

GroupBox.range(parameter: str) → Tuple | Set | range | None#

Get legal values for a parameter

Parameters:

parameter (str) – A component parameter name

Returns:

a tuple, or frozenset of legal values, or
a range of legal values (integer setttings only), or
a Tuple[float, float] defining minimum & maximum values, or
an exception if the parameter does not have a defined range.

Table of Contents

Previous topic

Next topic

Components#

Common#

Properties#

Location#

Layers#

Modules#

Clipboard#

Z-Ordering#

User Components#

Properties#

Ports#

Modules#

Connections#

Wires#

Sticky Wire#

Bus#

T-Line#

Cable#

Output Channels#

Graph Frame#

Overlay Graph#

Parameters#

Properties#

Position#

Zoom#

Curves#

Clipboard#

Polygraph#

Parameters#

Properties#

Position#

Zoom#

Curves#

Clipboard#

XY Plot Frame#

Parameters#

Properties#

Appearence#

Zoom#

Curves#

Clipboard#

Curve#

Properties#

Methods#

Instruments#

Oscilloscope#

Phasor Meter#

Poly Meter#

Input Controls#

Control Frame#

General#

Button#

Switch#

Selector#

Slider#

Annotations#

Sticky#

Divider#

Group Box#