Files#

Opening#

class mhi.psout.File(path: str | Path, sep: str = '/', *, open_type: OpenType = OpenType.OPEN_EXISTING, page_size: PageSize | int = PageSize.DEFAULT, reserve_size: ReserveSize | int = ReserveSize.DEFAULT, growth_size: GrowthSize | int = GrowthSize.DEFAULT)#

A PSOUT file object

The PSOUT file contains a “Call Stack” and a list of “Runs”. The “Call Stack” describes a tree of calls into which traces are organized, and is shared by all runs. The traces themselves are stored in distinct “Runs”. A trace can only be retrieved given both a run and a call.

The file must be closed when no longer in use. To assist, File implements the context manager interface, so it may be used in a with statement so that it is automatically closed.

Example:

with mhi.psout.File("Cigre.psout") as file:
    ac_voltage_a_call = file.call("Root/Main/AC Voltage/Record/1")
    run = file.run(0)
    va = run.trace(ac_voltage_a_call)
    time = va.domain
    matplotlib.pyplot.plot(time.data, va.data, label="Phase A voltage")

Note

When a file is opened with CREATE_RENAME, use the File.path attribute to retrieve the filename which was created.

Changed in version 1.3: Adds a default sep argument for later call paths

Changed in version 2.0: Adds open_type, page_size, reserve_size, and growth_size

Identification#

File.path#

Usually, this is the same path that was used to open the file, but will be different when CREATE_RENAME is used and the given file already existed.

Changed in version 2.0: Returns a Path even when the file is opened with a string.

File.created#

The ‘created on’ datetime

File.modified#

The ‘modified on’ datetime

File.variables() → Dict[str, Any]#

Retrieve the key=value attributes stored with this object as a dictionary.

If only a single variable value is required, item["VariableName"] may be used to fetch just that value.

File.close()#

Closes the record file

Calls#

File.root#

The root call for the file

File.call(*path: int | str, sep: str = '') → Call#

Retrieve a call from the given path in the call stack / tree

Parameters:

  • path – The call path, as names or ids

  • sep – A delimiter string, used when single string argument is given

Examples:

call = file.call("Root/Main/AC Voltage/Record/1", sep="/")
call = file.call("Root", "Main", "AC Voltage", "Record", 1)

Note

A path segment composed entirely of digits is converted to an integer and used as a call id.

File.calls(path: str = '**', *, sep: str = '') → Iterable[Call]#

Return the calls in the file that match the given path pattern.

Parameters:

  • path – An XPath-esque filter pattern

  • sep – A delimiter string (optional)

Example:

for call in file.calls("/**/*[@Source='PGB']"):
    print(call)

Added in version 1.3.

File.paths(path: str = '**', *, sep: str = '') → Iterable[str]#

Return the paths in the file that match the given path pattern.

Parameters:

  • path – An XPath-esque filter pattern

  • sep – A delimiter string (optional)

Example:

for call in file.paths("/**/*[@Source='PGB']"):
    print(call)

Added in version 1.3.

File.call_paths(path: str = '**', *, sep: str = '') → Iterable[Tuple[Call, str]]#

Return the calls and paths in the file that match the given path pattern.

Parameters:

  • path – An XPath-esque filter pattern

  • sep – A delimiter string (optional)

Example:

for call, path in file.call_paths("/**/*[@Source='PGB']"):
    print(path, call)

Added in version 1.3.

File.call_tree(width: int = 0, file: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → None#

Print the call tree of the .psout file

Parameters:

  • width – Limit output to given number of characters

  • file – stream to write output to (defaults to stdout)

Changed in version 1.3: Adds file argument

File.make_pscad_root() → Call#

Create a PSCAD conformant root module node

Returns a top-level MODULE call node with Name="Root", Description="Root", and Source="Module".

Added in version 2.0.

File.make_pscad_domain(iid: int, prefix: str) → Call#

Create a PSCAD conformant domain trace call

Returns a top-level TRACE call node with Name="{prefix}:Domain", and Description="{prefix}:Domain".

Added in version 2.0.

Runs#

File.num_runs#

The number of runs in file

File.runs() → Iterable[Run]#

Return the runs stored in the .psout file

File.run(index: int) → Run#

Get the nth run in the .psout file

File.fetch_run(run_id: int) → Run#

Fetch the run with the specified id.

File.run_list(*, width: int = 0, traces: bool = False, file: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → None#

Print all of the runs stored in the .psout file

Parameters:

  • width (int) – Limit output to given number of characters

  • traces (bool) – If True, also out traces stored in each run

  • file (TextIO) – Output stream

Changed in version 1.3: Adds file argument

File.add_run(iid: int = 0, **kwargs) → Run#

Add a new run to the .psout file

Parameters:

  • iid – identifier which may be used for “fetching” the run.

  • kwargs – Additional name/value pairs to store with the run.

Added in version 2.0.