Skip to content

Commit

Permalink
finish documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@Elyahu41
Elyahu41 committed Jan 8, 2024
1 parent a6281de commit e58b223
Show file tree
Hide file tree
Showing 8 changed files with 100 additions and 130 deletions.
8 changes: 4 additions & 4 deletions Sources/KosherSwift/AstronomicalCalendar.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ public class AstronomicalCalendar {
* the calculation uses ``GEOMETRIC_ZENITH`` geometric zenith of 90° plus
* ``AstronomicalCalculator.getElevationAdjustment(double)``. This is adjusted by the
* ``AstronomicalCalculator`` 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 {@link AstronomicalCalculator#adjustZenith 90.83333°}.
* and 16 archminutes for the sun's radius for a total of ``AstronomicalCalculator.adjustZenith`` 90.83333°.
* See documentation for the specific implementation of the ``AstronomicalCalculator`` that you are using. 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
Expand Down Expand Up @@ -187,7 +187,7 @@ public class AstronomicalCalendar {
* 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 <code>nil</code> will be returned. See detailed explanation on top of the page.
* @see AstronomicalCalendar#getSunset
* @see AstronomicalCalendar#getUTCSeaLevelSunset 2see {@link #getSunset()}
* @see AstronomicalCalendar#getUTCSeaLevelSunset 2see ``getSunset()``
*/
public func getSeaLevelSunset() -> Date? {
let sunset = getUTCSeaLevelSunset(zenith: AstronomicalCalendar.GEOMETRIC_ZENITH);
Expand Down Expand Up @@ -348,7 +348,7 @@ public class AstronomicalCalendar {
* the degrees below the horizon. For time after sunrise use negative numbers.
* @return 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, {@link Double#NaN} will be returned. See detailed explanation on top of the page.
* not set, ``Double.nan`` will be returned. See detailed explanation on top of the page.
*/
public func getUTCSunrise(zenith:Double) -> Double {
return getAstronomicalCalculator().getUTCSunrise(date: workingDate, geoLocation: getGeoLocation(), zenith: zenith, adjustForElevation: true);
Expand All @@ -364,7 +364,7 @@ public class AstronomicalCalendar {
* the degrees below the horizon. For time after sunrise use negative numbers.
* @return 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, {@link Double#NaN} will be returned. See detailed explanation on top of the page.
* not set, ``Double.nan`` will be returned. See detailed explanation on top of the page.
* @see AstronomicalCalendar#getUTCSunrise
* @see AstronomicalCalendar#getUTCSeaLevelSunset
*/
Expand Down
66 changes: 26 additions & 40 deletions Sources/KosherSwift/util/AstronomicalCalculator.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ import Foundation
/**
* An abstract class that all sun time calculating classes extend. This allows the algorithm used to be changed at
* runtime, easily allowing comparison the results of using different algorithms.
* @todo Consider methods that would allow atmospheric modeling. This can currently be adjusted by {@link
* #setRefraction(double) setting the refraction}.
*
* //todo Consider methods that would allow atmospheric modeling. This can currently be adjusted by ``setRefraction(refraction:)`` setting the refraction.
*
* @author &copy; Eliyahu Hershfeld 2004 - 2023
*/
Expand Down Expand Up @@ -65,12 +65,12 @@ public class AstronomicalCalculator {
public static let GEOMETRIC_ZENITH = 90.0;

/**
* Returns the default class for calculating sunrise and sunset. This is currently the {@link NOAACalculator},
* Returns the default class for calculating sunrise and sunset. This is currently the ``NOAACalculator``,
* but this may change. The NOAACalculator is the most accurate sunrise/sunset calculator that is currently available.
* It should be prefered over the SunTimesCalculator.
*
* @return AstronomicalCalculator the default class for calculating sunrise and sunset. In the current
* implementation the default calculator returned is the {@link NOAACalculator}.
* implementation the default calculator returned is the ``NOAACalculator``.
*/
public static func getDefault(geoLocation: GeoLocation) -> AstronomicalCalculator {
return NOAACalculator(geoLocation: geoLocation);
Expand All @@ -80,22 +80,14 @@ public class AstronomicalCalculator {
* 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
* {@link com.kosherjava.zmanim.AstronomicalCalendar#getBeginNauticalTwilight() nautical twilight} since those
* ``AstronomicalCalendar.getBeginNauticalTwilight()`` 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&deg; {@link #adjustZenith adjusted}
* for refraction and solar radius. The algorithm used is
*
* <pre>
* elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));
* </pre>
* affected by elevation, the adjustment should only made if the zenith == 90&deg; ``adjustZenith`` adjusted
* for refraction and solar radius. The algorithm used is: elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));
*
* The source of this algorithm is <a href="http://www.calendarists.com">Calendrical Calculations</a> 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:
*
* <pre>
* elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);
* </pre>
* result found in Ma'aglay Tzedek by Moishe Kosower and other sources is: elevationAdjustment = 0.0347 x Math.sqrt(elevationMeters);
*
* @param elevation
* elevation in Meters.
Expand All @@ -114,28 +106,28 @@ public class AstronomicalCalculator {
* is not a point, and because the atmosphere refracts light, this 90&deg; zenith does not, in fact, correspond to
* true sunset or sunrise, instead the center 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&deg; must be used. The Sun subtends an angle of 16
* minutes of arc (this can be changed via the {@link #setSolarRadius(double)} method , and atmospheric refraction
* accounts for 34 minutes or so (this can be changed via the {@link #setRefraction(double)} method), giving a total
* minutes of arc (this can be changed via the ``setSolarRadius(solarRadius:)`` method , and atmospheric refraction
* accounts for 34 minutes or so (this can be changed via the ``setRefraction(refraction:)`` method), giving a total
* of 50 arcminutes. The total value for ZENITH is 90+(5/6) or 90.8333333&deg; 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&deg; below the horizon or {@link com.kosherjava.zmanim.AstronomicalCalendar#ASTRONOMICAL_ZENITH 108&deg;
* below the zenith}. This is traditionally calculated with none of the above mentioned adjustments. The same goes
* 18&deg; below the horizon or ``AstronomicalCalendar.ASTRONOMICAL_ZENITH`` 108&deg;
* below the zenith. This is traditionally calculated with none of the above mentioned adjustments. The same goes
* for various <em>tzais</em> and <em>alos</em> times such as the
* {@link com.kosherjava.zmanim.ZmanimCalendar#ZENITH_16_POINT_1 16.1&deg;} dip used in
* {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getAlos16Point1Degrees()}.
* ``ZmanimCalendar.ZENITH_16_POINT_1`` 16.1&deg; dip used in
* ``ComplexZmanimCalendar.getAlos16Point1Degrees()``.
*
* @param zenith
* the azimuth below the vertical zenith of 90&deg;. For sunset typically the {@link #adjustZenith
* zenith} used for the calculation uses geometric zenith of 90&deg; and {@link #adjustZenith adjusts}
* the azimuth below the vertical zenith of 90&deg;. For sunset typically the ``adjustZenith``
* zenith used for the calculation uses geometric zenith of 90&deg; and ``adjustZenith`` adjusts
* this slightly to account for solar refraction and the sun's radius. Another example would be
* {@link com.kosherjava.zmanim.AstronomicalCalendar#getEndNauticalTwilight()} that passes
* {@link com.kosherjava.zmanim.AstronomicalCalendar#NAUTICAL_ZENITH} to this method.
* ``AstronomicalCalendar.getEndNauticalTwilight()`` that passes
* ``AstronomicalCalendar.NAUTICAL_ZENITH`` to this method.
* @param elevation
* elevation in Meters.
* @return The zenith adjusted to include the {@link #getSolarRadius sun's radius}, {@link #getRefraction
* refraction} and {@link #getElevationAdjustment elevation} adjustment. This will only be adjusted for
* @return The zenith adjusted to include the ``getSolarRadius()`` sun's radius, ``getRefraction()``
* refraction and ``getElevationAdjustment`` elevation adjustment. This will only be adjusted for
* sunrise and sunset (if the zenith == 90&deg;)
* @see #getElevationAdjustment(double)
*/
Expand All @@ -149,9 +141,7 @@ public class AstronomicalCalculator {

/**
* Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34 arc
* minutes. The <a href=
* "https://web.archive.org/web/20150915094635/http://emr.cs.iit.edu/home/reingold/calendar-book/second-edition/errata.pdf"
* >Errata and Notes for Calendrical Calculations: The Millennium Edition</a> by Edward M. Reingold and Nachum Dershowitz
* minutes. The <a href="https://web.archive.org/web/20150915094635/http://emr.cs.iit.edu/home/reingold/calendar-book/second-edition/errata.pdf">Errata and Notes for Calendrical Calculations: The Millennium Edition</a> by Edward M. Reingold and Nachum Dershowitz
* lists the actual average refraction value as 34.478885263888294 or approximately 34' 29". The refraction value as well
* as the solarRadius and elevation adjustment are added to the zenith used to calculate sunrise and sunset.
*
Expand Down Expand Up @@ -206,21 +196,17 @@ public class AstronomicalCalculator {
self.solarRadius = solarRadius;
}

/*
Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class
*/
///Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class
public func getUTCSunrise(date: Date, geoLocation: GeoLocation, zenith: Double, adjustForElevation: Bool) -> Double {
return Double.nan
}
/*
Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class
*/

///Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class
public func getUTCSunset(date: Date, geoLocation: GeoLocation, zenith: Double, adjustForElevation: Bool) -> Double {
return Double.nan
}
/*
Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class
*/

///Do not use this method directly, it must be overrided by sub classes like the NOAACalculator class
public func getUTCNoon(date: Date, geoLocation: GeoLocation) -> Double {
return Double.nan
}
Expand Down
23 changes: 9 additions & 14 deletions Sources/KosherSwift/util/GeoLocation.swift
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import Foundation
/**
* 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. Check the documentation for
* specific implementations of the {@link AstronomicalCalculator} to see if elevation is calculated as part of the
* specific implementations of the ``AstronomicalCalculator`` to see if elevation is calculated as part of the
* algorithm.
*
* @author &copy; Eliyahu Hershfeld 2004 - 2022
Expand Down Expand Up @@ -98,7 +98,7 @@ public class GeoLocation {
* GeoLocation constructor with parameters for all required fields.
*
* @param name
* The location name for display use such as &quot;Lakewood, NJ&quot;
* The location name for display use such as &quot;Lakewood, NJ&quot;. This can be an empty string as well
* @param latitude
* 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.
Expand All @@ -121,7 +121,7 @@ public class GeoLocation {
* GeoLocation constructor with parameters for all required fields.
*
* @param name
* The location name for display use such as &quot;Lakewood, NJ&quot;
* The location name for display use such as &quot;Lakewood, NJ&quot;. This can be an empty string as well
* @param latitude
* 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.
Expand Down Expand Up @@ -278,12 +278,7 @@ public class GeoLocation {
}

/**
* Method to set the TimeZone. If this is ever set after the GeoLocation is set in the
* {@link com.kosherjava.zmanim.AstronomicalCalendar}, it is critical that
* {@link com.kosherjava.zmanim.AstronomicalCalendar#getCalendar()}.
* {@link java.util.Calendar#setTimeZone(TimeZone) setTimeZone(TimeZone)} be called in order for the
* AstronomicalCalendar to output times in the expected offset. This situation will arise if the
* AstronomicalCalendar is ever {@link com.kosherjava.zmanim.AstronomicalCalendar#clone() cloned}.
* Method to set the TimeZone.
*
* @param timeZone
* The timeZone to set.
Expand All @@ -293,11 +288,11 @@ public class GeoLocation {
}

/**
* This method is not tested at all. If you want to use this method or fix it, please submit an issue on github.
* This method is not tested at all. If you want to use this method or fix it, please submit an issue on the KosherSwift github.
* A method that will return the location's local mean time offset in milliseconds from local <a
* href="https://en.wikipedia.org/wiki/Standard_time">standard time</a>. The globe is split into 360&deg;, with
* 15&deg; per hour of the day. For a local that is at a longitude that is evenly divisible by 15 (longitude % 15 ==
* 0), at solar {@link com.kosherjava.zmanim.AstronomicalCalendar#getSunTransit() noon} (with adjustment for the <a
* 0), at solar ``AstronomicalCalendar.getSunTransit()`` noon (with adjustment for the <a
* href="https://en.wikipedia.org/wiki/Equation_of_time">equation of time</a>) the sun should be directly overhead,
* so a user who is 1&deg; west of this will have noon at 4 minutes after standard time noon, and conversely, a user
* who is 1&deg; east of the 15&deg; longitude will have noon at 11:56 AM. Lakewood, N.J., whose longitude is
Expand All @@ -311,7 +306,7 @@ public class GeoLocation {
* @since 1.1
*/
public func getLocalMeanTimeOffset() -> Double {
//This method might not work properly. I did not test it at all.
//This method might not work properly. I did not test it at all as it is not currently used anywhere in the codebase
return Double(Int(getLongitude()) * 4 * GeoLocation.MINUTE_MILLIS - getTimeZone().secondsFromGMT());
}

Expand Down Expand Up @@ -401,8 +396,8 @@ public class GeoLocation {
* @param location
* the destination location
* @param formula
* This formula calculates initial bearing ({@link #INITIAL_BEARING}), final bearing (
* {@link #FINAL_BEARING}) and distance ({@link #DISTANCE}).
* This formula calculates initial bearing (``INITIAL_BEARING``), final bearing (
* ``FINAL_BEARING``) and distance (``DISTANCE``).
* @return geodesic distance in Meters
*/
private func vincentyFormula(location: GeoLocation, formula: Int) -> Double {
Expand Down
Loading

0 comments on commit e58b223

Please sign in to comment.