/*
 * Zmanim Java API
 * Copyright © 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.
 *
 * 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.time.Duration;
import java.time.Instant;
import java.time.LocalDate;
import java.util.Objects;

import com.kosherjava.zmanim.hebrewcalendar.JewishCalendar;
import com.kosherjava.zmanim.util.AstronomicalCalculator;
import com.kosherjava.zmanim.util.GeoLocation;

/**
 * The ZmanimCalendar is a specialized calendar that can calculate sunrise, sunset and Jewish <em>zmanim</em> (religious times)
 * for prayers and other Jewish religious duties. This class contains the main functionality of the <em>Zmanim</em> library. For
 * a much more extensive list of <em>zmanim</em>, use the {@link ComprehensiveZmanimCalendar} that extends this class. See
 * documentation for the {@link ComprehensiveZmanimCalendar} and {@link AstronomicalCalendar} for simple examples on using the API. 
 * <strong>Elevation based <em>zmanim</em> (even sunrise and sunset) should not be used <em>lekula</em> without the guidance
 * of a <em>posek</em></strong>. According to Rabbi Dovid Yehudah Bursztyn in his <a href="https://www.worldcat.org/oclc/1158574217"
 * >Zmanim Kehilchasam, 7th edition</a> chapter 2, section 7 (pages 181-182) and section 9 (pages 186-187), no <em>zmanim</em>
 * besides sunrise and sunset should use elevation. However, Rabbi Yechiel Avrahom Zilber in the <a href=
 * "https://hebrewbooks.org/51654">Birur Halacha Vol. 6</a> Ch. 58 Pages <a href=
 * "https://hebrewbooks.org/pdfpager.aspx?req=51654&amp;pgnum=42">34</a> and <a href=
 * "https://hebrewbooks.org/pdfpager.aspx?req=51654&amp;pgnum=50">42</a> is of the opinion that elevation should be accounted for
 * in <em>zmanim</em> calculations. Related to this, Rabbi Yaakov Karp in <a href="https://www.worldcat.org/oclc/919472094"
 * >Shimush Zekeinim</a>, Ch. 1, page 17 states that obstructing horizons should be factored into <em>zmanim</em> calculations. The
 * setting defaults to false (elevation will not be used for <em>zmanim</em> calculations besides sunrise and sunset), unless the
 * setting is changed to true in {@link #setUseElevation(boolean)}. This will impact sunrise and sunset-based <em>zmanim</em> such as
 * {@link #getSunrise()}, {@link #getSunset()}, {@link #getSofZmanShmaGRA()}, <em>alos</em>-based
 * <em>zmanim</em> such as {@link #getSofZmanShmaMGA72Minutes()} that are based on a fixed offset of sunrise or sunset and
 * <em>zmanim</em> based on a percentage of the day such as {@link ComprehensiveZmanimCalendar#getSofZmanShmaMGA90MinutesZmanis()}
 * that are based on sunrise and sunset. Even when set to true it will not impact <em>zmanim</em> that are a degree-based offset of
 * sunrise and sunset, such as {@link ComprehensiveZmanimCalendar#getSofZmanShmaMGA16Point1Degrees()} or {@link
 * ComprehensiveZmanimCalendar#getSofZmanShmaBaalHatanya()} since these <em>zmanim</em> are not linked to sunrise or sunset times
 * (the calculations are based on the astronomical definition of sunrise and sunset calculated in a vacuum with the solar radius
 * above the horizon), and are therefore not impacted by the use of elevation. For additional information on the <em>halachic</em>
 * impact of elevation on <em>zmanim</em> see:
 * <ul>
 * <li><a href="https://www.nli.org.il/en/books/NNL_ALEPH002542826/NLI">Zmanei Halacha Lema'aseh</a> 4th edition by <a href=
 * "http://beinenu.com/rabbis/%D7%94%D7%A8%D7%91-%D7%99%D7%93%D7%99%D7%93%D7%99%D7%94-%D7%9E%D7%A0%D7%AA">Rabbi Yedidya Manat</a>.
 * See section 1, pages 11-12 for a very concise write-up, with details in section 2, pages 37 - 63 and 133 - 151.</li>
 * <li><a href="https://www.worldcat.org/oclc/1158574217">Zmanim Kehilchasam</a> 7th edition, by Rabbi Dovid Yehuda Burstein,  vol 1,
 * chapter 2, pages 95 - 188.</li>
 * <li><a href="https://www.worldcat.org/oclc/36089452">Hazmanim Bahalacha</a> by Rabbi Chaim Benish , perek 7, pages 53 - 63.</li>
 * </ul>
 * 
 * <p><b>Note:</b> It is important to read the technical notes on top of the {@link AstronomicalCalculator} documentation
 * before using this code.
 * <p>I would like to thank <a href="https://www.worldcat.org/search?q=au%3AShakow%2C+Yaakov">Rabbi Yaakov Shakow</a>, the
 * author of Luach Ikvei Hayom who spent a considerable amount of time reviewing, correcting and making suggestions on the
 * documentation in this library.
 * <h2>Disclaimer:</h2> I did my best to get accurate results, but please double-check before relying on these
 * <em>zmanim</em> for <em>halacha lema'aseh</em>.
 * 
 * @author © Eliyahu Hershfeld 2004 - 2026
 */
public class ZmanimCalendar extends AstronomicalCalendar {
        
        /**
         * Is elevation factored in for some <em>zmanim</em> (see {@link #isUseElevation()} for additional information).
         * @see #isUseElevation()
         * @see #setUseElevation(boolean)
         */
        private boolean useElevation;

        /**
         * Is elevation above sea level calculated for times besides sunrise and sunset. According to Rabbi Dovid Yehuda Bursztyn in
         * his <a href="https://www.worldcat.org/oclc/659793988">Zmanim Kehilchasam (second edition published in 2007)</a> chapter 2
         * (pages 186-187) no <em>zmanim</em> besides sunrise and sunset should use elevation. However, Rabbi Yechiel Avrahom Zilber
         * in the <a href="https://hebrewbooks.org/51654">Birur Halacha Vol. 6</a> Ch. 58 Pages <a href=
         * "https://hebrewbooks.org/pdfpager.aspx?req=51654&amp;pgnum=42">34</a> and <a href=
         * "https://hebrewbooks.org/pdfpager.aspx?req=51654&amp;pgnum=50">42</a> is of the opinion that elevation should be accounted
         * for in <em>zmanim</em> calculations. Related to this, Rabbi Yaakov Karp in <a href=
         * "https://www.worldcat.org/oclc/919472094">Shimush Zekeinim</a>, Ch. 1, page 17 states that obstructing horizons should be
         * factored into <em>zmanim</em> calculations.The setting defaults to false (elevation will not be used for <em>zmanim</em>
         * calculations), unless the setting is changed to true in {@link #setUseElevation(boolean)}. This will impact sunrise and
         * sunset based <em>zmanim</em> such as  {@link #getSofZmanShmaGRA()}, alos based <em>zmanim</em> such as {@link
         * getSofZmanShmaMGA72Minutes()} that are based on a fixed offset of sunrise or sunset and <em>zmanim</em> based on a
         * percentage of the day such as {@link ComprehensiveZmanimCalendar#getSofZmanShmaMGA90MinutesZmanis()} that are based on
         * sunrise and sunset. It will not impact <em>zmanim</em> that are a degree based offset of sunrise and sunset, such as {@link
         * ComprehensiveZmanimCalendar#getSofZmanShmaMGA16Point1Degrees()} or {@link
         * ComprehensiveZmanimCalendar#getSofZmanShmaBaalHatanya()}.
         * 
         * @return if the use of elevation is active
         * 
         * @see #setUseElevation(boolean)
         */
        public boolean isUseElevation() {
                return useElevation;
        }

        /**
         * Sets whether elevation above sea level is factored into <em>zmanim</em> calculations for times besides sunrise and sunset.
         * See {@link #isUseElevation()} for more details. 
         * @see #isUseElevation()
         * 
         * @param useElevation set to true to use elevation in <em>zmanim</em> calculations
         */
        public void setUseElevation(boolean useElevation) {
                this.useElevation = useElevation;
        }
        
        /**
         * Is astronomical <em>chatzos</em> used for <em>zmanim</em> calculations. The default value of <code>true</code> will
         * keep the standard astronomical <em>chatzos</em> calculation, while setting it to <code>false</code> will use half of
         * a solar day / night calculation for <em>chatzos</em>.
         * @see #isUseAstronomicalChatzos()
         * @see #isUseAstronomicalChatzosForOtherZmanim()
         * @see #setUseAstronomicalChatzos(boolean)
         * @see #getChatzosHayom()
         * @see #getChatzosHalayla()
         * @see #getSunTransit()
         * @see #getChatzosHayomAsHalfDay()
         */
        private boolean useAstronomicalChatzos = true;
        
        /**
         * Is {@link #getSunTransit() astronomical <em>chatzos</em>} used for {@link #getChatzosHayom()} and {@link #getChatzosHalayla()}
         * for enhanced accuracy. For example as the day lengthens, the second half of the day is longer than the first and astronomical
         * <em>chatzos</em> would be a drop earlier than half of the time between sunrise and sunset.
         *  
         * @todo In the future, if this is set to true, the following may change to enhance accuracy. {@link #getSofZmanShmaGRA()
         * <em>Sof zman Shma</em> GRA} would be calculated as 3 <em>shaos zmaniyos</em> after sunrise, but the <em>shaos
         * zmaniyos</em> would be calculated a a 6th of the time between sunrise and <em>chatzos</em>, as opposed to a 12th of the
         * time between sunrise and sunset. {@link #getMinchaGedolaGRA() <em>mincha gedola</em>} will be calculated as half a
         * <em>shaah zmanis</em> of afternoon hours (a 6th of the time between <em>chatzos</em> and sunset after astronomical
         * <em>chatzos</em> as opposed to 6.5 <em>shaos zmaniyos</em> after sunrise. {@link #getPlagHaminchaGRA() <em>Plag
         * hamincha</em>} would be calculated as 4.75 <em>shaos zmaniyos</em> after astronomical <em>chatzos</em> as opposed to 10.75
         * <em>shaos zmaniyos</em> after sunrise. Etc.
         * 
         * @return if the use of astronomical <em>chatzos</em> is active.
         * @see #isUseAstronomicalChatzos()
         * @see #setUseAstronomicalChatzos(boolean)
         * @see #getChatzosHayom()
         * @see #getChatzosHalayla()
         * @see #getSunTransit()
         * @see #getChatzosHayomAsHalfDay()
         * @see #isUseAstronomicalChatzosForOtherZmanim()
         */
        public boolean isUseAstronomicalChatzos() {
                return useAstronomicalChatzos;
        }

        /**
         * Sets if astronomical <em>chatzos</em> should be used in calculations of other <em>zmanim</em> for enhanced accuracy.
         * @param useAstronomicalChatzos set to true to use astronomical in <em>chatzos</em> in <em>zmanim</em> calculations.
         * @see #isUseAstronomicalChatzos()
         * @see #getChatzosHayom()
         * @see #getChatzosHalayla()
         * @see #getSunTransit()
         * @see #getChatzosHayomAsHalfDay()
         * @see #setUseAstronomicalChatzosForOtherZmanim(boolean)
         */
        public void setUseAstronomicalChatzos(boolean useAstronomicalChatzos) {
                this.useAstronomicalChatzos = useAstronomicalChatzos;
        }
        
        /**
         * Is astronomical <em>chatzos</em> used for <em>zmanim</em> calculations besides <em>chatzos</em> itself for enhanced
         * accuracy. The default value of <code>false</code> will keep the standard start to end of day calculations, while setting
         * it to <code>true</code> will use half of a solar day calculation for <em>zmanim</em>.
         * @see #isUseAstronomicalChatzosForOtherZmanim()
         * @see #setUseAstronomicalChatzosForOtherZmanim(boolean)
         * @see #isUseAstronomicalChatzos()
         * @see #setUseAstronomicalChatzos(boolean)
         * @see #getChatzosHayom()
         * @see #getChatzosHalayla()
         */
        private boolean useAstronomicalChatzosForOtherZmanim = false;
        
        /**
         * Is astronomical <em>chatzos</em> used for <em>zmanim</em> calculations besides <em>chatzos</em> itself for enhanced
         * accuracy. For example as the day is lengthening (as we approach spring season), the second half of the day is longer than
         * the first and astronomical <em>chatzos</em> would be a drop earlier than half of the time between sunrise and sunset.
         * Conversely, the second half of the day would be shorter in the autumn as the days start getting shorter.
         * 
         * @todo In the future, if this is set to true, the following may change to enhance accuracy. {@link #getSofZmanShmaGRA()
         * <em>Sof zman Shma</em> GRA} would be calculated as 3 <em>shaos zmaniyos</em> after sunrise, but the <em>shaos
         * zmaniyos</em> would be calculated a a 6th of the time between sunrise and <em>chatzos</em>, as opposed to a 12th of the
         * time between sunrise and sunset. {@link #getMinchaGedolaGRA() <em>mincha gedola GRA</em>} will be calculated as half a
         * <em>shaah zmanis</em> of afternoon hours (a 6th of the time between <em>chatzos</em> and sunset after astronomical
         * <em>chatzos</em> as opposed to 6.5 <em>shaos zmaniyos</em> after sunrise. {@link #getPlagHaminchaGRA() <em>Plag
         * hamincha</em>} would be calculated as 4.75 <em>shaos zmaniyos</em> after astronomical <em>chatzos</em> as opposed to 10.75
         * <em>shaos zmaniyos</em> after sunrise. Etc.
         * 
         * @return if the use of astronomical <em>chatzos</em> is active.
         * @see #setUseAstronomicalChatzosForOtherZmanim(boolean)
         * @see #isUseAstronomicalChatzos()
         * @see #setUseAstronomicalChatzos(boolean)
         */
        public boolean isUseAstronomicalChatzosForOtherZmanim() {
                return useAstronomicalChatzosForOtherZmanim;
        }

        /**
         * Sets if astronomical <em>chatzos</em> should be used in calculations of other <em>zmanim</em> for enhanced accuracy.
         * @param useAstronomicalChatzosForOtherZmanim set to true to use astronomical in <em>chatzos</em> in <em>zmanim</em> calculations.
         * @see #isUseAstronomicalChatzos()
         */
        public void setUseAstronomicalChatzosForOtherZmanim(boolean useAstronomicalChatzosForOtherZmanim) {
                this.useAstronomicalChatzosForOtherZmanim = useAstronomicalChatzosForOtherZmanim;
        }

        /**
         * The zenith of 16.1° below geometric zenith (90°).
         * @see #getAlos16Point1Degrees()
         * @see ComprehensiveZmanimCalendar#getTzais16Point1Degrees()
         * @see ComprehensiveZmanimCalendar#getSofZmanShmaMGA16Point1Degrees()
         * @see ComprehensiveZmanimCalendar#getSofZmanTfilaMGA16Point1Degrees()
         * @see ComprehensiveZmanimCalendar#getMinchaGedola16Point1Degrees()
         * @see ComprehensiveZmanimCalendar#getMinchaKetana16Point1Degrees()
         * @see ComprehensiveZmanimCalendar#getPlagHamincha16Point1Degrees()
         * 
         * @see ComprehensiveZmanimCalendar#getSofZmanShmaAlos16Point1DegreesToTzaisGeonim7Point083Degrees()
         * @see ComprehensiveZmanimCalendar#getPlagAlos16Point1DegreesToTzaisGeonim7Point083Degrees()
         * @see ComprehensiveZmanimCalendar#getSofZmanShmaAlos16Point1ToSunset()
         * @see ComprehensiveZmanimCalendar#getShaahZmanis16Point1Degrees()
         * @see ComprehensiveZmanimCalendar#getShaahZmanisAlos16Point1DegreesToTzaisGeonim3Point7Degrees()
         * @see ComprehensiveZmanimCalendar#getShaahZmanisAlos16Point1DegreesToTzaisGeonim3Point8Degrees()
         * @see ComprehensiveZmanimCalendar#getShaahZmanisAlos16Point1DegreesToTzaisGeonim7Point083Degrees()
         * 
         */
        protected static final double ZENITH_16_POINT_1 = GEOMETRIC_ZENITH + 16.1;

        /**
         * The zenith of 8.5° below geometric zenith (90°).
         * @see #getTzaisGeonim8Point5Degrees()
         */
        protected static final double ZENITH_8_POINT_5 = GEOMETRIC_ZENITH + 8.5;
        
        /**
         * The zenith of 1.583° below {@link AstronomicalCalendar#GEOMETRIC_ZENITH} (90°).
         * @see #getSunriseBaalHatanya()
         * @see #getSunsetBaalHatanya()
         */
        protected static final double ZENITH_1_POINT_583 = GEOMETRIC_ZENITH + 1.583;

        /**
         * The default <em>Shabbos</em> candle lighting offset is 18 minutes. This can be changed via the
         * {@link #setCandleLightingOffset(double)} and retrieved by the {@link #getCandleLightingOffset()}.
         */
        private double candleLightingOffset = 18;
        
        /**
         * This method will return {@link #getSeaLevelSunrise() sea level sunrise} if {@link #isUseElevation()} is false (the default),
         * or elevation adjusted {@link #getSunrise()} if it is true. This allows relevant <em>zmanim</em> in this and
         * extending classes (such as the {@link ComprehensiveZmanimCalendar}) to automatically adjust to the elevation setting.
         * 
         * @return {@link #getSeaLevelSunrise()} if {@link #isUseElevation()} is false (the default), or elevation adjusted
         *         {@link #getSunrise()} if it is true.
         * @see #getSunrise()
         */
        protected Instant getSunriseBasedOnElevationSetting() {
                if (isUseElevation()) {
                        return super.getSunrise();
                }
                return getSeaLevelSunrise();
        }
        
        /**
         * This method will return {@link #getSeaLevelSunset() sea level sunset} if {@link #isUseElevation()} is false (the default), or
         * elevation adjusted {@link #getSunset()} if it is true. This allows relevant <em>zmanim</em>in this and extending classes (such
         * as the {@link ComprehensiveZmanimCalendar}) to automatically adjust to the elevation setting.
         * 
         * @return {@link #getSeaLevelSunset()} if {@link #isUseElevation()} is false (the default), or elevation adjusted
         *         {@link #getSunset()} if it is true.
         * @see #getSunset()
         */
        protected Instant getSunsetBasedOnElevationSetting() {
                if (isUseElevation()) {
                        return super.getSunset();
                }
                return getSeaLevelSunset();
        }

        /**
         * A method that returns <em>tzais</em> (nightfall) when the sun is {@link ZENITH_8_POINT_5 8.5°} below the {@link
         * AstronomicalCalendar#GEOMETRIC_ZENITH} (90°) after {@link #getSunset() sunset}, a time that Rabbi Meir Posen in his the <em><a
         * href="https://www.worldcat.org/oclc/29283612">Ohr Meir</a></em> calculated that 3 small stars are visible, which is later than
         * the required 3 medium stars. This calculation is based on the sun's position below the horizon 36 minutes after {@link
         * getSeaLevelSunrise() sunset} in Jerusalem <a href="https://kosherjava.com/2022/01/12/equinox-vs-equilux-zmanim-calculations/"
         * >around the equinox / equilux</a>, which is 8.5° below {@link AstronomicalCalendar#GEOMETRIC_ZENITH}.
         * 
         * @return The <code>Instant</code> of nightfall. If the calculation can't be computed such as northern and southern locations
         *         even south of the Arctic Circle and north of the Antarctic Circle where the sun may not reach low enough below the
         *         horizon for this calculation, a <code>null</code> will be returned. See detailed explanation on top of the {@link
         *         AstronomicalCalendar} documentation.
         * ComprehensiveZmanimCalendar#getTzaisGeonim8Point5Degrees() that returns an identical time to this generic <em>tzais</em>
         */
        public Instant getTzaisGeonim8Point5Degrees() {
                return getSunsetOffsetByDegrees(ZENITH_8_POINT_5);
        }

        /**
         * Returns <em>alos</em> (dawn) based on the time when the sun is {@link ZENITH_16_POINT_1 16.1°} below the eastern {@link
         * AstronomicalCalendar#GEOMETRIC_ZENITH} before {@link #getSunrise() sunrise}. This is based on the calculation that the time
         * between dawn and sunrise (and sunset to nightfall) is 72 minutes, the time that is takes to walk 4 <a href=
         * "https://en.wikipedia.org/wiki/Biblical_mile">mil</a> at 18 minutes a mil (<a href="https://en.wikipedia.org/wiki/Maimonides"
         * >Rambam</a> and others). The sun's position below the horizon 72 minutes before {@link #getSunrise() sunrise} in Jerusalem on
         * the <a href="https://kosherjava.com/2022/01/12/equinox-vs-equilux-zmanim-calculations/">around the equinox / equilux</a> is
         * 16.1° below {@link AstronomicalCalendar#GEOMETRIC_ZENITH}.
         * 
         * @see ComprehensiveZmanimCalendar#getTzais16Point1Degrees()
         * 
         * @return The <code>Instant</code> of dawn. If the calculation can't be computed such as northern and southern
         *         locations even south of the Arctic Circle and north of the Antarctic Circle where the sun may not reach
         *         low enough below the horizon for this calculation, a <code>null</code> will be returned. See detailed
         *         explanation on top of the {@link AstronomicalCalendar} documentation.
         */
        public Instant getAlos16Point1Degrees() {
                return getSunriseOffsetByDegrees(ZENITH_16_POINT_1);
        }

        /**
         * Method to return <em>alos</em> (dawn) calculated as 72 minutes before {@link #getSunrise() sunrise} or {@link
         * #getSeaLevelSunrise() sea level sunrise} (depending on the {@link #isUseElevation()} setting). This time
         * is based on the time to walk the distance of 4 <a href="https://en.wikipedia.org/wiki/Biblical_mile">mil</a> at 18 minutes a mil. The
         * 72-minute time (but not the concept of fixed minutes) is based on the opinion that the time of the <em>Neshef</em>
         * (twilight between dawn and sunrise) does not vary by the time of year or location but depends on the time it takes
         * to walk the distance of 4 mil.
         * 
         * @return the <code>Instant</code> representing the 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 {@link AstronomicalCalendar}
         *         documentation.
         */
        public Instant getAlos72Minutes() {
                return getTimeOffset(getSunriseBasedOnElevationSetting(), Duration.ofMinutes(-72));
        }
        
        /**
         * This method returns {@link #getSunTransit() Astronomical <em>chatzos hayom</em>} if the
         * {@link com.kosherjava.zmanim.util.AstronomicalCalculator calculator} class used supports it and
         * {@link #isUseAstronomicalChatzos() isUseAstronomicalChatzos()} is set to <em>true</em> or the {@link #getChatzosHayomAsHalfDay()
         * halfway point between sunrise and sunset} if it does not support it, or it is not configured to use it. There are currently
         * two {@link com.kosherjava.zmanim.util.AstronomicalCalculator calculators} available in the API, the default {@link
         * com.kosherjava.zmanim.util.NOAACalculator NOAA calculator} and the {@link com.kosherjava.zmanim.util.SunTimesCalculator USNO
         * calculator}. The USNO calculator calculates <em>chatzos</em> as halfway between sunrise and sunset (identical to six <em>shaos
         * zmaniyos</em> after sunrise), while the NOAACalculator calculates it more accurately as {@link #getSunTransit() astronomical
         * <em>chatzos</em>}. See <a href="https://kosherjava.com/2020/07/02/definition-of-chatzos/">The Definition of <em>Chatzos</em></a>
         * for a detailed explanation of the ways to calculate <em>Chatzos</em>. Since half-day <em>chatzos</em> can be <code>null</code> in
         * the Arctic on a day when either sunrise or sunset did not happen and astronomical <em>chatzos</em> can be calculated even in the
         * Arctic, if half-day <em>chatzos</em> calculates as <code>null</code> and astronomical <em>chatzos</em> is supported by the
         * calculator, astronomical <em>chatzos</em> will be returned to avoid returning a <code>null</code>.
         * 
         * @see #getSunTransit()
         * @see #getChatzosHayomAsHalfDay()
         * @see #isUseAstronomicalChatzos()
         * @see #setUseAstronomicalChatzos(boolean)
         * @return the <code>Instant</code> of <em>chatzos</em>. If the calculation can't be computed such as in the Arctic Circle
         *         where there is at least one day where the sun does not rise, and one where it does not set, and the calculator does not
         *         support astronomical calculations (that will never report a <code>null</code>) a <code>null</code> will be returned.
         *         See detailed explanation on top of the {@link AstronomicalCalendar} documentation.
         */
        public Instant getChatzosHayom() {
                if (isUseAstronomicalChatzos()) {
                        return getSunTransit(); // can be null if the calculator does not support astronomical chatzos
                } else {
                        Instant halfDayChatzos = getChatzosHayomAsHalfDay();
                        if (halfDayChatzos == null) {
                                return getSunTransit(); // can be null if the calculator does not support astronomical chatzos
                        } else {
                                return halfDayChatzos;
                        }
                }
        }
        
        /**
         * A method that returns <em>chatzos halayla</em> at the <b>end of the day</b> (the last <em>zman</em> of the day
         * returned by the calendar, that may actually be after midnight of the day it is being calculated for). For example, if
         * calculating it for the date of <em>Erev Pesach</em>, the calculation will be for <em>Lail Pesach</em> to allow you to use the
         * <em>zman</em> as <em>sof zman achilas afikoman</em>. {@link #getSolarMidnight() Astronomical <em>chatzos halayla</em>} will be
         * returned if the {@link com.kosherjava.zmanim.util.AstronomicalCalculator calculator} class used supports it and {@link
         * isUseAstronomicalChatzos() isUseAstronomicalChatzos()} is set to <em>true</em>. Otherwise the {@link #getChatzos(Instant,
         * Instant) halfway point} between sunset and the following day's sunrise, if it does not support it, or it is not configured to
         * use it. There are currently two {@link com.kosherjava.zmanim.util.AstronomicalCalculator calculators} available in the API,
         * the default {@link com.kosherjava.zmanim.util.NOAACalculator NOAA calculator} and the {@link
         * com.kosherjava.zmanim.util.SunTimesCalculator USNO calculator}. The USNO calculator calculates <em>chatzos halayla</em> as
         * halfway between sunset and the following day's sunrise (identical to six <em>shaos zmaniyos</em> after sunset), while the
         * NOAACalculator calculates it more accurately as {@link #getSolarMidnight() astronomical <em>chatzos halayla</em>}. See <a href=
         * "https://kosherjava.com/2020/07/02/definition-of-chatzos/">The Definition of <em>Chatzos</em></a> for a detailed explanation
         * of the ways to calculate <em>Chatzos</em>. Since half-night <em>chatzos</em> can be <code>null</code> in the Arctic on a day
         * when either sunset or the following day's sunrise did not happen and astronomical <em>chatzos halayla</em> can be calculated
         * even in the Arctic, if half-day <em>chatzos</em> calculates as <code>null</code> and astronomical <em>chatzos</em> is
         * supported by the calculator, astronomical <em>chatzos</em> will be returned to avoid returning a <code>null</code>.
         * 
         * @see #getSolarMidnight()
         * @see #getChatzos(Instant, Instant)
         * @see #isUseAstronomicalChatzos()
         * @see #setUseAstronomicalChatzos(boolean)
         * @return the <code>Instant</code> of <em>chatzos halayla</em> at the <b>end of the current day</b>. If the calculation can't be
         *         computed such as in the Arctic Circle where there is at least one day where the sun does not rise, and one where it
         *         does not set, and the calculator does not support astronomical calculations (that will never report a
         *         <code>null</code>) a <code>null</code> will be returned. See detailed explanation on top of the
         *         {@link AstronomicalCalendar} documentation.
         */
        public Instant getChatzosHalayla() {
                if (isUseAstronomicalChatzos()) {
                        return getSolarMidnight(); // can be null if the calculator does not support astronomical chatzos
                } else {
                        ZmanimCalendar clonedCalendar = (ZmanimCalendar)this.clone();
                        clonedCalendar.setLocalDate(getLocalDate().plusDays(1));
                        Instant halfNightChatzos = getChatzos(getSeaLevelSunset(), clonedCalendar.getSeaLevelSunrise());
                        if (halfNightChatzos == null) {
                                return getSolarMidnight(); // can be null if the calculator does not support astronomical chatzos
                        } else {
                                return halfNightChatzos;
                        }
                }
        }
        
        /**
         * A method that returns <em>chatzos</em> (<em>hayom</em> or <em>layla</em>) calculated as halfway between the begin and end
         * times passed in. If sunrise and sunset (or sunset and the following sunrise for <em>chatzos halayla</em>) are passed in,
         * the <em>zman</em> returned will be close to, but not exactly, 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> 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
         * <em>Chatzos</em></a> for a detailed explanation of the ways to calculate <em>Chatzos</em>. This method is a convenience
         * method that calls the parent class's {@link #getSunTransit(Instant, Instant)}. A practical example of using this would be
         * calculating <em>chatzos halayla</em> for the end of <em>zman achilas afikoman</em> on <em>Pesach</em> night, where
         * <a href="https://en.wikipedia.org/wiki/Shlomo_Zalman_Auerbach">Rav Shlomo Zalman Auerbach</a> in the Halichos Shlomo,
         * Moadim Nisan - Av, ch. 9, no. 44, pages 289-292, questioned the common practice of considering <em>chatzos halayla</em> as
         * astronomical <em>chatzos halayla</em>, and felt that for this it should be at <em>chatzi halayla</em>, halfway between sunset
         * and <em>alos</em> or <em>bedieved</em> from an early <em>tzais</em> that is lower (degree-wise) than <em>alos</em> the next
         * morning, thus making this <em>zman</em> significantly earlier. <a href="https://en.wikipedia.org/wiki/Moshe_Sternbuch">Rav
         * Moshe Sternbuch</a> in <a href="https://hebrewbooks.org/pdfpager.aspx?req=69091&pgnum=15">Teshuvos Vehanhagos v. VII, ch 1, p.
         * 3</a>, agreed to this calculation for <em>chatzos halayla</em> on <em>Pesach</em> night.
         * 
         * @param begin the beginning of day or night for calculating <em>chatzos</em>. For <em>chatzos hayom</em>, this can be sea level
         *         sunrise, or any arbitrary sunrise or <em>alos</em> used as the beginning of the day, and for <em>chatzos halayla</em>
         *         this can be sea level sunset, or any arbitrary sunset or <em>tzais</em> used as the beginning of the night.
         * @param end the end of day or night for calculating <em>chatzos</em>. For <em>chatzos hayom</em>, this can be sea level sunset,
         *         or any arbitrary sunset or <em>tzais</em> used as the end of day, and for <em>chatzos halayla</em> this can be sea
         *         level sunrise, or any arbitrary sunrise or <em>alos</em> used as the end of the night.
         * @return the <code>Instant</code> representing <em>chatzos</em>. 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.
         * @see #getSunTransit(Instant, Instant)
         * @see #getChatzosHayomAsHalfDay()
         * @see #getChatzosHayom()
         * @see #getChatzosHalayla()
         */
        public Instant getChatzos(Instant begin, Instant end) {
                return getSunTransit(begin, end);
        }
        
        /**
         * Returns <em>chatzos</em> calculated as halfway between sunrise and sunset. Many are of the opinion that
         * <em>chatzos</em> is calculated as the midpoint between {@link #getSeaLevelSunrise() sea level sunrise} and
         * {@link #getSeaLevelSunset() sea level sunset}, despite it not being the most accurate way to calculate it. A day
         * starting at <em>alos</em> and ending at <em>tzais</em> using the same time or degree offset will also return
         * the same time. In reality due to lengthening or shortening of day, this is not necessarily the exact midpoint of
         * the day, but it is very close. This method allows you to use the NOAACalculator and still calculate <em>chatzos
         * </em> as six <em>shaos zmaniyos</em> after sunrise. There are currently two {@link
         * com.kosherjava.zmanim.util.AstronomicalCalculator calculators} available in the API, the {@link
         * com.kosherjava.zmanim.util.NOAACalculator} and the {@link com.kosherjava.zmanim.util.SunTimesCalculator}.
         * The SunTimesCalculator calculates <em>chatzos</em> as halfway between sunrise and sunset (and of six <em>shaos
         * zmaniyos</em>), while the NOAACalculator calculates it as astronomical <em>chatzos</em> that is slightly more
         * accurate. This method allows you to use the NOAACalculator and still calculate <em>chatzos</em> as six <em>shaos
         * zmaniyos</em> after sunrise. See <a href="https://kosherjava.com/2020/07/02/definition-of-chatzos/">The Definition
         * of <em>Chatzos</em></a> for a detailed explanation of the ways to calculate <em>Chatzos</em>.
         *
         * @return the <code>Instant</code> of the latest <em>chatzos</em>. 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
         *         {@link AstronomicalCalendar} documentation.
         * @see com.kosherjava.zmanim.util.NOAACalculator#getUTCNoon(LocalDate, GeoLocation)
         * @see com.kosherjava.zmanim.util.SunTimesCalculator#getUTCNoon(LocalDate, GeoLocation)
         * @see com.kosherjava.zmanim.util.AstronomicalCalculator#getUTCNoon(LocalDate, GeoLocation)
         * @see #getSunTransit(Instant, Instant)
         * @see #getChatzosHayom()
         * @see #getChatzosHalayla()
         * @see #getChatzos(Instant, Instant)
         * @see #getSunTransit()
         * @see #isUseAstronomicalChatzos()
         */
        public Instant getChatzosHayomAsHalfDay() {
                return getChatzos(getSeaLevelSunrise(), getSeaLevelSunset());
        }

        /**
         * A generic method for calculating the latest <em>zman krias shema</em> (time to recite shema in the morning) that is 3 *
         * <em>shaos zmaniyos</em> (temporal hours) after the start of the day, calculated using the start and end of the day passed
         * to this method. The time from the start of day to the end of day are divided into 12 <em>shaos zmaniyos</em> (temporal
         * hours), and the latest <em>zman krias shema</em> is calculated as 3 of those <em>shaos zmaniyos</em> after the beginning of
         * the day. If {@link #isUseAstronomicalChatzosForOtherZmanim()} is <code>true</code>, the 3 <em>shaos zmaniyos</em> will be
         * based on 1/6 of the time between sunrise and {@link #getSunTransit() astronomical <em>chatzos</em>}. As an example, passing
         * {@link #getSunrise() sunrise} and {@link #getSunset() sunset} or {@link #getSeaLevelSunrise() sea level
         * sunrise} and {@link #getSeaLevelSunset() sea level sunset} to this method (or {@link #getSunriseBasedOnElevationSetting()} and
         * {@link #getSunsetBasedOnElevationSetting()} that is driven off the {@link #isUseElevation()} setting) will return <em>sof zman
         * krias shema</em> according to the opinion of the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. In cases where
         * the start and end dates are not synchronous such as in {@link ComprehensiveZmanimCalendar
         * #getSofZmanShmaAlos16Point1ToTzaisGeonim7Point083Degrees()} <code>false</code> should be passed to the synchronous parameter
         * to ensure that {@link #isUseAstronomicalChatzosForOtherZmanim()} will not be used.
         * 
         * @param startOfDay the start of day for calculating <em>zman krias shema</em>. This can be sunrise or any <em>alos</em> passed
         *         to this method.
         * @param endOfDay the end of day for calculating <em>zman krias shema</em>. This can be sunset or any <em>tzais</em> passed to
         *         this method.
         * @param synchronous If the <em>zman</em> has a synchronous start and end of the day. If this is <code>false</code>, using a
         *         {@link #isUseAstronomicalChatzosForOtherZmanim()} makes no sense and will be ignored even if set to true, since by
         *         definition <em>chatzos</em> will not be the middle of the day for the <em>zman</em>.
         * @see #isUseAstronomicalChatzosForOtherZmanim()
         * @return the <code>Instant</code> of the latest <em>zman shema</em> based on the start and end of day times passed to this
         *         method. 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 {@link AstronomicalCalendar} documentation.
         */
        public Instant getSofZmanShma(Instant startOfDay, Instant endOfDay, boolean synchronous) {
                if (isUseAstronomicalChatzosForOtherZmanim() && synchronous) {
                        return getHalfDayBasedZman(startOfDay, getChatzosHayom(), 3);
                } else {
                        return getShaahZmanisBasedZman(startOfDay, endOfDay, 3);
                }
        }
        
        /**
         * A generic method for calculating the latest <em>zman krias shema</em> that calls {@link #getSofZmanShma(Instant, Instant, boolean)}
         * passing <code>false</code> to the synchronous parameter since there is no way to know if the start and end of the day are 
         * synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
         * @param startOfDay the start of day for calculating <em>zman krias shema</em>. This can be sunrise or any <em>alos</em> passed
         *         to this method.
         * @param endOfDay the end of day for calculating <em>zman krias shema</em>. This can be sunset or any <em>tzais</em> passed to
         *         this method.
         * @return the <code>Instant</code> of the latest <em>zman shema</em> based on the start and end of day times passed to this
         *         method. 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 {@link AstronomicalCalendar} documentation.
         * @see #getSofZmanShma(Instant, Instant, boolean)
         */
        public Instant getSofZmanShma(Instant startOfDay, Instant endOfDay) {
                return getSofZmanShma(startOfDay, endOfDay, false);
        }

        /**
         * This method returns the latest <em>zman krias shema</em> (time to recite shema in the morning) that is 3 *
         * {@link #getShaahZmanisGRA() <em>shaos zmaniyos</em>} (solar hours) after {@link #getSunrise() sunrise} or
         * {@link #getSeaLevelSunrise() sea level sunrise} (depending on the {@link #isUseElevation()} setting), according
         * to the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. 
         *  The day is calculated from {@link #getSeaLevelSunrise() sea level sunrise} to {@link #getSeaLevelSunset() sea level
         *  sunset} or from {@link #getSunrise() sunrise} to {@link #getSunset() sunset} (depending on the
         *  {@link #isUseElevation()} setting).
         * 
         * @see #getSofZmanShma(Instant, Instant)
         * @see #getShaahZmanisGRA()
         * @see #isUseElevation()
         * @see ComprehensiveZmanimCalendar#getSofZmanShmaBaalHatanya()
         * @return the <code>Instant</code> of the latest <em>zman shema</em> according to the GRA. 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 the detailed explanation on top
         *         of the {@link AstronomicalCalendar} documentation.
         */
        public Instant getSofZmanShmaGRA() {
                return getSofZmanShma(getSunriseBasedOnElevationSetting(), getSunsetBasedOnElevationSetting(), true);
        }

        /**
         * This method returns the latest <em>zman krias shema</em> (time to recite Shema in the morning) according to the opinion of
         * the <a href="https://en.wikipedia.org/wiki/Avraham_Gombiner">Magen Avraham (MGA)</a> based on <em>alos</em> being {@link
         * getAlos72Minutes() 72} minutes before {@link #getSunrise() sunrise}. This time is 3 {@link
         * getShaahZmanis72Minutes() <em>shaos zmaniyos</em>} (solar hours) after {@link #getAlos72Minutes() dawn} based on the opinion
         * of the MGA that the day is calculated from a {@link #getAlos72Minutes() dawn} of 72 minutes before sunrise to
         * {@link #getTzais72Minutes() nightfall} of 72 minutes after sunset. This returns the time of 3 * {@link
         * getShaahZmanis72Minutes()} after {@link #getAlos72Minutes() dawn}.
         * 
         * @return the <code>Instant</code> of the latest <em>zman krias shema</em>. 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
         *         {@link AstronomicalCalendar} documentation.
         * @see #isUseAstronomicalChatzosForOtherZmanim()
         * @see #getShaahZmanis72Minutes()
         * @see #getAlos72Minutes()
         * @see #getSofZmanShmaMGA72Minutes()
         * @see #getSofZmanShma(Instant, Instant, boolean)
         */
        public Instant getSofZmanShmaMGA72Minutes() {
                return getSofZmanShma(getAlos72Minutes(), getTzais72Minutes(), true);
        }

        /**
         * This method returns the <em>tzais</em> (nightfall) based on the opinion of <em>Rabbeinu Tam</em> that <em>tzais hakochavim</em>
         * is calculated as 72 minutes after sunset, the time it takes to walk 4 <a href=
         * "https://en.wikipedia.org/wiki/Biblical_mile">mil</a> at 18 minutes a mil. According to the <a href=
         * "https://en.wikipedia.org/wiki/Samuel_Loew">Machtzis Hashekel</a> in Orach Chaim 235:3, the <a href=
         * "https://en.wikipedia.org/wiki/Joseph_ben_Meir_Teomim">Pri Megadim</a> in Orach Chaim 261:2 (see the Biur Halacha) and others
         * (see Hazmanim Bahalacha 17:3 and 17:5) the 72 minutes are standard clock minutes any time of the year in any location.
         * Depending on the {@link #isUseElevation()} setting, a 72-minute offset from  either {@link #getSunset() sunset} or
         * {@link #getSeaLevelSunset() sea level sunset} is used.
         * 
         * @return the <code>Instant</code> representing 72 minutes after sunset. 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
         *         {@link AstronomicalCalendar} documentation.
         * @see ComprehensiveZmanimCalendar#getTzais16Point1Degrees()
         */
        public Instant getTzais72Minutes() {
                return getTimeOffset(getSunsetBasedOnElevationSetting(), Duration.ofMinutes(72));
        }

        /**
         * A method to return candle lighting time, calculated as {@link #getCandleLightingOffset()} minutes before {@link
         * #getSeaLevelSunset() sea level sunset}. This will return the time for any day of the week, since it can be used to calculate
         * candle lighting time for <em>Yom Tov</em> (mid-week holidays) as well. Elevation adjustments are intentionally not performed
         * by this method, but you can calculate it by passing the elevation adjusted sunset to {@link #getTimeOffset(Instant, Duration)}.
         * 
         * @return candle lighting 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 {@link AstronomicalCalendar} documentation.
         * @see #getSeaLevelSunset()
         * @see #getCandleLightingOffset()
         * @see #setCandleLightingOffset(double)
         */
        public Instant getCandleLighting() {
                long totalNanos = (long) (-getCandleLightingOffset() * MINUTE_NANOS);
                return getTimeOffset(getSeaLevelSunset(), Duration.ofNanos(totalNanos));
        }

        /**
         * A generic method for calculating the latest <em>zman tfilah</em> (time to recite the morning prayers) that is 4 * <em>shaos
         * zmaniyos</em> (temporal hours) after the start of the day, calculated using the start and end of the day passed to this method.
         * The time from the start of day to the end of day are divided into 12 <em>shaos zmaniyos</em> (temporal hours), and <em>sof
         * zman tfila</em> is calculated as 4 of those <em>shaos zmaniyos</em> after the beginning of the day. As an example, passing
         * {@link #getSunriseBasedOnElevationSetting()} and {@link #getSunsetBasedOnElevationSetting()} (depends on the {@link
         * #isUseElevation()} elevation setting) to this method will return <em>zman tfilah</em> according to the opinion of the <a href=
         * "https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. This method's synchronous parameter indicates if the start and end of day
         * for the calculation are synchronous, having the same offset. This is typically the case, but some <em>zmanim</em> calculations
         * are based on a start and end at different offsets from the real start and end of the day, such as starting the day at
         * <em>alos</em> and an ending it at <em>tzais Geonim</em> or some other variant. If the day is not synchronous a {@link
         * #getHalfDayBasedZman(Instant, Instant, double) half-day based calculations} will be bypassed. It would be illogical to use a
         * half-day based calculation that start/end at <em>chatzos</em> when the two "halves" of the day are not equal, and the halfway
         * point between them is not at <em>chatzos</em>.
         * 
         * @param startOfDay the start of day for calculating <em>zman tfilah</em>. This can be sunrise or any <em>alos</em> passed
         *         to this method.
         * @param endOfDay the end of day for calculating <em>zman tfilah</em>. This can be sunset or any <em>tzais</em> passed
         *         to this method.
         * @param synchronous If the <em>zman</em> has a synchronous start and end of the day. If this is <code>false</code>, using a
         *         {@link #isUseAstronomicalChatzosForOtherZmanim()} makes no sense and will be ignored even if set to true, since by
         *         definition <em>chatzos</em> will not be the middle of the day for the <em>zman</em>.
         * @return the <code>Instant</code> of the latest <em>zman tfilah</em> based on the start and end of day times passed to this
         *         method. 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 {@link AstronomicalCalendar} documentation.
         */
        public Instant getSofZmanTfila(Instant startOfDay, Instant endOfDay, boolean synchronous) {
                if (isUseAstronomicalChatzosForOtherZmanim() && synchronous) {
                        return getHalfDayBasedZman(startOfDay, getChatzosHayom(), 4);
                } else {
                        return getShaahZmanisBasedZman(startOfDay, endOfDay, 4);
                }
        }
        
        /**
         * A generic method for calculating <em>sof zman biur chametz</em> or the latest time one is allowed burning
         * <em>chametz</em> on <em>Erev Pesach</em> that is 5 * <em>shaos zmaniyos</em> (temporal hours) after the start of the
         * day, calculated using the start and end of the day passed to this method. If the date is not <em>erev Pesach</em>, a
         * null will be returned. The time from the start of day to the end of day is divided into 12 <em>shaos zmaniyos</em>
         * (temporal hours), and <em>sof zman biur chametz</em> is calculated as 5 of those <em>shaos zmaniyos</em> after the
         * beginning of the day. As an example, passing {@link #getSunrise() sunrise} and {@link #getSunset() sunset} to this
         * method will return <em>sof zman biur chametz</em> according to the opinion of the <a href=
         * "https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. This method's synchronous parameter indicates if the start
         * and end of day for the calculation are synchronous, having the same offset. This is typically the case, but some
         * <em>zmanim</em> calculations are based on a start and end at different offsets from the real start and end of the day,
         * such as starting the day at <em>alos</em> and an ending it at <em>tzais Geonim</em> or some other variant. If the day
         * is not synchronous a {@link #getHalfDayBasedZman(Instant, Instant, double) half-day based calculations} will be bypassed.
         * It would be illogical to use a half-day based calculation that start/end at <em>chatzos</em> when the two "halves" of
         * the day are not equal, and the halfway point between them is not at <em>chatzos</em>.
         * 
         * @param startOfDay the start of day for calculating <em>sof zman biur chametz</em>. This can be sunrise or any <em>alos</em>
         *         passed to this method.
         * @param endOfDay the end of day for calculating <em>sof zman biur chametz</em>. This can be sunset or any <em>tzais</em>
         *         passed to this method.
         * @param synchronous If the <em>zman</em> has a synchronous start and end of the day. If this is <code>false</code>, using a
         *         {@link #isUseAstronomicalChatzosForOtherZmanim()} makes no sense and will be ignored even if set to true, since by
         *         definition <em>chatzos</em> will not be the middle of the day for the <em>zman</em>.
         * @return the <code>Instant</code> of the <em>sof zman biur chametz</em> based on the start and end of day times passed
         *         to this method. If the date is not <em>Erev Pesach</em> or 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 {@link AstronomicalCalendar}
         *         documentation.
         */
        public Instant getSofZmanBiurChametz(Instant startOfDay, Instant endOfDay, boolean synchronous) {
                JewishCalendar jewishCalendar = new JewishCalendar(getLocalDate());
                if (jewishCalendar.getJewishMonth() == JewishCalendar.NISSAN && jewishCalendar.getJewishDayOfMonth() == 14) {
                        if (isUseAstronomicalChatzosForOtherZmanim() && synchronous) {
                                return getHalfDayBasedZman(startOfDay, getChatzosHayom(), 5);
                        } else {
                                return getShaahZmanisBasedZman(startOfDay, endOfDay, 5);
                        }
                } else {
                        return null;
                }
        }
        
        /**
         * A generic method for calculating <em>sof zman achilas chametz</em> or the latest time one is allowed eating
         * <em>chametz</em> on <em>Erev Pesach</em> that is 4 * <em>shaos zmaniyos</em> (temporal hours) after the start of the
         * day, calculated using the start and end of the day passed to this method. If the date is not <em>erev Pesach</em>, a
         * null will be returned. The time from the start of day to the end of day is divided into 12 <em>shaos zmaniyos</em>
         * (temporal hours), and <em>sof zman achilas chametz</em> is calculated as 4 of those <em>shaos zmaniyos</em> after the
         * beginning of the day. As an example, passing {@link #getSunrise() sunrise} and {@link #getSunset() sunset} to this
         * method will return <em>sof zman achilas chametz</em> according to the opinion of the <a href=
         * "https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. This method's synchronous parameter indicates if the start
         * and end of day for the calculation are synchronous, having the same offset. This is typically the case, but some
         * <em>zmanim</em> calculations are based on a start and end at different offsets from the real start and end of the day,
         * such as starting the day at <em>alos</em> and an ending it at <em>tzais Geonim</em> or some other variant. If the day
         * is not synchronous a {@link #getHalfDayBasedZman(Instant, Instant, double) half-day based calculations} will be bypassed.
         * It would be illogical to use a half-day based calculation that start/end at <em>chatzos</em> when the two "halves" of
         * the day are not equal, and the halfway point between them is not at <em>chatzos</em>.
         * 
         * @param startOfDay the start of day for calculating <em>sof zman achilas chametz</em>. This can be sunrise or any <em>alos</em>
         *         passed to this method.
         * @param endOfDay the end of day for calculating <em>sof zman achilas chametz</em>. This can be sunset or any <em>tzais</em>
         *         passed to this method.
         * @param synchronous If the <em>zman</em> has a synchronous start and end of the day. If this is <code>false</code>, using a {@link
         *         isUseAstronomicalChatzosForOtherZmanim()} makes no sense and will be ignored even if set to true, since by definition
         *         <em>chatzos</em> will not be the middle of the day for the <em>zman</em>.
         * @return the <code>Instant</code> of the <em>sof zman achilas chametz</em> based on the start and end of day times passed
         *         to this method. If the date is not <em>Erev Pesach</em> or 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 {@link AstronomicalCalendar}
         *         documentation.
         */
        public Instant getSofZmanAchilasChametz(Instant startOfDay, Instant endOfDay, boolean synchronous) {
                JewishCalendar jewishCalendar = new JewishCalendar(getLocalDate());
                if (jewishCalendar.getJewishMonth() == JewishCalendar.NISSAN && jewishCalendar.getJewishDayOfMonth() == 14) {
                        return getSofZmanTfila(startOfDay, endOfDay, synchronous);
                } else {
                        return null;
                }
        }
        
        /**
         * A generic method for calculating the latest <em>zman tfila</em> that calls {@link #getSofZmanTfila(Instant, Instant, boolean)}
         * passing <code>false</code> to the synchronous parameter since there is no way to know if the start and end of the day are 
         * synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
         * @param startOfDay the start of day for calculating <em>zman tfilah</em>. This can be sunrise or any <em>alos</em> passed
         *         to this method.
         * @param endOfDay the end of day for calculating <em>zman tfilah</em>. This can be sunset or any <em>tzais</em> passed to
         *         this method.
         * @return the <code>Instant</code> of the latest <em>zman tfilah</em> based on the start and end of day times passed to this
         *         method. 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 {@link AstronomicalCalendar} documentation.
         * @see #getSofZmanShma(Instant, Instant, boolean)
         */
        public Instant getSofZmanTfila(Instant startOfDay, Instant endOfDay) {
                return getSofZmanTfila(startOfDay, endOfDay, false);
        }

        /**
         * This method returns the latest <em>zman tfila</em> (time to recite shema in the morning) that is 4 *
         * {@link #getShaahZmanisGRA() <em>shaos zmaniyos</em> }(solar hours) after {@link #getSunrise() sunrise} or
         * {@link #getSeaLevelSunrise() sea level sunrise} (depending on the {@link #isUseElevation()} setting), according
         * to the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. 
         * The day is calculated from {@link #getSeaLevelSunrise() sea level sunrise} to {@link #getSeaLevelSunset() sea level
         * sunset} or from {@link #getSunrise() sunrise} to {@link #getSunset() sunset} (depending on the
         * {@link #isUseElevation()} setting).
         * 
         * @see #getSofZmanTfila(Instant, Instant)
         * @see #getShaahZmanisGRA()
         * @see ComprehensiveZmanimCalendar#getSofZmanTfilaBaalHatanya()
         * @return the <code>Instant</code> of the latest <em>zman tfilah</em>. 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
         *         {@link AstronomicalCalendar} documentation.
         */
        public Instant getSofZmanTfilaGRA() {
                return getSofZmanTfila(getSunriseBasedOnElevationSetting(), getSunsetBasedOnElevationSetting(), true);
        }

        /**
         * This method returns the latest <em>zman tfila</em> (time to recite shema in the morning) that is 4 * {@link
         * getShaahZmanis72Minutes() <em>shaos zmaniyos</em>} (solar hours) after {@link #getAlos72Minutes()}, according to the
         * <em><a href="https://en.wikipedia.org/wiki/Avraham_Gombiner">Magen Avraham (MGA)</a></em>. The day is calculated
         * from 72 minutes before {@link #getSunriseBasedOnElevationSetting()} to 72 minutes after {@link
         * getSunsetBasedOnElevationSetting()}. The use of elevation depends on the {@link #isUseElevation()} setting).
         * 
         * @return the <code>Instant</code> of the latest <em>zman tfila</em>. 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
         *         {@link AstronomicalCalendar} documentation.
         * @see #getSofZmanTfila(Instant, Instant, boolean)
         * @see #getShaahZmanis72Minutes()
         * @see #getAlos72Minutes()
         */
        public Instant getSofZmanTfilaMGA72Minutes() {
                return getSofZmanTfila(getAlos72Minutes(), getTzais72Minutes(), true);
        }

        /**
         * A generic method for calculating <em>mincha gedola</em> (the earliest time to recite the <em>mincha</em> prayers) that
         * is 6.5 * <em>shaos zmaniyos</em> (temporal hours) after the start of the day, calculated using the start and end of the
         * day passed to this method. The time from the start of day to the end of day are divided into 12 <em>shaos zmaniyos</em>
         * (temporal hours), and <em>mincha gedola</em> is calculated as 6.5 of those <em>shaos zmaniyos</em> after the beginning
         * of the day. As an example, passing {@link #getSunrise() sunrise} and {@link #getSunset() sunset} or
         * {@link #getSeaLevelSunrise() sea level sunrise} and {@link #getSeaLevelSunset() sea level sunset} (depending on the {@link
         * isUseElevation()} elevation setting) to this method will return <em>mincha gedola</em> according to the opinion of the
         * <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. Alternatively, this method uses {@link
         * isUseAstronomicalChatzosForOtherZmanim()} to control if the time is based on 6.5 <em>shaos zmaniyos</em> into the day
         * mentioned above, or as half an hour <em>zmaniyos</em> based on the second half of the day after <em>chatzos</em> ({@link
         * getSunTransit() astronomical <em>chatzos</em>} if supported by the {@link AstronomicalCalculator calculator} and {@link
         * isUseAstronomicalChatzos() configured} or {@link #getChatzosHayomAsHalfDay() <em>chatzos</em> as half a day} if not. This
         * method's synchronous parameter indicates if the start and end of day for the calculation are synchronous, having the same
         * offset. This is typically the case, but some <em>zmanim</em> calculations are based on a start and end at different offsets
         * from the real start and end of the day, such as starting the day at <em>alos</em> and an ending it at <em>tzais Geonim</em>
         * or some other variant. If the day is not synchronous a {@link #getHalfDayBasedZman(Instant, Instant, double) half-day based
         * calculations} will be bypassed. It would be illogical to use a half-day based calculation that start/end at <em>chatzos</em>
         * when the two "halves" of the day are not equal, and the halfway point between them is not at <em>chatzos</em>.
         * 
         * @param startOfDay the start of day for calculating <em>Mincha gedola</em>. This can be sunrise or any <em>alos</em> passed
         *         to this method.
         * @param endOfDay the end of day for calculating <em>Mincha gedola</em>. This can be sunset or any <em>tzais</em> passed
         *         to this method.
         * @param synchronous If the <em>zman</em> has a synchronous start and end of the day. If this is <code>false</code>, using a
         *         {@link #isUseAstronomicalChatzosForOtherZmanim()} makes no sense and will be ignored even if set to true, since by
         *         definition <em>chatzos</em> will not be the middle of the day for the <em>zman</em>.
         * @return the <code>Instant</code> of the time of <em>Mincha gedola</em> based on the start and end of day times
         *         passed to this method. 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 {@link AstronomicalCalendar} documentation.
         * @see #getSunTransit()
         * @see #getChatzosHayomAsHalfDay()
         * @see #getChatzosHayom()
         * @see #getChatzosHalayla()
         * @see #isUseAstronomicalChatzos()
         * @see #isUseAstronomicalChatzosForOtherZmanim()
         */
        public Instant getMinchaGedola(Instant startOfDay, Instant endOfDay, boolean synchronous) {
                if (isUseAstronomicalChatzosForOtherZmanim() && synchronous) {
                        return getHalfDayBasedZman(getChatzosHayom(), endOfDay, 0.5);
                } else {
                        return getShaahZmanisBasedZman(startOfDay, endOfDay, 6.5);
                }
        }
        
        /**
         * A generic method for calculating <em>mincha gedola</em> that calls {@link #getMinchaGedola(Instant, Instant, boolean)} passing
         * <code>false</code> to the synchronous parameter since there is no way to know if the start and end of the day are
         * synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more
         * details.
         * @param startOfDay the start of day for calculating <em>Mincha gedola</em>. This can be sunrise or any <em>alos</em> passed
         *         to this method.
         * @param endOfDay the end of day for calculating <em>Mincha gedola</em>. This can be sunset or any <em>tzais</em> passed to
         *         this method.
         * @return the <code>Instant</code> of the latest <em>Mincha gedola</em> based on the start and end of day times passed to this
         *         method. 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 {@link AstronomicalCalendar} documentation.
         * @see #getMinchaGedola(Instant, Instant, boolean)
         */
        public Instant getMinchaGedola(Instant startOfDay, Instant endOfDay) {
                return getMinchaGedola(startOfDay, endOfDay, false);
        }

        /**
         * This method returns the latest <em>mincha gedola</em>,the earliest time one can pray <em>mincha</em> that is 6.5 *
         * {@link #getShaahZmanisGRA() <em>shaos zmaniyos</em>} (solar hours) after {@link #getSunrise() sunrise} or
         * {@link #getSeaLevelSunrise() sea level sunrise} (depending on the {@link #isUseElevation()} setting), according
         * to the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. <em>Mincha gedola</em> is the earliest
         * time one can pray <em>mincha</em>. The Ramba"m is of the opinion that it is better to delay <em>mincha</em> until
         * {@link #getMinchaKetanaGRA() <em>mincha ketana GRA</em>} while the Ra"sh, Tur, GRA and others are of the
         * opinion that <em>mincha</em> can be prayed <em>lechatchila</em> starting at <em>mincha gedola</em>.
         * The day is calculated from {@link #getSeaLevelSunrise() sea level sunrise} to {@link #getSeaLevelSunset() sea level
         * sunset} or {@link #getSunrise() sunrise} to {@link #getSunset() sunset} (depending on the {@link #isUseElevation()}
         * setting).
         * @todo Consider adjusting this to calculate the time as half an hour <em>zmaniyos</em> after {@link #getChatzosHayom()}
         *         that uses {@link #isUseAstronomicalChatzos()} to determine the type of <em>chatzos</em> to utilize (if the
         *         {@link com.kosherjava.zmanim.util.AstronomicalCalculator calculator} support astronomical <em>chatzos</em>),
         *         based on the {@link #isUseAstronomicalChatzos()} setting.
         * @see #getMinchaGedola(Instant, Instant)
         * @see #getShaahZmanisGRA()
         * @see #getMinchaKetanaGRA()
         * @see ComprehensiveZmanimCalendar#getMinchaGedolaBaalHatanya()
         * @return the <code>Instant</code> of the time of mincha gedola. 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
         *         {@link AstronomicalCalendar} documentation.
         */
        public Instant getMinchaGedolaGRA() {
                return getMinchaGedola(getSunriseBasedOnElevationSetting(), getSunsetBasedOnElevationSetting(), true);
        }
        
        /**
         * A generic method for calculating <em>samuch lemincha ketana</em>, / near <em>mincha ketana</em> time that is half
         * an hour before {@link #getMinchaKetana(Instant, Instant)}  or 9 * <em>shaos zmaniyos</em> (temporal hours) after the
         * start of the day, calculated using the start and end of the day passed to this method.
         * The time from the start of day to the end of day are divided into 12 <em>shaos zmaniyos</em> (temporal hours), and
         * <em>samuch lemincha ketana</em> is calculated as 9 of those <em>shaos zmaniyos</em> after the beginning of the day.
         * For example, passing {@link #getSunrise() sunrise} and {@link #getSunset() sunset} or {@link #getSeaLevelSunrise() sea
         * level sunrise} and {@link #getSeaLevelSunset() sea level sunset} (depending on the {@link #isUseElevation()} elevation
         * setting) to this method will return <em>samuch lemincha ketana</em> according to the opinion of the
         * <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. See the <a href=
         * "https://hebrewbooks.org/pdfpager.aspx?req=60387&st=&pgnum=294">Mechaber and Mishna Berurah 232</a> and <a href=
         * "https://hebrewbooks.org/pdfpager.aspx?req=60388&pgnum=34">249:2</a>.
         * 
         * @param startOfDay the start of day for calculating <em>samuch lemincha ketana</em>. This can be sunrise or any <em>alos</em>
         *         passed to this method.
         * @param endOfDay the end of day for calculating <em>samuch lemincha ketana</em>. This can be sunset or any <em>tzais</em>
         *         passed to this method.
         * @param synchronous If the <em>zman</em> has a synchronous start and end of the day. If this is <code>false</code>, using a
         *         {@link #isUseAstronomicalChatzosForOtherZmanim()} makes no sense and will be ignored even if set to true, since by
         *         definition <em>chatzos</em> will not be the middle of the day for the <em>zman</em>.
         * @return the <code>Instant</code> of the time of <em>Mincha ketana</em> based on the start and end of day times
         *         passed to this method. 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 {@link AstronomicalCalendar} documentation.
         * @see ComprehensiveZmanimCalendar#getSamuchLeMinchaKetanaGRA()
         * @see ComprehensiveZmanimCalendar#getSamuchLeMinchaKetana16Point1Degrees()
         * @see ComprehensiveZmanimCalendar#getSamuchLeMinchaKetana72Minutes()
         */
        public Instant getSamuchLeMinchaKetana(Instant startOfDay, Instant endOfDay, boolean synchronous) {
                if (isUseAstronomicalChatzosForOtherZmanim() && synchronous) {
                        return getHalfDayBasedZman(getChatzosHayom(), endOfDay, 3);
                } else {
                        return getShaahZmanisBasedZman(startOfDay, endOfDay, 9);
                }
        }
        
        /**
         * A generic method for calculating <em>samuch lemincha ketana</em> that calls {@link #getSamuchLeMinchaKetana(Instant, Instant, boolean)}
         * passing <code>false</code> to the synchronous parameter since there is no way to know if the start and end of the day are 
         * synchronous. Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
         * @param startOfDay the start of day for calculating <em>samuch lemincha ketana</em>. This can be sunrise or any <em>alos</em>
         *         passed to this method.
         * @param endOfDay the end of day for calculating <em>samuch lemincha ketana</em>. This can be sunset or any <em>tzais</em>
         *         passed to this method.
         * @return the <code>Instant</code> of the time of <em>samuch lemincha ketana</em> based on the start and end of day times
         *         passed to this method. 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 {@link AstronomicalCalendar} documentation.
         * @see #getSamuchLeMinchaKetana(Instant, Instant, boolean)
         */
        public Instant getSamuchLeMinchaKetana(Instant startOfDay, Instant endOfDay) {
                return getSamuchLeMinchaKetana(startOfDay, endOfDay, false);
        }

        /**
         * A generic method for calculating <em>mincha ketana</em>, (the preferred time to recite the mincha prayers in
         * the opinion of the <em><a href="https://en.wikipedia.org/wiki/Maimonides">Rambam</a></em> and others) that is
         * 9.5 * <em>shaos zmaniyos</em> (temporal hours) after the start of the day, calculated using the start and end
         * of the day passed to this method.
         * The time from the start of day to the end of day are divided into 12 <em>shaos zmaniyos</em> (temporal hours), and
         * <em>mincha ketana</em> is calculated as 9.5 of those <em>shaos zmaniyos</em> after the beginning of the day. As an
         * example, passing {@link #getSunrise() sunrise} and {@link #getSunset() sunset} or {@link #getSeaLevelSunrise() sea
         * level sunrise} and {@link #getSeaLevelSunset() sea level sunset} (depending on the {@link #isUseElevation()}
         * elevation setting) to this method will return <em>mincha ketana</em> according to the opinion of the
         * <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. This method's synchronous parameter indicates if the start
         * and end of day for the calculation are synchronous, having the same offset. This is typically the case, but some
         * <em>zmanim</em> calculations are based on a start and end at different offsets from the real start and end of the day,
         * such as starting the day at <em>alos</em> and an ending it at <em>tzais Geonim</em> or some other variant. If the day
         * is not synchronous a {@link #getHalfDayBasedZman(Instant, Instant, double) half-day based calculations} will be bypassed.
         * It would be illogical to use a half-day based calculation that start/end at <em>chatzos</em> when the two "halves" of
         * the day are not equal, and the halfway point between them is not at <em>chatzos</em>.
         * 
         * @param startOfDay the start of day for calculating <em>Mincha ketana</em>. This can be sunrise or any <em>alos</em> passed
         *         to this method.
         * @param endOfDay the end of day for calculating <em>Mincha ketana</em>. This can be sunset or any <em>tzais</em> passed to
         *         this method.
         * @param synchronous If the <em>zman</em> has a synchronous start and end of the day. If this is <code>false</code>, using a
         *         {@link #isUseAstronomicalChatzosForOtherZmanim()} makes no sense and will be ignored even if set to true, since by
         *         definition <em>chatzos</em> will not be the middle of the day for the <em>zman</em>.
         * @return the <code>Instant</code> of the time of <em>Mincha ketana</em> based on the start and end of day times
         *         passed to this method. 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 {@link AstronomicalCalendar} documentation.
         */
        public Instant getMinchaKetana(Instant startOfDay, Instant endOfDay, boolean synchronous) {
                if (isUseAstronomicalChatzosForOtherZmanim() && synchronous) {
                        return getHalfDayBasedZman(getChatzosHayom(), endOfDay, 3.5);
                } else {
                        return getShaahZmanisBasedZman(startOfDay, endOfDay, 9.5);
                }
        }
        
        /**
         * A generic method for calculating <em>mincha ketana</em> that calls {@link #getMinchaKetana(Instant, Instant, boolean)} passing
         * <code>false</code> to the synchronous parameter since there is no way to know if the start and end of the day are synchronous.
         * Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
         * @param startOfDay the start of day for calculating <em>Mincha ketana</em>. This can be sunrise or any <em>alos</em> passed
         *         to this method.
         * @param endOfDay the end of day for calculating <em>Mincha ketana</em>. This can be sunset or any <em>tzais</em> passed to
         *         this method.
         * @return the <code>Instant</code> of the time of <em>Mincha ketana</em> based on the start and end of day times
         *         passed to this method. 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 {@link AstronomicalCalendar} documentation.
         * @see #getMinchaKetana(Instant, Instant, boolean)
         */
        public Instant getMinchaKetana(Instant startOfDay, Instant endOfDay) {
                return getMinchaKetana(startOfDay, endOfDay, false);
        }

        /**
         * This method returns <em>mincha ketana</em>,the preferred earliest time to pray <em>mincha</em> in the
         * opinion of the <em><a href="https://en.wikipedia.org/wiki/Maimonides">Rambam</a></em> and others, that is 9.5
         * * {@link #getShaahZmanisGRA() <em>shaos zmaniyos</em>} (solar hours) after {@link #getSunrise() sunrise} or
         * {@link #getSeaLevelSunrise() sea level sunrise} (depending on the {@link #isUseElevation()} setting), according
         * to the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. For more information on this see the
         * documentation on {@link #getMinchaGedolaGRA() <em>mincha gedola</em>}.
         * The day is calculated from {@link #getSeaLevelSunrise() sea level sunrise} to {@link #getSeaLevelSunset() sea level
         * sunset} or from {@link #getSunrise() sunrise} to {@link #getSunset() sunset} (depending on the {@link #isUseElevation()}
         * setting.
         * 
         * @see #getMinchaKetana(Instant, Instant)
         * @see #getShaahZmanisGRA()
         * @see #getMinchaGedolaGRA()
         * @see ComprehensiveZmanimCalendar#getMinchaKetanaBaalHatanya()
         * @return the <code>Instant</code> of the time of mincha ketana. 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
         *         {@link AstronomicalCalendar} documentation.
         */
        public Instant getMinchaKetanaGRA() {
                return getMinchaKetana(getSunriseBasedOnElevationSetting(), getSunsetBasedOnElevationSetting(), true);
        }

        /**
         * A generic method for calculating <em>plag hamincha</em> (the earliest time that Shabbos can be started) that is
         * 10.75 hours after the start of the day, (or 1.25 hours before the end of the day) based on the start and end of
         * the day passed to the method.
         * The time from the start of day to the end of day are divided into 12 <em>shaos zmaniyos</em> (temporal hours), and
         * <em>plag hamincha</em> is calculated as 10.75 of those <em>shaos zmaniyos</em> after the beginning of the day. As an
         * example, passing {@link #getSunrise() sunrise} and {@link #getSunset() sunset} or {@link #getSeaLevelSunrise() sea level
         * sunrise} and {@link #getSeaLevelSunset() sea level sunset} (depending on the {@link #isUseElevation()} elevation
         * setting) to this method will return <em>plag mincha</em> according to the opinion of the
         * <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. This method's synchronous parameter indicates if the start
         * and end of day for the calculation are synchronous, having the same offset. This is typically the case, but some
         * <em>zmanim</em> calculations are based on a start and end at different offsets from the real start and end of the day,
         * such as starting the day at <em>alos</em> and an ending it at <em>tzais Geonim</em> or some other variant. If the day
         * is not synchronous a {@link #getHalfDayBasedZman(Instant, Instant, double) half-day based calculations} will be bypassed. It
         * would be illogical to use a half-day based calculation that start/end at <em>chatzos</em> when the two "halves" of the
         * day are not equal, and the halfway point between them is not at <em>chatzos</em>.
         * 
         * @param startOfDay the start of day for calculating <em>plag hamincha</em>. This can be sunrise or any <em>alos</em> passed to
         *         this method.
         * @param endOfDay the end of day for calculating <em>plag hamincha</em>. This can be sunset or any <em>tzais</em> passed to
         *         this method.
         * @param synchronous If the <em>zman</em> has a synchronous start and end of the day. If this is <code>false</code>, using a
         *         {@link #isUseAstronomicalChatzosForOtherZmanim()} makes no sense and will be ignored even if set to true, since by
         *         definition <em>chatzos</em> will not be the middle of the day for the <em>zman</em>.
         * @return the <code>Instant</code> of the time of <em>plag hamincha</em> based on the start and end of day times
         *         passed to this method. 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 {@link AstronomicalCalendar} documentation.
         */
        public Instant getPlagHamincha(Instant startOfDay, Instant endOfDay, boolean synchronous) {
                if (isUseAstronomicalChatzosForOtherZmanim() && synchronous) {
                        return getHalfDayBasedZman(getChatzosHayom(), endOfDay, 4.75);
                } else {
                        return getShaahZmanisBasedZman(startOfDay, endOfDay, 10.75);
                }
        }
        
        /**
         * A generic method for calculating <em>plag hamincha</em> that calls {@link #getPlagHamincha(Instant, Instant, boolean)} passing
         * <code>false</code> to the synchronous parameter since there is no way to know if the start and end of the day are synchronous.
         * Passing true when they are not synchronous is too much of a risk. See information on that method for more details.
         * @param startOfDay the start of day for calculating <em>plag hamincha</em>. This can be sunrise or any <em>alos</em> passed to
         *         this method.
         * @param endOfDay the end of day for calculating <em>plag hamincha</em>. This can be sunset or any <em>tzais</em> passed to this
         *         method.
         * @return the <code>Instant</code> of the time of <em>plag hamincha</em> based on the start and end of day times
         *         passed to this method. 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 {@link AstronomicalCalendar} documentation.
         * @see #getPlagHamincha(Instant, Instant, boolean)
         */
        public Instant getPlagHamincha(Instant startOfDay, Instant endOfDay) {
                return getPlagHamincha(startOfDay, endOfDay, false);
        }

        /**
         * This method returns <em>plag hamincha</em>, that is 10.75 * {@link #getShaahZmanisGRA() <em>shaos zmaniyos</em>}
         * (solar hours) after {@link #getSunrise() sunrise} or {@link #getSeaLevelSunrise() sea level sunrise} (depending on
         * the {@link #isUseElevation()} setting), according to the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon"
         * >GRA</a>. <em>Plag hamincha</em> is the earliest time that <em>Shabbos</em> can be started.
         * The day is calculated from {@link #getSeaLevelSunrise() sea level sunrise} to {@link #getSeaLevelSunset() sea level
         * sunset} or {@link #getSunrise() sunrise} to {@link #getSunset() sunset} (depending on the {@link #isUseElevation()}
         * 
         * @see #getPlagHamincha(Instant, Instant, boolean)
         * @see #getPlagHamincha(Instant, Instant)
         * @see ComprehensiveZmanimCalendar#getPlagHaminchaBaalHatanya()
         * @return the <code>Instant</code> of the time of <em>plag hamincha</em>. 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
         *         {@link AstronomicalCalendar} documentation.
         */
        public Instant getPlagHaminchaGRA() {
                return getPlagHamincha(getSunriseBasedOnElevationSetting(), getSunsetBasedOnElevationSetting(), true);
        }

        /**
         * A method that returns a <em>shaah zmanis</em> ({@link #getTemporalHour(Instant, Instant) temporal hour}) according to
         * the opinion of the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>. This calculation divides the day
         * based on the opinion of the <em>GRA</em> that the day runs from {@link #getSeaLevelSunrise() sea level sunrise} to
         * {@link #getSeaLevelSunset() sea level sunset} or {@link #getSunrise() sunrise} to {@link #getSunset() sunset} (depending
         * on the {@link #isUseElevation()} setting). The day is split into 12 equal parts with each one being a <em>shaah zmanis</em>.
         * This method is similar to {@link #getTemporalHour()}, but can account for elevation.
         * 
         * @return the <code>Duration</code> of a <em>shaah zmanis</em> calculated from sunrise to sunset. 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
         *         {@link AstronomicalCalendar} documentation.
         * @see #getTemporalHour(Instant, Instant)
         * @see #getSeaLevelSunrise()
         * @see #getSeaLevelSunset()
         * @see ComprehensiveZmanimCalendar#getShaahZmanisBaalHatanya()
         */
        public Duration getShaahZmanisGRA() {
                return getTemporalHour(getSunriseBasedOnElevationSetting(), getSunsetBasedOnElevationSetting());
        }
        
        /**
         * A utility method to return <em>alos</em> (dawn) or <em>tzais</em> (dusk) based on a fractional day offset. As an
         * example passing 1.5 to this method as done in the {@link ComprehensiveZmanimCalendar#getTzais90Zmanis()} will return
         * the time 90 minutes <em>zmaniyos</em> after {@link #getSunsetBasedOnElevationSetting()}, a <em>zman</em> known as
         * the <em>achtel zman</em> or 1/8th of the length of the day (12 * 60 = 720-minute day / 8 = 90 or 1.5 hours
         * <em>zmaniyos</em>) after sunset.
         * @param hours the number of <em>shaos zmaniyos</em> (temporal hours) before sunrise or after sunset that defines dawn
         *        or dusk. If a negative number is passed in, it will return the time of <em>alos</em> (dawn) (subtracting the
         *        time from sunrise) and if a positive number is passed in, it will return the time of <em>tzais</em> (dusk)
         *        (adding the time to sunset). If 0 is passed in, a <code>null</code> will be returned (since we can't tell if it
         *        is sunrise or sunset based).
         * @return the <code>Instant</code> representing the 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 {@link AstronomicalCalendar}
         *         documentation. A <code>null</code> will also be returned if 0 is passed in, since we can't tell if it is a 
         *         sunrise or sunset based <em>zman</em>.
         * @see <a href="{@docRoot}/search.html?q=ComprehensiveZmanimCalendar%20Zmanis()">ComprehensiveZmanimCalendar...Zmanis()</a>
         * based <em>zmanim</em>.
         */
        public Instant getZmanisBasedOffset(double hours) {
                Duration shaahZmanis = getShaahZmanisGRA();
                if (shaahZmanis == null || hours == 0) {
                        return null;
                }

                long totalNanos = (long) (shaahZmanis.toNanos() * hours);
                Duration offsetDuration = Duration.ofNanos(totalNanos);

                if (hours > 0) {
                        return getTimeOffset(getSunsetBasedOnElevationSetting(), offsetDuration);
                } else {
                        return getTimeOffset(getSunriseBasedOnElevationSetting(), offsetDuration);
                }
        }

        /**
         * A method that returns a <em>shaah zmanis</em> (temporal hour) according to the opinion of the <em><a href=
         * "https://en.wikipedia.org/wiki/Avraham_Gombiner">Magen Avraham (MGA)</a></em> based on a 72-minute <em>alos</em>
         * and <em>tzais</em>. This calculation divides the day that runs from dawn to dusk (for <em>sof zman krias shema</em> and
         * <em>tfila</em>). Dawn for this calculation is 72 minutes before {@link #getSunrise() sunrise} or {@link #getSeaLevelSunrise()
         * sea level sunrise} (depending on the {@link #isUseElevation()} elevation setting) and dusk is 72 minutes after {@link
         * getSunset() sunset} or {@link #getSeaLevelSunset() sea level sunset} (depending on the {@link #isUseElevation()} elevation
         * setting). This day is split into 12 equal parts with each part being a <em>shaah zmanis</em>. Alternate methods of calculating
         * a <em>shaah zmanis</em> according to the Magen Avraham (MGA) are available in the subclass {@link ComprehensiveZmanimCalendar}.
         * 
         * @return the <code>Duration</code> of a <em>shaah zmanis</em>. 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
         *         {@link AstronomicalCalendar} documentation.
         */
        public Duration getShaahZmanis72Minutes() {
                return getTemporalHour(getAlos72Minutes(), getTzais72Minutes());
        }

        /**
         * Default constructor will set a default {@link GeoLocation#GeoLocation()}, a default
         * {@link AstronomicalCalculator#getDefault() AstronomicalCalculator} and default the calendar to the current date.
         * 
         * @see AstronomicalCalendar#AstronomicalCalendar()
         */
        public ZmanimCalendar() {
                super();
        }

        /**
         * A constructor that takes a {@link GeoLocation} as a parameter.
         * 
         * @param location the location
         */
        public ZmanimCalendar(GeoLocation location) {
                super(location);
        }

        /**
         * A method to get the offset in minutes before {@link #getSeaLevelSunset() sea level sunset} which
         * is used in calculating candle lighting time. The default time used is 18 minutes before sea level sunset. Some
         * calendars use 15 minutes, while the custom in Jerusalem is to use a 40-minute offset. Please check the local custom
         * for candle lighting time.
         * 
         * @return Returns the currently set candle lighting offset in minutes.
         * @see #getCandleLighting()
         * @see #setCandleLightingOffset(double)
         */
        public double getCandleLightingOffset() {
                return candleLightingOffset;
        }

        /**
         * A method to set the offset in minutes before {@link #getSeaLevelSunset() sea level sunset} that is
         * used in calculating candle lighting time. The default time used is 18 minutes before sunset. Some calendars use 15
         * minutes, while the custom in Jerusalem is to use a 40-minute offset.
         * 
         * @param candleLightingOffset The candle lighting offset to set in minutes.
         * @see #getCandleLighting()
         * @see #getCandleLightingOffset()
         */
        public void setCandleLightingOffset(double candleLightingOffset) {
                this.candleLightingOffset = candleLightingOffset;
        }
        
        /**
         * This is a utility method to determine if the current Instant passed in has a <em>melacha</em> (work) prohibition.
         * Since there are many opinions on the time of <em>tzais</em>, the <em>tzais</em> for the current day has to be passed to this
         * class. Sunset is the classes current day's {@link #getSunsetBasedOnElevationSetting() elevation adjusted sunset} that observes the
         * {@link #isUseElevation()} settings. The {@link JewishCalendar#getInIsrael()} will be set by the inIsrael parameter.
         * 
         * @param currentTime the current time
         * @param tzais the time of tzais
         * @param inIsrael whether to use Israel holiday scheme or not
         * @return true if <em>melacha</em> is prohibited or false if it is not.
         * @see JewishCalendar#isAssurBemelacha()
         * @see JewishCalendar#hasCandleLighting()
         * @see JewishCalendar#setInIsrael(boolean)
         */
        public boolean isAssurBemelacha(Instant currentTime, Instant tzais, boolean inIsrael) {
                JewishCalendar jewishCalendar = new JewishCalendar();
                jewishCalendar.setGregorianDate(getLocalDate());
                
                jewishCalendar.setInIsrael(inIsrael);
                
                if (jewishCalendar.hasCandleLighting() && currentTime.compareTo(getSunsetBasedOnElevationSetting()) >= 0) { //erev shabbos, YT or YT sheni and after shkiah
                        return true;
                }
                
                //is shabbos or YT and it is before tzais
                return jewishCalendar.isAssurBemelacha() && currentTime.compareTo(tzais) <= 0;
        }
        
        /**
         * A method that returns the <a href="https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi">Baal Hatanya</a>'s <em>netz amiti</em>
         * (sunrise) without {@link AstronomicalCalculator#getElevationAdjustment(double)}. This forms the base for the Baal Hatanya's
         * dawn-based calculations that are calculated as a dip below the horizon before sunrise. According to the Baal Hatanya, <em>netz
         * amiti</em>, or true (halachic) sunrise, is when the top of the sun's disk is visible at an elevation similar to the mountains
         * of Eretz Yisrael. The time is calculated as the point at which the center of the sun's disk is 1.583° below the horizon. This
         * degree-based calculation can be found in Rabbi Shalom DovBer Levine's commentary on The <a href=
         * "https://www.chabadlibrary.org/books/pdf/Seder-Hachnosas-Shabbos.pdf">Baal Hatanya's Seder Hachnasas Shabbos</a>. From an
         * elevation of 546 meters, the top of <a href="https://en.wikipedia.org/wiki/Mount_Carmel">Har Hacarmel</a>, the sun disappears
         * when it is 1° 35' or 1.583° below the sea level horizon. This in turn is based on the Gemara <a href=
         * "https://hebrewbooks.org/shas.aspx?mesechta=2&daf=35">Shabbos 35a</a>. There are other opinions brought down by Rabbi Levine,
         * including Rabbi Yosef Yitzchok Feigelstock who calculates it as the degrees below the horizon 4 minutes after sunset in
         * Yerushalayim (on the equinox). That is brought down as 1.583°. This is identical to the 1° 35' <em>zman</em> and is probably a
         * typo and should be 1.683°. These calculations are used by most <a href="https://en.wikipedia.org/wiki/Chabad">Chabad</a>
         * calendars that use the Baal Hatanya's <em>zmanim</em>. See
         * <a href="https://www.chabad.org/library/article_cdo/aid/3209349/jewish/About-Our-Zmanim-Calculations.htm">About Our
         * <em>Zmanim</em> Calculations @ Chabad.org</a>.
         *
         * Note: <em>netz amiti</em> is used only for calculating certain <em>zmanim</em>, and is intentionally unpublished. For
         * practical purposes, daytime <em>mitzvos</em> like <em>shofar</em> and <em>lulav</em> should not be done until after the
         * published time for <em>netz</em> / sunrise.
         * 
         * @return the <code>Instant</code> representing the exact sea level <em>netz amiti</em> (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 #getSeaLevelSunrise()
         * @see #getSunsetBaalHatanya()
         * @see #ZENITH_1_POINT_583
         */
        protected Instant getSunriseBaalHatanya() {
                return getSunriseOffsetByDegrees(ZENITH_1_POINT_583);
        }
        
        /**
         * A method that returns the <a href="https://en.wikipedia.org/wiki/Shneur_Zalman_of_Liadi">Baal Hatanya</a>'s <em>shkiah
         * amiti</em> (sunset) without {@link AstronomicalCalculator#getElevationAdjustment(double) elevation adjustment}. This forms
         * the base for the Baal Hatanya's dusk-based calculations that are calculated as a dip below the horizon after sunset. According
         * to the Baal Hatanya, <em>shkiah amiti</em>, true (<em>halachic</em>) sunset, is when the top of the sun's disk disappears from
         * view at an elevation similar to the mountains of <em>Eretz Yisrael</em>. This time is calculated as the point at which the
         * center of the sun's disk is 1.583° below the horizon.
         *
         * Note: <em>shkiah amiti</em> is used only for calculating certain <em>zmanim</em>, and is intentionally unpublished. For
         * practical purposes, all daytime mitzvos should be completed before the published time for <em>shkiah</em> / sunset. For further
         * explanation of the calculations used for the Baal Hatanya's <em>zmanim</em> in this library, see <a href=
         * "https://www.chabad.org/library/article_cdo/aid/3209349/jewish/About-Our-Zmanim-Calculations.htm">About Our <em>Zmanim</em>
         * Calculations @ Chabad.org</a>.
         * 
         * @return the <code>Instant</code> representing the exact sea level <em>shkiah amiti</em> (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 {@link
         *         AstronomicalCalendar} documentation.
         * @see #getSunset()
         * @see #getSeaLevelSunset()
         * @see #getSunriseBaalHatanya()
         * @see #ZENITH_1_POINT_583
         */
        protected Instant getSunsetBaalHatanya() {
                return getSunsetOffsetByDegrees(ZENITH_1_POINT_583);
        }

        /**
         * A generic utility method for calculating any <em>shaah zmanis</em> (temporal hour) based <em>zman</em> with the day
         * defined as the start and end of day (or night) and the number of <em>shaos zmaniyos</em> passed to the method. This
         * simplifies the code in other methods such as {@link #getPlagHamincha(Instant, Instant)} and cuts down on code replication.
         * As an example, passing {@link #getSunrise() sunrise} and {@link #getSunset() sunset} or {@link
         * getSeaLevelSunrise() sea level sunrise} and {@link #getSeaLevelSunset() sea level sunset} (depending on the {@link
         * isUseElevation()} elevation setting) and 10.75 hours to this method will return <em>plag mincha</em> according to the
         * opinion of the <a href="https://en.wikipedia.org/wiki/Vilna_Gaon">GRA</a>.
         * 
         * @param startOfDay the start of day for calculating the <em>zman</em>. This can be sunrise or any <em>alos</em> passed to
         *         this method.
         * @param endOfDay the end of day for calculating the <em>zman</em>. This can be sunset or any <em>tzais</em> passed to this
         *         method.
         * @param hours the number of <em>shaos zmaniyos</em> (temporal hours) to offset from the start of day
         * @return the <code>Instant</code> of the time of <em>zman</em> with the <em>shaos zmaniyos</em> (temporal hours)
         *         in the day offset from the start of day passed to this method. 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
         *         {@link AstronomicalCalendar} documentation.
         */
        public Instant getShaahZmanisBasedZman(Instant startOfDay, Instant endOfDay, double hours) {
                Duration shaahZmanis = getTemporalHour(startOfDay, endOfDay);
                if (shaahZmanis == null) { //defensive, should not be needed
                        return null;
                }
                
                long totalNanos = (long) (shaahZmanis.toNanos() * hours);
                return getTimeOffset(startOfDay, Duration.ofNanos(totalNanos));
        }
        
        
        /**
         * A utility method that returns the percentage of a <em>shaah zmanis</em> after sunset (or before sunrise) for a given degree
         * offset. For the <a href="https://kosherjava.com/2022/01/12/equinox-vs-equilux-zmanim-calculations/">equilux</a> where there
         * is a 720-minute day, passing 16.1° for the location of Jerusalem will return about 1.2. This will work for any location or
         * date, but will typically only be of interest at the equinox/equilux to calculate the percentage of a <em>shaah zmanis</em> for
         * those who want to use the <a href="https://en.wikipedia.org/wiki/Abraham_Cohen_Pimentel">Minchas Cohen</a> in Ma'amar 2:4 and
         * the <a href="https://en.wikipedia.org/wiki/Hezekiah_da_Silva">Pri Chadash</a> who calculate <em>tzais</em> as a percentage of
         * the day after sunset. While the Minchas Cohen only applies this to 72 minutes or a 1/10 of the day around the world (based on
         * the equinox / equilux in Israel), this method allows calculations for any degree level for any location.
         * 
         * @param degrees the number of degrees below the horizon after sunset.
         * @param sunset if <code>true</code> the calculation is in degrees after sunset, otherwise it is degrees before sunrise.
         * @return the <code>double</code> percentage of a <em>sha'ah zmanis</em> for a given set of degrees below the astronomical horizon
         *         for the current calendar.  If the calculation can't be computed a {@link Double#MIN_VALUE} will be returned. See detailed
         *         explanation on top of the page.
         */
        public double getPercentOfShaahZmanisFromDegrees(double degrees, boolean sunset) {
                Instant seaLevelSunrise = getSeaLevelSunrise();
                Instant seaLevelSunset = getSeaLevelSunset();
                Instant twilight;
                if (sunset) {
                        twilight = getSunsetOffsetByDegrees(GEOMETRIC_ZENITH + degrees);
                } else {
                        twilight = getSunriseOffsetByDegrees(GEOMETRIC_ZENITH + degrees);
                }
                if (seaLevelSunrise == null || seaLevelSunset == null || twilight == null) {
                        return Double.MIN_VALUE;
                }
                double shaahZmanis = (seaLevelSunset.toEpochMilli() - seaLevelSunrise.toEpochMilli()) / 12.0;
                long riseSetToTwilight;
                if (sunset) {
                        riseSetToTwilight = twilight.toEpochMilli() - seaLevelSunset.toEpochMilli();
                } else {
                        riseSetToTwilight = seaLevelSunrise.toEpochMilli() - twilight.toEpochMilli();
                }
                return riseSetToTwilight / shaahZmanis;
        }
        
        /**
         * A utility method to calculate <em>zmanim</em> based on <a href="https://en.wikipedia.org/wiki/Moshe_Feinstein">Rav Moshe
         * Feinstein</a> and others as calculated in <a href="https://en.wikipedia.org/wiki/Mesivtha_Tifereth_Jerusalem">MTJ</a>, <a href=
         * "https://en.wikipedia.org/wiki/Mesivtha_Tifereth_Jerusalem">Yeshiva of Staten Island</a>, and Camp Yeshiva
         * of Staten Island and other calendars. The day is split in two, from <em>alos</em> / sunrise to <em>chatzos</em>, and the
         * second half of the day, from <em>chatzos</em> to sunset / <em>tzais</em>. Morning based times are calculated. based on the first
         * 6 hours of the day, and afternoon times based on the second half of the day. As an example, passing 0.5, a start of
         * <em>chatzos</em> and an end of day as sunset will return the time of <em>mincha gedola</em> GRA as half an hour <em>zmanis</em>
         * based on the second half of the day. Some <em>zmanim</em> calculations can be based on subtracting <em>shaos zmaniyos</em>
         * from the end of the day, and that is supported by passing a negative hour to this method.
         * 
         * @param startOfHalfDay The start of the half day. This would be <em>alos</em> or sunrise for morning based times such as
         *         <em>sof zman krias shema</em> and <em>chatzos</em> for afternoon based times such as <em>mincha gedola</em>.
         * @param endOfHalfDay The end of the half day. This would be <em>chatzos</em> for morning based times  such as <em>sof zman
         *         krias shema</em>  and sunset or <em>tzais</em> for afternoon based times such as <em>mincha gedola</em>.
         * @param hours The number of <em>shaos zmaniyos</em> (hours) to offset the beginning of the first or second half of the day. For
         *         example, 3 for <em>sof zman Shma</em>, 0.5 for <em>mincha gedola</em> (half an hour after <em>chatzos</em>) and 4.75
         *         for <em>plag hamincha</em>. If the number of hours is negative, it will subtract the number of <em>shaos zmaniyos</em>
         *         from the end of the day.
         * @return the <code>Instant</code> of <em>zman</em> based on calculation of the first or second half of the day. 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 {@link AstronomicalCalendar} documentation.
         * @see ComprehensiveZmanimCalendar#getFixedLocalChatzosHayom()
         */
        public Instant getHalfDayBasedZman(Instant startOfHalfDay, Instant endOfHalfDay, double hours) {
                if (startOfHalfDay == null || endOfHalfDay == null) {
                        return null;
                }
                Duration shaahZmanis = getHalfDayBasedShaahZmanis(startOfHalfDay, endOfHalfDay);
                if (shaahZmanis == null) { //defensive, should not be needed
                        return null;
                }
                
                long totalNanos = (long)(shaahZmanis.toNanos() * hours);
                Duration offsetDuration = Duration.ofNanos(totalNanos);
                
                if (hours >= 0) { // forward from start of day
                        return getTimeOffset(startOfHalfDay, offsetDuration);
                } else { // subtract from end of day
                        return getTimeOffset(endOfHalfDay, offsetDuration);
                }
        }
        
        /**
         * A utility method to calculate the length of a <em>sha'ah zmanis</em> based on 1/6 of a 6-hour day.
         * @param startOfHalfDay The start of the half-day. This would be <em>alos</em> or sunrise for the first half of the day, or
         *         <em>chatzos</em> for the second half of the day.
         * @param endOfHalfDay The end of the half-day. This would be <em>chatzos</em> for the first half of the day, or sunset or
         *         <em>tzais</em> for the second half of the day.
         * @return The <code>Duration</code> of a <em>shaah zmanis</em> based on 1/6 of a half-day. 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 {@link AstronomicalCalendar}
         *         documentation.
         * @see #getHalfDayBasedZman(Instant, Instant, double)
         * @see #isUseAstronomicalChatzosForOtherZmanim()
         * @todo Consider adjusting various shaah zmanis times to use this.
         */
        public Duration getHalfDayBasedShaahZmanis(Instant startOfHalfDay, Instant endOfHalfDay) {
                if (startOfHalfDay == null || endOfHalfDay == null) {
                        return null;
                }
                return Duration.between(startOfHalfDay, endOfHalfDay).dividedBy(6);
        }
        
        /**
         * @see java.lang.Object#equals(Object)
         */
        public boolean equals(Object object) {
                if (this == object) {
                        return true;
                }
                if (object == null || getClass() != object.getClass()) {
                        return false;
                }
                if (!super.equals(object)) {
                        return false;
                }
                ZmanimCalendar that = (ZmanimCalendar) object;
                return useElevation == that.useElevation
                                && useAstronomicalChatzos == that.useAstronomicalChatzos
                                && useAstronomicalChatzosForOtherZmanim == that.useAstronomicalChatzosForOtherZmanim
                                && candleLightingOffset == that.candleLightingOffset;
        }

        /**
         * @see java.lang.Object#hashCode()
         */
        public int hashCode() {
                return Objects.hash(super.hashCode(), useElevation, useAstronomicalChatzos,
                                useAstronomicalChatzosForOtherZmanim, Double.hashCode(candleLightingOffset));
        }
}