Enerplot#

Launch & Connect#

mhi.enerplot.application() → Enerplot#

This method will find try to find a currently running Enerplot application, and connect to it. If no running Enerplot application can be found, or if it is unable to connect to that application, a new Enerplot application will be launched and a connection will be made to it.

If running inside a Python environment embedded within an Enerplot application, the containing application instance is always returned.

Returns:: The Enerplot application proxy object

Example:

import mhi.enerplot
enerplot = mhi.enerplot.application()
enerplot.load_files('myproject')

mhi.enerplot.connect(host: str | None = None, port: int = 0, timeout: int = 5) → Enerplot#

This method will find try to find a currently running Enerplot application, and connect to it.

Parameters:

host – The host the Enerplot application is running on (defaults to the local host)
port – The port to connect to. Required if running multiple Enerplot instances.
timeout – Seconds to wait for the connection to be accepted.

Returns:

The Enerplot application proxy object

Example:

import mhi.enerplot
enerplot = mhi.enerplot.connect()
enerplot.load_files('myproject')

mhi.enerplot.launch(port: int | range = 0, silence: bool = True, timeout: int = 5, version: str | None = None, minimum: str | None = '1.0', maximum: str | None = None, address: str | None = None, allow_alpha: bool | None = None, allow_beta: bool = False, x64: bool = True, **options) → Enerplot#

Launch a new Enerplot instance and return a connection to it.

Parameters:

port – The port to connect to. Required if running multiple Enerplot instances.
silence – Suppresses dialogs which can block automation.
timeout – Time (seconds) to wait for the connection to be accepted.
version – Specific version to launch if multiple versions present.
minimum – Minimum allowed version to run (default ‘1.0’)
maximum – Maximum allowed version to run (default: unlimited)
address – Interface address to bind PSCAD’s automation server on
options – Additional keyword=value options

Returns:

The Enerplot application proxy object

Example:

import mhi.enerplot
enerplot = mhi.enerplot.launch()
enerplot.load_files('myproject')

Changed in version 2.2.1: added minimum, maximum, allow_alpha, allow_beta, x64 parameters.

Changed in version 2.6.1: allow_alpha, allow_beta parameters are no longer supported.

Changed in version 3.0.0: allow_beta parameter is supported again.

mhi.enerplot.versions() → List[Tuple[str, bool]]#

Find the installed versions of Enerplot

Returns:: List of tuples of version string and 64-bit flag

Application Object#

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

The Enerplot Application

This object is a proxy object, used to communicate with a running Enerplot Application.

Properties#

Enerplot.version#: The Enerplot application version. (Read-only)

Added in version 2.2.

Enerplot.examples#: The Enerplot “Examples directory”. (Read-only)

Added in version 2.2.

Enerplot.substitute(value: str) → str#

Substitute Enerplot workspace and environment variables in the given string.

Parameters:: value – The format string to interpolate the variables into.
Returns:: The string with known variables substituted.

Example:

>>> enerplot.substitute('Running Enerplot version $(Version)')
'Running Enerplot version 1.1'

Added in version 2.3.

Workspace#

Enerplot.new_workspace(default_book: bool = True)#

Create a new workspace

The workspace will contain an ‘Untitled’ book, unless default_book is set to False.

Parameters:: default_book – Create an ‘Untitled’ book in the new workspace

Enerplot.load_workspace(workspace: Path | str, folder: Path | str | None = None)#

Load an existing Enerplot workspace

Parameters:

workspace – pathname to the workspace to load. The extension .epwx is appended if not present.
folder – If provided, the path to the workspace is resolved relative to this folder.

Enerplot.reload()#

Reload the workspace

Discard all unsaved changes and reload the workspace.

Enerplot.save_workspace(*, save_projects: bool = True)#

Save the current Enerplot workspace

Parameters:: save_projects – Set to False if only the workspace should be saved, and not any unsaved projects.

Enerplot.save_workspace_as(workspace: Path | str, *, folder: Path | str | None = None, save_projects: bool = True)#

Save the current Enerplot workspace

Parameters:

workspace – pathname to save the workspace as. The extension .epwx is appended if not present.
folder – If provided, the path to the workspace is resolved relative to this folder.
save_projects – Set to False if only the workspace should be saved, and not any unsaved projects.

Enerplot.is_dirty() → bool#

Determine whether the workspace has been modified since the last time it was saved.

Returns:: True if the workspace has unsaved changes, False otherwise.

Enerplot.workspace_dir#: Return the current workspace directory

Added in version 2.3.

Enerplot.workspace_name#: Return the current workspace name

Added in version 2.3.

Enerplot.workspace_path#: Return the current workspace path

Added in version 2.3.

Books#

Enerplot.load_books(*files: Path | str, folder: Path | str | None = None)#

Load one or more books into the workspace.

Parameters:

*files – pathnames to one or more project book files. A ~ or ~user prefix, as well as any $var, ${var} and %var% patterns in the pathnames are expanded, and the resulting pathnames are converted to absolute paths before being passed to the remote application.
folder – If provided, the relative paths to the files are resolved relative to this folder.

Enerplot.new_book(path: Path | str, folder: Path | str | None = None) → Book#

Create a new book

Parameters:

path – location to store the book. The extension .epbx is appended if not present.
folder – If provided, the path to the book is resolved relative to this folder.

Returns:

the book proxy object

Enerplot.books() → IndexableDict[str, Book]#

Returns:: an indexable dictionary of all currently loaded books

Enerplot.book(name: str) → Book#

Retrieve a book reference, by name

Parameters:: name – The simple name of the book. No punctuation characters.
Returns:: the book proxy object

Data Files#

Enerplot.load_datafiles(*files: Path | str, folder: Path | str | None = None, load_data: bool = True, fmt: int = 0) → IndexableDict[str, DataFile]#

Load data files

Parameters:

*files – One or more pathnames to datafiles.
folder – If provided, the datafile paths are resolved relative to this folder.
load_data – Set to False to delay loading of the data until it is needed.
fmt – If the extensions do not indicate a unique format, a format code is required.

Returns:

an indexable dictionary of data files

“File Load Type” Format Codes#
Format Code	Description
DataFile.FLT_EMTDC	PSCAD/EMTDC
DataFile.FLT_CSV	Comma Separated Files
DataFile.FLT_CSV_UNFORMATTED	Comma Separated Files (Unformatted)
DataFile.FLT_COMTRADE	COMTRADE Files
DataFile.FLT_PSSE	PSS/E Files
DataFile.FLT_HFS	Harmonic Frequency Scanner Files
DataFile.FLT_RSCAD	RSCAD Files

Enerplot.new_datafile(path: Path | str = 'External_Data', folder: Path | str | None = None, label: str | None = None) → DataFile#

Create a new “.mod.csv” datafile

Parameters:

path – The name and location to store the datafile.
folder – If provided, the datafile is located relative to this folder.
label – If provided, a label for the new datafile

Returns:

the created data file

Enerplot.datafiles() → IndexableDict[str, DataFile]#

List the currently loaded data files

Returns:: an indexable dictionary of data files

Enerplot.datafile(name: str) → DataFile#

Retrieve a data file reference, by name.

Parameters:: name – The name or label of the data file
Returns:: the named data file

Status & Progress#

The status bar at the bottom of the application is used to give feedback to the user about the progress of various operations as well as the final results. The following functions grant a script access to this feedback.

Enerplot.status(message: str, window: int = 0)#

Display a message in a status bar message window

Parameters:

message – Message to display in status bar
window – Status bar message window number (0, 1, or 2)

Enerplot.progress(text: str = '', total: int = 100, status: int = 0, priority: int = 0) → Progress#

Create and return a Progress Bar

Parameters:

text – Message to display in progress bar
total – Maximum progress value (default: 100)
status – 0 = running, 1 = waiting, 2 = stopped
priority – priority for the progress bar display

Returns:

a progress bar

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

Progress Bar in the application’s Status Bar area

When finished with a progress bar, it is imperative to call the close() method to allow Enerplot to remove the bar from the status window. This is easiest done using a with statement which will automatically close the resource, even if an exception or early return occurs:

with enerplot.progress() as progress_bar:
    progress_bar.update(10)
    progress_bar.update(50)
    progress_bar.update(100)

Update a previously created progress bar

Parameters:

amount – new amount of progress to display in the bar
total – new maximum value for the progress bar (optional)
status – 0 = running, 1 = waiting, 2 = stopped (optional)
priority – priority for the progress bar (optional)
text – message to display in progress bar (optional)

property amount#: progress bar amount (write-only)

property total#: progress bar total (write-only)

property status#: progress bar status code (write-only)

property priority#: progress bar priority (write-only)

property text#: progress bar text (write-only)

close() → None#

Remove the progress bar from the status bar at the bottom of the application.

with enerplot.progress() as progress_bar:
    progress_bar.update(10)
    progress_bar.update(50)
    progress_bar.update(100)

Table of Contents

Previous topic

Next topic

Enerplot#

Launch & Connect#

Application Object#

Properties#

Workspace#

Books#

Data Files#

Status & Progress#