sunergy-calc

TypeScript library for geometry-based solar potential, irradiance, and solar PV energy calculations — no external APIs, only math and physics.

Features

• Accurate solar geometry: Compute sun position (declination, hour angle, altitude, azimuth, zenith) for any lat/lon/date.
• Instantaneous and integrated PV power calculation using panel specs and solar irradiance.
• Energy output estimation for any period and PV system (daily, annual, custom).
• Physics-based, no Google API or network dependency.
• TypeScript-first, typed, and fully documented.

Formulas

| Step | Equation | | ----------- | --------------------------------------------------- | | Declination | δ = 23.45 × sin[(360/365) × (n − 81)] | | Hour angle | H = 15 × (solar-time-hours − 12) | | Altitude | sin(α) = sin(δ) sin(φ) + cos(δ) cos(φ) cos(H) | | Azimuth | sin(Az) = cos(δ) sin(H) / cos(α) | | Irradiance | I = I₀ × sin(α) (for horizontal surface, clear sky) |

Installation

npm install sunergy-calc

# or

yarn add sunergy-calc

Usage

import {
    computeSolarPotential,
    computePanelPower,
    estimateEnergyProduced
} from "sunergy-calc";

// Example 1: Sun position and irradiance at NY, August 15, 2025, 16:00 UTC
const sun = computeSolarPotential(
    40.7128, // latitude
    -74.0060, // longitude
    new Date(Date.UTC(2025, 7, 15, 16, 0, 0)) // UTC date/time
);

console.log(sun);

{
    declination: ...,
    hourAngle: ...,
    altitude: ...,
    azimuth: ...,
    zenith: ...,
    irradiance: ... // W/m² on horizontal
}


// Example 2: Compute actual panel output at this moment
const area = 1.6; // m² (single panel)
const efficiency = 0.20; // 20%
const powerW = computePanelPower(area, efficiency, sun.irradiance);

// Example 3: Estimate daily energy (kWh) for your panel
const averageIrradiance = 5 \* 1000 / 24; // e.g., 5kWh/m²/day avg = ~208 W/m² avg
const kWh = estimateEnergyProduced(
    area,
    efficiency,
    averageIrradiance,
    24, // hours in day
    0.75 // typical performance ratio (losses)
);

API

computeSolarPotential(lat, lon, date): SolarPosition

• All angles in degrees; irradiance in W/m².
• Calculates solar declination, hour angle, altitude, azimuth, zenith, and solar irradiance for a given moment/location.
• See: Solar Insolation Formula

computePanelPower(area, efficiency, irradiance): number

• area: Panel area (m²)
• efficiency: PV efficiency (0...1)
• irradiance: Solar irradiance (W/m²)
• Power (W) = area * efficiency * irradiance
• See: PV Power Equation

estimateEnergyProduced(area, efficiency, averageIrradiance, periodHours, performanceRatio=0.75): number

• Estimates energy output for the system over the given period in kWh
• Typical PR (performance ratio) = 0.75–0.85 (accounts for temperature, dust, inverter)
• See: Output Formulas, EcoFlow Guide

References

• Calculation of Solar Insolation
• How To Calculate Solar Panel Output
• Solar Energy Output: Full Guide
• Solar Output Math/Examples

Development & Testing

• Written in TypeScript, fully typed
• Robust Jest test suite
• To run tests:

npm install
npx jest

License

MIT © Abdullah Waqar

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