mirror of
https://github.com/acamarata/nrel-spa.git
synced 2026-07-01 11:24:25 +00:00
165 lines
6.9 KiB
Markdown
165 lines
6.9 KiB
Markdown
# API Reference
|
|
|
|
## Functions
|
|
|
|
### `getSpa(date, latitude, longitude, timezone?, options?, angles?)`
|
|
|
|
Computes solar position for the given date and location. Returns raw numerical values.
|
|
|
|
**Parameters:**
|
|
|
|
| Parameter | Type | Required | Description |
|
|
| ----------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------ |
|
|
| `date` | `Date` | Yes | UTC date and time. Uses UTC components internally. |
|
|
| `latitude` | `number` | Yes | Observer latitude, -90 to 90. Negative = south. |
|
|
| `longitude` | `number` | Yes | Observer longitude, -180 to 180. Negative = west. |
|
|
| `timezone` | `number \| null` | No | Hours from UTC (e.g., -4 for EDT). Default: `0`. |
|
|
| `options` | `SpaOptions \| null` | No | Atmospheric and calculation parameters. |
|
|
| `angles` | `[number, ...number[]]` | No | One or more custom zenith angles in degrees. See [Twilight Calculations](Twilight-Calculations). |
|
|
|
|
**Returns:** `SpaResult`
|
|
|
|
```typescript
|
|
interface SpaResult {
|
|
zenith: number; // topocentric zenith angle (degrees)
|
|
azimuth: number; // topocentric azimuth, eastward from north (degrees)
|
|
sunrise: number; // local sunrise (fractional hours, e.g. 5.417 = 05:25)
|
|
solarNoon: number; // local solar noon (fractional hours)
|
|
sunset: number; // local sunset (fractional hours)
|
|
}
|
|
```
|
|
|
|
`sunrise`, `solarNoon`, and `sunset` are `NaN` when `options.function` is `SPA_ZA` or `SPA_ZA_INC` (those codes skip the rise/set calculation).
|
|
|
|
When `angles` is provided, returns `SpaResultWithAngles`:
|
|
|
|
```typescript
|
|
interface SpaResultWithAngles extends SpaResult {
|
|
angles: SpaAnglesResult[];
|
|
}
|
|
|
|
interface SpaAnglesResult {
|
|
sunrise: number; // rise time for this zenith angle (fractional hours)
|
|
sunset: number; // set time for this zenith angle (fractional hours)
|
|
}
|
|
```
|
|
|
|
**Throws:**
|
|
|
|
- `TypeError` if `date` is not a valid Date, or `latitude`/`longitude` are not finite numbers
|
|
- `RangeError` if `latitude` is outside [-90, 90] or `longitude` outside [-180, 180]
|
|
- `RangeError` if `options.function` is not 0, 1, 2, or 3
|
|
- `RangeError` if `angles` is provided with a non-RTS function code (`SPA_ZA` or `SPA_ZA_INC`)
|
|
- `Error` if the internal SPA calculation returns a non-zero error code
|
|
|
|
---
|
|
|
|
### `calcSpa(date, latitude, longitude, timezone?, options?, angles?)`
|
|
|
|
Same parameters as `getSpa()`. Formats `sunrise`, `solarNoon`, and `sunset` as `HH:MM:SS` strings.
|
|
|
|
**Returns:** `SpaFormattedResult`
|
|
|
|
```typescript
|
|
interface SpaFormattedResult {
|
|
zenith: number; // same as SpaResult
|
|
azimuth: number; // same as SpaResult
|
|
sunrise: string; // "HH:MM:SS" or "N/A" during polar day/night, or when using SPA_ZA/SPA_ZA_INC
|
|
solarNoon: string; // "HH:MM:SS" or "N/A"
|
|
sunset: string; // "HH:MM:SS" or "N/A"
|
|
}
|
|
```
|
|
|
|
When `angles` is provided, returns `SpaFormattedResultWithAngles`:
|
|
|
|
```typescript
|
|
interface SpaFormattedResultWithAngles extends SpaFormattedResult {
|
|
angles: SpaFormattedAnglesResult[];
|
|
}
|
|
|
|
interface SpaFormattedAnglesResult {
|
|
sunrise: string; // "HH:MM:SS" or "N/A"
|
|
sunset: string; // "HH:MM:SS" or "N/A"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### `formatTime(hours)`
|
|
|
|
Converts a fractional hour value to `HH:MM:SS` format.
|
|
|
|
```javascript
|
|
formatTime(5.417489); // "05:25:03"
|
|
formatTime(12); // "12:00:00"
|
|
formatTime(23.9997); // "23:59:59"
|
|
formatTime(-1); // "N/A"
|
|
formatTime(NaN); // "N/A"
|
|
formatTime(Infinity); // "N/A"
|
|
```
|
|
|
|
---
|
|
|
|
## SpaOptions
|
|
|
|
All options are optional. Defaults match the NREL C reference implementation.
|
|
|
|
| Option | Type | Default | Description |
|
|
| --------------- | ----------------- | ------------ | ----------------------------------------------------------------------------------------- |
|
|
| `elevation` | `number` | `0` | Observer elevation above sea level in meters. |
|
|
| `pressure` | `number` | `1013` | Annual average atmospheric pressure in millibars. |
|
|
| `temperature` | `number` | `15` | Annual average temperature in degrees Celsius. |
|
|
| `delta_ut1` | `number` | `0` | Fractional second difference between UTC and UT1. Valid range: (-1, 1). |
|
|
| `delta_t` | `number` | `67` | Difference between Terrestrial Time and UTC in seconds. |
|
|
| `slope` | `number` | `0` | Surface slope from horizontal in degrees. Used for incidence angle (SPA_ZA_INC, SPA_ALL). |
|
|
| `azm_rotation` | `number` | `0` | Surface azimuth rotation from south in degrees. |
|
|
| `atmos_refract` | `number` | `0.5667` | Atmospheric refraction at sunrise/sunset in degrees. |
|
|
| `function` | `SpaFunctionCode` | `SPA_ZA_RTS` | Which outputs to compute. |
|
|
|
|
---
|
|
|
|
## Function Codes
|
|
|
|
```javascript
|
|
import { SPA_ZA, SPA_ZA_INC, SPA_ZA_RTS, SPA_ALL } from 'nrel-spa';
|
|
```
|
|
|
|
| Constant | Value | Outputs Computed |
|
|
| ------------ | ----- | -------------------------------------------------------------------------- |
|
|
| `SPA_ZA` | `0` | `zenith`, `azimuth` |
|
|
| `SPA_ZA_INC` | `1` | `zenith`, `azimuth`, incidence angle (for solar panels on sloped surfaces) |
|
|
| `SPA_ZA_RTS` | `2` | `zenith`, `azimuth`, `sunrise`, `solarNoon`, `sunset` |
|
|
| `SPA_ALL` | `3` | All outputs from SPA_ZA_INC and SPA_ZA_RTS combined |
|
|
|
|
The default is `SPA_ZA_RTS`. Use `SPA_ZA` for zenith/azimuth-only calculations if you do not need rise/set times; it skips the three-day calculation that rise/set requires and is slightly faster. Custom zenith `angles` require `SPA_ZA_RTS` or `SPA_ALL`.
|
|
|
|
---
|
|
|
|
## SpaFunctionCode Type
|
|
|
|
```typescript
|
|
type SpaFunctionCode = 0 | 1 | 2 | 3;
|
|
```
|
|
|
|
---
|
|
|
|
## Named Types
|
|
|
|
All interfaces and types are exported from `nrel-spa` and can be imported in TypeScript:
|
|
|
|
```typescript
|
|
import type {
|
|
SpaOptions,
|
|
SpaResult,
|
|
SpaFormattedResult,
|
|
SpaAnglesResult,
|
|
SpaFormattedAnglesResult,
|
|
SpaResultWithAngles,
|
|
SpaFormattedResultWithAngles,
|
|
SpaFunctionCode,
|
|
} from 'nrel-spa';
|
|
```
|
|
|
|
---
|
|
|
|
[Home](Home) . [Architecture](Architecture) . [Twilight Calculations](Twilight-Calculations) . [NREL SPA Algorithm](NREL-SPA-Algorithm)
|