.. _tutorial-1:

Tutorial 1: Outputs
===================
One of the first steps in modeling is to decide what the desired outputs should
be. For example, the outputs of a PV power simulation might be hourly energy and
the corresponding timestamps. In this tutorial we'll demonstrate how to specify
the outputs for a SimKit model. We use the term *outputs* to refer to the
results from calculations. We'll explain what the term *calculations* refers to
in :ref:`the next tutorial <tutorial-2>`, and we'll define the term *models* in
:ref:`the last tutorial <tutorial-5>`.

As discussed in :ref:`getting-started` there are two styles for specifying
SimKit parameters. First we'll show the preferred method to specify output
parameters using :class:`~simkit.core.outputs.OutputParameter` as attributes
in a subclass of :class:`~simkit.core.outputs.Output`. Later we'll also show
how to specify output parameters in a JSON file.

Outputs Class
-------------
We'll need to create a new Python module inside the ``pvpower`` package created
by running ``simkit-quickstart``. We can actually define all of our SimKit
parameters in this file. Let's call the new module ``performance.py``. Inside
the new module, we'll have to import the :class:`~simkit.core.outputs.Output`
class so we can create a subclass called ``PVPowerOutputs`` to hold our output
specifications. We also import :class:`~simkit.core.outputs.OutputParameter`
to specify outputs like hourly energy and the corresponding hourly timeseries.
We can also specify attributes like "units" and "size" for each output
parameter. Copy the following snippet into the PV power ``performance.py``
module to specify the rest of the output parameters. ::


    """
    PV power performance simulation
    """

    from simkit.core.outputs import Output, OutputParameter


    class PVPowerOutputs(Output):
        """
        Outputs for PV Power demo
        """

        timestamps = OutputParameter(isconstant=True, size=8761)

        hourly_energy = OutputParameter(
            isconstant=True,
            timeseries="hourly_timeseries",
            units="Wh",
            size=8760
        )
        # timestamps corresponding to hourly energy
        hourly_timeseries = OutputParameter(
            isconstant=True,units="Wh", size=8760
        )

        monthly_energy = OutputParameter(
            isconstant=True, units="Wh", size=12
        )

        annual_energy = OutputParameter(isconstant=True, units="Wh")

Outputs Registry
~~~~~~~~~~~~~~~~
When the model is initialized, the outputs from all output subclasses in the
model are stored together in a dictionary called the output *registry*. When the
simulation is executed, the output values are stored and retrieved from the
registry as needed. The :ref:`last tutorial <tutorial-5>` will explain more
about SimKit registries and how they're used.

Output Attributes
~~~~~~~~~~~~~~~~~
In the ``PVPowerOutputs`` snippet above each output is specified as a class
attribute set to an instance of an ``OutputParameter`` that has arguments like
units, initial value and size. The arguments of an ``OutputParameter`` represent
the attributes of that output parameter and are also stored in the output
registry. The following attributes can be passed to as arguments to
``OutputParameter``:

==========  =======================================
Attribute   Description
==========  =======================================
units       output units
init        initial value
size        array size
isconstant  constant value flag
isproperty  material property flag
timeseries  name of corresponding timeseries output
==========  =======================================

Attributes can be skipped or set to ``None`` if necessary. If the attributes are
passed as positional arguments, then the order corresponds to table above;
keyword arguments can be passed to ``OutputParameter`` in any order.

There are also some output attributes such as uncertainty and variance that are
calculated during the simulation and therefore should not be passed as arguments
to ``OutputParameter``. The following attributes are generated by SimKit:

+---------------+--------------------------------------------------------+
| Attribute     | Description                                            |
+===============+========================================================+
| uncertainty   | square roots of variance diagonal components           |
+---------------+--------------------------------------------------------+
| variance      | dictionary of covariance between formula outputs       |
+---------------+--------------------------------------------------------+
| jacobian      | dictionary of sensitivities between formula inputs and |
|               | outputs                                                |
+---------------+--------------------------------------------------------+
| output_source | name of the class in which outputs were specified      |
+---------------+--------------------------------------------------------+

Material Property Flag
++++++++++++++++++++++
Outputs of dynamic calculations that represent a material property remain at the
last value when the calculation is skipped because a simulation threshold is
exceeded. For example, PV performance degradation is an output that is a
material property. When performance is not calculated, for example at night, the
accumulated degradation remains at the last calculated value. On the other hand
PV cell power is not a material property; when not calculatd it would revert to
a default value. Set the ``isproperty`` attribute to true to indicate that an
output parameter is a material property.

Constant Value Flag and Timeseries
++++++++++++++++++++++++++++++++++
Constant values do not change during dynamic calculations. This flag has no
effect on static calculations and is only used in dynamic calculations to resize
outputs for writing files.

The timeseries output attribute is optional and is not currently used in
SimKit. However it can be used to indicate the index of an output that is a
timeseries perhaps making generation of a ``pandas.DataFrame`` easier.

Parameter File
--------------
The alternate style of specifying output parameters for each calculation is to
use a JSON file to list the desired outputs and their attributes in a file in
the ``outputs`` folder of the project.

For example create ``PVPower/outputs/pvpower.json`` and paste the following
snippet::

    {
      "timestamps": {"isconstant": true, "size": 8761},
      "hourly_energy": {
        "isconstant": true,
        "timeseries": "hourly_timeseries",
        "units": "W*h",
        "size": 8760
      },
      "hourly_timeseries": {
        "isconstant": true, "units": "W*h", "size": 8760
      },
      "monthly_energy": {
        "isconstant": true, "units": "W*h", "size": 12
      },
      "annual_energy": {"isconstant": true, "units": "W*h"}
    }

To tell SimKit to use these outputs, we need to create a new Python module in
the ``pvpower`` package, let's call it ``performance.py`` like in the example
above, and specify the file and path to the output parameter file in a
:class:`~simkit.core.outputs.Output` subclass::

    from simkit.core.outputs import Output
    import os
    from pvpower import PROJ_PATH


    class PVPowerOutputs(Output):
        """Outputs for PV Power demo"""
        class Meta:
            outputs_file = 'pvpower.json'
            outputs_path = os.path.join(PROJ_PATH, 'outputs')