# pysunergy-calc
Geometry-based solar potential, irradiance, and solar PV energy calculations in Python—**just math, physics, and data classes; no external APIs needed**.
[](https://pypi.org/project/pysunergy-calc/)
[](LICENSE)
[](https://github.com/abdullahwaqar/pysunergy_calc/actions/workflows/test.yml)
- **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
| 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) |
References:
- [PV Education: Solar Insolation](https://www.pveducation.org/pvcdrom/properties-of-sunlight/calculation-of-solar-insolation)
- [Panel Output Formula](https://www.sunbasedata.com/blog/how-to-calculate-solar-panel-output)
- [Solar Output Guide](https://palmetto.com/solar/how-much-energy-does-a-solar-panel-produce)
- [EcoFlow Output Math](https://www.ecoflow.com/us/blog/how-to-calculate-solar-panel-output)
---
## Installation
```bash
pip install pysunergy-calc
```
---
## Usage
```python
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:
```bash
uv pip install --group dev
pytest
```
- Code is linted/formatted automatically with [ruff](https://github.com/astral-sh/ruff).
---
## License
[MIT](LICENSE) © Abdullah Waqar
---
## See Also
### Node.js / TypeScript Version
Looking for a similar library for Node.js or TypeScript?
Check out the original [sunergy-calc](https://www.npmjs.com/package/sunergy-calc) package for JavaScript/TypeScript with the same solar geometry and PV calculation logic.
- **NPM package:** [sunergy-calc](https://www.npmjs.com/package/sunergy-calc)
- **Source repo:** [https://github.com/abdullahwaqar/sunergy-calc](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._
Raw data
{
"_id": null,
"home_page": null,
"name": "pysunergy-calc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "PV output calculation, cleantech, energy modeling, engineering, geometry, math, no API, photovoltaic, pv, pv system, renewable energy, solar, solar energy, solar insolation, solar irradiance, solar panel, solar potential, solar power, sun position",
"author": "Abdullah Waqar",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3d/bf/68a969720edfd16dfe5875f0072b5b12f845b3eb645581b72be28050fcda/pysunergy_calc-1.0.4.tar.gz",
"platform": null,
"description": "# pysunergy-calc\n\nGeometry-based solar potential, irradiance, and solar PV energy calculations in Python\u2014**just math, physics, and data classes; no external APIs needed**.\n\n[](https://pypi.org/project/pysunergy-calc/)\n[](LICENSE)\n[](https://github.com/abdullahwaqar/pysunergy_calc/actions/workflows/test.yml)\n\n- **Accurate solar geometry:** Compute sun position (declination, hour angle, altitude, azimuth, zenith) for any latitude, longitude, and datetime.\n- **Instantaneous PV power calculation:** Use panel specs and solar irradiance to compute real-time output.\n- **Energy output estimation:** Predict daily, yearly, or custom-period PV system yield.\n\n---\n\n## Formulas\n\n| Step | Equation |\n| ----------- | --------------------------------------------------- |\n| Declination | \u03b4 = 23.45 \u00d7 sin[(360/365) \u00d7 (n \u2212 81)] |\n| Hour angle | H = 15 \u00d7 (solar-time-hours \u2212 12) |\n| Altitude | sin(\u03b1) = sin(\u03b4) sin(\u03c6) + cos(\u03b4) cos(\u03c6) cos(H) |\n| Azimuth | sin(Az) = cos(\u03b4) sin(H) / cos(\u03b1) |\n| Irradiance | I = I\u2080 \u00d7 sin(\u03b1) (for horizontal surface, clear sky) |\n\nReferences:\n\n- [PV Education: Solar Insolation](https://www.pveducation.org/pvcdrom/properties-of-sunlight/calculation-of-solar-insolation)\n- [Panel Output Formula](https://www.sunbasedata.com/blog/how-to-calculate-solar-panel-output)\n- [Solar Output Guide](https://palmetto.com/solar/how-much-energy-does-a-solar-panel-produce)\n- [EcoFlow Output Math](https://www.ecoflow.com/us/blog/how-to-calculate-solar-panel-output)\n\n---\n\n## Installation\n\n```bash\npip install pysunergy-calc\n```\n\n---\n\n## Usage\n\n```python\nfrom pysunergy_calc import (\n compute_solar_potential,\n compute_panel_power,\n estimate_energy_produced,\n)\n\n# Example 1: Sun position and irradiance in New York on August 15, 2025, at 16:00 UTC\nfrom datetime import datetime, timezone\nsun = compute_solar_potential(\n 40.7128, # latitude\n -74.0060, # longitude\n datetime(2025, 8, 15, 16, 0, 0, tzinfo=timezone.utc) # UTC date/time\n)\nprint(sun)\n# SolarPosition(\n# declination=..., hour_angle=..., altitude=..., azimuth=..., zenith=..., irradiance=...\n# )\n\n# Example 2: Compute panel output at that instant\narea = 1.6 # m\u00b2 (panel area)\nefficiency = 0.20 # 20% PV efficiency\npower_W = compute_panel_power(area, efficiency, sun.irradiance)\nprint(power_W)\n\n# Example 3: Estimate daily energy (kWh) for your panel\naverage_irradiance = 5 * 1000 / 24 # e.g., 5kWh/m\u00b2/day avg \u2248 208 W/m\u00b2 avg\ndaily_kWh = estimate_energy_produced(\n area,\n efficiency,\n average_irradiance,\n 24, # hours in a day\n 0.75 # typical performance ratio (losses)\n)\nprint(daily_kWh)\n```\n\n---\n\n## API Reference\n\n### `compute_solar_potential(lat: float, lon: float, date: datetime) -> SolarPosition`\n\n- All angles are in degrees.\n- `irradiance` is in W/m\u00b2 (horizontal surface).\n- Calculates solar declination, hour angle, altitude, azimuth, zenith, and irradiance for a specified location/time.\n\n### `compute_panel_power(area: float, efficiency: float, irradiance: float) -> float`\n\n- `area`: Panel area (m\u00b2)\n- `efficiency`: Panel efficiency (0...1)\n- `irradiance`: Solar irradiance (W/m\u00b2)\n- Returns instantaneous PV output power (W).\n\n### `estimate_energy_produced(area: float, efficiency: float, average_irradiance: float, period_hours: float, performance_ratio: float=0.75) -> float`\n\n- Estimates total energy output for your system and conditions, in **kWh** over the specified period.\n- Typical `performance_ratio` is 0.75\u20130.85 (accounts for temperature, dust, inverter).\n- Average irradiance is entered in W/m\u00b2.\n\n---\n\n## Development & Testing\n\n- 100% Python, type-annotated and PEP 621 compliant.\n- Full Pytest test suite included.\n- To develop and run tests:\n\n```bash\nuv pip install --group dev\npytest\n```\n\n- Code is linted/formatted automatically with [ruff](https://github.com/astral-sh/ruff).\n\n---\n\n## License\n\n[MIT](LICENSE) \u00a9 Abdullah Waqar\n\n---\n\n## See Also\n\n### Node.js / TypeScript Version\n\nLooking for a similar library for Node.js or TypeScript?\n\nCheck out the original [sunergy-calc](https://www.npmjs.com/package/sunergy-calc) package for JavaScript/TypeScript with the same solar geometry and PV calculation logic.\n\n- **NPM package:** [sunergy-calc](https://www.npmjs.com/package/sunergy-calc)\n- **Source repo:** [https://github.com/abdullahwaqar/sunergy-calc](https://github.com/abdullahwaqar/sunergy-calc)\n\nUse that version if you want to run solar calculations in web apps, serverless functions, or Node/TypeScript projects.\n\n---\n\n_`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._\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Geometry-based solar potential, irradiance, and solar PV energy calculations in Python without external APIs.",
"version": "1.0.4",
"project_urls": {
"Homepage": "https://github.com/abdullahwaqar/pysunergy_calc",
"Repository": "https://github.com/abdullahwaqar/pysunergy_calc"
},
"split_keywords": [
"pv output calculation",
" cleantech",
" energy modeling",
" engineering",
" geometry",
" math",
" no api",
" photovoltaic",
" pv",
" pv system",
" renewable energy",
" solar",
" solar energy",
" solar insolation",
" solar irradiance",
" solar panel",
" solar potential",
" solar power",
" sun position"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "025d376e88d77c55a9385cce187e685b7d654616f574f4eda061ef21f62f2af1",
"md5": "669fa6ae6b524f15c4625bbecbad2123",
"sha256": "18f650ff4feae2baa8032854b6bd5eb65a8dfe53d7ec9be85125242e10592e08"
},
"downloads": -1,
"filename": "pysunergy_calc-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "669fa6ae6b524f15c4625bbecbad2123",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7166,
"upload_time": "2025-08-16T01:03:41",
"upload_time_iso_8601": "2025-08-16T01:03:41.045667Z",
"url": "https://files.pythonhosted.org/packages/02/5d/376e88d77c55a9385cce187e685b7d654616f574f4eda061ef21f62f2af1/pysunergy_calc-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3dbf68a969720edfd16dfe5875f0072b5b12f845b3eb645581b72be28050fcda",
"md5": "e72df52a7b67178b63178519d872f509",
"sha256": "5dc72d16ea1b13829f661eae85c0a7f2ce17db0ab05f98bb1af9a776f72d8b48"
},
"downloads": -1,
"filename": "pysunergy_calc-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "e72df52a7b67178b63178519d872f509",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19310,
"upload_time": "2025-08-16T01:03:42",
"upload_time_iso_8601": "2025-08-16T01:03:42.479685Z",
"url": "https://files.pythonhosted.org/packages/3d/bf/68a969720edfd16dfe5875f0072b5b12f845b3eb645581b72be28050fcda/pysunergy_calc-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 01:03:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abdullahwaqar",
"github_project": "pysunergy_calc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pysunergy-calc"
}
JSON
