Viborg Solceller ApS - PV Production Forecast Service

Input Configuration JSON Schema & Documentation Reference

Overview

This document details all supported configuration fields for the PV Production Forecast JSON input schema. The parameters control site localization, central inverter specifications, and physical string array features such as bifacial gain, horizon shading, and seasonal obstruction profiles.

JSON Configuration Example

{
  "lat": 55.6761,
  "lon": 12.5683,
  "inverter_kw": 10.0,
  "freq": "15min",
  "arrays": [
    {
      "kwp": 5.0,
      "azimuth_deg": 180.0,
      "tilt_deg": 25.0,
      "mismatch": 0.02,
      "module": {
        "gamma_pdc": -0.004,
        "noct_temp": 45.0
      },
      "bifacial": {
        "enabled": true,
        "bifaciality": 0.75,
        "albedo": 0.20,
        "mount": "open_rack",
        "k_geom": 0.50
      },
      "horizon": {
        "azimuth_deg": [0, 90, 180, 270],
        "horizon_deg": [0, 10, 15, 5]
      },
      "azimuth_multiplier": {
        "azimuth_deg": [0, 90, 180, 270, 360],
        "multiplier": [0.0, 1.0, 1.0, 0.8, 0.0]
      },
      "seasonal_shade": {
        "jan": [0.70],
        "jun": [
          0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
          0.5, 0.8, 1.0, 1.0, 1.0, 1.0,
          1.0, 1.0, 0.7, 0.5, 0.2, 0.0,
          0.0, 0.0, 0.0, 0.0, 0.0, 0.0
        ]
      }
    }
  ]
}

1. Top-Level Options

Field Type Status Default Description
lat float Required — Latitude of the PV installation site in decimal degrees (-90.0 to 90.0).
lon float Required — Longitude of the PV installation site in decimal degrees (-180.0 to 180.0).
inverter_kw float Optional 10.0 Total nominal AC power rating of the central inverter in kW. Serves as the maximum clipping threshold.
freq string Optional "15min" Output time series resolution/frequency (e.g., "5min", "15min", "1h").
arrays array[object] Required — List of PV array / string specifications.

2. Array Object Options (arrays[])

Each dictionary inside the arrays list represents an independent PV string connected to the system inverter.

Core Parameters

Field Type Status Default Description
kwp float Required — Peak DC rated capacity of the PV string in kilowatt-peak (kWp).
azimuth_deg float Optional 180.0 Compass azimuth orientation angle in degrees (0° = N, 90° = E, 180° = S, 270° = W).
tilt_deg float Optional 25.0 Panel tilt angle from horizontal in degrees (0° = Flat, 90° = Vertical).
mismatch float Optional null System DC mismatch / wiring loss factor as a fraction (e.g., 0.02 for 2% loss). Calculated as (1 - mismatch).

module Sub-Object (Optional)

Thermal and temperature loss settings for solar panels.

Field Type Default Description
gamma_pdc float -0.004 Temperature power coefficient in 1/°C (e.g., -0.004 = -0.4%/°C).
noct_temp float 45.0 Nominal Operating Cell Temperature (NOCT) in °C.

bifacial Sub-Object (Optional)

Rear-side irradiance model for bifacial panels.

Field Type Default Description
enabled boolean false Enables rear-side bifacial irradiance capture when true.
bifaciality float 0.75 Ratio of rear-side efficiency compared to front-side efficiency (0.75 = 75%).
albedo float 0.20 Ground reflectance factor (e.g., 0.2 for grass, 0.6 for bright concrete).
mount string "open_rack" Mount type configuration. Supported values: "open_rack" (default k_geom=0.50), "close_mount" (0.15), "ground_mount" (0.15).
k_geom float Derived Geometric ground view factor. Overrides default set by mount.

horizon Sub-Object (Optional)

Topographical or horizon obstruction masking profile.

Field Type Description
azimuth_deg array[float] Compass azimuth coordinates for horizon points (0° to 360°).
horizon_deg array[float] Horizon elevation angle in degrees corresponding to azimuth. Direct beam solar irradiance is set to 0 when solar elevation ≤ horizon height.
Note: Both azimuth_deg and horizon_deg arrays must contain the exact same number of elements.

azimuth_multiplier Sub-Object (Optional)

Directional scaling factors applied directly to Plane of Array (POA) irradiance based on solar position.

Field Type Description
azimuth_deg array[float] Solar azimuth orientation angles.
multiplier array[float] Scaling factors (≥ 0.0) applied to POA irradiance. Interpolates linearly across solar azimuth positions.

seasonal_shade Sub-Object (Optional)

Monthly and hourly shading multipliers applied directly to Plane of Array irradiance (1.0 = 0% shade, 0.0 = 100% shade).