Fixed-grid root isolation and conditional numerical certification. More...

#include <algorithm>
#include <array>
#include <cmath>
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <format>
#include <limits>
#include <numeric>
#include <optional>
#include <ranges>
#include <span>
#include <stdexcept>
#include <type_traits>
#include <vector>
#include "toolbox.hpp"

Classes
struct	astro::detail::event_search::Value
	A scalar observation with an absolute error allowance at the requested abscissa. More...
struct	astro::detail::event_search::LongitudeValue
	A longitude observation with an absolute circular error allowance in degrees. More...
struct	astro::detail::event_search::Sample
	A scalar observation whose allowance applies at the requested TT time. More...
struct	astro::detail::event_search::Bounds
	Uniform absolute first- and second-derivative bounds on a closed cell. More...
struct	astro::detail::event_search::Budget
	Shared limits on scalar-evaluation attempts and candidate slots. More...
struct	astro::detail::event_search::Cell
	A sampled bracket with an explicit rule for including exact endpoint roots. More...
struct	astro::detail::event_search::Candidate
	A retained bracket, either certified to contain one root or left unresolved. More...
struct	astro::detail::event_search::Root
	A reported TT root time and its certified local crossing direction. More...
struct	astro::detail::event_search::LongitudeRoot
	A longitude-level event, including a contact at a canonical numerical station. More...
struct	astro::detail::event_search::TrajectoryBounds
	Uniform smooth-longitude and D_h derivative bounds, with their absolute rate discrepancy. More...
struct	astro::detail::event_search::Interval
	A nonempty half-open interval in JDE(TT). More...
struct	astro::detail::event_search::NumericalContact
	A canonical contact and the entire certified extremum region it replaces. More...
struct	astro::detail::event_search::Grid
	A query-independent cell partition; the provider must cover its closed domain. More...
struct	astro::detail::event_search::StationContact
	A station's reported TT instant and contact outcome; an uncertified one has no two-sided region. More...
struct	astro::detail::event_search::RegionDirection
	A contact region's certified direction, if any; crosses_level marks a level sign change across it. More...

Namespaces
namespace	astro
namespace	astro::detail
namespace	astro::detail::event_search

Enumerations
enum class	astro::detail::event_search::ContactDirection : uint8_t { astro::detail::event_search::INCREASING , astro::detail::event_search::DECREASING , astro::detail::event_search::TANGENT }
	The level's direction across a canonical stationary contact, not the sign of its rate at that time. More...
enum class	astro::detail::event_search::Isolation : uint8_t { astro::detail::event_search::UNIQUE , astro::detail::event_search::UNRESOLVED }
	Whether a retained bracket has a unique-root certificate or remains unresolved. More...
enum class	astro::detail::event_search::EndpointOwnership : uint8_t { astro::detail::event_search::LEFT , astro::detail::event_search::BOTH }
	Exact endpoint roots belong to [left,right) for LEFT, or [left,right] for BOTH. More...
enum class	astro::detail::event_search::CellDecision : uint8_t { astro::detail::event_search::DISCARD , astro::detail::event_search::UNIQUE , astro::detail::event_search::SPLIT }
	A sufficient cell verdict: exclude, certify one root, or subdivide. More...

Functions
auto	astro::detail::event_search::lower (const double value) -> double
	Enclose a nearest-rounded result on its lower side.
auto	astro::detail::event_search::upper (const double value) -> double
	Enclose a nearest-rounded result on its upper side.
auto	astro::detail::event_search::finite_nonnegative (const double value) -> bool
	Test whether a scalar is finite and nonnegative.
auto	astro::detail::event_search::magnitude_floor (const Value evaluated) -> double
	Bound an observation's absolute magnitude from below; the bound may be negative.
auto	astro::detail::event_search::exact_zero (const Value evaluated) -> bool
	Recognize a certified zero, not merely a zero-valued observation.
auto	astro::detail::event_search::sign (const Value evaluated) -> int32_t
	Return a robust sign, or zero when the allowance includes zero.
auto	astro::detail::event_search::shifted (const Value evaluated, const double offset, const double first_derivative) -> Value
	Adjust a provider's error allowance when it evaluates at a different abscissa.
template<typename Provider> requires std::invocable<const Provider&, double> and std::same_as<std::invoke_result_t<const Provider&, double>, Value>
auto	astro::detail::event_search::sample (const Provider &provider, const double jde_tt, Budget &budget) -> Sample
	Charge an evaluation even if the provider fails.
auto	astro::detail::event_search::derivative_floor (const Sample left, const Sample right, const Bounds bounds) -> double
	Bound \|f'\| from below using the noisy secant and the curvature bound.
auto	astro::detail::event_search::valid_time_span (const double start_jde_tt, const double end_jde_tt) -> bool
	Test finite, strictly ordered TT endpoints whose difference is finite.
auto	astro::detail::event_search::validate_cell (const double start_jde_tt, const double end_jde_tt, const Bounds bounds) -> void
	Require a finite positive time span and finite nonnegative derivative bounds.
auto	astro::detail::event_search::endpoint_exclusion (const Cell &cell, const Bounds bounds) -> bool
	Test sufficient endpoint conditions for a cell to contain no root.
auto	astro::detail::event_search::classify_cell (const Cell &cell, const Bounds bounds) -> CellDecision
	Certify exclusion or uniqueness; otherwise request subdivision.
auto	astro::detail::event_search::append_candidate (const Cell &cell, const Isolation isolation, Budget &budget, std::vector< Candidate > &candidates) -> void
	Consume one candidate slot before retaining a bracket.
template<typename Provider> requires std::invocable<const Provider&, double> and std::same_as<std::invoke_result_t<const Provider&, double>, Value>
auto	astro::detail::event_search::visit_cell (const Provider &provider, const Cell &cell, const Bounds bounds, Budget &budget, const uint32_t depth, std::vector< Candidate > &candidates) -> void
	Traverse a sampled cell, retaining unresolved brackets when subdivision stops.
template<typename Provider> requires std::invocable<const Provider&, double> and std::same_as<std::invoke_result_t<const Provider&, double>, Value>
auto	astro::detail::event_search::isolate_cell (const Provider &provider, const double start_jde_tt, const double end_jde_tt, const Bounds bounds, Budget &budget, const EndpointOwnership ownership=EndpointOwnership::LEFT, const uint32_t maximum_depth=32) -> std::vector< Candidate >
	Isolate a C2 scalar on a fixed canonical cell, not a query-clipped cell.
auto	astro::detail::event_search::project_longitude_difference (const LongitudeValue first, const LongitudeValue second) -> Value
	Observe first minus second modulo 360 degrees, including subtraction roundoff.
auto	astro::detail::event_search::longitude_residual (const LongitudeValue observed, const toolbox::AngleDeg target) -> Value
	Return a scalar level residual only when its observation cannot straddle the antipodal cut.
auto	astro::detail::event_search::curvature_sign (const Sample left, const Sample middle, const Sample right, const double third_derivative) -> int32_t
	Certify one sign of f'' throughout three observations' span; zero means unresolved.
auto	astro::detail::event_search::contact_direction (const LongitudeValue at_station, const toolbox::AngleDeg target, const Value before, const Value after, const int32_t curvature) -> ContactDirection
	Classify an exact numerical contact from certified observations on both sides.
template<typename Provider> requires std::invocable<const Provider&, double> and std::same_as<std::invoke_result_t<const Provider&, double>, LongitudeValue>
auto	astro::detail::event_search::isolate_longitude_cell (const Provider &provider, const toolbox::AngleDeg target, const Interval cell, const Bounds bounds, Budget &budget, const EndpointOwnership ownership=EndpointOwnership::LEFT) -> std::vector< Candidate >
	Isolate longitude-level roots after excluding distant cells or certifying a continuous scalar lift.
auto	astro::detail::event_search::resolves_sample (const double minimum_slope, const Sample observed, const double time_resolution) -> bool
	Decide whether an observation ends refinement.
template<typename Provider> requires std::invocable<const Provider&, double> and std::same_as<std::invoke_result_t<const Provider&, double>, Value>
auto	astro::detail::event_search::refine_bracket (const Provider &provider, const Candidate &candidate, const double minimum_slope, Budget &budget, const double time_resolution, const uint32_t maximum_iterations) -> Root
	Bisect a unique-root bracket with robust signs and bounded work.
template<typename Provider> requires std::invocable<const Provider&, double> and std::same_as<std::invoke_result_t<const Provider&, double>, Value>
auto	astro::detail::event_search::refine (const Provider &provider, const Candidate &candidate, const Bounds bounds, Budget &budget, const double time_resolution=0.0, const uint32_t maximum_iterations=96) -> Root
	Refine a certified unique root to the requested time resolution or adjacent doubles.
auto	astro::detail::event_search::grid_time (const Grid grid, const uint32_t index, const uint32_t cell_count) -> double
	Return a stored grid boundary, with the first and final boundaries kept exact.
auto	astro::detail::event_search::grid_cell_count (const Grid grid) -> uint32_t
	Validate distinct representable cell boundaries and a bounded index range.
auto	astro::detail::event_search::containing_cell (const Grid grid, const uint32_t cell_count, const double jde_tt) -> uint32_t
	Locate the canonical cell containing an admitted time, correcting quotient rounding.
template<typename Visitor> requires std::invocable<const Visitor&, Interval>
auto	astro::detail::event_search::visit_query_cells (const Grid grid, const Interval query, const Visitor &visitor) -> void
	Visit whole canonical cells touching a query, including its preceding cell for rounded roots.
auto	astro::detail::event_search::reported_time (const double jde_tt, const double quantum_tt_days) -> double
	Round a reported TT time to a binary lattice; zero quantum preserves the refined double.
auto	astro::detail::event_search::validate_reporting_grid (const Grid grid, const double quantum_tt_days) -> void
	Require a power-of-two reporting lattice that fixes every canonical cell boundary.
template<typename Provider> requires std::invocable<const Provider&, double> and std::same_as<std::invoke_result_t<const Provider&, double>, Value>
auto	astro::detail::event_search::append_interval_roots (const Provider &provider, const std::span< const Candidate > candidates, const Interval query, const Bounds bounds, Budget &budget, const double time_resolution, std::vector< Root > &roots, const double report_quantum_tt_days=0.0) -> void
	Append only query-owned roots; intersecting unresolved regions and aliased root times fail.
auto	astro::detail::event_search::contact_window (const Grid grid, const uint32_t index, const uint32_t cell_count) -> Interval
	Return the fixed neighbor window of a canonical cell, clipped to the grid domain.
template<typename LongitudeProvider, typename RateProvider, typename WindowLongitudeProvider, typename WindowRateProvider> requires std::invocable<const LongitudeProvider&, double> and std::same_as<std::invoke_result_t<const LongitudeProvider&, double>, LongitudeValue> and std::invocable<const RateProvider&, double> and std::same_as<std::invoke_result_t<const RateProvider&, double>, Value> and std::invocable<const WindowLongitudeProvider&, double> and std::same_as<std::invoke_result_t<const WindowLongitudeProvider&, double>, LongitudeValue> and std::invocable<const WindowRateProvider&, double> and std::same_as<std::invoke_result_t<const WindowRateProvider&, double>, Value>
auto	astro::detail::event_search::certify_contact (const LongitudeProvider &longitude, const RateProvider &rate, const WindowLongitudeProvider &window_longitude, const WindowRateProvider &window_rate, const Candidate &candidate, const Interval cell, const Interval window, const toolbox::AngleDeg target, const TrajectoryBounds bounds, const TrajectoryBounds window_bounds, Budget &budget, const double time_resolution, const double report_quantum_tt_days) -> StationContact
	Certify one exact-level numerical contact, trying its cell before its fixed neighbor window.
template<typename LongitudeProvider, typename RateProvider, typename WindowLongitudeProvider, typename WindowRateProvider> requires std::invocable<const LongitudeProvider&, double> and std::same_as<std::invoke_result_t<const LongitudeProvider&, double>, LongitudeValue> and std::invocable<const RateProvider&, double> and std::same_as<std::invoke_result_t<const RateProvider&, double>, Value> and std::invocable<const WindowLongitudeProvider&, double> and std::same_as<std::invoke_result_t<const WindowLongitudeProvider&, double>, LongitudeValue> and std::invocable<const WindowRateProvider&, double> and std::same_as<std::invoke_result_t<const WindowRateProvider&, double>, Value>
auto	astro::detail::event_search::cell_contacts (const LongitudeProvider &longitude, const RateProvider &rate, const WindowLongitudeProvider &window_longitude, const WindowRateProvider &window_rate, const toolbox::AngleDeg target, const Interval cell, const Interval window, const TrajectoryBounds bounds, const TrajectoryBounds window_bounds, Budget &budget, const double time_resolution, const double report_quantum_tt_days, const Interval query) -> std::vector< NumericalContact >
	Verify isolated stations in a fixed grid cell using observations on both sides.
template<typename LongitudeProvider> requires std::invocable<const LongitudeProvider&, double> and std::same_as<std::invoke_result_t<const LongitudeProvider&, double>, LongitudeValue>
auto	astro::detail::event_search::cell_crossings (const LongitudeProvider &longitude, const toolbox::AngleDeg target, const Interval cell, const std::span< const Interval > exclusions, const Interval query, const Bounds bounds, Budget &budget, const double time_resolution, const double report_quantum_tt_days) -> std::vector< Root >
	Scan one visited cell for crossings outside its sorted, disjoint contact exclusions.
template<typename Contacts, typename Crossings> requires std::invocable<const Contacts&, Interval, Interval> and std::same_as<std::invoke_result_t<const Contacts&, Interval, Interval>, std::vector<NumericalContact>> and std::invocable<const Crossings&, Interval, std::span<const Interval>> and std::same_as<std::invoke_result_t<const Crossings&, Interval, std::span<const Interval>>, std::vector<Root>>
auto	astro::detail::event_search::contact_traversal (const Grid grid, const Interval query, const Contacts &contacts, const Crossings &crossings) -> std::vector< LongitudeRoot >
	Find crossings and exact contacts, reporting each contact from the cell containing its reported time.

Variables
constexpr uint32_t	astro::detail::event_search::MAXIMUM_CONTACT_REGION_ATTEMPTS

Detailed Description

Fixed-grid root isolation and conditional numerical certification.

See also: docs/EPHEMERIS_EVENTS.md for cell, certificate, allowance and boundary terminology.

Classes

Namespaces

Enumerations

Functions

Variables

Detailed Description