/*
 * Zmanim Java API
 * Copyright (C) 2004-2026 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)
 * any later version.
 *
 * This library is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 * details.
 * You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA,
 * or connect to: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
 */
package com.kosherjava.zmanim;

import java.math.BigDecimal;
import java.time.Duration;
import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.util.Objects;

import com.kosherjava.zmanim.util.AstronomicalCalculator;
import com.kosherjava.zmanim.util.GeoLocation;
import com.kosherjava.zmanim.util.ZmanimFormatter;

/**
 * A Java calendar that calculates astronomical times such as {@link getSunrise() sunrise}, {@link
 * getSunset() sunset} and twilight times. This class contains a {@link getLocalDate() LocalDate} and can therefore
 * use the standard Calendar functionality to change dates etc. The calculation engine used to calculate the astronomical times can
 * be changed to a different implementation by implementing the abstract {@link AstronomicalCalculator} and setting it withthe {@link
 * setAstronomicalCalculator(AstronomicalCalculator)}. A number of different calculation engine implementations are included in the
 * util package.
 * <b>Note:</b> There are times when the algorithms can't calculate proper values for sunrise, sunset and twilight. This is usually
 * caused by trying to calculate times for areas either very far North or South, where sunrise / sunset never happen on that date.
 * This is common when calculating twilight with a deep dip below the horizon for locations as far south of the North Pole as London,
 * in the northern hemisphere. The sun never reaches this dip at certain times of the year. When the calculations encounter this
 * condition a <code>null</code> will be returned when a <code>{@link java.time.Instant}</code> is expected and {@link Long#MIN_VALUE}
 * when a <code>long</code> is expected. The reason that <code>Exception</code>s are not thrown in these cases is because the lack of
 * a rise/set or twilight is not an exception, but an expected condition in many parts of the world.
 * <p>
 * Here is a simple example of how to use the API to calculate sunrise.
 * First create the Calendar for the location you would like to calculate sunrise or sunset times for:
 * 
 * <pre>
 * String locationName = &quot;Lakewood, NJ&quot;;
 * double latitude = 40.0828; // Lakewood, NJ
 * double longitude = -74.2094; // Lakewood, NJ
 * double elevation = 20; // optional elevation correction in Meters
 * // the String parameter in getZoneId() has to be a valid ZoneId listed in {@link java.time.ZoneId#getAvailableZoneIds()}
 * ZoneId zoneId = ZoneId.of(&quot;America/New_York&quot;);
 * GeoLocation location = new GeoLocation(locationName, latitude, longitude, elevation, zoneId);
 * AstronomicalCalendar ac = new AstronomicalCalendar(location);
 * </pre>
 * 
 * To get the time of sunrise, first set the date you want (if not set, the date will default to today):
 * 
 * <pre>
 * LocalDate localDate = LocalDate.of(1969, Month.FEBRUARY, 8);
 * ac.setLocalDate(localDate);
 * Instant sunrise = ac.getSunrise();
 * </pre>
 * 
 * @author &copy; Eliyahu Hershfeld 2004 - 2026
 */
public class AstronomicalCalendar implements Cloneable {

        /**
         * 90&deg; below the vertical. Used as a basis for most calculations since the location of the sun is 90&deg; below the horizon
         * at sunrise and sunset.
         * <b>Note </b>: it is important to note that for sunrise and sunset the {@link AstronomicalCalculator#adjustZenith(double,
         * double) adjusted zenith} is required to account for the radius of the sun and refraction. The adjusted zenith should not be
         * used for calculations above or below 90&deg; since they are usually calculated as an offset to 90&deg;.
         */
        public static final double GEOMETRIC_ZENITH = 90;

        /** Sun's zenith at civil twilight (96&deg;). */
        public static final double CIVIL_ZENITH = 96;

        /** Sun's zenith at nautical twilight (102&deg;). */
        public static final double NAUTICAL_ZENITH = 102;

        /** Sun's zenith at astronomical twilight (108&deg;). */
        public static final double ASTRONOMICAL_ZENITH = 108;

        /** constant for milliseconds in a minute (60,000) */
        public static final long MINUTE_MILLIS = 60 * 1000;

        /** constant for milliseconds in an hour (3,600,000) */
        public static final long HOUR_MILLIS = MINUTE_MILLIS * 60;
        
        /**
         * The <code>LocalDate</code> encapsulated by this class to track the current date used by the class
         */
        private LocalDate localDate;

        /**
         * the {@link GeoLocation} used for calculations.
         */
        private GeoLocation geoLocation;

        /**
         * the internal {@link AstronomicalCalculator} used for calculating solar based times.
         */
        private AstronomicalCalculator astronomicalCalculator;

        /**
         * The getSunrise method returns a <code>Instant</code> representing the {@link AstronomicalCalculator
         * #getElevationAdjustment(double) elevation adjusted} sunrise time. The zenith used for the calculation uses {@link
         * GEOMETRIC_ZENITH geometric zenith} of 90&deg; plus {@link AstronomicalCalculator#getElevationAdjustment(double)}. This is
         * adjusted by the {@link 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&deg;}.
         * See documentation for the specific implementation of the {@link AstronomicalCalculator} that you are using.
         * 
         * @return the <code>Instant</code> 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
         *         <code>null</code> will be returned. See detailed explanation on top of the page.
         * @see AstronomicalCalculator#adjustZenith(double, double)
         * @see getSeaLevelSunrise()
         * @see getUTCSunrise(double)
         */
        public Instant getSunrise() {
                double sunrise = getUTCSunrise(GEOMETRIC_ZENITH);
                if (Double.isNaN(sunrise)) {
                        return null;
                } else {
                        return getInstantFromTime(sunrise, SolarEvent.SUNRISE);
                }
        }

        /**
         * A method that returns the sunrise without {@link AstronomicalCalculator#getElevationAdjustment(double) 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.
         * 
         * @return the <code>Instant</code> 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 <code>null</code> will be returned. See detailed explanation on top of the page.
         * @see getSunrise()
         * @see getUTCSeaLevelSunrise(double)
         * @see getSeaLevelSunset()
         */
        public Instant getSeaLevelSunrise() {
                double sunrise = getUTCSeaLevelSunrise(GEOMETRIC_ZENITH);
                if (Double.isNaN(sunrise)) {
                        return null;
                } else {
                        return getInstantFromTime(sunrise, SolarEvent.SUNRISE);
                }
        }

        /**
         * A method that returns the beginning of <a href="https://en.wikipedia.org/wiki/Twilight#Civil_twilight">civil twilight</a>
         * (dawn) using a zenith of {@link CIVIL_ZENITH 96&deg;}.
         * 
         * @return The <code>Instant</code> of the beginning of civil twilight using a zenith of 96&deg;. If the calculation
         *         can't be computed, <code>null</code> will be returned. See detailed explanation on top of the page.
         */
        public Instant getBeginCivilTwilight() {
                return getSunriseOffsetByDegrees(CIVIL_ZENITH);
        }

        /**
         * A method that returns the beginning of <a href="https://en.wikipedia.org/wiki/Twilight#Nautical_twilight">nautical twilight</a>
         * using a zenith of {@link NAUTICAL_ZENITH 102&deg;}.
         * 
         * @return The <code>Instant</code> of the beginning of nautical twilight using a zenith of 102&deg;. If the calculation
         *         can't be computed <code>null</code> will be returned. See detailed explanation on top of the page.
         */
        public Instant getBeginNauticalTwilight() {
                return getSunriseOffsetByDegrees(NAUTICAL_ZENITH);
        }

        /**
         * A method that returns the beginning of <a href="https://en.wikipedia.org/wiki/Twilight#Astronomical_twilight">astronomical
         * twilight</a> using a zenith of {@link ASTRONOMICAL_ZENITH 108&deg;}.
         * 
         * @return The <code>Instant</code> of the beginning of astronomical twilight using a zenith of 108&deg;. If the calculation
         *         can't be computed, <code>null</code> will be returned. See detailed explanation on top of the page.
         */
        public Instant getBeginAstronomicalTwilight() {
                return getSunriseOffsetByDegrees(ASTRONOMICAL_ZENITH);
        }

    /**
     * The getSunset method returns an <code>Instant</code> representing the
     * {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjusted} sunset time. The zenith used for the
     * calculation uses {@link GEOMETRIC_ZENITH geometric zenith} of 90&deg; plus {@link AstronomicalCalculator
     * #getElevationAdjustment(double)}. This is adjusted by the {@link 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(double, double) 90.83333&deg;}. See documentation for the specific implementation of the
     * {@link AstronomicalCalculator} that you are using.
     * Note: In certain cases the calculates sunset will occur before sunrise. This will typically happen when a time zone other than
     * the local timezone is used (calculating Los Angeles sunset using a GMT time zone for example). In this case the sunset date
     * will be incremented to the following date.
     *
     * @return the <code>Instant</code> 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
     *         <code>null</code> will be returned. See detailed explanation on top of the page.
     * @see AstronomicalCalculator#adjustZenith(double, double)
     * @see getSeaLevelSunset()
     * @see getUTCSunset(double)
     */
    public Instant getSunset() {
        double sunset = getUTCSunset(GEOMETRIC_ZENITH);
        if (Double.isNaN(sunset)) {
            return null;
        } else {
            return getInstantFromTime(sunset, SolarEvent.SUNSET);
        }
    }
    
        /**
         * A method that returns the sunset without {@link AstronomicalCalculator#getElevationAdjustment(double) 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.
         * 
         * @return the <code>Instant</code> 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 <code>null</code> will be returned. See detailed explanation on top of the page.
         * @see getSunset()
         * @see getUTCSeaLevelSunset(double)
         */
        public Instant getSeaLevelSunset() {
                double sunset = getUTCSeaLevelSunset(GEOMETRIC_ZENITH);
                if (Double.isNaN(sunset)) {
                        return null;
                } else {
                        return getInstantFromTime(sunset, SolarEvent.SUNSET);
                }
        }

        /**
         * A method that returns the end of <a href="https://en.wikipedia.org/wiki/Twilight#Civil_twilight">civil twilight</a>
         * using a zenith of {@link CIVIL_ZENITH 96&deg;}.
         * 
         * @return The <code>Instant</code> of the end of civil twilight using a zenith of {@link CIVIL_ZENITH 96&deg;}. If the
         *         calculation can't be computed, <code>null</code> will be returned. See detailed explanation on top of the page.
         */
        public Instant getEndCivilTwilight() {
                return getSunsetOffsetByDegrees(CIVIL_ZENITH);
        }

        /**
         * A method that returns the end of nautical twilight using a zenith of {@link NAUTICAL_ZENITH 102&deg;}.
         * 
         * @return The <code>Instant</code> of the end of nautical twilight using a zenith of {@link NAUTICAL_ZENITH 102&deg;}. If
         *         the calculation can't be computed, <code>null</code> will be returned. See detailed explanation on top of the
         *         page.
         */
        public Instant getEndNauticalTwilight() {
                return getSunsetOffsetByDegrees(NAUTICAL_ZENITH);
        }

        /**
         * A method that returns the end of astronomical twilight using a zenith of {@link ASTRONOMICAL_ZENITH 108&deg;}.
         * 
         * @return the <code>Instant</code> of the end of astronomical twilight using a zenith of {@link ASTRONOMICAL_ZENITH
         *         108&deg;}. If the calculation can't be computed, <code>null</code> will be returned. See detailed
         *         explanation on top of the page.
         */
        public Instant getEndAstronomicalTwilight() {
                return getSunsetOffsetByDegrees(ASTRONOMICAL_ZENITH);
        }

        /**
         * A utility method that returns a date offset by the offset time passed in as a parameter. This method casts the
         * offset as a <code>long</code> and calls {@link getTimeOffset(Instant, long)}.
         * 
         * @param time
         *            the start time
         * @param offset
         *            the offset in milliseconds to add to the time
         * @return the {@link java.time.Instant} with the offset added to it
         */
        public static Instant getTimeOffset(Instant time, double offset) {
                return getTimeOffset(time, (long) offset);
        }
        
        /**
         * A utility method that returns an <code>Instant</code> 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.
         * 
         * @param time
         *            the start time
         * @param offsetMillis
         *            the offset in milliseconds to add to the time.
         * @return the {@link java.time.Instant} with the offset in milliseconds added to it
         */
        public static Instant getTimeOffset(Instant time, long offsetMillis) {
            if (time == null || offsetMillis == Long.MIN_VALUE) {
                return null;
            }
            return time.plusMillis(offsetMillis);
        }
        
        /**
         * A utility method that returns the time of an offset by degrees below or above the horizon of {@link getSunrise()
         * sunrise}. Note that the degree offset is from the vertical, so for a calculation of 14&deg; before sunrise, an offset of 14
         * + {@link GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
         * 
         * @param offsetZenith
         *            the degrees before {@link 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 + {@link GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
         * @return The {@link java.time.Instant} of the offset after (or before) {@link 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 <code>null</code> will be returned. See detailed explanation
         *         on top of the page.
         */
        public Instant getSunriseOffsetByDegrees(double offsetZenith) {
            double dawn = getUTCSunrise(offsetZenith);
            return Double.isNaN(dawn) ? null
                    : getInstantFromTime(dawn, SolarEvent.SUNRISE);
        }

        /**
         * A utility method that returns the time of an offset by degrees below or above the horizon of {@link getSunset()
         * sunset}. Note that the degree offset is from the vertical, so for a calculation of 14&deg; after sunset, an offset of 14 +
         * {@link GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
         * 
         * @param offsetZenith
         *            the degrees after {@link 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 + {@link GEOMETRIC_ZENITH} = 104 would have to be passed as a parameter.
         * @return The {@link java.time.Instant} of the offset after (or before) {@link 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
         *         and one where it does not set, a <code>null</code> will be returned. See detailed explanation on top of the page.
         */
        public Instant getSunsetOffsetByDegrees(double offsetZenith) {
            double sunset = getUTCSunset(offsetZenith);
            return Double.isNaN(sunset) ? null
                    : getInstantFromTime(sunset, SolarEvent.SUNSET);
        }

        /**
         * Default constructor will set a default {@link GeoLocation#GeoLocation()}, a default {@link AstronomicalCalculator#getDefault()
         * AstronomicalCalculator} and default the <code>LocalDate</code> to the current date.
         */
        public AstronomicalCalendar() {
                this(new GeoLocation());
        }

        /**
         * A constructor that takes in <a href="https://en.wikipedia.org/wiki/Geolocation">geolocation</a> information as a parameter.
         * The default {@link AstronomicalCalculator#getDefault() AstronomicalCalculator} used for solar calculations is the more
         * accurate {@link com.kosherjava.zmanim.util.NOAACalculator}.
         *
         * @param geoLocation
         *            The location information used for calculating astronomical sun times.
         *
         * @see setAstronomicalCalculator(AstronomicalCalculator) for changing the calculator class.
         */
        public AstronomicalCalendar(GeoLocation geoLocation) {
                setLocalDate(LocalDate.now(geoLocation.getZoneId()));
                setGeoLocation(geoLocation);// duplicate call
                setAstronomicalCalculator(AstronomicalCalculator.getDefault());
        }

        /**
         * A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight
         * savings time.
         * 
         * @param zenith
         *            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.
         */
        public double getUTCSunrise(double zenith) {
                return getAstronomicalCalculator().getUTCSunrise(getAdjustedLocalDate(), getGeoLocation(), zenith, true);
        }

        /**
         * 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.
         * 
         * @param zenith
         *            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.
         * @see getUTCSunrise(double)
         * @see getUTCSeaLevelSunset(double)
         */
        public double getUTCSeaLevelSunrise(double zenith) {
                return getAstronomicalCalculator().getUTCSunrise(getAdjustedLocalDate(), getGeoLocation(), zenith, false);
        }

        /**
         * A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using
         * daylight savings time.
         * 
         * @param zenith
         *            the degrees below the horizon. For time after sunset 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.
         * @see getUTCSeaLevelSunset(double)
         */
        public double getUTCSunset(double zenith) {
                return getAstronomicalCalculator().getUTCSunset(getAdjustedLocalDate(), getGeoLocation(), zenith, true);
        }

        /**
         * 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.
         * 
         * @param zenith
         *            the degrees below the horizon. For time before sunset 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.
         * @see getUTCSunset(double)
         * @see getUTCSeaLevelSunrise(double)
         */
        public double getUTCSeaLevelSunset(double zenith) {
                return getAstronomicalCalculator().getUTCSunset(getAdjustedLocalDate(), getGeoLocation(), zenith, false);
        }

        /**
         * A method that returns a sea-level based temporal (solar) hour. The day from {@link getSeaLevelSunrise() sea-level sunrise} to
         * {@link getSeaLevelSunset() sea-level sunset} is split into 12 equal parts with each one being a temporal hour.
         * 
         * @see getSeaLevelSunrise()
         * @see getSeaLevelSunset()
         * @see getTemporalHour(Instant, Instant)
         * 
         * @return the <code>long</code> millisecond length of a temporal hour. If the calculation can't be computed,
         *         {@link Long#MIN_VALUE} will be returned. See detailed explanation on top of the page.
         * 
         */
        public long getTemporalHour() {
                return getTemporalHour(getSeaLevelSunrise(), getSeaLevelSunset());
        }

        /**
         * 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 elevation adjusted temporal
         * hour by passing in {@link getSunrise() sunrise} and {@link getSunset() sunset} as parameters.
         * 
         * @param startOfDay
         *            The start of the day.
         * @param endOfDay
         *            The end of the day.
         * 
         * @return the <code>long</code> millisecond length of the temporal hour. If the calculation can't be computed a
         *         {@link Long#MIN_VALUE} will be returned. See detailed explanation on top of the page.
         * 
         * @see getTemporalHour()
         */
        public long getTemporalHour(Instant startOfDay, Instant endOfDay) {
            if (startOfDay == null || endOfDay == null) {
                return Long.MIN_VALUE;
            }

            return Duration.between(startOfDay, endOfDay).toMillis() / 12;
        }

        /**
         * A method that returns sundial or solar noon. It occurs when the Sun is <a href=
         * "https://en.wikipedia.org/wiki/Transit_%28astronomy%29">transiting</a> the <a
         * href="https://en.wikipedia.org/wiki/Meridian_%28astronomy%29">celestial meridian</a>. The calculations used by this class
         * depend on the {@link AstronomicalCalculator} used. If this calendar instance is {@link setAstronomicalCalculator(
         * AstronomicalCalculator) set} to use the {@link com.kosherjava.zmanim.util.NOAACalculator} (the default) it will calculate
         * astronomical noon. If the calendar instance is  to use the {@link com.kosherjava.zmanim.util.SunTimesCalculator}, that does
         * not have code to calculate astronomical noon, the sun transit is calculated as halfway between sea level sunrise and sea level
         * sunset, which can be slightly off the real transit time due to changes in declination (the lengthening or shortening day). See
         * <a href="https://kosherjava.com/2020/07/02/definition-of-chatzos/">The Definition of Chatzos</a> for details on the proper
         * definition of solar noon / midday.
         * 
         * @return the <code>Instant</code> representing Sun's transit. If the calculation can't be computed such as when using the {@link
         *         com.kosherjava.zmanim.util.SunTimesCalculator USNO calculator} that does not support getting solar noon for 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>null</code> will be returned. See detailed explanation on top of the page.
         * @see getSunTransit(Instant, Instant)
         * @see getTemporalHour()
         * @see com.kosherjava.zmanim.util.NOAACalculator#getUTCNoon(Calendar, GeoLocation)
         * @see com.kosherjava.zmanim.util.SunTimesCalculator#getUTCNoon(Calendar, GeoLocation)
         */
        public Instant getSunTransit() {
                double noon = getAstronomicalCalculator().getUTCNoon(getAdjustedLocalDate(), getGeoLocation());
                return getInstantFromTime(noon, SolarEvent.NOON);
        }
        
        /**
         * A method that returns solar midnight as the <b>end of the day</b> (that may actually be after midnight of the  day it is
         * being calculated for). For example calculating solar midnight for February 8, will calculate it for midnight between February
         * 8 and February 9. It occurs when the Sun is <a href="https://en.wikipedia.org/wiki/Transit_%28astronomy%29">transiting</a> the
         * lower <a href="https://en.wikipedia.org/wiki/Meridian_%28astronomy%29">celestial meridian</a>, or when the sun is at it's
         * <a href="https://en.wikipedia.org/wiki/Nadir">nadir</a>. The calculations used by this class depend on the {@link
         * AstronomicalCalculator} used. If this calendar instance is {@link setAstronomicalCalculator(AstronomicalCalculator) set} to use
         * the {@link com.kosherjava.zmanim.util.NOAACalculator} (the default) it will calculate astronomical midnight. If the calendar
         * instance is to use the {@link com.kosherjava.zmanim.util.SunTimesCalculator USNO Calculator}, that does not have code to
         * calculate astronomical noon, midnight is calculated as 12 hours after halfway between sea level sunrise and sea level sunset
         * of that day. This can be slightly off the real transit time due to changes in declination (the lengthening or shortening day).
         * See <a href="https://kosherjava.com/2020/07/02/definition-of-chatzos/">The Definition of Chatzos</a> for details on the proper
         * definition of solar noon / midday.
         * 
         * @return the <code>Instant</code> representing Sun's lower transit at the <b>end of the current day</b>. If the calculation
         *         can't be computed such as when using the {@link com.kosherjava.zmanim.util.SunTimesCalculator USNO calculator} that does
         *         not support getting solar noon or midnight for 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>null</code> will be returned. This is not relevant when using the
         *         {@link com.kosherjava.zmanim.util.NOAACalculator NOAA Calculator} that is never expected to return <code>null</code>.
         *         See the detailed explanation on top of the page.
         * 
         * @see getSunTransit()
         * @see com.kosherjava.zmanim.util.NOAACalculator#getUTCNoon(Calendar, GeoLocation)
         * @see com.kosherjava.zmanim.util.SunTimesCalculator#getUTCNoon(Calendar, GeoLocation)
         */
        public Instant getSolarMidnight() {
                double noon = getAstronomicalCalculator().getUTCMidnight(getAdjustedLocalDate(), getGeoLocation());
                return getInstantFromTime(noon, SolarEvent.MIDNIGHT);
        }

        /**
         * A method that returns sundial or solar noon (or midnight) calculated as halfway between the times passed in. It is close to,
         * but not exactly  occurs when the Sun is <a href="https://en.wikipedia.org/wiki/Transit_%28astronomy%29">transiting</a> the
         * <a href="https://en.wikipedia.org/wiki/Meridian_%28astronomy%29">celestial meridian</a>. It will not exactly match the
         * astronomical transit, due to changes in declination (the lengthening or shortening day).
         * 
         * @param startOfDay
         *            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.
         * @param endOfDay
         *            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.
         * 
         * @return the <code>Instant</code> 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, <code>null</code> will be returned. See detailed explanation on top of the page.
         */
        public Instant getSunTransit(Instant startOfDay, Instant endOfDay) {
                long temporalHour = getTemporalHour(startOfDay, endOfDay);
                if (temporalHour == Long.MIN_VALUE) {
                        return null;
                }
                return getTimeOffset(startOfDay, temporalHour * 6);
        }

        /**
         * An enum to indicate what type of solar event is being calculated.
         */
        protected enum SolarEvent {
                /**SUNRISE A solar event related to sunrise*/SUNRISE, /**SUNSET A solar event related to sunset*/SUNSET,
                /**NOON A solar event related to noon*/NOON, /**MIDNIGHT A solar event related to midnight*/MIDNIGHT,
                /**NONE solar event representing azimuth or elevation calculations that that can be any time of the day*/ NONE;
        }
        
        /**
         * Return the time at a given azimuth. This often will not occur and a null will be returned.
         * @param azimuth the azimuth that you want to get the time of day for.
         * @return the time that the azimuth will be reached. There are cases where this azimuth will never be reached for the date
         *            and location, and a null will be returned in that case.
         * @see com.kosherjava.zmanim.util.AstronomicalCalculator#getTimeAtAzimuth(LocalDate, GeoLocation, double)
         */
        public Instant getTimeAtAzimuth(double azimuth) {
                double rawAzimuth = getAstronomicalCalculator().getTimeAtAzimuth(getAdjustedLocalDate(), getGeoLocation(), azimuth);
                return getInstantFromTime(rawAzimuth, SolarEvent.NONE);
        }
        
        /**
         * A method that returns an <code>Instant</code> from the time passed in as a parameter.
         * 
         * @param time
         *            The time to be set as the time for the <code>Instant</code>. The time expected is in the format: 18.75
         *            for 6:45:00 PM.time is sunrise and false if it is sunset
         * @param solarEvent the type of {@link SolarEvent}
         * @return The Instant object representation of the time double
         */
        protected Instant getInstantFromTime(double time, SolarEvent solarEvent) {
            if (Double.isNaN(time)) {
                return null;
            }

        LocalDate date = getAdjustedLocalDate();

            double localTimeHours = (getGeoLocation().getLongitude() / 15) + time;

            if (solarEvent == SolarEvent.SUNRISE && localTimeHours > 18) {
                date = date.minusDays(1);
            } else if (solarEvent == SolarEvent.SUNSET && localTimeHours < 6) {
                date = date.plusDays(1);
            } else if (solarEvent == SolarEvent.MIDNIGHT && localTimeHours < 12) {
                date = date.plusDays(1);
            } else if (solarEvent == SolarEvent.NOON) {
                if (localTimeHours < 0) {
                    date = date.plusDays(1);
                } else if (localTimeHours > 24) {
                    date = date.minusDays(1);
                }
            }
            
        // Math.round(time * HOUR_MILLIS) * 1_000_000L could be used below, but this exactly matches the pre-3.0 Date-based code.
        LocalDateTime dateTime = date.atStartOfDay().plusNanos((long)(time * HOUR_MILLIS) * 1_000_000L);  

            // The computed time is in UTC fractional hours; anchor in UTC before converting.
            return ZonedDateTime.of(dateTime, ZoneOffset.UTC).toInstant();
        }

        /**
         * Returns the sun's elevation (number of degrees) below the horizon before sunrise that matches the offset minutes
         * on passed in as a parameter. For example passing in 72 minutes for a calendar set to the equinox in Jerusalem
         * returns a value close to 16.1&deg;.
         * 
         * @param minutes
         *            minutes before sunrise
         * @return the degrees below the horizon before sunrise that match the offset in minutes passed it as a parameter. If
         *            the calculation can't be computed (no sunrise occurs on this day) a {@link Double#NaN} will be returned.
         * @deprecated This method is slow and inefficient and should NEVER be used in a loop. This method should be replaced
         *            by calls to {@link AstronomicalCalculator#getSolarElevation(Calendar, GeoLocation)}. That method will
         *            efficiently return the the solar elevation (the sun's position in degrees below (or above) the horizon)
         *            at the given time even in the arctic when there is no sunrise.
         * @see AstronomicalCalculator#getSolarElevation(Calendar, GeoLocation)
         * @see getSunsetSolarDipFromOffset(double)
         */
        @Deprecated(forRemoval=false)
        public double getSunriseSolarDipFromOffset(double minutes) {
                Instant offsetByDegrees = getSeaLevelSunrise();
                if(offsetByDegrees == null) {
                        return Double.NaN;
                }
                Instant offsetByTime = getTimeOffset(getSeaLevelSunrise(), -(minutes * MINUTE_MILLIS));

                BigDecimal degrees = new BigDecimal(0);
                BigDecimal incrementor = new BigDecimal("0.0001");

                while (offsetByDegrees == null || ((minutes < 0.0 && offsetByDegrees.toEpochMilli() < offsetByTime.toEpochMilli()) ||
                                (minutes > 0.0 && offsetByDegrees.toEpochMilli() > offsetByTime.toEpochMilli()))) {
                        if (minutes > 0.0) {
                                degrees = degrees.add(incrementor);
                        } else {
                                degrees = degrees.subtract(incrementor);
                        }
                        offsetByDegrees = getSunriseOffsetByDegrees(GEOMETRIC_ZENITH + degrees.doubleValue());
                }
                return degrees.doubleValue();
        }

        /**
         * Returns the sun's elevation (number of degrees) below the horizon after sunset that matches the offset minutes
         * passed in as a parameter. For example passing in 72 minutes for a calendar set to the equinox in Jerusalem
         * returns a value close to 16.1&deg;.
         * 
         * @param minutes
         *            minutes after sunset
         * @return the degrees below the horizon after sunset that match the offset in minutes passed it as a parameter. If
         *            the calculation can't be computed (no sunset occurs on this day) a {@link Double#NaN} will be returned.
         * @deprecated This method is slow and inefficient and should NEVER be used in a loop. This method should be replaced
         *            by calls to {@link AstronomicalCalculator#getSolarElevation(ZonedDateTime, GeoLocation)}. That method will
         *            efficiently return the the solar elevation (the sun's position in degrees below (or above) the horizon)
         *            at the given time even in the arctic when there is no sunrise.
         * @see AstronomicalCalculator#getSolarElevation(ZonedDateTime, GeoLocation)
         * @see getSunriseSolarDipFromOffset(double)
         */
        @Deprecated(forRemoval=false)
        public double getSunsetSolarDipFromOffset(double minutes) {
                Instant offsetByDegrees = getSeaLevelSunset();
                if(offsetByDegrees == null) {
                        return Double.NaN;
                }
                Instant offsetByTime = getTimeOffset(getSeaLevelSunset(), minutes * MINUTE_MILLIS);
                BigDecimal degrees = new BigDecimal(0);
                BigDecimal incrementor = new BigDecimal("0.001");
                while (offsetByDegrees == null || ((minutes > 0.0 && offsetByDegrees.toEpochMilli() < offsetByTime.toEpochMilli()) ||
                                (minutes < 0.0 && offsetByDegrees.toEpochMilli() > offsetByTime.toEpochMilli()))) {
                        if (minutes > 0.0) {
                                degrees = degrees.add(incrementor);
                        } else {
                                degrees = degrees.subtract(incrementor);
                        }
                        offsetByDegrees = getSunsetOffsetByDegrees(GEOMETRIC_ZENITH + degrees.doubleValue());
                }
                return degrees.doubleValue();
        }
        
        /**
         * A method that returns <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean time (LMT)</a> time converted to
         * regular clock time for the local wall-clock time passed to this method. This time is adjusted from standard time to account for
         * the local latitude. The 360&deg; of the globe divided by 24 calculates to 15&deg; per hour with 4 minutes per degree, so at a
         * longitude of 0 , 15, 30 etc... noon is at exactly 12:00pm. Lakewood, N.J., with a longitude of -74.222, is 0.7906 away from the
         * closest multiple of 15 at -75&deg;. This is multiplied by 4 clock minutes (per degree) to yield 3 minutes and 7 seconds for a
         * noon time of 11:56:53am. This method is not tied to the theoretical 15&deg; time zones, but will adjust to the actual time zone
         * and <a href="https://en.wikipedia.org/wiki/Daylight_saving_time">Daylight saving time</a> to return LMT.
         * 
         * @param localTime
         *                      the local wall-clock time (such as 12:00 for noon and 00:00 for midnight) to calculate as LMT.
         * @return the <code>Instant</code> representing the local mean time (LMT) for the time passed in. In Lakewood,
         *         NJ, passing noon will return 11:56:50am.
         * @see GeoLocation#getLocalMeanTimeOffset(Instant)
         */
        public Instant getLocalMeanTime(LocalTime localTime) {
                Instant localMeanTime = LocalDateTime.of(getAdjustedLocalDate(), localTime).toInstant(ZoneOffset.UTC);
            long longitudeOffsetMillis = (long) (getGeoLocation().getLongitude() * 4 * MINUTE_MILLIS);
            return getTimeOffset(localMeanTime, -longitudeOffsetMillis);
        }

        /**
         * Adjusts the <code>LocalDate</code> to deal with edge cases where the location crosses the antimeridian.
         * 
         * @see GeoLocation#getAntimeridianAdjustment(Instant)
         * @return the adjusted Calendar
         */
        protected LocalDate getAdjustedLocalDate(){
        int offset = getGeoLocation().getAntimeridianAdjustment(getMidnightLastNight().toInstant());
        return offset == 0 ? getLocalDate() : getLocalDate().plusDays(offset);
        }
    
    /**
     * Used by Molad based <em>zmanim</em> to determine if <em>zmanim</em> occur during the current day. This is also used as the
     * anchor for current timezone-offset calculations.
     * @return midnight at the start of the current local date in the configured timezone
     */
    protected ZonedDateTime getMidnightLastNight() {
        return ZonedDateTime.of(getLocalDate(),LocalTime.MIDNIGHT,getGeoLocation().getZoneId());
    }

    /**
     * Used by Molad based <em>zmanim</em> to determine if <em>zmanim</em> occur during the current day.
     * @return following midnight
     */
    protected ZonedDateTime getMidnightTonight() {
        return ZonedDateTime.of(getLocalDate().plusDays(1),LocalTime.MIDNIGHT,getGeoLocation().getZoneId());
    }

        /**
         * Returns an XML formatted representation of the class using the default output of the
         *         {@link com.kosherjava.zmanim.util.ZmanimFormatter#toXML(AstronomicalCalendar) toXML} method.
         * @return an XML formatted representation of the class. It returns the default output of the
         *         {@link com.kosherjava.zmanim.util.ZmanimFormatter#toXML(AstronomicalCalendar) toXML} method.
         * @see com.kosherjava.zmanim.util.ZmanimFormatter#toXML(AstronomicalCalendar)
         * @see java.lang.Object#toString()
         */
        public String toString() {
                return ZmanimFormatter.toXML(this);
        }
        
        /**
         * Returns a JSON formatted representation of the class using the default output of the
         *         {@link com.kosherjava.zmanim.util.ZmanimFormatter#toJSON(AstronomicalCalendar) toJSON} method.
         * @return a JSON formatted representation of the class. It returns the default output of the
         *         {@link com.kosherjava.zmanim.util.ZmanimFormatter#toJSON(AstronomicalCalendar) toJSON} method.
         * @see com.kosherjava.zmanim.util.ZmanimFormatter#toJSON(AstronomicalCalendar)
         * @see java.lang.Object#toString()
         */
        public String toJSON() {
                return ZmanimFormatter.toJSON(this);
        }

        /**
         * @see java.lang.Object#equals(Object)
         */
        public boolean equals(Object object) {
                if (this == object) {
                        return true;
                }
                if (object == null || getClass() != object.getClass()) {
                        return false;
                }
                AstronomicalCalendar aCal = (AstronomicalCalendar) object;
                return Objects.equals(getLocalDate(), aCal.getLocalDate())
                                && Objects.equals(getGeoLocation(), aCal.getGeoLocation())
                                && Objects.equals(getAstronomicalCalculator(), aCal.getAstronomicalCalculator());
        }

        /**
         * @see java.lang.Object#hashCode()
         */
        public int hashCode() {
                int result = 17;
                result = 37 * result + getClass().hashCode(); // needed or this and subclasses will return identical hash
                result += 37 * result + Objects.hashCode(getLocalDate());
                result += 37 * result + Objects.hashCode(getGeoLocation());
                result += 37 * result + Objects.hashCode(getAstronomicalCalculator());
                return result;
        }

        /**
         * A method that returns the currently set {@link GeoLocation} which contains location information used for the
         * astronomical calculations.
         * 
         * @return Returns the geoLocation.
         */
        public GeoLocation getGeoLocation() {
                return this.geoLocation;
        }

        /**
         * Sets the {@link GeoLocation} <code>Object</code> to be used for astronomical calculations.
         * 
         * @param geoLocation
         *            The geoLocation to set.
         * @todo Possibly adjust for horizon elevation. It may be smart to just have the calculator check the GeoLocation
         *       though it doesn't really belong there.
         */
        public void setGeoLocation(GeoLocation geoLocation) {
                this.geoLocation = geoLocation;
        }

        /**
         * A method that returns the currently set AstronomicalCalculator.
         * 
         * @return Returns the astronomicalCalculator.
         * @see setAstronomicalCalculator(AstronomicalCalculator)
         */
        public AstronomicalCalculator getAstronomicalCalculator() {
                return this.astronomicalCalculator;
        }

        /**
         * A method to set the {@link AstronomicalCalculator} used for astronomical calculations. The Zmanim package ships
         * with a number of different implementations of the <code>abstract</code> {@link AstronomicalCalculator} based on
         * different algorithms, including the default {@link com.kosherjava.zmanim.util.NOAACalculator} based on <a href=
         * "https://noaa.gov">NOAA's</a> implementation of Jean Meeus's algorithms as well as {@link
         * com.kosherjava.zmanim.util.SunTimesCalculator} based on the <a href = "https://www.cnmoc.usff.navy.mil/usno/">US
         * Naval Observatory's</a> algorithm. This allows easy runtime switching and comparison of different algorithms.
         * 
         * @param astronomicalCalculator
         *            The astronomicalCalculator to set.
         */
        public void setAstronomicalCalculator(AstronomicalCalculator astronomicalCalculator) {
                this.astronomicalCalculator = astronomicalCalculator;
        }
        
        /**
         * returns the <code>LocalDate</code> object encapsulated in this class.
         * 
         * @return Returns the <code>LocalDate</code>.
         */
        public LocalDate getLocalDate() {
                return this.localDate;
        }
        
        /**
         * Sets the <code>LocalDate</code>  object for us in this class.
         * @param localDate
         *            The <code>LocalDate</code> to set.
         */
        public void setLocalDate(LocalDate localDate) {
                this.localDate = localDate;
        }

        /**
         * A method that creates a <a href="https://en.wikipedia.org/wiki/Object_copy#Deep_copy">deep copy</a> of the object.
         * 
         * @see java.lang.Object#clone()
         */
        public Object clone() {
                AstronomicalCalendar clone = null;
                try {
                        clone = (AstronomicalCalendar) super.clone();
                } catch (CloneNotSupportedException cnse) {
                        // Required by the compiler. Should never be reached since we implement clone()
                }
        if (clone != null) {
                        clone.setGeoLocation((GeoLocation) getGeoLocation().clone()); // consider converting the GeoLocation class to be immutable to avoid the deep copy
                        clone.setAstronomicalCalculator((AstronomicalCalculator) getAstronomicalCalculator().clone()); // likely not needed
                }
                return clone;
        }
}