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
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:
Create SunPeek plant object
Load measurement data
Perform Power Check analysis
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:
Define sensors with their units and metadata
Create the plant with location and sensor mappings
Configure the solar collector and heat transfer fluid
Create the array and add it to the plant
Load measurement data
Perform Power Check analysis and generate a report
"""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,
)
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,
area_gr=Q(500, 'm**2'),
azim=Q(180, 'deg'),
tilt=Q(30, 'deg'),
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.")
See also
Collectors — Technical reference for solar collector types and parameters
Fluids — Technical reference for heat transfer fluid configuration