py4dggs 0.2.0__py3-none-any.whl

py4dggs/__init__.py

@@ -0,0 +1,6 @@
+from py4dggs.grid import Grid
+from py4dggs.zone import Zone
+from py4dggs.registry import IGEO7, IVEA7H, RTEA7H, ISEA3H, IVEA3H, RTEA3H, get_grid
+from py4dggs.types import GeoPoint, PlanarPoint, GridConfig, InvalidZoneError
+from py4dggs import geojson
+__all__ = ["Grid", "Zone", "IGEO7", "IVEA7H", "RTEA7H", "ISEA3H", "IVEA3H", "RTEA3H", "get_grid", "GeoPoint", "PlanarPoint", "GridConfig", "InvalidZoneError", "geojson"]

py4dggs/geojson.py

@@ -0,0 +1,276 @@
+# src/py4dggs/geojson.py
+"""RFC 7946 GeoJSON output for cell boundaries.
+
+`Grid.vertices` mirrors DGGAL's ``getZoneWGS84Vertices`` exactly: the raw
+boundary points, longitudes in [-180, 180], in the engine's own order. That is
+the library's correctness contract (the conformance suite asserts bit-equality
+against pydggal), so **nothing here changes it**. This module sits above it and
+solves the two problems that raw contract leaves to the caller:
+
+* **Antimeridian.** A cell straddling +/-180 has vertices on both sides, so the
+  naive ring spans ~360 deg of longitude. Any planar consumer -- GeoJSON
+  readers, Shapely, Leaflet, PostGIS -- draws a sliver wrapped the wrong way
+  round the globe. Such a cell is cut at the antimeridian into a two-part
+  ``MultiPolygon``, per RFC 7946 s3.1.9.
+
+* **Poles.** A cell enclosing a pole winds +/-360 deg in longitude but carries
+  no vertex at lat +/-90, so it cannot be closed as a planar ring at all. The
+  boundary is re-anchored to run from lon -180 to +180 and then closed over the
+  pole itself.
+
+Every emitted exterior ring is closed (first point repeated) and wound
+counterclockwise, per RFC 7946 s3.1.6.
+
+The cut interpolates latitude linearly in longitude at the +/-180 meridian.
+That is what mainstream antimeridian splitters do and is accurate to well under
+a metre at any DGGS cell size; it is not a great-circle intersection.
+"""
+from __future__ import annotations
+
+import math
+from typing import Iterable
+
+from py4dggs.types import InvalidZoneError
+
+__all__ = ["zone_geometry", "zone_feature", "feature_collection"]
+
+_FULL_TURN = 360.0
+_HALF_TURN = 180.0
+# A ring whose total longitude turn is within this of +/-360 deg encloses a pole.
+_POLE_WINDING_TOLERANCE = 1.0
+
+
+# --- longitude bookkeeping ------------------------------------------------- #
+
+def _unwrap(ring: list[tuple[float, float]]) -> list[tuple[float, float]]:
+    """Make longitudes continuous, so consecutive steps are never > 180 deg.
+
+    The result may leave [-180, 180]; that is the point. It turns a ring that
+    "jumps" across the antimeridian into a single connected path that can be
+    reasoned about with ordinary planar geometry.
+    """
+    out = [ring[0]]
+    for lon, lat in ring[1:]:
+        prev = out[-1][0]
+        delta = lon - prev
+        delta -= _FULL_TURN * round(delta / _FULL_TURN)
+        out.append((prev + delta, lat))
+    return out
+
+
+def _winding(unwrapped: list[tuple[float, float]]) -> float:
+    """Total longitude turn around the closed ring, including the closing edge.
+
+    ~0 for an ordinary cell; ~+/-360 when the ring encircles a pole.
+    """
+    first, last = unwrapped[0][0], unwrapped[-1][0]
+    closing = first - last
+    closing -= _FULL_TURN * round(closing / _FULL_TURN)
+    return (last - first) + closing
+
+
+def _oriented(ring: list[tuple[float, float]]) -> tuple[list[tuple[float, float]], float]:
+    """Unwrap, and flip the traversal so the winding is non-negative."""
+    unwrapped = _unwrap(ring)
+    turn = _winding(unwrapped)
+    if turn < 0:
+        unwrapped = _unwrap(list(reversed(ring)))
+        turn = -turn
+    return unwrapped, turn
+
+
+def _wrap_lon(lon: float) -> float:
+    """Fold a longitude into [-180, 180], leaving the poles' +/-180 intact."""
+    if -_HALF_TURN <= lon <= _HALF_TURN:
+        return lon
+    return lon - _FULL_TURN * round(lon / _FULL_TURN)
+
+
+# --- ring hygiene ---------------------------------------------------------- #
+
+def _signed_area(ring: list[tuple[float, float]]) -> float:
+    """Planar shoelace over a closed ring. Positive == counterclockwise."""
+    return 0.5 * sum(
+        ring[i][0] * ring[i + 1][1] - ring[i + 1][0] * ring[i][1]
+        for i in range(len(ring) - 1)
+    )
+
+
+def _close_and_orient(ring: list[tuple[float, float]]) -> list[list[float]]:
+    """Repeat the first point and force counterclockwise winding (RFC 7946
+    s3.1.6). Applied to every emitted ring, so no earlier step has to reason
+    about traversal direction."""
+    closed = list(ring)
+    if closed[0] != closed[-1]:
+        closed.append(closed[0])
+    if _signed_area(closed) < 0:
+        closed.reverse()
+    return [[lon, lat] for lon, lat in closed]
+
+
+def _is_degenerate(ring: list[tuple[float, float]]) -> bool:
+    """A clipped part that collapsed to a line or a point carries no area."""
+    if len(ring) < 3:
+        return True
+    distinct = {(round(lon, 9), round(lat, 9)) for lon, lat in ring}
+    if len(distinct) < 3:
+        return True
+    closed = list(ring) + [ring[0]]
+    return abs(_signed_area(closed)) < 1e-12
+
+
+# --- the antimeridian cut -------------------------------------------------- #
+
+def _clip_half_plane(
+    ring: list[tuple[float, float]], meridian: float, keep_below: bool
+) -> list[tuple[float, float]]:
+    """Sutherland-Hodgman clip of a ring against a vertical line in lon.
+
+    `keep_below` keeps the lon <= meridian side, else the lon >= side. Latitude
+    at the cut is interpolated linearly in longitude.
+    """
+    out: list[tuple[float, float]] = []
+    n = len(ring)
+    for i in range(n):
+        lon1, lat1 = ring[i]
+        lon2, lat2 = ring[(i + 1) % n]
+        in1 = lon1 <= meridian if keep_below else lon1 >= meridian
+        in2 = lon2 <= meridian if keep_below else lon2 >= meridian
+        if in1:
+            out.append((lon1, lat1))
+        if in1 != in2 and lon2 != lon1:
+            t = (meridian - lon1) / (lon2 - lon1)
+            out.append((meridian, lat1 + t * (lat2 - lat1)))
+    return out
+
+
+def _split_at_antimeridian(
+    unwrapped: list[tuple[float, float]], meridian: float
+) -> list[list[tuple[float, float]]]:
+    """Cut at +180 or -180 and bring the far side back into [-180, 180]."""
+    below = _clip_half_plane(unwrapped, meridian, keep_below=True)
+    above = _clip_half_plane(unwrapped, meridian, keep_below=False)
+    # Exactly one side lies outside [-180, 180] and must be translated back.
+    shift_below, shift_above = (0.0, -_FULL_TURN) if meridian > 0 else (_FULL_TURN, 0.0)
+    parts = [
+        [(lon + shift_below, lat) for lon, lat in below],
+        [(lon + shift_above, lat) for lon, lat in above],
+    ]
+    return [p for p in parts if p and not _is_degenerate(p)]
+
+
+# --- the polar cap --------------------------------------------------------- #
+
+def _close_over_pole(
+    unwrapped: list[tuple[float, float]], turn: float
+) -> list[tuple[float, float]]:
+    """Re-anchor a pole-encircling boundary to run -180 -> +180, then close it
+    across the pole.
+
+    `unwrapped` is already oriented so longitude increases along the ring, and
+    `turn` is ~+360. The ring is re-cut at whichever antimeridian crossing it
+    contains, so the emitted boundary starts at lon -180 and ends at +180; the
+    two pole corners then seal it.
+    """
+    start_lon = unwrapped[0][0]
+    # The path spans [start_lon, start_lon + 360). Find the antimeridian inside it.
+    k = math.ceil((start_lon + _HALF_TURN) / _FULL_TURN)
+    cut = -_HALF_TURN + _FULL_TURN * k
+
+    # Walk the closed turn: the ring plus its own first point, one turn on.
+    path = unwrapped + [(start_lon + _FULL_TURN, unwrapped[0][1])]
+    lat_at_cut = None
+    for i in range(len(path) - 1):
+        lon1, lat1 = path[i]
+        lon2, lat2 = path[i + 1]
+        if lon1 <= cut <= lon2 and lon2 != lon1:
+            lat_at_cut = lat1 + (cut - lon1) / (lon2 - lon1) * (lat2 - lat1)
+            break
+    if lat_at_cut is None:                       # pragma: no cover - defensive
+        lat_at_cut = path[0][1]
+
+    # Rotate the cyclic ring to begin at the first vertex past the cut, lifting
+    # the wrapped-around tail by one turn so longitudes ascend across [cut,
+    # cut + 360). Rotating (rather than filtering by longitude) is what keeps
+    # every vertex: the cut rarely sits at the ring's own starting longitude.
+    count = len(unwrapped)
+    start = next((i for i, (lon, _) in enumerate(unwrapped) if lon >= cut), count)
+    ordered = []
+    for step in range(count):
+        index = start + step
+        lon, lat = unwrapped[index % count]
+        ordered.append((lon + (_FULL_TURN if index >= count else 0.0), lat))
+
+    shift = -_FULL_TURN * k                      # a whole number of turns: a true re-wrap
+    boundary = [(cut + shift, lat_at_cut)]
+    boundary += [(lon + shift, lat) for lon, lat in ordered]
+    boundary.append((cut + _FULL_TURN + shift, lat_at_cut))
+
+    pole_lat = 90.0 if sum(lat for _, lat in unwrapped) > 0 else -90.0
+    boundary.append((_HALF_TURN, pole_lat))
+    boundary.append((-_HALF_TURN, pole_lat))
+    return boundary
+
+
+# --- public API ------------------------------------------------------------ #
+
+def _rings_for(zone) -> list[list[list[float]]]:
+    vertices = zone.vertices
+    if not vertices or all(v.lat == 0.0 and v.lon == 0.0 for v in vertices):
+        raise InvalidZoneError(
+            f"zone {zone.value} has no geometry (DGGAL nullZone); nothing to render"
+        )
+
+    ring = [(v.lon, v.lat) for v in vertices]
+    unwrapped, turn = _oriented(ring)
+
+    if abs(turn - _FULL_TURN) < _POLE_WINDING_TOLERANCE:
+        return [_close_and_orient(_close_over_pole(unwrapped, turn))]
+
+    lons = [lon for lon, _ in unwrapped]
+    for meridian in (_HALF_TURN, -_HALF_TURN):
+        if min(lons) < meridian < max(lons):
+            parts = _split_at_antimeridian(unwrapped, meridian)
+            if len(parts) > 1:
+                return [_close_and_orient(p) for p in parts]
+            unwrapped = parts[0] if parts else unwrapped
+            break
+
+    return [_close_and_orient([(_wrap_lon(lon), lat) for lon, lat in unwrapped])]
+
+
+def zone_geometry(zone) -> dict:
+    """The zone's boundary as an RFC 7946 geometry.
+
+    Returns a ``Polygon`` normally, or a two-part ``MultiPolygon`` when the cell
+    straddles the antimeridian. A cell enclosing a pole comes back as a
+    ``Polygon`` closed over the pole. Raises `InvalidZoneError` for a zone with
+    no geometry (DGGAL's nullZone), rather than emitting a degenerate shape.
+    """
+    rings = _rings_for(zone)
+    if len(rings) == 1:
+        return {"type": "Polygon", "coordinates": [rings[0]]}
+    return {"type": "MultiPolygon", "coordinates": [[r] for r in rings]}
+
+
+def zone_feature(zone, properties: dict | None = None) -> dict:
+    """The zone as a GeoJSON Feature. Defaults to carrying its text id; pass
+    `properties` to replace that wholesale."""
+    return {
+        "type": "Feature",
+        "geometry": zone_geometry(zone),
+        "properties": {"zone": zone.text_id} if properties is None else properties,
+    }
+
+
+def feature_collection(zones: Iterable, properties=None) -> dict:
+    """A FeatureCollection over any iterable of zones.
+
+    `properties` may be a dict applied to every feature, or a callable taking a
+    zone and returning its properties.
+    """
+    resolve = properties if callable(properties) else lambda _zone: properties
+    return {
+        "type": "FeatureCollection",
+        "features": [zone_feature(zone, resolve(zone)) for zone in zones],
+    }

py4dggs/grid.py

@@ -0,0 +1,253 @@
+# src/py4dggs/grid.py
+"""A Grid is one DGGRS = Projection + Topology + Indexing. Operations needing
+all three (notably the grid-agnostic geographic edge-crossing k-ring) live
+here."""
+from __future__ import annotations
+import math
+from dataclasses import dataclass
+from py4dggs.interfaces import Projection, Topology, Indexing
+from py4dggs.types import GeoPoint, GridConfig, InvalidZoneError
+
+def _ll_to_xyz(lat, lon):
+    la, lo = math.radians(lat), math.radians(lon); cla = math.cos(la)
+    return [cla * math.cos(lo), cla * math.sin(lo), math.sin(la)]
+
+def _xyz_to_ll(v):
+    n = math.sqrt(sum(k * k for k in v)); x, y, z = (k / n for k in v)
+    return math.degrees(math.asin(max(-1.0, min(1.0, z)))), math.degrees(math.atan2(y, x))
+
+
+# DGGAL's geometry for a zone that has none: getZoneWGS84Centroid/Vertices on a
+# nullZone give the zero point and six zero vertices (six regardless of whether
+# the address is a pentagon path — verified against pydggal on all three
+# aperture-7 grids). See `Topology.is_null_geometry` in interfaces.py.
+_NULL_GEOPOINT = GeoPoint(0.0, 0.0)
+_NULL_VERTICES = tuple(GeoPoint(0.0, 0.0) for _ in range(6))
+
+
+@dataclass(frozen=True)
+class Grid:
+    projection: Projection
+    topology: Topology
+    indexing: Indexing
+    config: GridConfig
+    name: str
+
+    def __post_init__(self):
+        object.__setattr__(self, "_geom", self.projection.build_geometry(self.config))
+
+    # --- indexing entry points ---
+    def zone_from_geo(self, lat: float, lon: float, res: int):
+        if not 0 <= res <= self.indexing.max_resolution:
+            raise InvalidZoneError(f"resolution {res} out of range 0..{self.indexing.max_resolution}")
+        p = self.projection.forward(self._geom, lat, lon)
+        base, digits = self.topology.quantize(self._geom, p, res)
+        from py4dggs.zone import Zone
+        return Zone(self, self.indexing.encode(base, digits))
+
+    def zone_from_text(self, text: str):
+        """Construct a Zone from its canonical Z7 text id (validated via the indexing)."""
+        from py4dggs.zone import Zone
+        return Zone(self, self.indexing.from_text(text))
+
+    # --- geometry: planar (topology) -> geographic (projection) ---
+    def _is_null_geometry(self, base: int, digits: list[int]) -> bool:
+        """Whether the topology declares this address geometry-less (DGGAL's
+        `nullZone`). Optional capability — absent means "always has geometry",
+        which is right for every topology that has no degenerate level."""
+        fn = getattr(self.topology, "is_null_geometry", None)
+        return fn is not None and fn(self._geom, base, digits)
+
+    def centroid(self, value: int) -> GeoPoint:
+        base, digits = self.indexing.decode(value)
+        if self._is_null_geometry(base, digits):
+            return _NULL_GEOPOINT
+        p = self.topology.planar_centroid(self._geom, base, digits)
+        return self.projection.inverse(self._geom, p)
+
+    def vertices(self, value: int) -> tuple[GeoPoint, ...]:
+        base, digits = self.indexing.decode(value)
+        if self._is_null_geometry(base, digits):
+            return _NULL_VERTICES
+        ps = self.topology.planar_vertices(self._geom, base, digits)
+        return tuple(self.projection.inverse(self._geom, p) for p in ps)
+
+    # --- neighbours: exact topology override if provided, else grid-agnostic k-ring ---
+    def neighbors(self, value: int) -> tuple[int, ...]:
+        base, digits = self.indexing.decode(value)
+        # A zone with no geometry has no neighbours: pydggal's getZoneNeighbors
+        # returns [] for a Z7 level-20 zone. Checked before the k-ring below,
+        # which would otherwise reflect the degenerate (0,0) vertices back
+        # through quantize and raise a bare IndexError (it did so even before
+        # is_null_geometry existed, when the vertices were merely meaningless
+        # rather than zero).
+        if self._is_null_geometry(base, digits):
+            return ()
+        # A Topology MAY expose an exact `neighbors` (aperture-3 does — it ports
+        # DGGAL's exact adjacency); prefer it. Aperture-7 has none, so it falls
+        # through to the grid-agnostic edge k-ring below (proven exact for 7H).
+        nb_fn = getattr(self.topology, "neighbors", None)
+        if nb_fn is not None:
+            return tuple(self.indexing.encode(b, d) for (b, d) in nb_fn(self._geom, base, digits))
+        # --- grid-agnostic geographic edge-crossing k-ring ---
+        res = self.indexing.resolution(value)
+        c = self.centroid(value); verts = self.vertices(value)
+        c3 = _ll_to_xyz(c.lat, c.lon); n = len(verts)
+        origin, out, seen = value, [], set()
+        for i in range(n):
+            v0 = _ll_to_xyz(*verts[i]); v1 = _ll_to_xyz(*verts[(i + 1) % n])
+            t = [v0[k] + v1[k] - c3[k] for k in range(3)]
+            lat, lon = _xyz_to_ll(t)
+            p = self.projection.forward(self._geom, lat, lon)
+            base, digits = self.topology.quantize(self._geom, p, res)
+            nv = self.indexing.encode(base, digits)
+            if nv == origin or nv in seen:
+                continue
+            seen.add(nv); out.append(nv)
+        return tuple(out)
+
+    # --- hierarchy: exact topology override if provided, else congruent digit-path ---
+    def parents(self, value: int) -> tuple[int, ...]:
+        fn = getattr(self.topology, "parents", None)
+        if fn is not None:
+            base, digits = self.indexing.decode(value)
+            return tuple(self.indexing.encode(b, d) for (b, d) in fn(self._geom, base, digits))
+        p = self.indexing.parent(value)
+        return () if p is None else (p,)
+
+    def children(self, value: int) -> tuple[int, ...]:
+        fn = getattr(self.topology, "children", None)
+        base, digits = self.indexing.decode(value)
+        if fn is not None:
+            return tuple(self.indexing.encode(b, d) for (b, d) in fn(self._geom, base, digits))
+        # congruent digit-path default (Z7): a max-resolution zone has no
+        # children -- you cannot refine past max_resolution (a further digit
+        # does not fit the packing). Mirrors parent() -> () at resolution 0.
+        if self.indexing.resolution(value) >= self.indexing.max_resolution:
+            return ()
+        return tuple(self.indexing.encode(base, digits + [d]) for d in self.indexing.child_digits(value))
+
+    def centroid_parent(self, value: int) -> int | None:
+        fn = getattr(self.topology, "centroid_parent", None)
+        if fn is not None:
+            base, digits = self.indexing.decode(value)
+            r = fn(self._geom, base, digits)
+            return None if r is None else self.indexing.encode(*r)
+        return self.indexing.parent(value)  # congruent: the one parent IS the centroid parent
+
+    def is_centroid_child(self, value: int) -> bool:
+        fn = getattr(self.topology, "is_centroid_child", None)
+        if fn is not None:
+            base, digits = self.indexing.decode(value)
+            return fn(self._geom, base, digits)
+        return True  # congruent: every cell has exactly one parent
+
+    # --- sub-zones: required topology override (no congruent-digit default exists) ---
+    #: Ceiling on how many sub-zones :meth:`sub_zones` will materialise into a
+    #: tuple. `count_sub_zones` is a cheap closed form, but `sub_zones` builds
+    #: the whole sequence, and `relative_depth` was validated only against
+    #: `max_resolution` -- never against result *cardinality*. On an I3H grid at
+    #: resolution 0, depth 33 counts 4,632,550,579,746,406 sub-zones and passed
+    #: every guard, so a caller-supplied depth (the README's DGGS-as-tile-store
+    #: pattern) was a one-line denial of service. 4 million keeps every
+    #: realistic tiling request working -- an I3H cell has 6 sub-zones at depth
+    #: 1 and ~4.6M at depth 16 -- while refusing the unservable ones outright.
+    #: Callers who want the count without the cost still call `count_sub_zones`.
+    MAX_MATERIALISED_SUB_ZONES = 4_000_000
+
+    def _sub_zone_fn(self, name: str, value: int, relative_depth: int):
+        """Shared guard for count_sub_zones/first_sub_zone/sub_zones: resolve
+        the topology override (or raise), then reject the two invalid-input
+        cases that would otherwise reach the depth-dependent geometric
+        generators, which aren't designed for them and misbehave silently
+        (a negative depth turns `3**((depth-1)//2)`-style exponents into
+        floats; an over-deep depth produces a zone past `max_resolution`
+        with no error, since only `zone_from_geo` -- not the sub-zone path --
+        validates against it)."""
+        fn = getattr(self.topology, name, None)
+        if fn is None:
+            raise NotImplementedError("this grid has no sub-zone order")
+        if relative_depth < 0:
+            raise ValueError(f"relative_depth must be >= 0, got {relative_depth}")
+        target_res = self.indexing.resolution(value) + relative_depth
+        if target_res > self.indexing.max_resolution:
+            raise InvalidZoneError(
+                f"relative_depth {relative_depth} would reach resolution {target_res}, "
+                f"past max_resolution {self.indexing.max_resolution}"
+            )
+        return fn
+
+    def count_sub_zones(self, value: int, relative_depth: int) -> int:
+        fn = self._sub_zone_fn("count_sub_zones", value, relative_depth)
+        if relative_depth == 0:
+            # I3H's own override treats depth 0 as "the zone itself" (eC
+            # getI3HSubZoneCentroids, I3HSubZones.ec:1787-1790: "if(rDepth > 0)
+            # ... else centroids[0] = zone.centroid" -- the base DGGRS class's
+            # getSubZoneCRSCentroids is a null stub, not a generic dispatcher).
+            # We hoist that semantic to the Grid level (deliberate
+            # generalization, not a claim about where DGGAL implements it --
+            # "depth 0 = same level = the zone itself" is universal to any
+            # DGGS) because it's true regardless of grid/cell-class (verified
+            # against pydggal's getSubZones for interior hex, non-polar
+            # pentagon and polar pentagon -- all three return exactly [value]
+            # at depth 0, even though pydggal's own raw per-grid
+            # getFirstSubZone(zone, 0) is NOT self-consistent for the
+            # pentagon/pole cases, an oracle quirk this generic short-circuit
+            # deliberately does not replicate). Handled here, above the topology
+            # call, so it never reaches the depth-dependent geometric generators
+            # (which are not designed for depth 0 and would misbehave).
+            return 1
+        base, digits = self.indexing.decode(value)
+        return fn(self._geom, base, digits, relative_depth)
+
+    def first_sub_zone(self, value: int, relative_depth: int) -> int:
+        fn = self._sub_zone_fn("first_sub_zone", value, relative_depth)
+        if relative_depth == 0:
+            return value  # see count_sub_zones' depth-0 note
+        base, digits = self.indexing.decode(value)
+        b, d = fn(self._geom, base, digits, relative_depth)
+        return self.indexing.encode(b, d)
+
+    def sub_zones(self, value: int, relative_depth: int) -> tuple:
+        fn = self._sub_zone_fn("sub_zones", value, relative_depth)
+        if relative_depth == 0:
+            return (value,)  # see count_sub_zones' depth-0 note
+        n = self.count_sub_zones(value, relative_depth)
+        if n > self.MAX_MATERIALISED_SUB_ZONES:
+            raise InvalidZoneError(
+                f"relative_depth {relative_depth} yields {n} sub-zones, past the "
+                f"{self.MAX_MATERIALISED_SUB_ZONES} materialisation limit; use "
+                f"count_sub_zones() for the count, or refine in smaller steps"
+            )
+        base, digits = self.indexing.decode(value)
+        return tuple(self.indexing.encode(b, d) for (b, d) in fn(self._geom, base, digits, relative_depth))
+
+    def sub_zone_index(self, value: int, sub_zone_value: int) -> int:
+        """Generic (dggrs.ec:115-131): build the full ordered list, find the
+        position. Not the generators' internal index>=0 fast-forward path
+        (explicitly out of scope -- see the A3 design spec)."""
+        # caller must know the sub-zone's relative depth; derive it from level
+        sub_level = self.indexing.resolution(sub_zone_value)
+        parent_level = self.indexing.resolution(value)
+        relative_depth = sub_level - parent_level
+        if relative_depth == 0:
+            # depth 0 = "the zone itself": sub_zones(v, 0) == (v,),
+            # count_sub_zones(v, 0) == 1 and sub_zone_at_index(v, 0, 0) == v, so
+            # a zone IS its own sub-zone at index 0. Folding this into the
+            # `< 0` rejection reported a real sub-zone as not-a-descendant.
+            return 0 if sub_zone_value == value else -1
+        if relative_depth < 0:
+            return -1
+        subs = self.sub_zones(value, relative_depth)
+        try:
+            return subs.index(sub_zone_value)
+        except ValueError:
+            return -1
+
+    def sub_zone_at_index(self, value: int, relative_depth: int, index: int) -> int:
+        """Generic (dggrs.ec:133-149)."""
+        if index < 0 or index >= self.count_sub_zones(value, relative_depth):
+            raise IndexError(f"index {index} out of range for relative_depth {relative_depth}")
+        if index == 0:
+            return self.first_sub_zone(value, relative_depth)
+        return self.sub_zones(value, relative_depth)[index]

py4dggs/indexings/__init__.py

@@ -0,0 +1,2 @@
+# src/py4dggs/indexings/__init__.py
+"""Concrete Indexing implementations for each supported DGGRS."""