Solar conventions and entry points: standard altitudes, twilight constants, and the transit-centered API wired to the Sun's ephemeris. More...

Functions
auto	h0_from (const astro::earth::refraction::Params &p={}) -> toolbox::AngleDeg
	Convert atmospheric conditions to the sunrise/sunset altitude convention.
auto	transit_jde (const std::chrono::year_month_day &ymd_ut1, const GeoLocation &location) -> double
	Compute the instant of the Sun's upper culmination (solar transit / solar noon) on a date.
auto	rise_set_jde (const double transit_jde_tt, const bool is_rise, const GeoLocation &location, const toolbox::AngleDeg &h0=STANDARD_ALTITUDE) -> std::optional< double >
	Compute the instant at which the Sun crosses altitude h₀, before (sunrise) or after (sunset) a given transit.
auto	calculate (const std::chrono::year_month_day &ymd_ut1, const GeoLocation &location, const toolbox::AngleDeg &h0=STANDARD_ALTITUDE) -> Result
	Compute sunrise, transit, and sunset for a date and location.

Variables
constexpr auto	STANDARD_ALTITUDE
	The standard altitude of the Sun's center at rise/set: -0°50' = -0.8333…°.
constexpr toolbox::AngleDeg	CIVIL_TWILIGHT
	The Sun's altitude at civil twilight: -6°.
constexpr toolbox::AngleDeg	NAUTICAL_TWILIGHT
	The Sun's altitude at nautical twilight: -12°.
constexpr toolbox::AngleDeg	ASTRONOMICAL_TWILIGHT
	The Sun's altitude at astronomical twilight: -18°.
constexpr auto	provider
	The Sun's position provider: apparent equatorial coordinates at one instant (TT).

Detailed Description

Solar conventions and entry points: standard altitudes, twilight constants, and the transit-centered API wired to the Sun's ephemeris.

Function Documentation

◆ calculate()

auto astro::rise_set::sun::calculate	(	const std::chrono::year_month_day &	ymd_ut1,
		const GeoLocation &	location,
		const toolbox::AngleDeg &	h0 = STANDARD_ALTITUDE )->Result

inlinenodiscard

Compute sunrise, transit, and sunset for a date and location.

Parameters

ymd_ut1	The date, interpreted on the UT1 scale (callers handle time zones).
location	The observer's location.
h0	The event altitude. Defaults to STANDARD_ALTITUDE; pass a twilight constant to compute dawn/dusk instead.

Returns: The three instants (JDE, TT scale) and the polar topology; see Result's notes for the exact semantics.

Exceptions

std::invalid_argument	If ymd_ut1 is invalid, location is out of range, or h0 is not finite or outside [-90°, 90°], or a time conversion leaves its supported years.
std::runtime_error	For a transit or rise/set residual-guard failure.

Note: Consumer trap (deliberate semantics): because ymd_ut1 is a UT1 date, for eastern longitudes the returned sunrise can fall on the previous UT1 calendar day (e.g. Beijing's sunrise is ~21-22h UT of ymd_ut1 - 1); callers building a local calendar day must convert with their time zone, not assume all three instants share ymd_ut1.

◆ h0_from()

auto astro::rise_set::sun::h0_from ( const astro::earth::refraction::Params & p = {} ) ->toolbox::AngleDeg

inlinenodiscard

Convert atmospheric conditions to the sunrise/sunset altitude convention.

Parameters

p	The atmospheric refraction parameters. Defaults to 15°C/1013.25 hPa/Bennett.

Returns: The geometric altitude of the Sun's center that makes the Sun's upper limb appear at the horizon: −(horizon refraction + 16′).

Exceptions

std::invalid_argument If p contains non-finite, non-positive pressure, or temperature at or below −273°C. For Model::SAEMUNDSSON, may throw std::runtime_error if the horizon iteration does not converge.

Note: The default parameters reproduce STANDARD_ALTITUDE to within 0.02′.

◆ rise_set_jde()

auto astro::rise_set::sun::rise_set_jde	(	const double	transit_jde_tt,
		const bool	is_rise,
		const GeoLocation &	location,
		const toolbox::AngleDeg &	h0 = STANDARD_ALTITUDE )->std::optional< double >

inlinenodiscard

Compute the instant at which the Sun crosses altitude h₀, before (sunrise) or after (sunset) a given transit.

Parameters

transit_jde_tt	The transit instant, as a julian ephemeris day on the TT scale (from transit_jde).
is_rise	True for the upward crossing before transit, false for the downward crossing after it.
location	The observer's location.
h0	The crossing altitude. Defaults to STANDARD_ALTITUDE; pass a twilight constant for dawn/dusk instants.

Returns: The crossing instant (JDE, TT scale), or nullopt on polar day/night.

Exceptions

std::invalid_argument / std::runtime_error See the generic rise_set_jde.

◆ transit_jde()

auto astro::rise_set::sun::transit_jde	(	const std::chrono::year_month_day &	ymd_ut1,
		const GeoLocation &	location )->double

inlinenodiscard

Compute the instant of the Sun's upper culmination (solar transit / solar noon) on a date.

Parameters

ymd_ut1	The date, interpreted on the UT1 scale (not local civil time — callers handle time zones). The returned transit is the one nearest 12h local mean time on this date.
location	The observer's location.

Returns: The transit instant, as a julian ephemeris day on the TT scale.

Exceptions

std::invalid_argument	If ymd_ut1 is invalid, location is out of range, or a time conversion leaves its supported years.
std::runtime_error	If the transit solve fails its residual guard.

Note: The estimate is local mean noon; the bracket around it is one the equation of time can never escape (see TRANSIT_BRACKET_HALF_WIDTH_DAYS).

Variable Documentation

◆ ASTRONOMICAL_TWILIGHT

toolbox::AngleDeg astro::rise_set::sun::ASTRONOMICAL_TWILIGHT

inlineconstexpr

The Sun's altitude at astronomical twilight: -18°.

◆ CIVIL_TWILIGHT

toolbox::AngleDeg astro::rise_set::sun::CIVIL_TWILIGHT

inlineconstexpr

The Sun's altitude at civil twilight: -6°.

◆ NAUTICAL_TWILIGHT

toolbox::AngleDeg astro::rise_set::sun::NAUTICAL_TWILIGHT

inlineconstexpr

The Sun's altitude at nautical twilight: -12°.

◆ provider

auto astro::rise_set::sun::provider

inlineconstexpr

The Sun's position provider: apparent equatorial coordinates at one instant (TT).

◆ STANDARD_ALTITUDE

auto astro::rise_set::sun::STANDARD_ALTITUDE

inlineconstexpr

The standard altitude of the Sun's center at rise/set: -0°50' = -0.8333…°.

Note: Meeus Chapter 15: -34' of standard atmospheric refraction at the horizon, plus -16' so that the event refers to the Sun's upper limb, not its center.

Functions

Variables

Detailed Description

Function Documentation

◆ calculate()

◆ h0_from()

◆ rise_set_jde()

◆ transit_jde()

Variable Documentation

◆ ASTRONOMICAL_TWILIGHT

◆ CIVIL_TWILIGHT

◆ NAUTICAL_TWILIGHT

◆ provider

◆ STANDARD_ALTITUDE