11/*
22 * Zmanim Java API
3- * Copyright (C) 2004-2023 Eliyahu Hershfeld
3+ * Copyright (C) 2004-2025 Eliyahu Hershfeld
44 *
55 * This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General
66 * Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option)
2323 * @todo Consider methods that would allow atmospheric modeling. This can currently be adjusted by {@link
2424 * #setRefraction(double) setting the refraction}.
2525 *
26- * @author © Eliyahu Hershfeld 2004 - 2023
26+ * @author © Eliyahu Hershfeld 2004 - 2025
2727 */
2828public abstract class AstronomicalCalculator implements Cloneable {
2929 /**
30- * The commonly used average solar refraction. Calendrical Calculations lists a more accurate global average of
31- * 34.478885263888294
30+ * The commonly used average solar refraction. <a href="https://www.cs.tau.ac.il//~nachum/calendar-book/index.shtml"
31+ * >Calendrical Calculations</a> lists a more accurate global average of 34.478885263888294
3232 *
3333 * @see #getRefraction()
3434 */
@@ -49,6 +49,14 @@ public abstract class AstronomicalCalculator implements Cloneable {
4949 * @see #setEarthRadius(double)
5050 */
5151 private double earthRadius = 6356.9 ; // in KM
52+ 53+ /**
54+ * Default constructor using the default {@link #refraction refraction}, {@link #solarRadius solar radius} and
55+ * {@link #earthRadius earth radius}.
56+ */
57+ public AstronomicalCalculator () {
58+ // keep the defaults for now.
59+ }
5260
5361 /**
5462 * A method that returns the earth radius in KM. The value currently defaults to 6356.9 KM if not set.
@@ -75,8 +83,8 @@ public void setEarthRadius(double earthRadius) {
7583 private static final double GEOMETRIC_ZENITH = 90 ;
7684
7785 /**
78- * Returns the default class for calculating sunrise and sunset. This is currently the more accurate {@link NOAACalculator},
79- * but this may change.
86+ * Returns the default class for calculating sunrise and sunset. This is currently the more accurate
87+ * {@link NOAACalculator}, but this may change in the future .
8088 *
8189 * @return AstronomicalCalculator the default class for calculating sunrise and sunset. In the current
8290 * implementation the default calculator returned is the more accurate {@link NOAACalculator}.
@@ -155,6 +163,22 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
155163 * @return the time in minutes from zero UTC
156164 */
157165 public abstract double getUTCNoon (Calendar calendar , GeoLocation geoLocation );
166+ 167+ 168+ /**
169+ * Return <a href="https://en.wikipedia.org/wiki/Midnight">solar midnight</a> (UTC) for the given day at the
170+ * given location on earth. The the {@link com.kosherjava.zmanim.util.NOAACalculator} implementation calculates
171+ * true solar midnight, while the {@link com.kosherjava.zmanim.util.SunTimesCalculator} approximates it, calculating
172+ * the time as 12 hours after halfway between sunrise and sunset.
173+ *
174+ * @param calendar
175+ * Used to calculate day of year.
176+ * @param geoLocation
177+ * The location information used for astronomical calculating sun times.
178+ *
179+ * @return the time in minutes from zero UTC
180+ */
181+ public abstract double getUTCMidnight (Calendar calendar , GeoLocation geoLocation );
158182
159183 /**
160184 * Method to return the adjustment to the zenith required to account for the elevation. Since a person at a higher
@@ -169,9 +193,9 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
169193 * elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));
170194 * </pre>
171195 *
172- * The source of this algorithm is <a href="http ://www.calendarists.com ">Calendrical Calculations</a> by Edward M.
173- * Reingold and Nachum Dershowitz. An alternate algorithm that produces an almost identical (but not accurate)
174- * result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:
196+ * The source of this algorithm is <a href="https ://www.cs.tau.ac.il/~nachum/calendar-book/index.shtml ">Calendrical
197+ * Calculations</a> by Edward M. Reingold and Nachum Dershowitz. An alternate algorithm that produces similar (but
198+ * not completely accurate) result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:
175199 *
176200 * <pre>
177201 * elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);
@@ -201,7 +225,7 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
201225 * account for elevation if available. Note that this will only adjust the value if the zenith is exactly 90 degrees.
202226 * For values below and above this no correction is done. As an example, astronomical twilight is when the sun is
203227 * 18° below the horizon or {@link com.kosherjava.zmanim.AstronomicalCalendar#ASTRONOMICAL_ZENITH 108°
204- * below the zenith}. This is traditionally calculated with none of the above- mentioned adjustments. The same goes
228+ * below the zenith}. This is traditionally calculated with none of the abovementioned adjustments. The same goes
205229 * for various <em>tzais</em> and <em>alos</em> times such as the
206230 * {@link com.kosherjava.zmanim.ZmanimCalendar#ZENITH_16_POINT_1 16.1°} dip used in
207231 * {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getAlos16Point1Degrees()}.
@@ -228,11 +252,10 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
228252 }
229253
230254 /**
231- * Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34 arc
232- * minutes. The <a href=
233- * "https://web.archive.org/web/20150915094635/http://emr.cs.iit.edu/home/reingold/calendar-book/second-edition/errata.pdf"
234- * >Errata and Notes for Calendrical Calculations: The Millennium Edition</a> by Edward M. Reingold and Nachum Dershowitz
235- * lists the actual average refraction value as 34.478885263888294 or approximately 34' 29". The refraction value as well
255+ * Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34
256+ * arcminutes. The <a href="https://www.cs.tau.ac.il/~nachum/calendar-book/second-edition/errata.pdf">Errata and Notes
257+ * for Calendrical Calculations: The Millennium Edition</a> by Edward M. Reingold and Nachum Dershowitz lists the
258+ * actual average refraction value as 34.478885263888294 or approximately 34' 29". The refraction value as well
236259 * as the solarRadius and elevation adjustment are added to the zenith used to calculate sunrise and sunset.
237260 *
238261 * @return The refraction in arcminutes.
@@ -263,7 +286,7 @@ public void setRefraction(double refraction) {
263286 * the difference at the location of the <a href="https://www.rmg.co.uk/royal-observatory">Royal Observatory, Greenwich</a>
264287 * shows only a 4.494-second difference between the perihelion and aphelion radii, but moving into the arctic circle the
265288 * difference becomes more noticeable. Tests for Tromso, Norway (latitude 69.672312, longitude 19.049787) show that
266- * on May 17, the rise of the midnight sun, a 2- minute 23- second difference is observed between the perihelion and
289+ * on May 17, the rise of the midnight sun, a 2minute and 23 second difference is observed between the perihelion and
267290 * aphelion radii using the USNO algorithm, but only 1 minute and 6 seconds difference using the NOAA algorithm.
268291 * Areas farther north show an even greater difference. Note that these test are not real valid test cases because
269292 * they show the extreme difference on days that are not the perihelion or aphelion, but are shown for illustrative
0 commit comments