@hebcal/noaa 0.8.3 → 0.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +623 -5
  2. package/dist/cjs/index.js +123 -101
  3. package/dist/esm/index.js +1075 -0
  4. package/dist/index.d.ts +720 -0
  5. package/package.json +2 -2
package/README.md CHANGED
@@ -1,13 +1,631 @@
1
1
  # @hebcal/noaa
2
2
  sunrise and sunset via NOAA algorithm with elevation, based on KosherJava
3
3
 
4
- # Introduction
4
+ ## Introduction
5
5
  This is a fork/subset of [KosherZmanim](https://github.com/BehindTheMath/KosherZmanim) library with `Temporal` replacing usage of `Luxon`.
6
6
 
7
7
  Kosher Zmanim itself is a TS/JS port of the [KosherJava](https://github.com/KosherJava/zmanim) library.
8
8
 
9
- # Installation
10
- **NPM:**
11
- ```
12
- npm install @hebcal/noaa
9
+ ## Installation
10
+ ```bash
11
+ $ npm install @hebcal/noaa
13
12
  ```
13
+
14
+ ## Classes
15
+
16
+ <dl>
17
+ <dt><a href="#GeoLocation">GeoLocation</a></dt>
18
+ <dd><p>A class that contains location information such as latitude and longitude required for astronomical calculations. The
19
+ elevation field may not be used by some calculation engines and would be ignored if set. Check the documentation for
20
+ specific implementations of the <a href="AstronomicalCalculator">AstronomicalCalculator</a> to see if elevation is calculated as part of the
21
+ algorithm.</p>
22
+ </dd>
23
+ <dt><a href="#NOAACalculator">NOAACalculator</a></dt>
24
+ <dd><p>Implementation of sunrise and sunset methods to calculate astronomical times based on the <a
25
+ href="http://noaa.gov">NOAA</a> algorithm. This calculator uses the Java algorithm based on the implementation by <a
26
+ href="http://noaa.gov">NOAA - National Oceanic and Atmospheric Administration</a>&#39;s <a href =
27
+ "http://www.srrb.noaa.gov/highlights/sunrise/sunrise.html">Surface Radiation Research Branch</a>. NOAA&#39;s <a
28
+ href="http://www.srrb.noaa.gov/highlights/sunrise/solareqns.PDF">implementation</a> is based on equations from <a
29
+ href="http://www.willbell.com/math/mc1.htm">Astronomical Algorithms</a> by <a
30
+ href="http://en.wikipedia.org/wiki/Jean_Meeus">Jean Meeus</a>. Added to the algorithm is an adjustment of the zenith
31
+ to account for elevation. The algorithm can be found in the <a
32
+ href="http://en.wikipedia.org/wiki/Sunrise_equation">Wikipedia Sunrise Equation</a> article.</p>
33
+ </dd>
34
+ </dl>
35
+
36
+ <a name="GeoLocation"></a>
37
+
38
+ ## GeoLocation
39
+ A class that contains location information such as latitude and longitude required for astronomical calculations. The
40
+ elevation field may not be used by some calculation engines and would be ignored if set. Check the documentation for
41
+ specific implementations of the [AstronomicalCalculator](AstronomicalCalculator) to see if elevation is calculated as part of the
42
+ algorithm.
43
+
44
+ **Kind**: global class
45
+ **Version**: 1.1
46
+ **Author**: &copy; Eliyahu Hershfeld 2004 - 2016
47
+
48
+ * [GeoLocation](#GeoLocation)
49
+ * [new GeoLocation(name, latitude, longitude, elevation, timeZoneId)](#new_GeoLocation_new)
50
+ * [.getElevation()](#GeoLocation+getElevation) ⇒ <code>number</code>
51
+ * [.setElevation(elevation)](#GeoLocation+setElevation)
52
+ * [.getLatitude()](#GeoLocation+getLatitude) ⇒ <code>number</code>
53
+ * [.getLongitude()](#GeoLocation+getLongitude) ⇒ <code>number</code>
54
+ * [.getLocationName()](#GeoLocation+getLocationName) ⇒ <code>string</code> \| <code>null</code>
55
+ * [.setLocationName(name)](#GeoLocation+setLocationName)
56
+ * [.getTimeZone()](#GeoLocation+getTimeZone) ⇒ <code>string</code>
57
+ * [.setTimeZone(timeZone)](#GeoLocation+setTimeZone)
58
+
59
+ <a name="new_GeoLocation_new"></a>
60
+
61
+ ### new GeoLocation(name, latitude, longitude, elevation, timeZoneId)
62
+ GeoLocation constructor with parameters for all required fields.
63
+
64
+
65
+ | Param | Type | Description |
66
+ | --- | --- | --- |
67
+ | name | <code>string</code> | The location name for display use such as &quot;Lakewood, NJ&quot; |
68
+ | latitude | <code>number</code> | the latitude in a double format such as 40.095965 for Lakewood, NJ. <b>Note: </b> For latitudes south of the equator, a negative value should be used. |
69
+ | longitude | <code>number</code> | double the longitude in a double format such as -74.222130 for Lakewood, NJ. <b>Note: </b> For longitudes east of the <a href="http://en.wikipedia.org/wiki/Prime_Meridian">Prime Meridian </a> (Greenwich), a negative value should be used. |
70
+ | elevation | <code>number</code> | the elevation above sea level in Meters. Elevation is not used in most algorithms used for calculating sunrise and set. |
71
+ | timeZoneId | <code>string</code> | the <code>TimeZone</code> for the location. |
72
+
73
+ <a name="GeoLocation+getElevation"></a>
74
+
75
+ ### geoLocation.getElevation() ⇒ <code>number</code>
76
+ Method to get the elevation in Meters.
77
+
78
+ **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
79
+ **Returns**: <code>number</code> - Returns the elevation in Meters.
80
+ <a name="GeoLocation+setElevation"></a>
81
+
82
+ ### geoLocation.setElevation(elevation)
83
+ Method to set the elevation in Meters <b>above </b> sea level.
84
+
85
+ **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
86
+
87
+ | Param | Type | Description |
88
+ | --- | --- | --- |
89
+ | elevation | <code>number</code> | The elevation to set in Meters. An IllegalArgumentException will be thrown if the value is a negative. |
90
+
91
+ <a name="GeoLocation+getLatitude"></a>
92
+
93
+ ### geoLocation.getLatitude() ⇒ <code>number</code>
94
+ **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
95
+ **Returns**: <code>number</code> - Returns the latitude.
96
+ <a name="GeoLocation+getLongitude"></a>
97
+
98
+ ### geoLocation.getLongitude() ⇒ <code>number</code>
99
+ **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
100
+ **Returns**: <code>number</code> - Returns the longitude.
101
+ <a name="GeoLocation+getLocationName"></a>
102
+
103
+ ### geoLocation.getLocationName() ⇒ <code>string</code> \| <code>null</code>
104
+ **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
105
+ **Returns**: <code>string</code> \| <code>null</code> - Returns the location name.
106
+ <a name="GeoLocation+setLocationName"></a>
107
+
108
+ ### geoLocation.setLocationName(name)
109
+ **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
110
+
111
+ | Param | Type | Description |
112
+ | --- | --- | --- |
113
+ | name | <code>string</code> \| <code>null</code> | The setter method for the display name. |
114
+
115
+ <a name="GeoLocation+getTimeZone"></a>
116
+
117
+ ### geoLocation.getTimeZone() ⇒ <code>string</code>
118
+ **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
119
+ **Returns**: <code>string</code> - Returns the timeZone.
120
+ <a name="GeoLocation+setTimeZone"></a>
121
+
122
+ ### geoLocation.setTimeZone(timeZone)
123
+ Method to set the TimeZone. If this is ever set after the GeoLocation is set in the
124
+ [AstronomicalCalendar](AstronomicalCalendar), it is critical that
125
+ [AstronomicalCalendar#getCalendar()](AstronomicalCalendar#getCalendar()).
126
+ [setTimeZone(TimeZone)](java.util.Calendar#setTimeZone(TimeZone)) be called in order for the
127
+ AstronomicalCalendar to output times in the expected offset. This situation will arise if the
128
+ AstronomicalCalendar is ever [cloned](AstronomicalCalendar#clone()).
129
+
130
+ **Kind**: instance method of [<code>GeoLocation</code>](#GeoLocation)
131
+
132
+ | Param | Type | Description |
133
+ | --- | --- | --- |
134
+ | timeZone | <code>string</code> | The timeZone to set. |
135
+
136
+ <a name="NOAACalculator"></a>
137
+
138
+ ## NOAACalculator
139
+ Implementation of sunrise and sunset methods to calculate astronomical times based on the <a
140
+ href="http://noaa.gov">NOAA</a> algorithm. This calculator uses the Java algorithm based on the implementation by <a
141
+ href="http://noaa.gov">NOAA - National Oceanic and Atmospheric Administration</a>'s <a href =
142
+ "http://www.srrb.noaa.gov/highlights/sunrise/sunrise.html">Surface Radiation Research Branch</a>. NOAA's <a
143
+ href="http://www.srrb.noaa.gov/highlights/sunrise/solareqns.PDF">implementation</a> is based on equations from <a
144
+ href="http://www.willbell.com/math/mc1.htm">Astronomical Algorithms</a> by <a
145
+ href="http://en.wikipedia.org/wiki/Jean_Meeus">Jean Meeus</a>. Added to the algorithm is an adjustment of the zenith
146
+ to account for elevation. The algorithm can be found in the <a
147
+ href="http://en.wikipedia.org/wiki/Sunrise_equation">Wikipedia Sunrise Equation</a> article.
148
+
149
+ **Kind**: global class
150
+ **See**: #setAstronomicalCalculator(AstronomicalCalculator) for changing the calculator class.
151
+ **Author**: &copy; Eliyahu Hershfeld 2011 - 2019
152
+
153
+ * [NOAACalculator](#NOAACalculator)
154
+ * [new NOAACalculator(geoLocation, date)](#new_NOAACalculator_new)
155
+ * _instance_
156
+ * [.getSunrise()](#NOAACalculator+getSunrise) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
157
+ * [.getSeaLevelSunrise()](#NOAACalculator+getSeaLevelSunrise) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
158
+ * [.getBeginCivilTwilight()](#NOAACalculator+getBeginCivilTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
159
+ * [.getBeginNauticalTwilight()](#NOAACalculator+getBeginNauticalTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
160
+ * [.getBeginAstronomicalTwilight()](#NOAACalculator+getBeginAstronomicalTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
161
+ * [.getSunset()](#NOAACalculator+getSunset) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
162
+ * [.getSeaLevelSunset()](#NOAACalculator+getSeaLevelSunset) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
163
+ * [.getEndCivilTwilight()](#NOAACalculator+getEndCivilTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
164
+ * [.getEndNauticalTwilight()](#NOAACalculator+getEndNauticalTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
165
+ * [.getEndAstronomicalTwilight()](#NOAACalculator+getEndAstronomicalTwilight) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
166
+ * [.getSunriseOffsetByDegrees(offsetZenith)](#NOAACalculator+getSunriseOffsetByDegrees) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
167
+ * [.getSunsetOffsetByDegrees(offsetZenith)](#NOAACalculator+getSunsetOffsetByDegrees) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
168
+ * [.getUTCSunrise0(zenith)](#NOAACalculator+getUTCSunrise0) ⇒ <code>number</code>
169
+ * [.getUTCSeaLevelSunrise(zenith)](#NOAACalculator+getUTCSeaLevelSunrise) ⇒ <code>number</code>
170
+ * [.getUTCSunset0(zenith)](#NOAACalculator+getUTCSunset0) ⇒ <code>number</code>
171
+ * [.getUTCSeaLevelSunset(zenith)](#NOAACalculator+getUTCSeaLevelSunset) ⇒ <code>number</code>
172
+ * [.getElevationAdjustment(elevation)](#NOAACalculator+getElevationAdjustment) ⇒ <code>number</code>
173
+ * [.adjustZenith(zenith, elevation)](#NOAACalculator+adjustZenith) ⇒ <code>number</code>
174
+ * [.getUTCSunrise()](#NOAACalculator+getUTCSunrise)
175
+ * [.getUTCSunset()](#NOAACalculator+getUTCSunset)
176
+ * [.getTemporalHour(startOfDay, endOfDay)](#NOAACalculator+getTemporalHour) ⇒ <code>number</code>
177
+ * [.getSunTransit(startOfDay, endOfDay)](#NOAACalculator+getSunTransit) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
178
+ * [.getDateFromTime(time, isSunrise)](#NOAACalculator+getDateFromTime) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
179
+ * _static_
180
+ * [.CIVIL_ZENITH](#NOAACalculator.CIVIL_ZENITH)
181
+ * [.NAUTICAL_ZENITH](#NOAACalculator.NAUTICAL_ZENITH)
182
+ * [.ASTRONOMICAL_ZENITH](#NOAACalculator.ASTRONOMICAL_ZENITH)
183
+ * [.getTimeOffset(time, offset)](#NOAACalculator.getTimeOffset) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
184
+ * [.getSolarElevation(date, lat, lon)](#NOAACalculator.getSolarElevation) ⇒ <code>number</code>
185
+ * [.getSolarAzimuth(date, latitude, lon)](#NOAACalculator.getSolarAzimuth) ⇒ <code>number</code>
186
+
187
+ <a name="new_NOAACalculator_new"></a>
188
+
189
+ ### new NOAACalculator(geoLocation, date)
190
+ A constructor that takes in <a href="http://en.wikipedia.org/wiki/Geolocation">geolocation</a> information as a
191
+ parameter. The default [AstronomicalCalculator](AstronomicalCalculator#getDefault()) used for solar
192
+ calculations is the the [NOAACalculator](#NOAACalculator).
193
+
194
+
195
+ | Param | Type | Description |
196
+ | --- | --- | --- |
197
+ | geoLocation | [<code>GeoLocation</code>](#GeoLocation) | The location information used for calculating astronomical sun times. |
198
+ | date | <code>Temporal.PlainDate</code> | |
199
+
200
+ <a name="NOAACalculator+getSunrise"></a>
201
+
202
+ ### noaaCalculator.getSunrise() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
203
+ The getSunrise method Returns a `Date` representing the
204
+ [elevation adjusted](AstronomicalCalculator#getElevationAdjustment(double)) sunrise time. The zenith used
205
+ for the calculation uses [geometric zenith](#GEOMETRIC_ZENITH) of 90&deg; plus
206
+ [AstronomicalCalculator#getElevationAdjustment(double)](AstronomicalCalculator#getElevationAdjustment(double)). This is adjusted by the
207
+ [AstronomicalCalculator](AstronomicalCalculator) to add approximately 50/60 of a degree to account for 34 archminutes of refraction
208
+ and 16 archminutes for the sun's radius for a total of [90.83333&deg;](AstronomicalCalculator#adjustZenith).
209
+ See documentation for the specific implementation of the [AstronomicalCalculator](AstronomicalCalculator) that you are using.
210
+
211
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
212
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - the `Date` representing the exact sunrise time. If the calculation can't be computed such as
213
+ in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
214
+ does not set, a null will be returned. See detailed explanation on top of the page.
215
+ **See**
216
+
217
+ - AstronomicalCalculator#adjustZenith
218
+ - #getSeaLevelSunrise()
219
+ - AstronomicalCalendar#getUTCSunrise
220
+
221
+ <a name="NOAACalculator+getSeaLevelSunrise"></a>
222
+
223
+ ### noaaCalculator.getSeaLevelSunrise() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
224
+ A method that returns the sunrise without [elevation
225
+ adjustment](AstronomicalCalculator#getElevationAdjustment(double)). Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light,
226
+ something that is not affected by elevation. This method returns sunrise calculated at sea level. This forms the
227
+ base for dawn calculations that are calculated as a dip below the horizon before sunrise.
228
+
229
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
230
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - the `Date` representing the exact sea-level sunrise time. If the calculation can't be computed
231
+ such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one
232
+ where it does not set, a null will be returned. See detailed explanation on top of the page.
233
+ **See**
234
+
235
+ - AstronomicalCalendar#getSunrise
236
+ - AstronomicalCalendar#getUTCSeaLevelSunrise
237
+ - #getSeaLevelSunset()
238
+
239
+ <a name="NOAACalculator+getBeginCivilTwilight"></a>
240
+
241
+ ### noaaCalculator.getBeginCivilTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
242
+ A method that returns the beginning of civil twilight (dawn) using a zenith of [96&deg;](#CIVIL_ZENITH).
243
+
244
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
245
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the beginning of civil twilight using a zenith of 96&deg;. If the calculation
246
+ can't be computed, null will be returned. See detailed explanation on top of the page.
247
+ **See**: #CIVIL_ZENITH
248
+ <a name="NOAACalculator+getBeginNauticalTwilight"></a>
249
+
250
+ ### noaaCalculator.getBeginNauticalTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
251
+ A method that returns the beginning of nautical twilight using a zenith of [102&deg;](#NAUTICAL_ZENITH).
252
+
253
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
254
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the beginning of nautical twilight using a zenith of 102&deg;. If the
255
+ calculation can't be computed null will be returned. See detailed explanation on top of the page.
256
+ **See**: #NAUTICAL_ZENITH
257
+ <a name="NOAACalculator+getBeginAstronomicalTwilight"></a>
258
+
259
+ ### noaaCalculator.getBeginAstronomicalTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
260
+ A method that returns the beginning of astronomical twilight using a zenith of [108&deg;](#ASTRONOMICAL_ZENITH).
261
+
262
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
263
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the beginning of astronomical twilight using a zenith of 108&deg;. If the
264
+ calculation can't be computed, null will be returned. See detailed explanation on top of the page.
265
+ **See**: #ASTRONOMICAL_ZENITH
266
+ <a name="NOAACalculator+getSunset"></a>
267
+
268
+ ### noaaCalculator.getSunset() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
269
+ The getSunset method Returns a `Date` representing the
270
+ [elevation adjusted](AstronomicalCalculator#getElevationAdjustment(double)) sunset time. The zenith used for
271
+ the calculation uses [geometric zenith](#GEOMETRIC_ZENITH) of 90&deg; plus
272
+ [AstronomicalCalculator#getElevationAdjustment(double)](AstronomicalCalculator#getElevationAdjustment(double)). This is adjusted by the
273
+ [AstronomicalCalculator](AstronomicalCalculator) to add approximately 50/60 of a degree to account for 34 archminutes of refraction
274
+ and 16 archminutes for the sun's radius for a total of [90.83333&deg;](AstronomicalCalculator#adjustZenith).
275
+ See documentation for the specific implementation of the [AstronomicalCalculator](AstronomicalCalculator) that you are using. Note:
276
+ In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone
277
+ other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this
278
+ case the sunset date will be incremented to the following date.
279
+
280
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
281
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` representing the exact sunset time. If the calculation can't be computed such as in
282
+ the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it
283
+ does not set, a null will be returned. See detailed explanation on top of the page.
284
+ **See**
285
+
286
+ - AstronomicalCalculator#adjustZenith
287
+ - #getSeaLevelSunset()
288
+ - AstronomicalCalendar#getUTCSunset
289
+
290
+ <a name="NOAACalculator+getSeaLevelSunset"></a>
291
+
292
+ ### noaaCalculator.getSeaLevelSunset() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
293
+ A method that returns the sunset without [elevation
294
+ adjustment](AstronomicalCalculator#getElevationAdjustment(double)). Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light,
295
+ something that is not affected by elevation. This method returns sunset calculated at sea level. This forms the
296
+ base for dusk calculations that are calculated as a dip below the horizon after sunset.
297
+
298
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
299
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` representing the exact sea-level sunset time. If the calculation can't be computed
300
+ such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one
301
+ where it does not set, a null will be returned. See detailed explanation on top of the page.
302
+ **See**
303
+
304
+ - AstronomicalCalendar#getSunset
305
+ - AstronomicalCalendar#getUTCSeaLevelSunset 2see [#getSunset()](#getSunset())
306
+
307
+ <a name="NOAACalculator+getEndCivilTwilight"></a>
308
+
309
+ ### noaaCalculator.getEndCivilTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
310
+ A method that returns the end of civil twilight using a zenith of [96&deg;](#CIVIL_ZENITH).
311
+
312
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
313
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the end of civil twilight using a zenith of [96&deg;](#CIVIL_ZENITH). If
314
+ the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
315
+ **See**: #CIVIL_ZENITH
316
+ <a name="NOAACalculator+getEndNauticalTwilight"></a>
317
+
318
+ ### noaaCalculator.getEndNauticalTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
319
+ A method that returns the end of nautical twilight using a zenith of [102&deg;](#NAUTICAL_ZENITH).
320
+
321
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
322
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the end of nautical twilight using a zenith of [102&deg;](#NAUTICAL_ZENITH)
323
+ . If the calculation can't be computed, null will be returned. See detailed explanation on top of the
324
+ page.
325
+ **See**: #NAUTICAL_ZENITH
326
+ <a name="NOAACalculator+getEndAstronomicalTwilight"></a>
327
+
328
+ ### noaaCalculator.getEndAstronomicalTwilight() ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
329
+ A method that returns the end of astronomical twilight using a zenith of [108&deg;](#ASTRONOMICAL_ZENITH).
330
+
331
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
332
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the end of astronomical twilight using a zenith of [108&deg;](#ASTRONOMICAL_ZENITH). If the calculation can't be computed, null will be returned. See detailed explanation on top
333
+ of the page.
334
+ **See**: #ASTRONOMICAL_ZENITH
335
+ <a name="NOAACalculator+getSunriseOffsetByDegrees"></a>
336
+
337
+ ### noaaCalculator.getSunriseOffsetByDegrees(offsetZenith) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
338
+ A utility method that returns the time of an offset by degrees below or above the horizon of
339
+ [sunrise](#getSunrise()). Note that the degree offset is from the vertical, so for a calculation of 14&deg;
340
+ before sunrise, an offset of 14 + [#GEOMETRIC_ZENITH](#GEOMETRIC_ZENITH) = 104 would have to be passed as a parameter.
341
+
342
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
343
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` of the offset after (or before) [#getSunrise()](#getSunrise()). If the calculation
344
+ can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does
345
+ not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the
346
+ page.
347
+
348
+ | Param | Type | Description |
349
+ | --- | --- | --- |
350
+ | offsetZenith | <code>number</code> | the degrees before [#getSunrise()](#getSunrise()) to use in the calculation. For time after sunrise use negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14&deg; before sunrise, an offset of 14 + [#GEOMETRIC_ZENITH](#GEOMETRIC_ZENITH) = 104 would have to be passed as a parameter. |
351
+
352
+ <a name="NOAACalculator+getSunsetOffsetByDegrees"></a>
353
+
354
+ ### noaaCalculator.getSunsetOffsetByDegrees(offsetZenith) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
355
+ A utility method that returns the time of an offset by degrees below or above the horizon of [sunset](#getSunset()). Note that the degree offset is from the vertical, so for a calculation of 14&deg; after sunset, an
356
+ offset of 14 + [#GEOMETRIC_ZENITH](#GEOMETRIC_ZENITH) = 104 would have to be passed as a parameter.
357
+
358
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
359
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date`of the offset after (or before) [#getSunset()](#getSunset()). If the calculation can't
360
+ be computed such as in the Arctic Circle where there is at least one day a year where the sun does not
361
+ rise, and one where it does not set, a null will be returned. See detailed explanation on top of the
362
+ page.
363
+
364
+ | Param | Type | Description |
365
+ | --- | --- | --- |
366
+ | offsetZenith | <code>number</code> | the degrees after [#getSunset()](#getSunset()) to use in the calculation. For time before sunset use negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14&deg; after sunset, an offset of 14 + [#GEOMETRIC_ZENITH](#GEOMETRIC_ZENITH) = 104 would have to be passed as a parameter. |
367
+
368
+ <a name="NOAACalculator+getUTCSunrise0"></a>
369
+
370
+ ### noaaCalculator.getUTCSunrise0(zenith) ⇒ <code>number</code>
371
+ A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using
372
+ daylight savings time.
373
+
374
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
375
+ **Returns**: <code>number</code> - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the
376
+ Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
377
+ not set, [Double#NaN](Double#NaN) will be returned. See detailed explanation on top of the page.
378
+
379
+ | Param | Type | Description |
380
+ | --- | --- | --- |
381
+ | zenith | <code>number</code> | the degrees below the horizon. For time after sunrise use negative numbers. |
382
+
383
+ <a name="NOAACalculator+getUTCSeaLevelSunrise"></a>
384
+
385
+ ### noaaCalculator.getUTCSeaLevelSunrise(zenith) ⇒ <code>number</code>
386
+ A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using
387
+ daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible
388
+ light, something that is not affected by elevation. This method returns UTC sunrise calculated at sea level. This
389
+ forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.
390
+
391
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
392
+ **Returns**: <code>number</code> - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the
393
+ Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
394
+ not set, [Double#NaN](Double#NaN) will be returned. See detailed explanation on top of the page.
395
+ **See**
396
+
397
+ - AstronomicalCalendar#getUTCSunrise
398
+ - AstronomicalCalendar#getUTCSeaLevelSunset
399
+
400
+
401
+ | Param | Type | Description |
402
+ | --- | --- | --- |
403
+ | zenith | <code>number</code> | the degrees below the horizon. For time after sunrise use negative numbers. |
404
+
405
+ <a name="NOAACalculator+getUTCSunset0"></a>
406
+
407
+ ### noaaCalculator.getUTCSunset0(zenith) ⇒ <code>number</code>
408
+ A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using
409
+ daylight savings time.
410
+
411
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
412
+ **Returns**: <code>number</code> - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the
413
+ Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
414
+ not set, [Double#NaN](Double#NaN) will be returned. See detailed explanation on top of the page.
415
+ **See**: AstronomicalCalendar#getUTCSeaLevelSunset
416
+
417
+ | Param | Type | Description |
418
+ | --- | --- | --- |
419
+ | zenith | <code>number</code> | the degrees below the horizon. For time after sunset use negative numbers. |
420
+
421
+ <a name="NOAACalculator+getUTCSeaLevelSunset"></a>
422
+
423
+ ### noaaCalculator.getUTCSeaLevelSunset(zenith) ⇒ <code>number</code>
424
+ A method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and
425
+ without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the
426
+ amount of visible light, something that is not affected by elevation. This method returns UTC sunset calculated
427
+ at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after
428
+ sunset.
429
+
430
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
431
+ **Returns**: <code>number</code> - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the
432
+ Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
433
+ not set, [Double#NaN](Double#NaN) will be returned. See detailed explanation on top of the page.
434
+ **See**
435
+
436
+ - AstronomicalCalendar#getUTCSunset
437
+ - AstronomicalCalendar#getUTCSeaLevelSunrise
438
+
439
+
440
+ | Param | Type | Description |
441
+ | --- | --- | --- |
442
+ | zenith | <code>number</code> | the degrees below the horizon. For time before sunset use negative numbers. |
443
+
444
+ <a name="NOAACalculator+getElevationAdjustment"></a>
445
+
446
+ ### noaaCalculator.getElevationAdjustment(elevation) ⇒ <code>number</code>
447
+ Method to return the adjustment to the zenith required to account for the elevation. Since a person at a higher
448
+ elevation can see farther below the horizon, the calculation for sunrise / sunset is calculated below the horizon
449
+ used at sea level. This is only used for sunrise and sunset and not times before or after it such as
450
+ [nautical twilight](AstronomicalCalendar#getBeginNauticalTwilight()) since those
451
+ calculations are based on the level of available light at the given dip below the horizon, something that is not
452
+ affected by elevation, the adjustment should only made if the zenith == 90&deg; [adjusted](#adjustZenith)
453
+ for refraction and solar radius. The algorithm used is
454
+
455
+ <pre>
456
+ elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));
457
+ </pre>
458
+
459
+ The source of this algorithm is <a href="http://www.calendarists.com">Calendrical Calculations</a> by Edward M.
460
+ Reingold and Nachum Dershowitz. An alternate algorithm that produces an almost identical (but not accurate)
461
+ result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:
462
+
463
+ <pre>
464
+ elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);
465
+ </pre>
466
+
467
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
468
+ **Returns**: <code>number</code> - the adjusted zenith
469
+
470
+ | Param | Type | Description |
471
+ | --- | --- | --- |
472
+ | elevation | <code>number</code> | elevation in Meters. |
473
+
474
+ <a name="NOAACalculator+adjustZenith"></a>
475
+
476
+ ### noaaCalculator.adjustZenith(zenith, elevation) ⇒ <code>number</code>
477
+ Adjusts the zenith of astronomical sunrise and sunset to account for solar refraction, solar radius and
478
+ elevation. The value for Sun's zenith and true rise/set Zenith (used in this class and subclasses) is the angle
479
+ that the center of the Sun makes to a line perpendicular to the Earth's surface. If the Sun were a point and the
480
+ Earth were without an atmosphere, true sunset and sunrise would correspond to a 90&deg; zenith. Because the Sun
481
+ is not a point, and because the atmosphere refracts light, this 90&deg; zenith does not, in fact, correspond to
482
+ true sunset or sunrise, instead the centre of the Sun's disk must lie just below the horizon for the upper edge
483
+ to be obscured. This means that a zenith of just above 90&deg; must be used. The Sun subtends an angle of 16
484
+ minutes of arc (this can be changed via the [#setSolarRadius(double)](#setSolarRadius(double)) method , and atmospheric refraction
485
+ accounts for 34 minutes or so (this can be changed via the [#setRefraction(double)](#setRefraction(double)) method), giving a total
486
+ of 50 arcminutes. The total value for ZENITH is 90+(5/6) or 90.8333333&deg; for true sunrise/sunset. Since a
487
+ person at an elevation can see blow the horizon of a person at sea level, this will also adjust the zenith to
488
+ account for elevation if available. Note that this will only adjust the value if the zenith is exactly 90 degrees.
489
+ For values below and above this no correction is done. As an example, astronomical twilight is when the sun is
490
+ 18&deg; below the horizon or [108&deg;
491
+ below the zenith](AstronomicalCalendar#ASTRONOMICAL_ZENITH). This is traditionally calculated with none of the above mentioned adjustments. The same goes
492
+ for various <em>tzais</em> and <em>alos</em> times such as the
493
+ [16.1&deg;](ZmanimCalendar#ZENITH_16_POINT_1) dip used in
494
+ [ComplexZmanimCalendar#getAlos16Point1Degrees()](ComplexZmanimCalendar#getAlos16Point1Degrees()).
495
+
496
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
497
+ **Returns**: <code>number</code> - The zenith adjusted to include the [sun's radius](#getSolarRadius), [refraction](#getRefraction) and [elevation](#getElevationAdjustment) adjustment. This will only be adjusted for
498
+ sunrise and sunset (if the zenith == 90&deg;)
499
+ **See**: #getElevationAdjustment(double)
500
+
501
+ | Param | Type | Description |
502
+ | --- | --- | --- |
503
+ | zenith | <code>number</code> | the azimuth below the vertical zenith of 90&deg;. For sunset typically the [zenith](#adjustZenith) used for the calculation uses geometric zenith of 90&deg; and [adjusts](#adjustZenith) this slightly to account for solar refraction and the sun's radius. Another example would be [AstronomicalCalendar#getEndNauticalTwilight()](AstronomicalCalendar#getEndNauticalTwilight()) that passes [AstronomicalCalendar#NAUTICAL_ZENITH](AstronomicalCalendar#NAUTICAL_ZENITH) to this method. |
504
+ | elevation | <code>number</code> | elevation in Meters. |
505
+
506
+ <a name="NOAACalculator+getUTCSunrise"></a>
507
+
508
+ ### noaaCalculator.getUTCSunrise()
509
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
510
+ **See**: AstronomicalCalculator#getUTCSunrise(Calendar, GeoLocation, double, boolean)
511
+ <a name="NOAACalculator+getUTCSunset"></a>
512
+
513
+ ### noaaCalculator.getUTCSunset()
514
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
515
+ **See**: AstronomicalCalculator#getUTCSunset(Calendar, GeoLocation, double, boolean)
516
+ <a name="NOAACalculator+getTemporalHour"></a>
517
+
518
+ ### noaaCalculator.getTemporalHour(startOfDay, endOfDay) ⇒ <code>number</code>
519
+ A utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset
520
+ passed as parameters to this method. An example of the use of this method would be the calculation of a
521
+ non-elevation adjusted temporal hour by passing in [sea level sunrise](#getSeaLevelSunrise()) and
522
+ [sea level sunset](#getSeaLevelSunset()) as parameters.
523
+
524
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
525
+ **Returns**: <code>number</code> - the <code>long</code> millisecond length of the temporal hour. If the calculation can't be computed a
526
+ [Long#MIN_VALUE](Long#MIN_VALUE) will be returned. See detailed explanation on top of the page.
527
+ **See**: #getTemporalHour()
528
+
529
+ | Param | Type | Description |
530
+ | --- | --- | --- |
531
+ | startOfDay | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | The start of the day. |
532
+ | endOfDay | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | The end of the day. |
533
+
534
+ <a name="NOAACalculator+getSunTransit"></a>
535
+
536
+ ### noaaCalculator.getSunTransit(startOfDay, endOfDay) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
537
+ A method that returns sundial or solar noon. It occurs when the Sun is <a href
538
+ ="http://en.wikipedia.org/wiki/Transit_%28astronomy%29">transiting</a> the <a
539
+ href="http://en.wikipedia.org/wiki/Meridian_%28astronomy%29">celestial meridian</a>. In this class it is
540
+ calculated as halfway between the sunrise and sunset passed to this method. This time can be slightly off the
541
+ real transit time due to changes in declination (the lengthening or shortening day).
542
+
543
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
544
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The `Date` representing Sun's transit. If the calculation can't be computed such as in the
545
+ Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does
546
+ not set, null will be returned. See detailed explanation on top of the page.
547
+
548
+ | Param | Type | Description |
549
+ | --- | --- | --- |
550
+ | startOfDay | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | the start of day for calculating the sun's transit. This can be sea level sunrise, visual sunrise (or any arbitrary start of day) passed to this method. |
551
+ | endOfDay | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | the end of day for calculating the sun's transit. This can be sea level sunset, visual sunset (or any arbitrary end of day) passed to this method. |
552
+
553
+ <a name="NOAACalculator+getDateFromTime"></a>
554
+
555
+ ### noaaCalculator.getDateFromTime(time, isSunrise) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
556
+ A method that returns a `Date` from the time passed in as a parameter.
557
+
558
+ **Kind**: instance method of [<code>NOAACalculator</code>](#NOAACalculator)
559
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - The Date.
560
+ **Access**: protected
561
+
562
+ | Param | Type | Description |
563
+ | --- | --- | --- |
564
+ | time | <code>number</code> | The time to be set as the time for the `Date`. The time expected is in the format: 18.75 for 6:45:00 PM. |
565
+ | isSunrise | <code>boolean</code> | true if the time is sunrise, and false if it is sunset |
566
+
567
+ <a name="NOAACalculator.CIVIL_ZENITH"></a>
568
+
569
+ ### NOAACalculator.CIVIL\_ZENITH
570
+ Sun's zenith at civil twilight (96&deg;).
571
+
572
+ **Kind**: static property of [<code>NOAACalculator</code>](#NOAACalculator)
573
+ <a name="NOAACalculator.NAUTICAL_ZENITH"></a>
574
+
575
+ ### NOAACalculator.NAUTICAL\_ZENITH
576
+ Sun's zenith at nautical twilight (102&deg;).
577
+
578
+ **Kind**: static property of [<code>NOAACalculator</code>](#NOAACalculator)
579
+ <a name="NOAACalculator.ASTRONOMICAL_ZENITH"></a>
580
+
581
+ ### NOAACalculator.ASTRONOMICAL\_ZENITH
582
+ Sun's zenith at astronomical twilight (108&deg;).
583
+
584
+ **Kind**: static property of [<code>NOAACalculator</code>](#NOAACalculator)
585
+ <a name="NOAACalculator.getTimeOffset"></a>
586
+
587
+ ### NOAACalculator.getTimeOffset(time, offset) ⇒ <code>Temporal.ZonedDateTime</code> \| <code>null</code>
588
+ A utility method that returns a date offset by the offset time passed in. Please note that the level of light
589
+ during twilight is not affected by elevation, so if this is being used to calculate an offset before sunrise or
590
+ after sunset with the intent of getting a rough "level of light" calculation, the sunrise or sunset time passed
591
+ to this method should be sea level sunrise and sunset.
592
+
593
+ **Kind**: static method of [<code>NOAACalculator</code>](#NOAACalculator)
594
+ **Returns**: <code>Temporal.ZonedDateTime</code> \| <code>null</code> - the `Date` with the offset in milliseconds added to it
595
+
596
+ | Param | Type | Description |
597
+ | --- | --- | --- |
598
+ | time | <code>Temporal.ZonedDateTime</code> \| <code>null</code> | the start time |
599
+ | offset | <code>number</code> | the offset in milliseconds to add to the time. |
600
+
601
+ <a name="NOAACalculator.getSolarElevation"></a>
602
+
603
+ ### NOAACalculator.getSolarElevation(date, lat, lon) ⇒ <code>number</code>
604
+ Return the <a href="http://en.wikipedia.org/wiki/Celestial_coordinate_system">Solar Elevation</a> for the
605
+ horizontal coordinate system at the given location at the given time. Can be negative if the sun is below the
606
+ horizon. Not corrected for altitude.
607
+
608
+ **Kind**: static method of [<code>NOAACalculator</code>](#NOAACalculator)
609
+ **Returns**: <code>number</code> - solar elevation in degrees - horizon is 0 degrees, civil twilight is -6 degrees
610
+
611
+ | Param | Type | Description |
612
+ | --- | --- | --- |
613
+ | date | <code>Temporal.ZonedDateTime</code> | time of calculation |
614
+ | lat | <code>number</code> | latitude of location for calculation |
615
+ | lon | <code>number</code> | longitude of location for calculation |
616
+
617
+ <a name="NOAACalculator.getSolarAzimuth"></a>
618
+
619
+ ### NOAACalculator.getSolarAzimuth(date, latitude, lon) ⇒ <code>number</code>
620
+ Return the <a href="http://en.wikipedia.org/wiki/Celestial_coordinate_system">Solar Azimuth</a> for the
621
+ horizontal coordinate system at the given location at the given time. Not corrected for altitude. True south is 0
622
+ degrees.
623
+
624
+ **Kind**: static method of [<code>NOAACalculator</code>](#NOAACalculator)
625
+
626
+ | Param | Type | Description |
627
+ | --- | --- | --- |
628
+ | date | <code>Temporal.ZonedDateTime</code> | time of calculation |
629
+ | latitude | <code>number</code> | latitude of location for calculation |
630
+ | lon | <code>number</code> | longitude of location for calculation |
631
+