@hebcal/noaa v0.8.14

@hebcal/noaa

sunrise and sunset via NOAA algorithm with elevation, based on KosherJava

Introduction

This is a fork/subset of KosherZmanim library with Temporal replacing usage of Luxon.

Kosher Zmanim itself is a TS/JS port of the KosherJava library.

Installation

$ npm install @hebcal/noaa

Classes

GeoLocation

A class that contains location information such as latitude and longitude required for astronomical calculations. The elevation field may not be used by some calculation engines and would be ignored if set.

Kind: global class
Version: 1.1
Author: © Eliyahu Hershfeld 2004 - 2016

• GeoLocation
  • new GeoLocation(name, latitude, longitude, elevation, timeZoneId)
  • .getElevation() ⇒ number
  • .setElevation(elevation)
  • .getLatitude() ⇒ number
  • .getLongitude() ⇒ number
  • .getLocationName() ⇒ string | null
  • .setLocationName(name)
  • .getTimeZone() ⇒ string
  • .setTimeZone(timeZoneId)

new GeoLocation(name, latitude, longitude, elevation, timeZoneId)

GeoLocation constructor with parameters for all required fields.

geoLocation.getElevation() ⇒ number

Method to get the elevation in Meters.

Kind: instance method of GeoLocation
Returns: number - Returns the elevation in Meters.

geoLocation.setElevation(elevation)

Method to set the elevation in Meters above sea level.

Kind: instance method of GeoLocation

geoLocation.getLatitude() ⇒ number

Kind: instance method of GeoLocation
Returns: number - Returns the latitude.

geoLocation.getLongitude() ⇒ number

Kind: instance method of GeoLocation
Returns: number - Returns the longitude.

geoLocation.getLocationName() ⇒ string | null

Kind: instance method of GeoLocation
Returns: string | null - Returns the location name.

geoLocation.setLocationName(name)

Kind: instance method of GeoLocation

geoLocation.getTimeZone() ⇒ string

Kind: instance method of GeoLocation
Returns: string - Returns the timeZone.

geoLocation.setTimeZone(timeZoneId)

Method to set the TimeZone.

Kind: instance method of GeoLocation

NOAACalculator

Implementation of sunrise and sunset methods to calculate astronomical times based on the NOAA algorithm. This calculator uses the Java algorithm based on the implementation by NOAA - National Oceanic and Atmospheric Administration's Surface Radiation Research Branch. NOAA's implementation is based on equations from Astronomical Algorithms by Jean Meeus. Added to the algorithm is an adjustment of the zenith to account for elevation. The algorithm can be found in the Wikipedia Sunrise Equation article.

Kind: global class
Author: © Eliyahu Hershfeld 2011 - 2019

• NOAACalculator
  • new NOAACalculator(geoLocation, date)
  • instance
    • .getSunrise() ⇒ Temporal.ZonedDateTime | null
    • .getSeaLevelSunrise() ⇒ Temporal.ZonedDateTime | null
    • .getBeginCivilTwilight() ⇒ Temporal.ZonedDateTime | null
    • .getBeginNauticalTwilight() ⇒ Temporal.ZonedDateTime | null
    • .getBeginAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null
    • .getSunset() ⇒ Temporal.ZonedDateTime | null
    • .getSeaLevelSunset() ⇒ Temporal.ZonedDateTime | null
    • .getEndCivilTwilight() ⇒ Temporal.ZonedDateTime | null
    • .getEndNauticalTwilight() ⇒ Temporal.ZonedDateTime | null
    • .getEndAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null
    • .getSunriseOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null
    • .getSunsetOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null
    • .getUTCSunrise0(zenith) ⇒ number
    • .getUTCSeaLevelSunrise(zenith) ⇒ number
    • .getUTCSunset0(zenith) ⇒ number
    • .getUTCSeaLevelSunset(zenith) ⇒ number
    • .getElevationAdjustment(elevation) ⇒ number
    • .adjustZenith(zenith, elevation) ⇒ number
    • .getUTCSunrise(date, geoLocation, zenith, adjustForElevation) ⇒
    • .getUTCSunset(date, geoLocation, zenith, adjustForElevation) ⇒
    • .getTemporalHour(startOfDay, endOfDay) ⇒ number
    • .getSunTransit(startOfDay, endOfDay) ⇒ Temporal.ZonedDateTime | null
    • .getDateFromTime(time, isSunrise) ⇒ Temporal.ZonedDateTime | null
  • static
    • .CIVIL_ZENITH
    • .NAUTICAL_ZENITH
    • .ASTRONOMICAL_ZENITH
    • .getTimeOffset(time, offset) ⇒ Temporal.ZonedDateTime | null
    • .getSolarElevation(date, lat, lon) ⇒ number
    • .getSolarAzimuth(date, latitude, lon) ⇒ number

new NOAACalculator(geoLocation, date)

A constructor that takes in geolocation information as a parameter.

noaaCalculator.getSunrise() ⇒ Temporal.ZonedDateTime | null

The getSunrise method Returns a Date representing the elevation adjusted sunrise time. The zenith used for the calculation uses geometric zenith of 90° plus getElevationAdjustment. This is adjusted to add approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - the Date representing the exact sunrise time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

• adjustZenith
• getSeaLevelSunrise()
• getUTCSunrise

noaaCalculator.getSeaLevelSunrise() ⇒ Temporal.ZonedDateTime | null

A method that returns the sunrise without elevation adjustment. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - the Date representing the exact sea-level sunrise time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

• getSunrise
• getUTCSeaLevelSunrise
• getSeaLevelSunset()

noaaCalculator.getBeginCivilTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the beginning of civil twilight (dawn) using a zenith of 96°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the beginning of civil twilight using a zenith of 96°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: CIVIL_ZENITH

noaaCalculator.getBeginNauticalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the beginning of nautical twilight using a zenith of 102°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the beginning of nautical twilight using a zenith of 102°. If the calculation can't be computed null will be returned. See detailed explanation on top of the page.
See: NAUTICAL_ZENITH

noaaCalculator.getBeginAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the beginning of astronomical twilight using a zenith of 108°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the beginning of astronomical twilight using a zenith of 108°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: ASTRONOMICAL_ZENITH

noaaCalculator.getSunset() ⇒ Temporal.ZonedDateTime | null

The getSunset method Returns a Date representing the elevation adjusted sunset time. The zenith used for the calculation uses geometric zenith of 90° plus getElevationAdjustment. This is adjusted to add approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333°. Note: In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this case the sunset date will be incremented to the following date.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date representing the exact sunset time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

• adjustZenith
• getSeaLevelSunset()
• getUTCSunset

noaaCalculator.getSeaLevelSunset() ⇒ Temporal.ZonedDateTime | null

A method that returns the sunset without elevation adjustment. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after sunset.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date representing the exact sea-level sunset time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

• getSunset
• getUTCSeaLevelSunset

noaaCalculator.getEndCivilTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the end of civil twilight using a zenith of 96°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the end of civil twilight using a zenith of 96°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: CIVIL_ZENITH

noaaCalculator.getEndNauticalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the end of nautical twilight using a zenith of 102°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the end of nautical twilight using a zenith of 102° . If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: NAUTICAL_ZENITH

noaaCalculator.getEndAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the end of astronomical twilight using a zenith of 108°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the end of astronomical twilight using a zenith of 108°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: ASTRONOMICAL_ZENITH

noaaCalculator.getSunriseOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null

A utility method that returns the time of an offset by degrees below or above the horizon of sunrise. Note that the degree offset is from the vertical, so for a calculation of 14° before sunrise, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the offset after (or before) getSunrise. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.

noaaCalculator.getSunsetOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null

A utility method that returns the time of an offset by degrees below or above the horizon of sunset. Note that the degree offset is from the vertical, so for a calculation of 14° after sunset, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Dateof the offset after (or before) getSunset. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.

noaaCalculator.getUTCSunrise0(zenith) ⇒ number

A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.

Kind: instance method of NOAACalculator
Returns: number - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, NaN will be returned. See detailed explanation on top of the page.

noaaCalculator.getUTCSeaLevelSunrise(zenith) ⇒ number

A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.

Kind: instance method of NOAACalculator
Returns: number - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, NaN will be returned. See detailed explanation on top of the page.
See

• getUTCSunrise
• getUTCSeaLevelSunset

noaaCalculator.getUTCSunset0(zenith) ⇒ number

A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.

Kind: instance method of NOAACalculator
Returns: number - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, NaN will be returned. See detailed explanation on top of the page.
See: getUTCSeaLevelSunset

noaaCalculator.getUTCSeaLevelSunset(zenith) ⇒ number

A method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after sunset.

Kind: instance method of NOAACalculator
Returns: number - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, NaN will be returned. See detailed explanation on top of the page.
See

• getUTCSunset
• getUTCSeaLevelSunrise

noaaCalculator.getElevationAdjustment(elevation) ⇒ number

Method to return the adjustment to the zenith required to account for the elevation. Since a person at a higher elevation can see farther below the horizon, the calculation for sunrise / sunset is calculated below the horizon used at sea level. This is only used for sunrise and sunset and not times before or after it such as nautical twilight since those calculations are based on the level of available light at the given dip below the horizon, something that is not affected by elevation, the adjustment should only made if the zenith == 90° adjusted for refraction and solar radius. The algorithm used is

The source of this algorithm is Calendrical Calculations by Edward M. Reingold and Nachum Dershowitz. An alternate algorithm that produces an almost identical (but not accurate) result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:

Kind: instance method of NOAACalculator
Returns: number - the adjusted zenith

noaaCalculator.adjustZenith(zenith, elevation) ⇒ number

Adjusts the zenith of astronomical sunrise and sunset to account for solar refraction, solar radius and elevation. The value for Sun's zenith and true rise/set Zenith (used in this class and subclasses) is the angle that the center of the Sun makes to a line perpendicular to the Earth's surface. If the Sun were a point and the Earth were without an atmosphere, true sunset and sunrise would correspond to a 90° zenith. Because the Sun is not a point, and because the atmosphere refracts light, this 90° zenith does not, in fact, correspond to true sunset or sunrise, instead the centre of the Sun's disk must lie just below the horizon for the upper edge to be obscured. This means that a zenith of just above 90° must be used. The Sun subtends an angle of 16 minutes of arc, and atmospheric refraction accounts for 34 minutes or so, giving a total of 50 arcminutes. The total value for ZENITH is 90+(5/6) or 90.8333333° for true sunrise/sunset. Since a person at an elevation can see blow the horizon of a person at sea level, this will also adjust the zenith to account for elevation if available. Note that this will only adjust the value if the zenith is exactly 90 degrees. For values below and above this no correction is done. As an example, astronomical twilight is when the sun is 18° below the horizon or 108° below the zenith. This is traditionally calculated with none of the above mentioned adjustments. The same goes for various tzais and alos times such as the 16.1° dip used in ComplexZmanimCalendar#getAlos16Point1Degrees.

Kind: instance method of NOAACalculator
Returns: number - The zenith adjusted to include the sun's radius, refracton and elevation adjustment. This will only be adjusted for sunrise and sunset (if the zenith == 90°)
See: getElevationAdjustment

noaaCalculator.getUTCSunrise(date, geoLocation, zenith, adjustForElevation) ⇒

A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise.

Kind: instance method of NOAACalculator
Returns: The UTC time of sunrise in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, NaN will be returned.

noaaCalculator.getUTCSunset(date, geoLocation, zenith, adjustForElevation) ⇒

A method that calculates UTC sunset as well as any time based on an angle above or below sunset.

Kind: instance method of NOAACalculator
Returns: The UTC time of sunset in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, NaN will be returned.

noaaCalculator.getTemporalHour(startOfDay, endOfDay) ⇒ number

A utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset passed as parameters to this method. An example of the use of this method would be the calculation of a non-elevation adjusted temporal hour by passing in sea level sunrise and sea level sunset as parameters.

Kind: instance method of NOAACalculator
Returns: number - the long millisecond length of the temporal hour. If the calculation can't be computed a NaN will be returned. See detailed explanation on top of the page.
See: getTemporalHour()

noaaCalculator.getSunTransit(startOfDay, endOfDay) ⇒ Temporal.ZonedDateTime | null

A method that returns sundial or solar noon. It occurs when the Sun is transiting the celestial meridian. In this class it is calculated as halfway between the sunrise and sunset passed to this method. This time can be slightly off the real transit time due to changes in declination (the lengthening or shortening day).

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date representing Sun's transit. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, null will be returned. See detailed explanation on top of the page.

noaaCalculator.getDateFromTime(time, isSunrise) ⇒ Temporal.ZonedDateTime | null

A method that returns a Date from the time passed in as a parameter.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date.
Access: protected

NOAACalculator.CIVIL_ZENITH

Sun's zenith at civil twilight (96°).

Kind: static property of NOAACalculator

NOAACalculator.NAUTICAL_ZENITH

Sun's zenith at nautical twilight (102°).

Kind: static property of NOAACalculator

NOAACalculator.ASTRONOMICAL_ZENITH

Sun's zenith at astronomical twilight (108°).

Kind: static property of NOAACalculator

NOAACalculator.getTimeOffset(time, offset) ⇒ Temporal.ZonedDateTime | null

A utility method that returns a date offset by the offset time passed in. Please note that the level of light during twilight is not affected by elevation, so if this is being used to calculate an offset before sunrise or after sunset with the intent of getting a rough "level of light" calculation, the sunrise or sunset time passed to this method should be sea level sunrise and sunset.

Kind: static method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - the Date with the offset in milliseconds added to it

NOAACalculator.getSolarElevation(date, lat, lon) ⇒ number

Return the Solar Elevation for the horizontal coordinate system at the given location at the given time. Can be negative if the sun is below the horizon. Not corrected for altitude.

Kind: static method of NOAACalculator
Returns: number - solar elevation in degrees - horizon is 0 degrees, civil twilight is -6 degrees

NOAACalculator.getSolarAzimuth(date, latitude, lon) ⇒ number

Return the Solar Azimuth for the horizontal coordinate system at the given location at the given time. Not corrected for altitude. True south is 0 degrees.

Kind: static method of NOAACalculator