========
Tutorial
========

.. py:currentmodule:: mhi.psout

Setup
=====

Use ``py -m pip install mhi.psout`` to install the PSOut reader module.

.. only:: builder_html

	The following examples use this :download:`Cigre.psout <Cigre.psout>` file.

Opening a file
==============

To ensure the file is properly closed and resources are released,
a ``with`` statement should be used to open the file.

.. literalinclude:: step-00.py

.. literalinclude:: step-00.out
	:language: none


Finding a Call
==============

The call tree begins with the :attr:`File.root` node.
Each node may have subcall nodes, which in turn may have additional subnodes.
The :meth:`.calls() <Call.calls>` method may be used to iterate over the subcalls.

.. literalinclude:: step-01.py

.. literalinclude:: step-01.out
	:language: none
	:lines: 1-19
	:append: ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮

Beneath the :attr:`File.root` node (the only node which does not have a ``"Name"``),
PSCAD created a node called ``"Root"``.
Underneath that node, a call for the ``"Main"`` canvas was created.
Beneath that, a node was created for the ``"AC Voltage"`` PGB data.
The individual nodes for phase A, B and C are nested in an additional ``"Record"`` node.

The :meth:`File.call_tree` method already exists which will print out the
call tree with more detail:

.. literalinclude:: step-02.out
	:language: none
	:lines: 1-19
	:append: ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮   ⋮


Navigating to a Call
====================

When the path is known, you can navigated down from a node to a subnode
using :meth:`.call(...) <Call.call>` at each step.

.. literalinclude:: step-03.py

.. literalinclude:: step-03.out
	:language: none


As a convineance, :meth:`File.call(...) <File.call>` will traverse a path from the
:attr:`File.root` to the indicated node.
For instance, using ``"Root/Main/AC Voltage/Record"`` brings us to the
same node as above.
Instead of using a name (such as ``Record``), a node id (such as ``0``) may be used.
This is especially important when names are not unique,
such as with PSCAD naming all 3 subcalls ``"PGB:Data"``.

.. literalinclude:: step-04.py

.. literalinclude:: step-04.out
	:language: none


Getting a Trace
===============

Traces are stored within individual runs, and a ``.psout`` file can store many runs.
To retrieve a trace, we must first fetch the desired run.
Since our file only contains one run, we can simply retrieve the zeroth run.

.. literalinclude:: step-05.py
	:end-at: run = file.run(0)

Once we have the run, we simply request the trace for the given call.

.. literalinclude:: step-05.py
	:start-at: a = run.trace(ph_a)
	:end-at: print(c.datatype, c.size)

The :attr:`Trace.data` attribute contains the trace sample values.
We can display the first few values for each phase:

.. literalinclude:: step-05.py
	:start-at: print("A: "

.. literalinclude:: step-05.out
	:language: none


Domain
======

Samples values are meaningless without corresponding domain values.
In this case, the phase values are sampled over time, so the domain for each trace
will be the time axis.

The domain is itself a trace, with a :attr:`~Trace.datatype` and :attr:`~Trace.size`.
The domain for each trace can be retrieved using the :attr:`~Trace.domain` attribute.

While each trace may have its own domain, often those domains are shared.
In this case, the samples for the phases are all taken at the same moments in time,
so they all share the same "time domain".

.. literalinclude:: step-06.py
	:start-at: All domains are the same?

.. literalinclude:: step-06.out
	:language: none
	:start-at: All domains are the same?

.. note::

	PSCAD Animations are stored in traces, but since different animations can change
	appearences at different times, each animation trace will have its own time domain
	trace, containing only the time moments when the animation state changes.

Plotting Data
=============

With domain and range data, the traces may be directly plotted using
``matplotlib`` or other plotting packages:

.. literalinclude:: step-09.py

.. image:: ac_voltage.png

