Getting Started#

This page explains how to get started with SunPeek as a Python package.

Installation#

This assumes that you have Python installed, in a version compatible with SunPeek. See the backend README for currently compatible Python versions (e.g. Python 3.13). Then, install SunPeek:

pip install sunpeek[demo]

Note

The [demo] extra includes sample data for this tutorial. For your own projects, pip install sunpeek is sufficient.

Important

You do NOT need to clone the SunPeek repository to use these examples. Simply install via pip and copy the example code below into your own Python scripts.

If you have cloned the repository for development purposes and encounter errors about PNG files or missing assets, you need to install Git LFS and run:

git lfs install --force
git lfs pull

Using SunPeek with pre-defined demo plant#

This is a simplified example, based on the FHW plant in Graz, Austria. The data used here (together with a detailed description) is available as open data at https://doi.org/10.5281/zenodo.7741084

This example shows how to use SunPeek on this demo plant programmatically with Python, following 3 basic steps:

  1. Create SunPeek plant object

  2. Load measurement data

  3. Perform Power Check analysis

To run this example:

  1. Create a new Python file (e.g., demo_plant.py)

  2. Copy the code below into your file

  3. Run: python demo_plant.py

import logging
import sunpeek.demo
from sunpeek.common import config_parser
from sunpeek.common.utils import DatetimeTemplates
from sunpeek.components import FluidFactory
from sunpeek.core_methods.power_check.plotting import create_pdf_report
from sunpeek.core_methods.power_check.wrapper import run_power_check
from sunpeek.data_handling.wrapper import use_csv
from sunpeek.definitions.collectors import get_definition as get_collector_definition
from sunpeek.definitions.fluid_definitions import WPDFluids, get_definition

logging.getLogger('sp_logger').setLevel(logging.INFO)

# ----------------------------------------------------------------------------------------
# 1. Get plant object from pre-defined configuration
plant = config_parser.make_plant_from_config_file(sunpeek.demo.DEMO_CONFIG_PATH)
# Define collector type and heat transfer fluid
plant.arrays[0].collector = get_collector_definition("Arcon 3510")
plant.fluid_solar = FluidFactory(fluid=get_definition(WPDFluids.fhw_pekasolar.value.name))

# ----------------------------------------------------------------------------------------
# 2. Load measurement dataset
# dataset = sunpeek.demo.DEMO_DATA_PATH_2DAYS
dataset = sunpeek.demo.DEMO_DATA_PATH_1MONTH
use_csv(plant,
        csv_files=[dataset],
        timezone='utc',
        datetime_template=DatetimeTemplates.year_month_day)

# ----------------------------------------------------------------------------------------
# 3. Perform Power Check analysis, generate report
power_check_output = run_power_check(plant).output
report_path = create_pdf_report(power_check_output)
print(f"Power Check: {power_check_output.plant_output.n_intervals} intervals found.")

Using SunPeek with custom plant#

This example demonstrates how to use SunPeek for custom plants without a pre-existing configuration file. It reuses the demo plant’s data and structure for illustration purposes, but the step-by-step approach shows how to build any plant from scratch. It follows these main steps:

  1. Define sensors with their units and metadata

  2. Create the plant with location and sensor mappings

  3. Configure the solar collector and heat transfer fluid

  4. Create the array and add it to the plant

  5. Load measurement data

  6. Perform Power Check analysis and generate a report

To run this example:

  1. Create a new Python file (e.g., custom_plant.py)

  2. Copy the code below into your file

  3. Run: python custom_plant.py

"""Demo script showing how to create a SunPeek plant programmatically using the Python API.

This creates the same plant as script_demo_preconfigured.py, but without using a config file.
All components (Plant, Array, Sensors, Collector, Fluid) are created explicitly.
"""
import logging

import sunpeek.demo
from sunpeek.common.unit_uncertainty import Q
from sunpeek.common.utils import DatetimeTemplates
from sunpeek.components import (
    Plant, Array, Sensor, SensorInfo,
    CollectorQDT, CollectorTypes, IAM_Interpolated,
    FluidFactory, MountingFixed,
)
from sunpeek.core_methods.power_check.plotting import create_pdf_report
from sunpeek.core_methods.power_check.wrapper import run_power_check
from sunpeek.data_handling.wrapper import use_csv
from sunpeek.definitions.fluid_definitions import get_definition as get_fluid_definition

logging.getLogger('sp_logger').setLevel(logging.INFO)

# ----------------------------------------------------------------------------------------
# 1. Define all sensors

# Normal sensors: Specify name and physical unit.
# "raw_name" must match column headers in measurement data file.
sensors = [
    Sensor(raw_name='te_amb', native_unit='K'),
    Sensor('te_in', 'K'),
    Sensor('te_out', 'K'),
    Sensor('ve_wind', 'm s**-1'),
]

# Irradiance sensor, with orientation metadata
# Note: More irradiance measurements are available for the demo plant, but only global tilted irradiance is used here.
sensors.append(
    Sensor('rd_gti', 'W m**-2',
           info=SensorInfo(tilt=Q(30, 'deg'), azim=Q(180, 'deg')))
)

# Volume flow sensor, with position (between inlet and outlet temperature measurements)
sensors.append(
    Sensor('vf', 'm**3 s**-1',
           info=SensorInfo(position=Q(0, '')))
)

# ----------------------------------------------------------------------------------------
# 2. Create plant
plant = Plant(
    name='FHW Arcon South custom',
    latitude=Q(47.047201, 'deg'),
    longitude=Q(15.436428, 'deg'),
    elevation=Q(344, 'm'),
    raw_sensors=sensors,
    # Plant-level sensor mappings
    sensor_map={
        'te_amb': 'te_amb',
        've_wind': 've_wind',
        'vf': 'vf',
        'te_in': 'te_in',
        'te_out': 'te_out',
    },
)

# ----------------------------------------------------------------------------------------
# 3. Set solar collector and heat transfer fluid

# Define collector explicitly
# Note: QDT = Quasi-Dynamic Test per ISO 9806.
# For older, statically-tested collectors, use CollectorSST instead.
collector = CollectorQDT(
    name='my collector',
    manufacturer_name='xyz',
    product_name='abc',
    collector_type=CollectorTypes.flat_plate,
    test_reference_area='gross',
    area_gr=Q(12, 'm**2'),
    gross_length=Q(2400, 'mm'),
    gross_width=Q(5000, 'mm'),
    gross_height=Q(150, 'mm'),
    # Performance parameters from Solar Keymark certificate
    eta0b=Q(0.75, ''),
    a1=Q(2.3, 'W m**-2 K**-1'),
    a2=Q(0.01, 'W m**-2 K**-2'),
    a5=Q(7.5, 'kJ m**-2 K**-1'),
    kd=Q(0.94, ''),
    iam_method=IAM_Interpolated(
        aoi_reference=Q([10, 20, 30, 40, 50, 60, 70, 80, 90], 'deg'),
        iam_reference=Q([1, 0.99, 0.97, 0.94, 0.9, 0.82, 0.65, 0.32, 0]),
    ),
)

# Set heat transfer fluid
# Use a propylene glycol from CoolProp, with 40% concentration.
plant.fluid_solar = FluidFactory(
    fluid=get_fluid_definition('AL'),  # Antifrogen L (Propylene Glycol)
    concentration=Q(40, 'percent'),
)
# Notes:
# - Using own fluids (not available in CoolProp) is also possible with SunPeek.
#   See class WPDFluids in https://gitlab.com/sunpeek/sunpeek/-/blob/main/sunpeek/definitions/fluid_definitions.py
# - Defining fluid is only necessary if thermal power is not directly available in measurement data,
#   but needs to be computed based on fluid properties, volume or mass flow, and a temperature difference.
#   SunPeek does this calculation automatically if needed.


# ----------------------------------------------------------------------------------------
# 4. Create array and add to plant
array = Array(
    name='my array',
    plant=plant,
    collector=collector,
    mounting=MountingFixed(surface_tilt=Q(30, 'deg'), surface_azimuth=Q(180, 'deg')),
    area_gr=Q(500, 'm**2'),
    ground_tilt=Q(0, 'deg'),  # optional
    row_spacing=Q(3.1, 'm'),
    # Array-level sensor mappings
    sensor_map={
        'te_in': 'te_in',
        'te_out': 'te_out',
        'vf': 'vf',
        'in_global': 'rd_gti',
    },
)
plant.add_array(array)


# ----------------------------------------------------------------------------------------
# 5. Load measurement dataset
# dataset = sunpeek.demo.DEMO_DATA_PATH_2DAYS
dataset = sunpeek.demo.DEMO_DATA_PATH_1MONTH
use_csv(plant,
        csv_files=[dataset],
        timezone='utc',
        datetime_template=DatetimeTemplates.year_month_day)


# ----------------------------------------------------------------------------------------
# 6. Perform Power Check analysis, generate report
power_check_output = run_power_check(plant).output
report_path = create_pdf_report(power_check_output)
print(f"Power Check: {power_check_output.plant_output.n_intervals} intervals found.")

Note

This example uses MountingFixed to define the array’s fixed-tilt orientation. For single-axis tracking systems, use MountingSingleAxis instead. See Arrays and Mounting Configuration for details on mounting configuration.

For backward compatibility, the legacy tilt and azim parameters still work and are automatically converted to MountingFixed internally.

See also