mirror of
https://github.com/acamarata/nrel-spa-dart.git
synced 2026-07-01 03:14:25 +00:00
133 lines
4.4 KiB
Markdown
133 lines
4.4 KiB
Markdown
# API Reference
|
|
|
|
## getSpa
|
|
|
|
```dart
|
|
SpaResult getSpa(
|
|
DateTime date,
|
|
double latitude,
|
|
double longitude,
|
|
double timezone, {
|
|
double elevation = 0,
|
|
double pressure = 1013,
|
|
double temperature = 15,
|
|
double deltaUt1 = 0,
|
|
double deltaT = 67,
|
|
double slope = 0,
|
|
double azmRotation = 0,
|
|
double atmosRefract = 0.5667,
|
|
int functionCode = spaZaRts,
|
|
List<double> customAngles = const [],
|
|
})
|
|
```
|
|
|
|
Computes solar position for a given location and moment. Returns raw fractional-hour values.
|
|
|
|
Throws `ArgumentError` if any input falls outside the NREL SPA valid range.
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Default | Description |
|
|
| --- | --- | --- | --- |
|
|
| `date` | `DateTime` | required | UTC date and time |
|
|
| `latitude` | `double` | required | Degrees (-90 to 90, south negative) |
|
|
| `longitude` | `double` | required | Degrees (-180 to 180, west negative) |
|
|
| `timezone` | `double` | required | Hours from UTC (e.g., -5 for EST) |
|
|
| `elevation` | `double` | 0 | Meters above sea level |
|
|
| `pressure` | `double` | 1013 | Atmospheric pressure (mbar) |
|
|
| `temperature` | `double` | 15 | Temperature (Celsius) |
|
|
| `deltaUt1` | `double` | 0 | Difference UT1 - UTC (seconds, typically small) |
|
|
| `deltaT` | `double` | 67 | TT - UT1 (seconds) |
|
|
| `slope` | `double` | 0 | Surface tilt angle (degrees, for incidence) |
|
|
| `azmRotation` | `double` | 0 | Surface azimuth rotation (degrees, for incidence) |
|
|
| `atmosRefract` | `double` | 0.5667 | Atmospheric refraction at horizon (degrees) |
|
|
| `functionCode` | `int` | `spaZaRts` | What to calculate; one of `spaZa`, `spaZaInc`, `spaZaRts`, `spaAll` |
|
|
| `customAngles` | `List<double>` | `[]` | Zenith angles for custom rise/set computation |
|
|
|
|
### Function codes
|
|
|
|
| Constant | Value | Computes |
|
|
| --- | --- | --- |
|
|
| `spaZa` | 0 | Zenith and azimuth only |
|
|
| `spaZaInc` | 1 | Zenith, azimuth, and surface incidence |
|
|
| `spaZaRts` | 2 | Zenith, azimuth, sunrise, sunset, solar noon (default) |
|
|
| `spaAll` | 3 | All of the above |
|
|
|
|
### SpaResult fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `zenith` | `double` | Solar zenith angle (degrees) |
|
|
| `azimuth` | `double` | Solar azimuth angle, eastward from north (degrees) |
|
|
| `sunrise` | `double` | Sunrise in fractional hours, local time (NaN if polar) |
|
|
| `solarNoon` | `double` | Solar noon in fractional hours, local time (NaN if polar) |
|
|
| `sunset` | `double` | Sunset in fractional hours, local time (NaN if polar) |
|
|
| `incidence` | `double` | Surface incidence angle (degrees; `spaZaInc`/`spaAll` only) |
|
|
| `angles` | `List<SpaAnglesResult>` | Rise/set pairs for each entry in `customAngles` |
|
|
|
|
### SpaAnglesResult fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `sunrise` | `double` | Rise time in fractional hours for this zenith angle |
|
|
| `sunset` | `double` | Set time in fractional hours for this zenith angle |
|
|
|
|
---
|
|
|
|
## calcSpa
|
|
|
|
```dart
|
|
SpaFormattedResult calcSpa(
|
|
DateTime date,
|
|
double latitude,
|
|
double longitude,
|
|
double timezone, {
|
|
// same optional parameters as getSpa
|
|
})
|
|
```
|
|
|
|
Same as `getSpa`, but formats `sunrise`, `solarNoon`, and `sunset` as `HH:MM:SS` strings. Returns `"N/A"` for those fields during polar day or polar night.
|
|
|
|
### SpaFormattedResult fields
|
|
|
|
| Field | Type | Description |
|
|
| --- | --- | --- |
|
|
| `zenith` | `double` | Solar zenith angle (degrees) |
|
|
| `azimuth` | `double` | Solar azimuth angle (degrees) |
|
|
| `sunrise` | `String` | Sunrise as `HH:MM:SS`, or `"N/A"` |
|
|
| `solarNoon` | `String` | Solar noon as `HH:MM:SS`, or `"N/A"` |
|
|
| `sunset` | `String` | Sunset as `HH:MM:SS`, or `"N/A"` |
|
|
| `incidence` | `double` | Surface incidence angle (degrees) |
|
|
| `angles` | `List<SpaFormattedAnglesResult>` | Rise/set pairs with formatted strings |
|
|
|
|
---
|
|
|
|
## formatTime
|
|
|
|
```dart
|
|
String formatTime(double hours)
|
|
```
|
|
|
|
Formats fractional hours to an `HH:MM:SS` string. Returns `"N/A"` for non-finite or negative values (polar scenarios).
|
|
|
|
---
|
|
|
|
## Custom zenith angles
|
|
|
|
Pass any solar zenith angles to `customAngles` to get rise/set times at those depression depths. Standard angles: civil twilight = 96°, nautical = 102°, astronomical = 108°. Prayer time implementations use this for Fajr and Isha.
|
|
|
|
```dart
|
|
final result = getSpa(
|
|
DateTime.utc(2024, 3, 15, 12, 0, 0),
|
|
40.7128, -74.0060, -5.0,
|
|
customAngles: [96.0, 102.0, 108.0],
|
|
);
|
|
|
|
for (int i = 0; i < result.angles.length; i++) {
|
|
print('Angle ${i}: rise ${result.angles[i].sunrise}, set ${result.angles[i].sunset}');
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
[Home](Home)
|