From f1904b12393c48b069d1333a7397fce66804958d Mon Sep 17 00:00:00 2001 From: KosherJava Date: Wed, 1 Jan 2025 11:33:13 -0500 Subject: [PATCH] AstronomicalCalculator.java - Add abstract method getUTCMidnight - Add abstract method getUTCMidnight - add default constructor to avoid warnings on recent JDKs - Tweak JavaDocs --- .../zmanim/util/AstronomicalCalculator.java | 55 +++++++++++++------ 1 file changed, 39 insertions(+), 16 deletions(-) diff --git a/src/main/java/com/kosherjava/zmanim/util/AstronomicalCalculator.java b/src/main/java/com/kosherjava/zmanim/util/AstronomicalCalculator.java index 2eb9dccd..b5e33902 100644 --- a/src/main/java/com/kosherjava/zmanim/util/AstronomicalCalculator.java +++ b/src/main/java/com/kosherjava/zmanim/util/AstronomicalCalculator.java @@ -1,6 +1,6 @@ /* * Zmanim Java API - * Copyright (C) 2004-2023 Eliyahu Hershfeld + * Copyright (C) 2004-2025 Eliyahu Hershfeld * * This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General * Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) @@ -23,12 +23,12 @@ * @todo Consider methods that would allow atmospheric modeling. This can currently be adjusted by {@link * #setRefraction(double) setting the refraction}. * - * @author © Eliyahu Hershfeld 2004 - 2023 + * @author © Eliyahu Hershfeld 2004 - 2025 */ public abstract class AstronomicalCalculator implements Cloneable { /** - * The commonly used average solar refraction. Calendrical Calculations lists a more accurate global average of - * 34.478885263888294 + * The commonly used average solar refraction. Calendrical Calculations lists a more accurate global average of 34.478885263888294 * * @see #getRefraction() */ @@ -49,6 +49,14 @@ public abstract class AstronomicalCalculator implements Cloneable { * @see #setEarthRadius(double) */ private double earthRadius = 6356.9; // in KM + + /** + * Default constructor using the default {@link #refraction refraction}, {@link #solarRadius solar radius} and + * {@link #earthRadius earth radius}. + */ + public AstronomicalCalculator() { + // keep the defaults for now. + } /** * 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) { private static final double GEOMETRIC_ZENITH = 90; /** - * Returns the default class for calculating sunrise and sunset. This is currently the more accurate {@link NOAACalculator}, - * but this may change. + * Returns the default class for calculating sunrise and sunset. This is currently the more accurate + * {@link NOAACalculator}, but this may change in the future. * * @return AstronomicalCalculator the default class for calculating sunrise and sunset. In the current * implementation the default calculator returned is the more accurate {@link NOAACalculator}. @@ -155,6 +163,22 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation, * @return the time in minutes from zero UTC */ public abstract double getUTCNoon(Calendar calendar, GeoLocation geoLocation); + + + /** + * Return solar midnight (UTC) for the given day at the + * given location on earth. The the {@link com.kosherjava.zmanim.util.NOAACalculator} implementation calculates + * true solar midnight, while the {@link com.kosherjava.zmanim.util.SunTimesCalculator} approximates it, calculating + * the time as 12 hours after halfway between sunrise and sunset. + * + * @param calendar + * Used to calculate day of year. + * @param geoLocation + * The location information used for astronomical calculating sun times. + * + * @return the time in minutes from zero UTC + */ + public abstract double getUTCMidnight(Calendar calendar, GeoLocation geoLocation); /** * 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, * elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters))); * * - * 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: + * The source of this algorithm is Calendrical + * Calculations by Edward M. Reingold and Nachum Dershowitz. An alternate algorithm that produces similar (but + * not completely accurate) result found in Ma'aglay Tzedek by Moishe Kosower and other sources is: * * 
 	 * elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);
@@ -201,7 +225,7 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
 	 * 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 {@link com.kosherjava.zmanim.AstronomicalCalendar#ASTRONOMICAL_ZENITH 108°
-	 * below the zenith}. This is traditionally calculated with none of the above-mentioned adjustments. The same goes
+	 * 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
 	 * {@link com.kosherjava.zmanim.ZmanimCalendar#ZENITH_16_POINT_1 16.1°} dip used in
 	 * {@link com.kosherjava.zmanim.ComplexZmanimCalendar#getAlos16Point1Degrees()}.
@@ -228,11 +252,10 @@ public abstract double getUTCSunset(Calendar calendar, GeoLocation geoLocation,
 	}
 
 	/**
-	 * Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34 arc
-	 * minutes. The Errata and Notes for Calendrical Calculations: The Millennium Edition 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
+	 * Method to get the refraction value to be used when calculating sunrise and sunset. The default value is 34
+	 * arcminutes. The Errata and Notes
+	 * for Calendrical Calculations: The Millennium Edition 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.
 	 * 
 	 * @return The refraction in arcminutes.
@@ -263,7 +286,7 @@ public void setRefraction(double refraction) {
 	 * the difference at the location of the Royal Observatory, Greenwich
 	 * shows only a 4.494-second difference between the perihelion and aphelion radii, but moving into the arctic circle the
 	 * difference becomes more noticeable. Tests for Tromso, Norway (latitude 69.672312, longitude 19.049787) show that
-	 * on May 17, the rise of the midnight sun, a 2-minute 23-second difference is observed between the perihelion and
+	 * on May 17, the rise of the midnight sun, a 2 minute and 23 second difference is observed between the perihelion and
 	 * aphelion radii using the USNO algorithm, but only 1 minute and 6 seconds difference using the NOAA algorithm.
 	 * Areas farther north show an even greater difference. Note that these test are not real valid test cases because
 	 * they show the extreme difference on days that are not the perihelion or aphelion, but are shown for illustrative