/*
 * 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 #getSunriseWithElevation() sunrise}, {@link #getSunsetWithElevation()
 * 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 with
 * the {@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
         * 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 getSunriseWithElevation 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
         * @see #getSeaLevelSunrise()
         * @see AstronomicalCalendar#getUTCSunrise
         */
        public Instant getSunriseWithElevation() {
                double sunrise = getUTCSunrise(GEOMETRIC_ZENITH);
                if (Double.isNaN(sunrise)) {
                        return null;
                } else {
                        return getInstantFromTime(sunrise, SolarEvent.SUNRISE);
                }
        }
    /**
     * @deprecated Use {@link #getSunriseWithElevation()} instead.
     * This method already accounts for the observer's elevation, but the name
     * does not clearly indicate this behavior. The replacement method has a
     * clearer and more descriptive name.
     *
     * @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
     * @see #getSeaLevelSunrise()
     * @see AstronomicalCalendar#getUTCSunrise
     */
    @Deprecated(forRemoval = false)
    public Instant getSunrise() {
        return getSunriseWithElevation();
    }

        /**
         * 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 AstronomicalCalendar#getSunriseWithElevation
         * @see AstronomicalCalendar#getUTCSeaLevelSunrise
         * @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.
         * @see #CIVIL_ZENITH
         */
        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.
         * @see #NAUTICAL_ZENITH
         */
        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.
         * @see #ASTRONOMICAL_ZENITH
         */
        public Instant getBeginAstronomicalTwilight() {
                return getSunriseOffsetByDegrees(ASTRONOMICAL_ZENITH);
        }

    /**
     * The getSunsetWithElevation 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 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 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.
     *
     * @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
     * @see #getSeaLevelSunset()
     * @see AstronomicalCalendar#getUTCSunset
     */
    public Instant getSunsetWithElevation() {
        double sunset = getUTCSunset(GEOMETRIC_ZENITH);
        if (Double.isNaN(sunset)) {
            return null;
        } else {
            return getInstantFromTime(sunset, SolarEvent.SUNSET);
        }
    }

        /**
     * @deprecated Use {@link #getSunsetWithElevation()} instead.
     * This method already accounts for the observer's elevation, but its name
     * does not clearly reflect that behavior. The replacement method provides
     * a more accurate and descriptive name.
     *
         * @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
         * @see #getSeaLevelSunset()
         * @see AstronomicalCalendar#getUTCSunset
         */
    @Deprecated(forRemoval = false)
        public Instant getSunset() {
                return getSunsetWithElevation();
        }

        /**
         * 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 AstronomicalCalendar#getSunsetWithElevation
         * @see AstronomicalCalendar#getUTCSeaLevelSunset
         * @see #getSunsetWithElevation()
         */
        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.
         * @see #CIVIL_ZENITH
         */
        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.
         * @see #NAUTICAL_ZENITH
         */
        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.
         * @see #ASTRONOMICAL_ZENITH
         */
        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 #getSunriseWithElevation() 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 #getSunriseWithElevation()} 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 #getSunriseWithElevation()}. 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 #getSunsetWithElevation()
         * 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 #getSunsetWithElevation()} 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 #getSunsetWithElevation()}. 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 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 LocalDate 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 AstronomicalCalendar#getUTCSunrise
         * @see AstronomicalCalendar#getUTCSeaLevelSunset
         */
        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 AstronomicalCalendar#getUTCSeaLevelSunset
         */
        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 AstronomicalCalendar#getUTCSunset
         * @see AstronomicalCalendar#getUTCSeaLevelSunrise
         */
        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 #getSunriseWithElevation() sunrise} and
         * {@link #getSunsetWithElevation() 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) { //FIXME new code
            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); //FIXME NEW CODE
        }
        
        /**
         * A method that returns solar midnight at the end of the current day (that may actually be after midnight of the day it
         * is being calculated for). 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 end of the current day. 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. 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>. 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).
         * 
         * @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
        }
        
        /**
         * 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 civilTime = ZonedDateTime.of(getLocalDate(), localTime, getGeoLocation().getZoneId()).toInstant();
            return getTimeOffset(civilTime, -getGeoLocation().getLocalMeanTimeOffset(civilTime));
        }

        /**
         * Adjusts the <code>LocalDate</code> to deal with edge cases where the location crosses the antimeridian.
         * 
         * @see GeoLocation#getAntimeridianAdjustment(Instant)
         * @return the adjusted Calendar
         */
        private 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.
         * <b>Note:</b> If the {@link java.util.TimeZone} in the cloned {@link com.kosherjava.zmanim.util.GeoLocation} will
         * be changed from the original, it is critical that
         * {@link com.kosherjava.zmanim.AstronomicalCalendar#getLocalDate()}.
         * 
         * @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());
                        clone.setAstronomicalCalculator((AstronomicalCalculator) getAstronomicalCalculator().clone());
                }
                return clone;
        }
}