Module elevation 

Heights, grades and chord bounds of elevation laws, including the profile given by its own curvature, which has no closed form (#238).

Closed forms are delegated, the intrinsic profile is integrated

A polynomial or a circular vertical arc answers ElevationLaw::height_at and ElevationLaw::grade_at exactly, and this module calls those unchanged. An ElevationLaw::Intrinsic profile is a planar curve in (d, z) whose curvature runs along its own arc length s, so a height at PLAN distance d needs two numerical steps, both stated here:

1. the position (d(s), z(s)) is intrinsic_point on the profile curve, the Gauss-Legendre quadrature pinned against the Fresnel closed form (ADR 0060);
2. d(s) = d is inverted by a Newton iteration safeguarded by a bracket, since d'(s) = cos t(s) is exact from the closed-form heading.

Accuracy contract

The inversion stops once |d(s) - d| <= INVERSION_TOLERANCE * max(1, d) and corrects the height to first order by the residual times the grade. A reported height therefore carries the quadrature error of intrinsic_point plus at most |grade| * INVERSION_TOLERANCE * max(1, d); a grade carries the curvature times that same arc-length residual, divided by cos^2 t. Measured against an independent 50-digit integration and root, a 150 m sag-to-crest clothoid agrees to within 4e-15 m in height and 2e-17 in grade; the tests pin 1e-13 and 1e-15.

Where the plan distance stops increasing

d(s) is monotone only while the profile’s direction stays strictly inside (-pi/2, pi/2). That is certified, never assumed: over the arc-length span that brackets the inverse, the heading is bounded by its closed-form value at a panel start plus the total variation of curvature over the panel, and panels are bisected until the bound stays below vertical. The root is then unique in its bracket. A profile that reaches vertical first, or that cannot be certified within the bisection budget, is refused by name rather than read on a branch of d(s) that runs backwards.

Constants

INVERSION_TOLERANCE

Relative stopping tolerance of the plan-distance inversion: the solve ends once |d(s) - d| <= INVERSION_TOLERANCE * max(1, d).

Functions

elevation_chord_bound

Certified bound on how far an elevation law strays from the chord of its heights over the plan-distance span [a, b]: sup |z(d) - L(d)|, L the straight line through (a, z(a)) and (b, z(b)).

elevation_grade

Grade dz/dd at plan distance distance, for every law in the family.

elevation_height

Height at plan distance distance, for every law in the family.