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)

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

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

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

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

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, *, parameters: Dict[str, Any] | None = None, **kwargs) Dict[str, Any] | 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)#

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

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(parameters: Dict[str, Any] | None = None, **kwargs) Dict[str, Any] | 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)#

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

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

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#

PlotFrame.zoom(xmin: float | None = None, xmax: float | None = None, ymin: float | None = None, ymax: float | None = None, start: float | None = None, end: float | None = None) None#

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, y: PGB | Curve) Tuple[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.

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=None, **kwargs)#

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

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

Related / linked component id

property linked: Component#

Component which this control component is linked to.

property order: Any#

Position in Control Panel

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.

range(parameter: str)#

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 switch with between 3 to 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)#

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

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.

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

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

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.