Namespaces
namespace	literals

Classes
struct	Angle
	Represents an angle. More...
struct	Distance
	Represents a distance. More...
struct	SphericalCoordinate
	Represents a position in a spherical coordinate system. More...
struct	GoldenSectionRules
	Arithmetic, comparison and stopping rules supplied by an extremum-search caller. More...
struct	GoldenSectionBracket
	The final bracket; converged is false when the update budget runs out. More...

Typedefs
using	AngleDeg
	An angle measured in degrees.
using	AngleRad
using	DistanceAu
	A distance measured in astronomical units; see AngleDeg for the alias convention.
using	DistanceKm

Enumerations
enum class	AngleUnit : uint8_t { RAD , DEG }
enum class	DistanceUnit : uint8_t { AU , KM }
	The unit of distance, either AU or KM. More...

Functions
constexpr auto	normalize_deg (const double deg) -> double
	Normalize degree to [0, 360).
constexpr auto	normalize_rad (const double rad) -> double
	Normalize radian to [0, 2π).
constexpr auto	normalize_pm180 (const double deg) -> double
	Normalize degree to [-180, 180). Useful for hour angles, where sign carries meaning.
auto	remainder_deg (const double difference_deg) -> double
	Return the IEEE remainder in [-180°, 180°], retaining signed zero and either sign at 180°.
auto	unwrap_near (const double wrapped_deg, const double reference_deg) -> double
	Shift an angle by whole turns toward a reference, without normalizing either input.
constexpr auto	deg_to_rad (const double deg) -> double
	Convert degree to radian.
constexpr auto	rad_to_deg (const double rad) -> double
	Convert radian to degree.
constexpr auto	arcmin_to_deg (const double arcmin) -> double
	Convert minutes to degrees.
constexpr auto	arcsec_to_deg (const double arcsec) -> double
	Convert seconds to degrees.
auto	canonical_longitude_difference (const AngleDeg difference) -> AngleDeg
	Canonicalize a finite directed longitude difference to (-180, 180] degrees.
constexpr auto	au_to_km (const double au) -> double
	Convert from AU to KM.
constexpr auto	km_to_au (const double km) -> double
	Convert from KM to AU.
auto	ulp (const double x) -> double
	The gap between x and the next representable double — one unit in the last place.
template<typename Func> requires std::invocable<const Func&, double> and std::convertible_to<std::invoke_result_t<const Func&, double>, double>
auto	newton_method (const Func &f, const double start_jde, const double end_jde, const double mean_rate_deg_per_day, const std::size_t max_iterations=NEWTON_MAX_ITERATIONS) -> double
	Apply Newton's method to find the JDE at which f crosses zero.
template<typename Func, typename Rules> requires std::invocable<const Func&, double> and std::convertible_to<std::invoke_result_t<const Func&, double>, double>
auto	golden_section_bracket (const Func &f, const double lower, const double upper, const double tolerance, const std::size_t maximum_updates, const Rules &rules) -> GoldenSectionBracket
	Contract a unimodal bracket using the caller's numerical rules.

Variables
constexpr double	DEG_PER_RAD
	The number of degrees in a radian.
constexpr double	LONGITUDE_PERIOD_DEG
	The angular period of an ecliptic longitude, in degrees.
constexpr double	SIDEREAL_RATE_DEG_PER_DAY
	The mean angular rate of Earth's rotation relative to the stars, in degrees per day. Used to convert between time offsets and hour angle offsets.
constexpr double	SOLAR_MEAN_MOTION_DEG_PER_DAY
	The Sun's mean apparent motion along the ecliptic, in degrees per day. A tropical year of 365.2422 days carries it through a full 360°.
constexpr double	MOON_ELONGATION_RATE_DEG_PER_DAY
	The mean rate at which the Moon's apparent longitude pulls away from the Sun's, in degrees per day. A synodic month of 29.530588853 days closes a full 360°.
constexpr uint32_t	MIN_PER_DEG
	The number of minutes in a degree.
constexpr uint32_t	SEC_PER_MIN
	The number of seconds in a minute.
constexpr uint32_t	SEC_PER_DEG
	The number of seconds in a degree.
constexpr double	AU_KM_SCALE
	The scaling factor from AU to KM.
constexpr double	NEWTON_INITIAL_STEP_DAYS
	The initial half-width of the central difference approximating f', in days.
constexpr double	NEWTON_MIN_STEP_ULP
	The floor on that half-width, as a multiple of ulp(jde).
constexpr double	NEWTON_RESIDUAL_TOL_ULP
	The residual tolerance, as a multiple of the angle swept during one ulp(jde).
constexpr std::size_t	NEWTON_MAX_ITERATIONS
	The Newton iteration budget.
constexpr double	INV_PHI
	(√5 − 1)/2, rounded directly to binary64.
constexpr double	INV_PHI_SQ
	(3 − √5)/2, rounded independently of INV_PHI.

Typedef Documentation

◆ AngleDeg

using astro::toolbox::AngleDeg

An angle measured in degrees.

Note: Angle<DEG> needs both names in scope, which outside astro::toolbox only a namespace-scope using can arrange — and headers may not have one (#51). These aliases keep the unit in the type name without asking the reader's namespace for anything: toolbox::AngleDeg.

◆ AngleRad

using astro::toolbox::AngleRad

◆ DistanceAu

using astro::toolbox::DistanceAu

A distance measured in astronomical units; see AngleDeg for the alias convention.

◆ DistanceKm

using astro::toolbox::DistanceKm

Enumeration Type Documentation

◆ AngleUnit

enum class astro::toolbox::AngleUnit : uint8_t

strong

the angle's unit, either degree or radian.

Enumerator
RAD
DEG

◆ DistanceUnit

enum class astro::toolbox::DistanceUnit : uint8_t

strong

The unit of distance, either AU or KM.

Enumerator
AU
KM

Function Documentation

◆ arcmin_to_deg()

auto astro::toolbox::arcmin_to_deg ( const double arcmin ) ->double

nodiscardconstexpr

Convert minutes to degrees.

◆ arcsec_to_deg()

auto astro::toolbox::arcsec_to_deg ( const double arcsec ) ->double

nodiscardconstexpr

Convert seconds to degrees.

◆ au_to_km()

auto astro::toolbox::au_to_km ( const double au ) ->double

nodiscardconstexpr

Convert from AU to KM.

◆ canonical_longitude_difference()

auto astro::toolbox::canonical_longitude_difference ( const AngleDeg difference ) ->AngleDeg

inlinenodiscard

Canonicalize a finite directed longitude difference to (-180, 180] degrees.

Exceptions

std::invalid_argument If the angle is not finite.

See also: normalize_pm180 for [-180°, 180°); remainder_deg for signed zero and even-quotient ties.

◆ deg_to_rad()

auto astro::toolbox::deg_to_rad ( const double deg ) ->double

nodiscardconstexpr

Convert degree to radian.

◆ golden_section_bracket()

template<typename Func, typename Rules>
requires std::invocable<const Func&, double> and std::convertible_to<std::invoke_result_t<const Func&, double>, double>

auto astro::toolbox::golden_section_bracket	(	const Func &	f,
		const double	lower,
		const double	upper,
		const double	tolerance,
		const std::size_t	maximum_updates,
		const Rules &	rules )->GoldenSectionBracket

inlinenodiscard

Contract a unimodal bracket using the caller's numerical rules.

Parameters

f	The objective, evaluated at two initial probes even when maximum_updates is zero.
lower	The initial lower bound.
upper	The initial upper bound.
tolerance	The width threshold passed to rules.finished.
maximum_updates	The contraction budget, excluding the two initial probes.
rules	The lower-probe arithmetic, move-lower comparison and width stopping predicate.

Returns: The final bounds and whether rules.finished accepted them.

Note: The stopping predicate is checked before each update, never after the final allowed update. Midpoint selection, witnesses and the meaning of budget exhaustion belong to the caller.

◆ km_to_au()

auto astro::toolbox::km_to_au ( const double km ) ->double

nodiscardconstexpr

Convert from KM to AU.

◆ newton_method()

template<typename Func>
requires std::invocable<const Func&, double> and std::convertible_to<std::invoke_result_t<const Func&, double>, double>

auto astro::toolbox::newton_method	(	const Func &	f,
		const double	start_jde,
		const double	end_jde,
		const double	mean_rate_deg_per_day,
		const std::size_t	max_iterations = NEWTON_MAX_ITERATIONS )->double

inlinenodiscard

Apply Newton's method to find the JDE at which f crosses zero.

Parameters

f	The function to find the root of. Must be smooth over [start_jde, end_jde) — callers that work with a wrapping angle are responsible for unwrapping it first.
start_jde	The left bound of the search, inclusive.
end_jde	The right bound of the search, exclusive.
mean_rate_deg_per_day	The mean rate at which f sweeps. This sets the scale of the residual tolerance; it is not used as the derivative.
max_iterations	The iteration budget.

Returns: The JDE of the root, always within [start_jde, end_jde).

Note: It is the caller's responsibility to ensure a root exists in the range.

◆ normalize_deg()

auto astro::toolbox::normalize_deg ( const double deg ) ->double

nodiscardconstexpr

Normalize degree to [0, 360).

Exceptions

std::invalid_argument If deg is not finite — a non-finite angle has no normal form, and returning one would pass it off as already normalized (#88).

◆ normalize_pm180()

auto astro::toolbox::normalize_pm180 ( const double deg ) ->double

nodiscardconstexpr

Normalize degree to [-180, 180). Useful for hour angles, where sign carries meaning.

Exceptions

std::invalid_argument If deg is not finite — inherited from normalize_deg.

See also: remainder_deg for signed zero and even-quotient ties; canonical_longitude_difference for (-180°, 180°].

◆ normalize_rad()

auto astro::toolbox::normalize_rad ( const double rad ) ->double

nodiscardconstexpr

Normalize radian to [0, 2π).

Exceptions

std::invalid_argument If rad is not finite.

Note: Twin of normalize_deg — same three edges, same order; the reasoning is written out there.

◆ rad_to_deg()

auto astro::toolbox::rad_to_deg ( const double rad ) ->double

nodiscardconstexpr

Convert radian to degree.

◆ remainder_deg()

auto astro::toolbox::remainder_deg ( const double difference_deg ) ->double

inlinenodiscard

Return the IEEE remainder in [-180°, 180°], retaining signed zero and either sign at 180°.

Note: Half-turn ties use the even quotient. Non-finite inputs follow std::remainder's domain behavior.

See also: normalize_pm180 for [-180°, 180°); canonical_longitude_difference for (-180°, 180°].

◆ ulp()

auto astro::toolbox::ulp ( const double x ) ->double

inlinenodiscard

The gap between x and the next representable double — one unit in the last place.

Parameters

x	The value to measure at.

Returns: The ulp at x, always positive.

Note: Doubles carry 52 fraction bits, so the ulp doubles every time the exponent does. At JDE 2451545 (J2000.0) it is 4.7e-10 day (~40 μs); once jde crosses 2^22 = 4194304 — that is 6771-07-07 — it steps up to 9.3e-10 day.

◆ unwrap_near()

auto astro::toolbox::unwrap_near	(	const double	wrapped_deg,
		const double	reference_deg )->double

inlinenodiscard

Shift an angle by whole turns toward a reference, without normalizing either input.

Note: Half-turn ties follow std::round (away from zero); the arithmetic does not validate finiteness.

Variable Documentation

◆ AU_KM_SCALE

double astro::toolbox::AU_KM_SCALE

inlineconstexpr

The scaling factor from AU to KM.

See also: NIST SP 330 (2019), Table 8: the astronomical unit is exactly 149'597'870'700 m.; ERFA v2.0.1 erfam.h, ERFA_DAU.

◆ DEG_PER_RAD

double astro::toolbox::DEG_PER_RAD

inlineconstexpr

The number of degrees in a radian.

◆ INV_PHI

double astro::toolbox::INV_PHI

inlineconstexpr

(√5 − 1)/2, rounded directly to binary64.

◆ INV_PHI_SQ

double astro::toolbox::INV_PHI_SQ

inlineconstexpr

(3 − √5)/2, rounded independently of INV_PHI.

◆ LONGITUDE_PERIOD_DEG

double astro::toolbox::LONGITUDE_PERIOD_DEG

inlineconstexpr

The angular period of an ecliptic longitude, in degrees.

◆ MIN_PER_DEG

uint32_t astro::toolbox::MIN_PER_DEG

inlineconstexpr

The number of minutes in a degree.

◆ MOON_ELONGATION_RATE_DEG_PER_DAY

double astro::toolbox::MOON_ELONGATION_RATE_DEG_PER_DAY

inlineconstexpr

The mean rate at which the Moon's apparent longitude pulls away from the Sun's, in degrees per day. A synodic month of 29.530588853 days closes a full 360°.

Note: This is a mean rate — near perigee the Moon runs at roughly 1.2× this value.

◆ NEWTON_INITIAL_STEP_DAYS

double astro::toolbox::NEWTON_INITIAL_STEP_DAYS

inlineconstexpr

The initial half-width of the central difference approximating f', in days.

◆ NEWTON_MAX_ITERATIONS

std::size_t astro::toolbox::NEWTON_MAX_ITERATIONS

inlineconstexpr

The Newton iteration budget.

◆ NEWTON_MIN_STEP_ULP

double astro::toolbox::NEWTON_MIN_STEP_ULP

inlineconstexpr

The floor on that half-width, as a multiple of ulp(jde).

◆ NEWTON_RESIDUAL_TOL_ULP

double astro::toolbox::NEWTON_RESIDUAL_TOL_ULP

inlineconstexpr

The residual tolerance, as a multiple of the angle swept during one ulp(jde).

Note: About as tight as it goes — f bottoms out near half an ulp's worth.

◆ SEC_PER_DEG

uint32_t astro::toolbox::SEC_PER_DEG

inlineconstexpr

The number of seconds in a degree.

◆ SEC_PER_MIN

uint32_t astro::toolbox::SEC_PER_MIN

inlineconstexpr

The number of seconds in a minute.

◆ SIDEREAL_RATE_DEG_PER_DAY

double astro::toolbox::SIDEREAL_RATE_DEG_PER_DAY

inlineconstexpr

The mean angular rate of Earth's rotation relative to the stars, in degrees per day. Used to convert between time offsets and hour angle offsets.

See also: Jean Meeus, "Astronomical Algorithms", Ch.12.

◆ SOLAR_MEAN_MOTION_DEG_PER_DAY

double astro::toolbox::SOLAR_MEAN_MOTION_DEG_PER_DAY

inlineconstexpr

The Sun's mean apparent motion along the ecliptic, in degrees per day. A tropical year of 365.2422 days carries it through a full 360°.

Note: This is a mean rate — the true rate varies by about ±1.7% over a year, since Earth's orbit is an ellipse and perihelion passage is faster than aphelion passage.

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

◆ AngleDeg

◆ AngleRad

◆ DistanceAu

◆ DistanceKm

Enumeration Type Documentation

◆ AngleUnit

◆ DistanceUnit

Function Documentation

◆ arcmin_to_deg()

◆ arcsec_to_deg()

◆ au_to_km()

◆ canonical_longitude_difference()

◆ deg_to_rad()

◆ golden_section_bracket()

◆ km_to_au()

◆ newton_method()

◆ normalize_deg()

◆ normalize_pm180()

◆ normalize_rad()

◆ rad_to_deg()

◆ remainder_deg()

◆ ulp()

◆ unwrap_near()

Variable Documentation

◆ AU_KM_SCALE

◆ DEG_PER_RAD

◆ INV_PHI

◆ INV_PHI_SQ

◆ LONGITUDE_PERIOD_DEG

◆ MIN_PER_DEG

◆ MOON_ELONGATION_RATE_DEG_PER_DAY

◆ NEWTON_INITIAL_STEP_DAYS

◆ NEWTON_MAX_ITERATIONS

◆ NEWTON_MIN_STEP_ULP

◆ NEWTON_RESIDUAL_TOL_ULP

◆ SEC_PER_DEG

◆ SEC_PER_MIN

◆ SIDEREAL_RATE_DEG_PER_DAY

◆ SOLAR_MEAN_MOTION_DEG_PER_DAY