pysunergy-calc

Geometry-based solar potential, irradiance, and solar PV energy calculations in Python—just math, physics, and data classes; no external APIs needed.

• Accurate solar geometry: Compute sun position (declination, hour angle, altitude, azimuth, zenith) for any latitude, longitude, and datetime.
• Instantaneous PV power calculation: Use panel specs and solar irradiance to compute real-time output.
• Energy output estimation: Predict daily, yearly, or custom-period PV system yield.

Formulas

References:

• PV Education: Solar Insolation
• Panel Output Formula
• Solar Output Guide
• EcoFlow Output Math

Installation

pip install pysunergy-calc

Usage

from pysunergy_calc import (
    compute_solar_potential,
    compute_panel_power,
    estimate_energy_produced,
)

# Example 1: Sun position and irradiance in New York on August 15, 2025, at 16:00 UTC
from datetime import datetime, timezone
sun = compute_solar_potential(
    40.7128,          # latitude
    -74.0060,         # longitude
    datetime(2025, 8, 15, 16, 0, 0, tzinfo=timezone.utc) # UTC date/time
)
print(sun)
# SolarPosition(
#     declination=..., hour_angle=..., altitude=..., azimuth=..., zenith=..., irradiance=...
# )

# Example 2: Compute panel output at that instant
area = 1.6      # m² (panel area)
efficiency = 0.20  # 20% PV efficiency
power_W = compute_panel_power(area, efficiency, sun.irradiance)
print(power_W)

# Example 3: Estimate daily energy (kWh) for your panel
average_irradiance = 5 * 1000 / 24  # e.g., 5kWh/m²/day avg ≈ 208 W/m² avg
daily_kWh = estimate_energy_produced(
    area,
    efficiency,
    average_irradiance,
    24,      # hours in a day
    0.75     # typical performance ratio (losses)
)
print(daily_kWh)

API Reference

compute_solar_potential(lat: float, lon: float, date: datetime) -> SolarPosition

• All angles are in degrees.
• irradiance is in W/m² (horizontal surface).
• Calculates solar declination, hour angle, altitude, azimuth, zenith, and irradiance for a specified location/time.

compute_panel_power(area: float, efficiency: float, irradiance: float) -> float

• area: Panel area (m²)
• efficiency: Panel efficiency (0...1)
• irradiance: Solar irradiance (W/m²)
• Returns instantaneous PV output power (W).

estimate_energy_produced(area: float, efficiency: float, average_irradiance: float, period_hours: float, performance_ratio: float=0.75) -> float

• Estimates total energy output for your system and conditions, in kWh over the specified period.
• Typical performance_ratio is 0.75–0.85 (accounts for temperature, dust, inverter).
• Average irradiance is entered in W/m².

Development & Testing

• 100% Python, type-annotated and PEP 621 compliant.
• Full Pytest test suite included.
• To develop and run tests:

uv pip install --group dev
pytest

• Code is linted/formatted automatically with ruff.

License

MIT © Abdullah Waqar

See Also

Node.js / TypeScript Version

Looking for a similar library for Node.js or TypeScript?

Check out the original sunergy-calc package for JavaScript/TypeScript with the same solar geometry and PV calculation logic.

• NPM package: sunergy-calc
• Source repo: https://github.com/abdullahwaqar/sunergy-calc

Use that version if you want to run solar calculations in web apps, serverless functions, or Node/TypeScript projects.

pysunergy-calc is not affiliated with nor endorsed by pveducation.org, palmetto.com, Sunbase, or EcoFlow. Reference links are for scientific documentation and transparency only.