Reference#

A *.psout file reader library.

The PSOUT file is a binary file that contains one or more collections of traces. Each trace is a 1-d vector of data. A trace may have an associated “domain” trace with the same length. Different traces are identified by a location in a “call tree”. All trace collections, known as “runs” share the same call tree, although a trace may not exist at every location of the call tree in different runs.

File#

class mhi.psout.File#

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

General#

File.path#

Path of the file

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='/') → Call#

Retrive 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.call_tree(width: int = 0) → None#

Print the call tree of the .psout file

Runs#

File.num_runs#

The number of runs in file

File.runs() → Iterator[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) → 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

Call#

class mhi.psout.Call#

A Call in the global call tree of the file.

All calls other than the root call node will have a parent. Every call may have child subcalls, which in turn can have grandchildren, great-grandchildern, and so on.

Identification#

Call.id#

Returns call handle id

Call.parent#

Return the parent call handle

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

Children#

Call.num_calls#

Returns number of sub call handles

Call.calls() → Iterator[Call]#

Return the subcall children of the current node

Call.call(child: int | str) → Call#

Return a subcall of the current node, identified by either an id number, or a name.

Parameters:

child – the id or “Name” of a subcall

Run#

class mhi.psout.Run(file: File)#

A handle to a run set in the file. A run set is a collection of traces that match the set structure defined by the call nodes

Identification#

Run.id#

Returns run handle id

Run.file#

File run is from

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

Traces#

Run.num_traces#

Returns number of traces

Run.traces() → Iterator[Trace]#

Return the traces of this run

Run.trace(ident: int | Call) → Trace#

Return a trace from this run identified by index or call.

Parameters:

ident – the index or call of the trace

Run.trace_list(width: int = 0) → None#

Print all of the traces held within this run.

Run.call(*args, sep='/') → Trace#

Retrive a trace from this run for the given call path.

Parameters:

  • path – The call path, as names or ids

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

Examples:

trace = run.call("Root/Main/AC Voltage/Record/1", sep="/")
trace = run.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.

Trace#

class mhi.psout.Trace#

An individual trace stored in the file, identified by run and call.

Trace data is returned as an array.array(), with an underlying type code specifying byte, int or float values of various precision.

A trace may have an associated domain trace, such as time or frequency.

Note

Neither str not complex data types are supported by array.array() at this time.

Identification#

Trace.id#

Returns run handle id

Trace.call#

Returns the associated call

Trace.run#

Run trace is from

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

Data#

Trace.domain#

The domain of the trace

Trace.datatype#

Returns the trace datatype

Trace.size#

Returns the size

Trace.data#

Returns the sample values