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 Carousel 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 Carousel 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 carousel-quickstart. We can actually define all of our Carousel 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 carousel.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 Carousel 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 Carousel:

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 Carousel. 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 Carousel 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 carousel.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')