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(path: str | Path, sep: str = '/')#

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

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

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: 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

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

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.call(path: int | str, *, sep: str = '') → Call#

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

Parameters:

path – the id or xpath of a subcall
sep – A delimiter string (optional)

Changed in version 1.3: Accepts a path instead of a name, simplifying access to grandchildren

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

Return the subcall children of the current call, matching the given path pattern.

Parameters:

path – An XPath-esque filter pattern
sep – A delimiter string (optional)

Examples:

for child in call.calls():
    print(child)

for descendent in call.calls('**'):
    print(descendent)

Changed in version 1.3: Added optional path argument (defaults to *)

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

Return the subcall child paths of the current call, matching the given path pattern.

Parameters:

path – An XPath-esque filter pattern
sep – A delimiter string (optional)

Examples:

for path in call.paths():
    print(path)

for path in call.paths('**'):
    print(path)

Added in version 1.3.

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

Return the calls and paths from the current call that match the given path pattern.

Parameters:

path – An XPath-esque filter pattern
sep – A delimiter string (optional)

Example:

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

Added in version 1.3.

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() → Iterable[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, file: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → None#: Print all of the traces held within this run.

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

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

Run.trace_paths(path: str = "**/[@Source='Trace']", sep: str = '') → Iterable[Tuple[Trace, str]]#

Retrieve the traces and paths from this run which match the given call path.

Parameters:

path – The call path to find traces
sep – A delimiter string (optional)

Example:

for trace, path in run.trace_paths("**/[@Source='Trace']"):
    print(path, trace)

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

Table of Contents

Previous topic

Next topic

Reference#

File#

General#

Calls#

Runs#

Call#

Identification#

Children#

Run#

Identification#

Traces#

Trace#

Identification#

Data#