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 the next tutorial, and we’ll define the term models in the last tutorial.

As discussed in Getting Started there are two styles for specifying SimKit parameters. First we’ll show the preferred method to specify output parameters using OutputParameter as attributes in a subclass of 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 Output class so we can create a subclass called PVPowerOutputs to hold our output specifications. We also import 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 last tutorial 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 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')