mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/readers/grib2/geometry.py

@@ -0,0 +1,1133 @@
+"""Where the numbers are: grid coordinates in closed form, with no C library and no grid file.
+
+A weather message carries a rectangular array of values and a compact description of the grid
+those values sit on.  It does not carry a latitude and a longitude beside each value -- that
+would double the file -- so placing a value on the earth is arithmetic, and this module is that
+arithmetic.
+
+Why the maths is written out here
+---------------------------------
+The obvious alternative is to let a library do it.  The library this Reader vendors computes
+latitudes and longitudes for the flagship's grid only under a feature that binds the C PROJ
+library, and the rule for this Reader is pure Rust with no C geospatial stack in the hot path.
+So the choice is between relaxing the rule and writing the projection, and the projection is
+short, closed form, and -- the part that makes it safe rather than merely possible -- needs no
+grid-shift files.  Grid-shift files are what make a projection library's answer depend on which
+data files happen to be installed; a conic projection on a stated earth shape is trigonometry
+with no lookup in it.  So the maths is vendorable, pinnable, and testable, and the rule stands.
+
+The formulae follow the standard presentation of the Lambert conformal conic on a sphere: the
+cone constant ``n`` from the two standard parallels, the scale ``F``, the polar radius ``rho``
+at a latitude, and the origin radius ``rho_origin`` at the projection's own origin latitude.
+The names below are those names, so a reviewer can check this code against a reference rather
+than against itself.
+
+How it is graded
+----------------
+Every message states the latitude and longitude of its own first grid point, and a regular
+latitude and longitude grid additionally states its last.  Building a grid recomputes those and
+compares them with what the message declares -- see ``validate_against_declaration``, which runs
+on every grid construction and not only in tests.  Our projection and the publisher's are two
+implementations of one specification, and this compares them on every message, using values the
+publisher put in the file for exactly that purpose.
+
+What is deliberately absent
+---------------------------
+There is no default earth shape.  A message declaring an ellipsoid and read as a sphere is
+wrong by a few hundred metres everywhere, which is the worst size an error has: too small to
+notice and too large to ignore.  An earth shape this module does not carry is named and
+refused.
+
+There is no clamping.  A point outside the grid is refused, because a value handed back for a
+place the model does not cover is a number attributed to somewhere it does not describe, and
+that failure verifies clean, plots plausibly, and is wrong.
+
+There is no cached state.  Every derived quantity is recomputed from the record's own fields on
+each call, so grid objects do not share mutable state.
+
+There is no C library trigonometry.  ``sin``, ``cos``, ``tan``, ``log``, ``atan``, ``atan2``,
+``hypot`` and ``power`` below are this package's own, from ``portable_math``, and they are read
+here as the names a reference writes.  The reason is in that module's own account of it: IEEE-754
+does not require a C library's transcendental functions to be correctly rounded, two conforming
+machines answered ``sin(radians(38.5))`` one unit in the last place apart, and this projection
+turns that into a grid coordinate that differs between architectures.  What remains from ``math``
+here is ``fmod``, ``floor`` and ``isfinite``, which are exact operations on every machine.
+
+Import discipline: ``readers.contracts``, ``readers.grib2.admission``,
+``readers.grib2.portable_math``, and the standard library.  Nothing else, ever -- a geospatial
+package imported here would undo the entire reason this module exists.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import ClassVar, NoReturn
+
+from mostlyright.data_harness.readers.contracts import ReaderError
+from mostlyright.data_harness.readers.grib2.admission import MessageAdmission
+from mostlyright.data_harness.readers.grib2.portable_math import (
+    PI,
+    atan,
+    atan2,
+    cos,
+    degrees,
+    hypot,
+    log,
+    power,
+    radians,
+    sin,
+    tan,
+)
+
+__all__ = [
+    "EARTH_RADIUS_METRES",
+    "GRID_SELF_VALIDATION_TOLERANCE_DEGREES",
+    "GRID_SELF_VALIDATION_TOLERANCE_METRES",
+    "IMPLEMENTED_GRID_TEMPLATES",
+    "SUPPORTED_EARTH_SHAPE",
+    "Grid",
+    "GridAgreement",
+    "LambertConformalGrid",
+    "LatitudeLongitudeGrid",
+    "ScanningMode",
+    "build_grid",
+    "nearest_grid_index",
+    "normalise_longitude",
+    "validate_against_declaration",
+]
+
+# The grid templates this module can place values for.  It is held equal to the grid half of
+# the admission allowlist by test: a grid admitted with no projection here would be a message
+# accepted and then unplaceable, and a projection for a grid nobody admits is maths nobody
+# verifies.
+IMPLEMENTED_GRID_TEMPLATES: frozenset[int] = frozenset({0, 30})
+
+# The one earth shape these projections carry, and the radius edition 2's code table gives it.
+# Both vendored messages declare it.  Every other shape is refused by name.
+SUPPORTED_EARTH_SHAPE = 6
+EARTH_RADIUS_METRES = 6371229.0
+
+# What each shape means, in the words a refusal uses.  A number alone in an error message sends
+# the reader to a code table; the sentence saves them the trip.
+_EARTH_SHAPES: Mapping[int, str] = {
+    0: "a sphere of radius 6367470.0 m",
+    1: "a sphere whose radius the message states for itself",
+    2: "the IAU 1965 spheroid",
+    3: "a spheroid whose axes the message states in kilometres",
+    4: "the IAG-GRS80 spheroid",
+    5: "the WGS 84 ellipsoid",
+    6: "a sphere of radius 6371229.0 m",
+    7: "a spheroid whose axes the message states in metres",
+    8: "a sphere of radius 6371200.0 m",
+    9: "the OSGB 1936 ellipsoid",
+    10: "a sphere of radius 6378160.0 m",
+    11: "the IAG-GRS80 spheroid on a Gaussian grid",
+}
+
+# The units the message's own fields are quantised to.  Both divisors are exactly representable
+# as doubles, so dividing by them is correctly rounded and an integer field reproduces the
+# decimal a human would write for it.
+_ANGLE_DIVISOR = 1_000_000.0
+_LENGTH_DIVISOR = 1_000.0
+
+# Scanning-mode flags, edition 2 flag table 3.4.  The first three decide the direction of each
+# axis and which axis is consecutive in the packed values.  The fourth says rows alternate
+# direction, and the last four shift points by half a cell; none of those four is implemented,
+# and each is refused rather than ignored, because ignoring a half-cell offset moves every
+# answer half a cell and nothing says so.
+_SCAN_I_NEGATIVE = 0x80
+_SCAN_J_POSITIVE = 0x40
+_SCAN_J_CONSECUTIVE = 0x20
+_SCAN_ALTERNATING_ROWS = 0x10
+_SCAN_OFFSET_FLAGS = 0x0F
+
+# Resolution and component flags, edition 2 flag table 3.3.  A regular grid must state both of
+# its increments; a grid that leaves them to be inferred from its corners is not one this
+# Reader computes.
+_RESOLUTION_I_GIVEN = 0x20
+_RESOLUTION_J_GIVEN = 0x10
+
+# Two standard parallels closer than this are the tangent case, where the cone constant is the
+# sine of the parallel and the secant formula divides by a logarithm of one.  A millionth of a
+# degree is the finest distinction the message's own fields can express, so parallels that
+# differ by less than that are not two parallels.
+_TANGENT_PARALLEL_EPSILON = 1e-6
+
+# The smallest section a template's fields fit in, by template number.
+_TEMPLATE_OCTETS: Mapping[int, int] = {0: 72, 30: 81}
+
+# How far the computed grid may sit from the grid the message declares before the message is
+# refused.  Both numbers are five units of the precision the message's own fields carry: angles
+# are integers in millionths of a degree, grid increments are integers in thousandths of a metre,
+# and a message cannot state a disagreement finer than one of its own units.
+#
+# Five rather than one, because the publisher's corner is their arithmetic rounded to their last
+# place and ours is ours, and a refresh should not halt over a rounding neither side can express.
+# Five rather than fifty, because five millionths of a degree is about half a metre and five
+# thousandths of a metre is half a centimetre, both of them three orders of magnitude below the
+# three-kilometre spacing of the finest grid on the list -- so a disagreement large enough to
+# move a value into a neighbouring cell cannot fit under either number.
+#
+# Observed margins on the vendored messages: the
+# regular grid agrees exactly, at 0.0 degrees on both its corners, and the conic grid agrees to
+# 3.55e-15 degrees on its first point and 1.40e-09 metres on its worst plane round trip.  Both
+# are the arithmetic's own precision rather than a bound anyone chose, which is what makes them
+# worth watching.  Widening either tolerance to make a message pass is not a fix; it is the
+# finding.
+GRID_SELF_VALIDATION_TOLERANCE_DEGREES = 5e-6
+GRID_SELF_VALIDATION_TOLERANCE_METRES = 5e-3
+
+
+@dataclass(frozen=True)
+class ScanningMode:
+    """Which way the two axes run, and which of them is consecutive in the packed values.
+
+    This is read as three independent facts rather than assumed, because assuming it is how a
+    grid ends up flipped, and a flipped grid does not raise: it answers every question with a
+    real number measured somewhere else.
+    """
+
+    raw: int
+    i_negative: bool
+    j_positive: bool
+    j_consecutive: bool
+
+    @classmethod
+    def from_octet(cls, octet: int, where: str) -> ScanningMode:
+        """The three flags this Reader implements, refusing the five it does not."""
+
+        if octet & _SCAN_ALTERNATING_ROWS:
+            _refuse(
+                "READER_GRID_UNKNOWN",
+                "reader.grib2.geometry.scanning",
+                f"scans its alternate rows in opposite directions{where}, and this Reader reads "
+                f"grids whose rows all run the same way; reading one as the other reverses every "
+                f"other row of the field without failing",
+            )
+        if octet & _SCAN_OFFSET_FLAGS:
+            _refuse(
+                "READER_GRID_UNKNOWN",
+                "reader.grib2.geometry.scanning",
+                f"sets scanning flag bits {octet & _SCAN_OFFSET_FLAGS:#04x}{where}, which offset "
+                f"points by half a cell or vary the row length; this Reader computes grids "
+                f"without those offsets, and applying none where the message asks for one moves "
+                f"every answer half a cell",
+            )
+        return cls(
+            raw=octet,
+            i_negative=bool(octet & _SCAN_I_NEGATIVE),
+            j_positive=bool(octet & _SCAN_J_POSITIVE),
+            j_consecutive=bool(octet & _SCAN_J_CONSECUTIVE),
+        )
+
+    @property
+    def column_step(self) -> int:
+        """+1 if columns run west to east in the grid's own axis, -1 if they run the other way."""
+
+        return -1 if self.i_negative else 1
+
+    @property
+    def row_step(self) -> int:
+        """+1 if rows run towards the north edge, -1 if row zero is the north edge."""
+
+        return 1 if self.j_positive else -1
+
+
+@dataclass(frozen=True)
+class _GridBase:
+    """What every grid has: a size, an earth, and a direction for each axis."""
+
+    TEMPLATE: ClassVar[int] = -1
+
+    rows: int
+    columns: int
+    earth_radius_metres: float
+    scanning: ScanningMode
+
+    @property
+    def template(self) -> int:
+        """The grid definition template this grid was read from."""
+
+        return self.TEMPLATE
+
+    @property
+    def point_count(self) -> int:
+        """How many values the grid holds, which the message declares independently."""
+
+        return self.rows * self.columns
+
+    def data_index(self, row: int, column: int) -> int:
+        """Which element of the packed array this cell is, honouring the consecutive flag.
+
+        The decoder wants one element of one array.  Whether rows or columns run consecutively
+        is the whole difference between the right element and a plausible wrong one, so it is
+        answered here, once, from the flag the message set.
+        """
+
+        self._require_addressable(row, column)
+        if self.scanning.j_consecutive:
+            return column * self.rows + row
+        return row * self.columns + column
+
+    def coordinate_at(self, row: int, column: int) -> tuple[float, float]:
+        """The latitude and longitude of one cell, as a pair of doubles."""
+
+        self._require_addressable(row, column)
+        return self._coordinate(row, column)
+
+    def _require_addressable(self, row: int, column: int) -> None:
+        if not isinstance(row, int) or not isinstance(column, int):
+            _refuse(
+                "READER_CONTRACT",
+                "reader.grib2.geometry.cell",
+                "a cell is addressed by two integers",
+            )
+        if not 0 <= row < self.rows or not 0 <= column < self.columns:
+            _refuse(
+                "READER_CONTRACT",
+                "reader.grib2.geometry.cell",
+                f"cell ({row}, {column}) is outside the {self.rows} by {self.columns} grid this "
+                f"message declares",
+            )
+
+    def _coordinate(self, row: int, column: int) -> tuple[float, float]:
+        raise NotImplementedError
+
+    def _continuous_index(self, latitude: float, longitude: float) -> tuple[float, float]:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class LatitudeLongitudeGrid(_GridBase):
+    """A regular grid on the sphere: constant spacing in latitude and in longitude.
+
+    There is no projection here at all.  A cell's coordinate is the first point plus a whole
+    number of increments, in the direction the scanning mode gives each axis.  The message
+    states the last point as well as the first, which makes it the one grid whose arithmetic can
+    be graded against a second statement by the publisher rather than against itself.
+    """
+
+    TEMPLATE: ClassVar[int] = 0
+
+    first_latitude: float
+    first_longitude: float
+    last_latitude: float
+    last_longitude: float
+    latitude_increment: float
+    longitude_increment: float
+
+    @property
+    def wraps_the_globe(self) -> bool:
+        """Whether the columns close the circle, so the last column adjoins the first.
+
+        A global grid's final column is a neighbour of column zero, and a point between them is
+        nearer to one of the two than to any other -- which is only true if the wrap is stated.
+        """
+
+        return abs(self.columns * self.longitude_increment - 360.0) < _TANGENT_PARALLEL_EPSILON
+
+    def _coordinate(self, row: int, column: int) -> tuple[float, float]:
+        latitude = self.first_latitude + row * self.scanning.row_step * self.latitude_increment
+        longitude = (
+            self.first_longitude + column * self.scanning.column_step * self.longitude_increment
+        )
+        return latitude, normalise_longitude(longitude)
+
+    def _continuous_index(self, latitude: float, longitude: float) -> tuple[float, float]:
+        row = (latitude - self.first_latitude) / (self.scanning.row_step * self.latitude_increment)
+        offset = (longitude - self.first_longitude) * self.scanning.column_step
+        if self.wraps_the_globe:
+            column = math.fmod(offset, 360.0)
+            if column < 0.0:
+                column += 360.0
+        else:
+            column = _signed_turn(offset)
+        return row, column / self.longitude_increment
+
+
+@dataclass(frozen=True)
+class LambertConformalGrid(_GridBase):
+    """A grid regular on a cone tangent to, or secant with, the sphere.
+
+    The flagship publishes on this.  A cell's coordinate is the first point's projected
+    position plus a whole number of increments in metres, carried back to the sphere by the
+    inverse projection.  The projection is closed form in the parameters the message already
+    carries, so nothing is looked up and nothing is installed.
+    """
+
+    TEMPLATE: ClassVar[int] = 30
+
+    first_latitude: float
+    first_longitude: float
+    origin_latitude: float
+    central_meridian: float
+    standard_parallel_1: float
+    standard_parallel_2: float
+    x_increment_metres: float
+    y_increment_metres: float
+
+    def project(self, latitude: float, longitude: float) -> tuple[float, float]:
+        """Sphere to plane: the position of a point in the grid's own metres."""
+
+        return _project(_cone_of(self), self, latitude, longitude)
+
+    def unproject(self, x: float, y: float) -> tuple[float, float]:
+        """Plane to sphere: the latitude and longitude of a position in the grid's own metres."""
+
+        return _unproject(_cone_of(self), self, x, y)
+
+    def _coordinate(self, row: int, column: int) -> tuple[float, float]:
+        cone = _cone_of(self)
+        x, y = _cell_position(cone, self, float(row), float(column))
+        return _unproject(cone, self, x, y)
+
+    def _continuous_index(self, latitude: float, longitude: float) -> tuple[float, float]:
+        cone = _cone_of(self)
+        x, y = _project(cone, self, latitude, longitude)
+        column = (x - cone.x_first) / (self.scanning.column_step * self.x_increment_metres)
+        row = (y - cone.y_first) / (self.scanning.row_step * self.y_increment_metres)
+        return row, column
+
+
+Grid = LatitudeLongitudeGrid | LambertConformalGrid
+
+
+@dataclass(frozen=True)
+class GridAgreement:
+    """How far the computed grid sat from the declared one, in the units of each comparison.
+
+    Reported rather than merely asserted, so the margin can be recorded and watched.  A field is
+    ``None`` where the template states nothing to compare: the conic template declares no far
+    corner, and the regular grid has no plane to round-trip through.
+    """
+
+    corner_degrees: float
+    extent_degrees: float | None
+    round_trip_metres: float | None
+
+
+@dataclass(frozen=True)
+class _Cone:
+    """The four constants a Lambert conformal conic is fully described by, plus the origin cell.
+
+    ``n`` is the cone constant, ``scale`` is the radius scale (the standard ``R * F``),
+    ``rho_origin`` is the polar radius at the projection's origin latitude, and ``x_first`` and
+    ``y_first`` are the projected position of the message's own first grid point.  They are
+    recomputed on every call rather than cached, so no state can carry between calls.
+    """
+
+    n: float
+    scale: float
+    rho_origin: float
+    x_first: float
+    y_first: float
+
+
+def build_grid(
+    admission: MessageAdmission,
+    content: bytes,
+    *,
+    origin: str | None = None,
+) -> Grid:
+    """Read the geometry of an admitted message and return the grid it describes.
+
+    Takes an admission result, which is the only way a grid may be built: the parameters are
+    read from the grid section that admission already located and bounded, so a message nobody
+    admitted has nothing to pass here.  ``origin`` is whatever the recipe called the source, and
+    it is carried into refusals so a halted refresh names the file.
+    """
+
+    where = _origin_clause(origin)
+    if not isinstance(admission, MessageAdmission):
+        _refuse(
+            "READER_CONTRACT",
+            "reader.grib2.geometry.admission",
+            "a grid is built from an admission result, so an unadmitted message has nothing to "
+            "pass; this is the same rule that keeps a decoder from reaching one",
+        )
+    if not isinstance(content, (bytes, bytearray, memoryview)):
+        _refuse("READER_CONTRACT", "reader.grib2.geometry.message", "must be exact bytes")
+
+    template = admission.grid_template
+    if template not in IMPLEMENTED_GRID_TEMPLATES:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.template",
+            f"is on grid template 3.{template}{where}, which this Reader admits but has no "
+            f"projection for, so it will not guess where the values belong; this is a gap "
+            f"between the admission list and the maths, and closing it means writing the "
+            f"projection rather than widening anything",
+        )
+
+    section = _GridSection(
+        content=bytes(content),
+        start=admission.grid_start,
+        length=admission.grid_length,
+        where=where,
+    )
+    section.require(_TEMPLATE_OCTETS[template], template)
+    radius = _earth_radius(section)
+    if template == LatitudeLongitudeGrid.TEMPLATE:
+        grid: Grid = _regular_grid(section, radius)
+    else:
+        grid = _conic_grid(section, radius)
+    validate_against_declaration(grid, admission, origin=origin)
+    return grid
+
+
+def validate_against_declaration(
+    grid: Grid,
+    admission: MessageAdmission,
+    *,
+    origin: str | None = None,
+) -> GridAgreement:
+    """Grade the computed grid against what the message says about itself, or refuse it.
+
+    This runs on every grid construction and not only in tests, and the reason is worth stating
+    plainly: our projection and the publisher's are two independent implementations of one
+    specification, and the publisher put the coordinates of the grid's own corners in the file
+    for exactly this purpose.  Comparing them costs four projections per message -- nothing
+    beside decoding two million values -- and it is the difference between a projection we
+    believe is right and one that is checked against the party that made the file, on every file,
+    including the one where they change the grid and do not say so.
+
+    Three comparisons, each against a number the message states independently of the others.
+
+    *The shape holds the point count.*  Rows times columns must equal the point count the message
+    declares in another octet of the same section.
+
+    *The first grid point comes back.*  Index (0, 0) is recomputed through the projection and
+    compared with the declared corner.  On the regular grid this is arithmetic returning its own
+    input and it is exact; on the conic grid it is the forward projection graded against the
+    inverse, which is where a sign error, a unit error, or a radius that entered only one
+    direction shows up.
+
+    *The far corner agrees, where the message states one.*  The regular grid declares its last
+    point as well as its first, so that one is a genuine second statement by the publisher and
+    the strongest of the three.  The conic template declares no far corner -- there is nothing
+    to compare -- so in its place every corner of the conic grid is required to round-trip
+    through the plane to within the tolerance in metres, which is what refuses a grid running
+    past the far side of its own cone.
+
+    Return the observed margins for recording and comparison.
+    """
+
+    where = _origin_clause(origin)
+    if not isinstance(grid, (LatitudeLongitudeGrid, LambertConformalGrid)):
+        _refuse("READER_CONTRACT", "reader.grib2.geometry.grid", "must be a computed grid")
+    if not isinstance(admission, MessageAdmission):
+        _refuse(
+            "READER_CONTRACT",
+            "reader.grib2.geometry.admission",
+            "a grid is graded against the admission of the message that declared it",
+        )
+
+    if grid.point_count != admission.declared_points:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.extent",
+            f"declares {admission.declared_points} grid points{where} and a shape of {grid.rows} "
+            f"by {grid.columns}, which holds {grid.point_count}; the two numbers come from "
+            f"different octets of the same section and taking either one on its own is how a "
+            f"field ends up read shifted, which produces real numbers in the wrong places",
+        )
+
+    corner = _disagreement(grid.coordinate_at(0, 0), (grid.first_latitude, grid.first_longitude))
+    _require_agreement(
+        corner,
+        "first grid point",
+        (grid.first_latitude, grid.first_longitude),
+        grid.coordinate_at(0, 0),
+        where,
+    )
+
+    if isinstance(grid, LatitudeLongitudeGrid):
+        declared = (grid.last_latitude, grid.last_longitude)
+        computed = grid.coordinate_at(grid.rows - 1, grid.columns - 1)
+        extent = _disagreement(computed, declared)
+        _require_agreement(extent, "last grid point", declared, computed, where)
+        return GridAgreement(corner_degrees=corner, extent_degrees=extent, round_trip_metres=None)
+
+    return GridAgreement(
+        corner_degrees=corner,
+        extent_degrees=None,
+        round_trip_metres=_conic_corners_round_trip(grid, where),
+    )
+
+
+def nearest_grid_index(
+    grid: Grid,
+    latitude: float,
+    longitude: float,
+    *,
+    name: str | None = None,
+    origin: str | None = None,
+) -> tuple[int, int]:
+    """The one cell a named place falls in, as ``(row, column)``, or a refusal.
+
+    **What nearest means.**  Distance is measured in the grid's own coordinates: degrees on the
+    regular grid, metres on the plane for the conic one.  Both grids are regular in those
+    coordinates, so the nearest cell is the nearest on each axis independently -- the two axes
+    separate exactly, and per-axis rounding is the true nearest rather than an approximation of
+    it.  That is asserted by measurement in the tests and not merely argued here.
+
+    **The tie-break.**  Floating-point distances tie more often than intuition suggests: on a
+    one-degree grid every half degree is an exact tie, in binary and not nearly.  So the rule is
+    stated rather than left to whichever comparison ran first: **a tie goes to the cell with the
+    lower coordinate, latitude first and then longitude** -- the more southerly cell, and the
+    more westerly one.
+
+    The rule is stated in the grid's own directions rather than as "the lower position in the
+    packed values", and the difference matters.  A file written from its south edge and the same
+    grid written from its north edge store their rows in opposite orders, so a rule about
+    storage positions would answer a boundary point differently in the two files, making the
+    answer a property of how the publisher wrote the file rather than of where the place is.  On
+    a grid whose rows run in the same direction as their positions -- the flagship's -- the two
+    statements of the rule are the same statement.
+
+    **A place the model does not cover is refused.**  Not clamped to the nearest edge: a value
+    handed back for a place outside the grid is a real number attributed to somewhere it does
+    not describe, and nothing downstream can tell.  The edge sits half a cell beyond the last
+    cell's centre, which is where the nearest cell stops being meaningful, and by the tie-break
+    above a point exactly half a cell out belongs to the grid on its north and east sides and
+    not on its south and west ones.  One rule, applied in the grid's own directions, so the same
+    place gets the same answer whichever way the file was written.
+
+    ``name`` is what the recipe called the place, carried into the refusal so a halted refresh
+    names the place a user asked for rather than a pair of numbers.
+    """
+
+    where = _origin_clause(origin)
+    if not isinstance(grid, (LatitudeLongitudeGrid, LambertConformalGrid)):
+        _refuse(
+            "READER_CONTRACT",
+            "reader.grib2.geometry.grid",
+            "a place is located on a grid built from a message, not on anything else",
+        )
+    _require_latitude(latitude)
+    _require_longitude(longitude)
+
+    row_offset, column_offset = grid._continuous_index(
+        float(latitude), normalise_longitude(longitude)
+    )
+    row = _select(row_offset, grid.scanning.row_step)
+    column = _select(column_offset, grid.scanning.column_step)
+    if isinstance(grid, LatitudeLongitudeGrid) and grid.wraps_the_globe:
+        column %= grid.columns
+    if not 0 <= row < grid.rows or not 0 <= column < grid.columns:
+        _refuse_uncovered(grid, latitude, longitude, name, where)
+    return row, column
+
+
+def _select(offset: float, step: int) -> int:
+    """Round a continuous position to a cell, with the tie going to the lower coordinate.
+
+    ``step`` says which way the coordinate runs against the position, so an exact half takes the
+    lower position where they run together and the higher one where they run opposite -- which
+    is the same cell on the ground either way.
+    """
+
+    lower = math.floor(offset)
+    fraction = offset - lower
+    if fraction < 0.5:
+        return lower
+    if fraction > 0.5:
+        return lower + 1
+    return lower if step > 0 else lower + 1
+
+
+def _refuse_uncovered(
+    grid: Grid,
+    latitude: float,
+    longitude: float,
+    name: str | None,
+    where: str,
+) -> NoReturn:
+    """Say which place, where it is, and what the grid does cover."""
+
+    called = f"{name} at " if isinstance(name, str) and name.strip() else ""
+    corners = [
+        grid.coordinate_at(row, column)
+        for row, column in (
+            (0, 0),
+            (0, grid.columns - 1),
+            (grid.rows - 1, 0),
+            (grid.rows - 1, grid.columns - 1),
+        )
+    ]
+    _refuse(
+        "READER_OPTIONS",
+        "reader.grib2.geometry.point",
+        f"asks for {called}({latitude}, {longitude}){where}, which is outside the area this "
+        f"file covers; its corners are {corners}. The nearest place on the grid is not returned "
+        f"instead, because a value from somewhere else carries no sign that it came from "
+        f"somewhere else: it verifies, it plots, and it is a reading of another place. Either "
+        f"name a place inside the area, or use a file whose grid covers this one",
+    )
+
+
+def normalise_longitude(value: float) -> float:
+    """Every longitude in this module lives in [0, 360), and this is the one rule that puts it
+    there.
+
+    A message states its longitudes east of Greenwich; a recipe naming a place in the Americas
+    will state a negative one.  Both name the same meridian, and both must select the same cell,
+    so both pass through here first and nothing downstream compares two conventions.
+    """
+
+    turn = math.fmod(float(value), 360.0)
+    if turn < 0.0:
+        turn += 360.0
+    if turn == 0.0 or turn == 360.0:
+        return 0.0
+    return turn
+
+
+# --- Reading the grid section --------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _GridSection:
+    """One message's grid definition section, addressed by the octet numbers the format uses.
+
+    Octets are numbered from one within the section, which is how every reference writes them,
+    so the call sites below can be read against a reference table directly.
+    """
+
+    content: bytes
+    start: int
+    length: int
+    where: str
+
+    def require(self, octets: int, template: int) -> None:
+        if self.length < octets:
+            _refuse(
+                "READER_GRID_UNKNOWN",
+                "reader.grib2.geometry.section",
+                f"declares a grid section of {self.length} bytes{self.where} while grid template "
+                f"3.{template} needs {octets}; a section shorter than its own template does not "
+                f"state where its values belong",
+            )
+
+    def octet(self, number: int) -> int:
+        return self.content[self.start + number - 1]
+
+    def unsigned(self, first: int, last: int) -> int:
+        return int.from_bytes(self.content[self.start + first - 1 : self.start + last], "big")
+
+    def signed(self, first: int, last: int) -> int:
+        return _signed(self.content[self.start + first - 1 : self.start + last])
+
+
+def _earth_radius(section: _GridSection) -> float:
+    """The radius the message's declared earth shape means, or a refusal naming that shape."""
+
+    shape = section.octet(15)
+    if shape == SUPPORTED_EARTH_SHAPE:
+        return EARTH_RADIUS_METRES
+    described = _EARTH_SHAPES.get(shape, "a value that is not defined by edition 2's code table")
+    _refuse(
+        "READER_GRID_UNKNOWN",
+        "reader.grib2.geometry.earth_shape",
+        f"declares earth shape {shape}{section.where}, {described}; this Reader places values on "
+        f"shape {SUPPORTED_EARTH_SHAPE}, {_EARTH_SHAPES[SUPPORTED_EARTH_SHAPE]}, and on nothing "
+        f"else. Reading one shape as another is not an error at one point, it is a few hundred "
+        f"metres at every point, which is too small to notice and too large to ignore",
+    )
+
+
+def _regular_grid(section: _GridSection, radius: float) -> LatitudeLongitudeGrid:
+    """Grid template 3.0: a constant step in latitude and a constant step in longitude."""
+
+    basic_angle = section.unsigned(39, 42)
+    if basic_angle != 0:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.angular_unit",
+            f"states its angles in a unit it defines for itself, a basic angle of "
+            f"{basic_angle}{section.where}; this Reader reads angles in millionths of a degree, "
+            f"which is what a basic angle of zero means",
+        )
+    resolution = section.octet(55)
+    if resolution & (_RESOLUTION_I_GIVEN | _RESOLUTION_J_GIVEN) != (
+        _RESOLUTION_I_GIVEN | _RESOLUTION_J_GIVEN
+    ):
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.resolution",
+            f"does not state both of its own increments{section.where}: its resolution flags are "
+            f"{resolution:#04x}, and a grid whose spacing has to be inferred from its corners is "
+            f"not one this Reader computes",
+        )
+    columns = _positive(section.unsigned(31, 34), "points along a parallel", section.where)
+    rows = _positive(section.unsigned(35, 38), "points along a meridian", section.where)
+    return LatitudeLongitudeGrid(
+        rows=rows,
+        columns=columns,
+        earth_radius_metres=radius,
+        scanning=ScanningMode.from_octet(section.octet(72), section.where),
+        first_latitude=section.signed(47, 50) / _ANGLE_DIVISOR,
+        first_longitude=normalise_longitude(section.signed(51, 54) / _ANGLE_DIVISOR),
+        last_latitude=section.signed(56, 59) / _ANGLE_DIVISOR,
+        last_longitude=normalise_longitude(section.signed(60, 63) / _ANGLE_DIVISOR),
+        latitude_increment=_positive_angle(section.unsigned(68, 71), "latitude", section.where),
+        longitude_increment=_positive_angle(section.unsigned(64, 67), "longitude", section.where),
+    )
+
+
+def _conic_grid(section: _GridSection, radius: float) -> LambertConformalGrid:
+    """Grid template 3.30: a constant step in metres on a cone, and the cone's own parameters."""
+
+    centre = section.octet(64)
+    if centre != 0:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.projection_centre",
+            f"sets projection centre flags {centre:#04x}{section.where}, which select the "
+            f"southern cone or a two-cone projection; this Reader computes the single northern "
+            f"cone both of its checked messages use",
+        )
+    pole_latitude = section.signed(74, 77)
+    pole_longitude = section.signed(78, 81)
+    if pole_latitude != 0 or pole_longitude != 0:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.rotation",
+            f"rotates its projection about a pole at ({pole_latitude}, "
+            f"{pole_longitude}){section.where}; this Reader computes unrotated grids",
+        )
+    columns = _positive(section.unsigned(31, 34), "points along the x axis", section.where)
+    rows = _positive(section.unsigned(35, 38), "points along the y axis", section.where)
+    return LambertConformalGrid(
+        rows=rows,
+        columns=columns,
+        earth_radius_metres=radius,
+        scanning=ScanningMode.from_octet(section.octet(65), section.where),
+        first_latitude=section.signed(39, 42) / _ANGLE_DIVISOR,
+        first_longitude=normalise_longitude(section.signed(43, 46) / _ANGLE_DIVISOR),
+        origin_latitude=section.signed(48, 51) / _ANGLE_DIVISOR,
+        central_meridian=normalise_longitude(section.signed(52, 55) / _ANGLE_DIVISOR),
+        standard_parallel_1=section.signed(66, 69) / _ANGLE_DIVISOR,
+        standard_parallel_2=section.signed(70, 73) / _ANGLE_DIVISOR,
+        x_increment_metres=_positive_length(section.unsigned(56, 59), "x", section.where),
+        y_increment_metres=_positive_length(section.unsigned(60, 63), "y", section.where),
+    )
+
+
+def _positive(value: int, subject: str, where: str) -> int:
+    if value < 1:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.extent",
+            f"declares {value} {subject}{where}, and a grid with no extent along an axis holds "
+            f"no values at all",
+        )
+    return value
+
+
+def _positive_angle(value: int, axis: str, where: str) -> float:
+    if value < 1:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.increment",
+            f"declares a {axis} increment of {value}{where}; a grid whose points do not advance "
+            f"is a grid where every cell is the same cell",
+        )
+    return value / _ANGLE_DIVISOR
+
+
+def _positive_length(value: int, axis: str, where: str) -> float:
+    if value < 1:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.increment",
+            f"declares a {axis} increment of {value}{where}; a grid whose points do not advance "
+            f"is a grid where every cell is the same cell",
+        )
+    return value / _LENGTH_DIVISOR
+
+
+# --- The Lambert conformal conic, on a sphere ----------------------------------------------
+
+
+def _cone_of(grid: LambertConformalGrid) -> _Cone:
+    """The cone constant, the radius scale, and the projected position of the first grid point.
+
+    Naming follows the standard presentation: ``n`` is the cone constant, and where a reference
+    writes ``rho = R * F / tan(pi/4 + phi/2) ** n`` this carries ``scale = R * F`` and divides
+    by the same tangent power.  The tangent case, where the two standard parallels coincide, has
+    its own branch because the secant formula divides by the logarithm of one there.
+    """
+
+    phi1 = _cone_parallel(grid.standard_parallel_1, grid)
+    phi2 = _cone_parallel(grid.standard_parallel_2, grid)
+    if abs(grid.standard_parallel_1 - grid.standard_parallel_2) < _TANGENT_PARALLEL_EPSILON:
+        n = sin(phi1)
+    else:
+        n = log(cos(phi1) / cos(phi2)) / log(
+            tan(PI / 4.0 + phi2 / 2.0) / tan(PI / 4.0 + phi1 / 2.0)
+        )
+    if not 0.0 < n < 1.0:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.cone",
+            f"has standard parallels of {grid.standard_parallel_1} and "
+            f"{grid.standard_parallel_2}{_NO_ORIGIN}, which give a cone constant of {n}; a "
+            f"northern conic projection has one strictly between zero and one, and a value "
+            f"outside that is a cone that does not close",
+        )
+    scale = grid.earth_radius_metres * cos(phi1) * power(tan(PI / 4.0 + phi1 / 2.0), n)
+    scale /= n
+    rho_origin = _polar_radius(scale, n, grid.origin_latitude)
+    cone = _Cone(n=n, scale=scale, rho_origin=rho_origin, x_first=0.0, y_first=0.0)
+    x_first, y_first = _project(cone, grid, grid.first_latitude, grid.first_longitude)
+    return _Cone(n=n, scale=scale, rho_origin=rho_origin, x_first=x_first, y_first=y_first)
+
+
+def _cone_parallel(parallel: float, grid: LambertConformalGrid) -> float:
+    """A standard parallel in radians, refusing one at a pole where the cone has no radius."""
+
+    if not -90.0 < parallel < 90.0:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.cone",
+            f"places a standard parallel at {parallel} degrees, where a cone touching the sphere "
+            f"has no radius; the grid is {grid.rows} by {grid.columns}",
+        )
+    return radians(parallel)
+
+
+def _polar_radius(scale: float, n: float, latitude: float) -> float:
+    """``rho`` at a latitude: the distance from the cone's apex, in metres."""
+
+    tangent = tan(PI / 4.0 + radians(latitude) / 2.0)
+    if tangent <= 0.0:
+        _refuse(
+            "READER_OPTIONS",
+            "reader.grib2.geometry.point",
+            f"names latitude {latitude}, the pole this projection never reaches; a northern cone "
+            f"unrolls the sphere away from the southern pole and that point has no position on "
+            f"it",
+        )
+    return scale / power(tangent, n)
+
+
+def _project(
+    cone: _Cone,
+    grid: LambertConformalGrid,
+    latitude: float,
+    longitude: float,
+) -> tuple[float, float]:
+    """Sphere to plane, in the grid's own metres."""
+
+    _require_latitude(latitude)
+    turn = _signed_turn(normalise_longitude(longitude) - grid.central_meridian)
+    theta = cone.n * radians(turn)
+    if abs(theta) >= PI:
+        _refuse(
+            "READER_OPTIONS",
+            "reader.grib2.geometry.point",
+            f"names longitude {longitude}, which is {turn} degrees from this grid's central "
+            f"meridian of {grid.central_meridian} and wraps past the far side of the cone; a "
+            f"point there has two positions on the plane and neither is this grid's",
+        )
+    rho = _polar_radius(cone.scale, cone.n, latitude)
+    return rho * sin(theta), cone.rho_origin - rho * cos(theta)
+
+
+def _unproject(
+    cone: _Cone,
+    grid: LambertConformalGrid,
+    x: float,
+    y: float,
+) -> tuple[float, float]:
+    """Plane to sphere, the exact inverse of ``_project`` on the cone's single-valued wedge."""
+
+    towards_apex = cone.rho_origin - y
+    rho = hypot(x, towards_apex)
+    if rho == 0.0:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.extent",
+            f"reaches the apex of its own cone at ({x}, {y}), where every longitude meets and no "
+            f"single one is the answer; the grid is {grid.rows} by {grid.columns}",
+        )
+    theta = atan2(x, towards_apex)
+    turn = degrees(theta / cone.n)
+    if abs(turn) > 180.0:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.extent",
+            f"has a cell at ({x}, {y}) that unrolls to {turn} degrees from its central meridian "
+            f"of {grid.central_meridian}, which is more than half a turn; a grid wrapping past "
+            f"the far side of its own cone has two answers for one cell",
+        )
+    latitude = degrees(2.0 * atan(power(cone.scale / rho, 1.0 / cone.n)) - PI / 2.0)
+    return latitude, normalise_longitude(grid.central_meridian + turn)
+
+
+def _cell_position(
+    cone: _Cone,
+    grid: LambertConformalGrid,
+    row: float,
+    column: float,
+) -> tuple[float, float]:
+    """Where a cell sits on the plane: the first point plus whole increments, signed by scan."""
+
+    x = cone.x_first + column * grid.scanning.column_step * grid.x_increment_metres
+    y = cone.y_first + row * grid.scanning.row_step * grid.y_increment_metres
+    return x, y
+
+
+# --- Grading the grid against the message ---------------------------------------------------
+
+
+def _disagreement(
+    computed: tuple[float, float],
+    declared: tuple[float, float],
+) -> float:
+    """How far apart two points are, as the larger of the two angular differences.
+
+    The longitudes are compared as a turn rather than as two numbers, so a grid whose corner sits
+    a millionth of a degree west of the meridian is a millionth of a degree away from one a
+    millionth east of it, and not a full turn away.
+    """
+
+    return max(
+        abs(computed[0] - declared[0]),
+        abs(_signed_turn(computed[1] - declared[1])),
+    )
+
+
+def _require_agreement(
+    difference: float,
+    which: str,
+    declared: tuple[float, float],
+    computed: tuple[float, float],
+    where: str,
+) -> None:
+    """Refuse a message whose own declaration this Reader cannot reproduce."""
+
+    if difference <= GRID_SELF_VALIDATION_TOLERANCE_DEGREES:
+        return
+    _refuse(
+        "READER_GRID_UNKNOWN",
+        "reader.grib2.geometry.declaration",
+        f"declares its {which} at {declared}{where} and this Reader computes {computed}; they "
+        f"differ by {difference} degrees, which is more than the "
+        f"{GRID_SELF_VALIDATION_TOLERANCE_DEGREES} degrees a message's own precision allows. "
+        f"The projection here and the publisher's are two implementations of one specification "
+        f"and this is where they are compared, so a difference this size is a disagreement "
+        f"rather than rounding. Nothing is decoded from a message whose grid cannot be "
+        f"reproduced, because the values would be real numbers at coordinates nobody has "
+        f"checked",
+    )
+
+
+def _conic_corners_round_trip(grid: LambertConformalGrid, where: str) -> float:
+    """Send all four corners to the sphere and back, and report the worst error in metres.
+
+    The conic template states no far corner, so there is no second declaration to compare with.
+    What is available instead is that the projection must be its own inverse across the whole
+    grid, and it is not: a grid reaching past the far side of its own cone, or past the cone's
+    apex, has two positions for one cell.  Those are refused inside the inverse itself; this
+    grades what survives.
+    """
+
+    cone = _cone_of(grid)
+    worst = 0.0
+    for row in (0, grid.rows - 1):
+        for column in (0, grid.columns - 1):
+            x, y = _cell_position(cone, grid, float(row), float(column))
+            latitude, longitude = _unproject(cone, grid, x, y)
+            back_x, back_y = _project(cone, grid, latitude, longitude)
+            worst = max(worst, abs(back_x - x), abs(back_y - y))
+    if worst > GRID_SELF_VALIDATION_TOLERANCE_METRES:
+        _refuse(
+            "READER_GRID_UNKNOWN",
+            "reader.grib2.geometry.declaration",
+            f"has a corner that does not return to itself through its own projection{where}: the "
+            f"round trip moves it {worst} metres, more than the "
+            f"{GRID_SELF_VALIDATION_TOLERANCE_METRES} metres a grid stated in thousandths of a "
+            f"metre allows. A projection that is not its own inverse on this grid places values "
+            f"somewhere this Reader cannot state",
+        )
+    return worst
+
+
+# --- Shared arithmetic and refusals ---------------------------------------------------------
+
+
+_NO_ORIGIN = ""
+
+
+def _signed_turn(angle: float) -> float:
+    """An angular difference in (-180, 180], so the shorter way round is always the answer.
+
+    The argument is in degrees, and it is named ``angle`` rather than ``degrees`` because
+    ``degrees`` is the conversion this module imports.
+    """
+
+    turn = math.fmod(angle, 360.0)
+    if turn > 180.0:
+        return turn - 360.0
+    if turn <= -180.0:
+        return turn + 360.0
+    return turn
+
+
+def _require_longitude(longitude: float) -> None:
+    if not isinstance(longitude, (int, float)) or not math.isfinite(longitude):
+        _refuse(
+            "READER_OPTIONS",
+            "reader.grib2.geometry.point",
+            "names a longitude that is not a finite number",
+        )
+
+
+def _require_latitude(latitude: float) -> None:
+    if not isinstance(latitude, (int, float)) or not math.isfinite(latitude):
+        _refuse(
+            "READER_OPTIONS",
+            "reader.grib2.geometry.point",
+            "names a latitude that is not a finite number",
+        )
+    if not -90.0 <= latitude <= 90.0:
+        _refuse(
+            "READER_OPTIONS",
+            "reader.grib2.geometry.point",
+            f"names latitude {latitude}, which is not on the earth",
+        )
+
+
+def _origin_clause(origin: str | None) -> str:
+    """The recipe's own name for the source, so a halted refresh names the file."""
+
+    if origin is None:
+        return ""
+    if not isinstance(origin, str) or not origin.strip():
+        _refuse(
+            "READER_CONTRACT",
+            "reader.grib2.geometry.origin",
+            "must be a nonempty name or absent",
+        )
+    return f" in {origin.strip()}"
+
+
+def _signed(raw: bytes) -> int:
+    """A GRIB2 signed integer: a sign bit and a magnitude, never two's complement.
+
+    The same rule admission reads its scale factors with, written out here rather than imported
+    across the module boundary, and held to agree with it by test -- the way the identifier
+    pattern is duplicated between the Reader contract and the recipe and asserted equal.
+    """
+
+    value = int.from_bytes(raw, "big")
+    sign = 1 << (8 * len(raw) - 1)
+    return -(value & ~sign) if value & sign else value
+
+
+def _refuse(code: str, subject: str, detail: str) -> NoReturn:
+    raise ReaderError(code, subject, detail)