hilbertplot 0.0.0__py3-none-any.whl

hilbertplot/__init__.py

@@ -0,0 +1,69 @@
+"""hilbertplot -- the complete set of 40 two-dimensional Hilbert curves, and data plots on them.
+
+``hilbertplot`` implements every two-dimensional Hilbert-type space-filling curve proved to
+exist by Estevez-Rams *et al.*, "Hilbert curves in two dimensions", *Rev. Cub. Fis.*
+**34**, 9 (2017): twelve homogeneous (six proper, six improper) and twenty-eight
+inhomogeneous -- forty in all -- and uses them to lay long 1-D data vectors onto 2-D
+images (Estevez-Rams *et al.*, *Comput. Phys. Commun.* **197** (2015) 118).
+
+Curves
+------
+>>> import hilbertplot
+>>> hilbertplot.curve("Moore").show(6)                 # doctest: +SKIP
+>>> hilbertplot.curve(0).points(3).shape
+(64, 2)
+>>> print(hilbertplot.proper())                        # doctest: +SKIP
+ #  name     kind    closed
+ ...
+
+Data plots
+----------
+``plot_data`` / ``hilbert_plot`` return a ``HilbertPlot`` that holds the data and draws
+nothing until you call ``.show`` / ``.save`` -- where you pick the colormap (a name or a
+list of colours to interpolate), the granularity, and how to fit a length that is not a
+power of four:
+
+>>> plot = hilbertplot.hilbert_plot(0, range(1024))    # curve 0, the Hilbert curve
+>>> plot.show(["red", "green", "tab:blue"])      # doctest: +SKIP
+>>> plot.show("viridis", granularity=4)          # doctest: +SKIP
+
+Round trip
+----------
+``curve.unroll(image)`` reads a ``2**k`` by ``2**k`` array back into a 1-D vector in
+curve order -- the inverse of the data mapping.
+
+The public API is exactly the names in ``hilbertplot.__all__``; everything else is internal.
+"""
+
+from __future__ import annotations
+
+from ._core.curve import (
+    by_kernels,
+    catalog,
+    closed,
+    curve,
+    generalizing,
+    homogeneous,
+    improper,
+    inhomogeneous,
+    proper,
+)
+from ._viz.hilbert_plot import hilbert_plot
+from ._viz.render import gallery
+
+__version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+    "curve",
+    "catalog",
+    "homogeneous",
+    "inhomogeneous",
+    "proper",
+    "improper",
+    "closed",
+    "generalizing",
+    "by_kernels",
+    "hilbert_plot",
+    "gallery",
+]

hilbertplot/_core/__init__.py

@@ -0,0 +1 @@
+"""Internal subpackage (not part of the public API)."""

hilbertplot/_core/arbitrary.py

@@ -0,0 +1,114 @@
+"""Arbitrary-size (non-power-of-two) square generation for the curves that support it.
+
+Only eight of the forty curves can be laid on an arbitrary ``n x n`` square as a single
+connected space-filling path (the rest are provably obstructed -- see
+``research/quasisquares/``). This module implements the approximately-even-partition
+(AEP) construction of Wu & Chang, generalized to those eight curves via the catalog
+quadrant rules and the full dihedral group ``D4``, with a per-curve *swap rule* that
+keeps the path connected at odd sizes.
+
+Public surface is the :meth:`hilbertplot.Curve.grid` method and the :func:`hilbertplot.generalizing`
+group; this module is the engine behind them.  ``grid(2**k)`` reproduces the standard
+``points(k)`` curve exactly for all eight, so the two are interchangeable.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .catalog import SPECS
+from .symmetry import MORPHISMS
+
+#: The eight curves that tile arbitrary squares (proved in research/quasisquares/).
+FEASIBLE: frozenset[int] = frozenset({0, 3, 4, 5, 24, 29, 30, 31})
+
+#: The size-independent swap rule for each feasible curve: (width-split, height-split),
+#: each in {"first" = force low half even, "second" = high half even, "none"}.
+_SWAP: dict[int, tuple[str, str]] = {
+    0: ("first", "first"), 3: ("first", "second"), 4: ("second", "first"),
+    5: ("first", "second"), 24: ("first", "second"), 29: ("second", "first"),
+    30: ("second", "first"), 31: ("first", "second"),
+}
+
+#: For each infeasible curve, a small square size at which it provably fails (for messages).
+WITNESS: dict[int, int] = {
+    1: 7, 2: 7, 6: 3, 7: 9, 8: 3, 9: 5, 10: 5, 11: 5, 12: 3, 13: 5, 14: 3, 15: 5,
+    16: 7, 17: 5, 18: 13, 19: 7, 20: 7, 21: 13, 22: 7, 23: 9, 25: 13, 26: 7, 27: 7,
+    28: 13, 32: 5, 33: 5, 34: 5, 35: 5, 36: 5, 37: 3, 38: 7, 39: 14,
+}
+
+# D4 matrices (act on column (x, y): new = M @ (x, y)) and catalog rules.
+_MAT = {code: (tuple(s.matrix[0]), tuple(s.matrix[1])) for code, s in MORPHISMS.items()}
+_IDENT = _MAT["e"]
+_RULES = {s.index: [(q.base, _MAT[q.morphism], q.reverse) for q in s.quadrants] for s in SPECS}
+
+
+def _matmul(A, B):
+    return ((A[0][0]*B[0][0]+A[0][1]*B[1][0], A[0][0]*B[0][1]+A[0][1]*B[1][1]),
+            (A[1][0]*B[0][0]+A[1][1]*B[1][0], A[1][0]*B[0][1]+A[1][1]*B[1][1]))
+
+
+# Canonical base-tile visit orders (Wc, Hc) -> cells; the 2x2 is orientation A's U.
+_BASE = {(1, 1): ((0, 0),), (2, 1): ((0, 0), (1, 0)), (1, 2): ((0, 0), (0, 1)),
+         (2, 2): ((0, 0), (0, 1), (1, 1), (1, 0))}
+_ORDER = (0, 1, 2, 3)
+_ORDER_REV = (3, 2, 1, 0)
+
+
+def _fill(index, x0, y0, w, h, M, rev, out):
+    """Append the (x, y) cells of curve `index` on region (x0,y0,w,h), orientation `M`,
+    to the list `out` (reversed if `rev`).  Hot path -- all affine maths is inlined."""
+    (a, b), (c, d) = M
+    Wc, Hc = (h, w) if a == 0 else (w, h)
+    # translate so the canonical box maps into the region's own frame (D4 matrices only)
+    ox = x0 - ((a * (Wc - 1) if a < 0 else 0) + (b * (Hc - 1) if b < 0 else 0))
+    oy = y0 - ((c * (Wc - 1) if c < 0 else 0) + (d * (Hc - 1) if d < 0 else 0))
+    if w <= 2 and h <= 2:
+        cells = _BASE[(Wc, Hc)]
+        mapped = [(ox + a * cx + b * cy, oy + c * cx + d * cy) for (cx, cy) in cells]
+        out.extend(reversed(mapped) if rev else mapped)
+        return
+    sw, sh = _SWAP.get(index, ("first", "first"))
+    Wc1 = Wc // 2; Wc2 = Wc - Wc1
+    if sw == "first" and Wc1 & 1: Wc1, Wc2 = Wc2, Wc1
+    elif sw == "second" and Wc2 & 1: Wc1, Wc2 = Wc2, Wc1
+    Hc1 = Hc // 2; Hc2 = Hc - Hc1
+    if sh == "first" and Hc1 & 1: Hc1, Hc2 = Hc2, Hc1
+    elif sh == "second" and Hc2 & 1: Hc1, Hc2 = Hc2, Hc1
+    boxes = ((0, 0, Wc1, Hc1), (0, Hc1, Wc1, Hc2), (Wc1, Hc1, Wc2, Hc2), (Wc1, 0, Wc2, Hc1))
+    rules = _RULES[index]
+    for i in (_ORDER_REV if rev else _ORDER):
+        base_i, morph_i, revi = rules[i]
+        cx0, cy0, cw, ch = boxes[i]
+        x1 = cx0 + cw - 1; y1 = cy0 + ch - 1
+        # absolute bounding box of the four transformed sub-box corners
+        u0 = ox + a * cx0 + b * cy0; u1 = ox + a * x1 + b * cy0
+        u2 = ox + a * cx0 + b * y1; u3 = ox + a * x1 + b * y1
+        v0 = oy + c * cx0 + d * cy0; v1 = oy + c * x1 + d * cy0
+        v2 = oy + c * cx0 + d * y1; v3 = oy + c * x1 + d * y1
+        axmin = u0 if u0 < u1 else u1
+        if u2 < axmin: axmin = u2
+        if u3 < axmin: axmin = u3
+        axmax = u0 if u0 > u1 else u1
+        if u2 > axmax: axmax = u2
+        if u3 > axmax: axmax = u3
+        aymin = v0 if v0 < v1 else v1
+        if v2 < aymin: aymin = v2
+        if v3 < aymin: aymin = v3
+        aymax = v0 if v0 > v1 else v1
+        if v2 > aymax: aymax = v2
+        if v3 > aymax: aymax = v3
+        _fill(base_i, axmin, aymin, axmax - axmin + 1, aymax - aymin + 1,
+              _matmul(M, morph_i), revi ^ rev, out)
+
+
+def square_points(index: int, n: int) -> np.ndarray:
+    """Return the ``(n*n, 2)`` cell path of feasible curve ``index`` on an ``n x n`` grid.
+
+    The caller is responsible for checking ``index in FEASIBLE`` and ``n >= 1``.
+    """
+    if n == 1:
+        return np.zeros((1, 2), dtype=np.int64)
+    out: list = []
+    _fill(index, 0, 0, n, n, _IDENT, False, out)
+    return np.array(out, dtype=np.int64)

hilbertplot/_core/catalog.py

@@ -0,0 +1,451 @@
+"""Declarative specification of the forty two-dimensional Hilbert curves.
+
+This module is pure data plus the small dataclasses that give it structure.  It is
+the single source of truth for the whole library and maps one-to-one onto the tag
+systems of Estevez-Rams *et al.*, "Hilbert curves in two dimensions",
+*Rev. Cub. Fis.* **34**, 9 (2017).
+
+The construction
+----------------
+Every order ``k`` curve is assembled from four sub-curves of order ``k - 1`` -- one
+per quadrant -- joined by the fixed connectors ``u``, ``r``, ``d``::
+
+    word_k(nu) = Q0 . 'u' . Q1 . 'r' . Q2 . 'd' . Q3
+
+The quadrants are numbered as in Fig. 1 of the paper, clockwise from the lower
+left: ``0`` = bottom-left, ``1`` = top-left, ``2`` = top-right, ``3`` =
+bottom-right.  The connectors therefore trace ``0 -(up)-> 1 -(right)-> 2 -(down)->
+3``.
+
+Each quadrant ``Qi`` is obtained from a *kernel* curve ``base`` (also of order
+``k - 1``) by applying a morphism and, optionally, a reversion:
+
+    Qi = [reversion?] ( morphism ( word_{k-1}(base) ) )
+
+The classification the paper draws -- and that the user asked us to reflect -- falls
+straight out of the kernels:
+
+* **homogeneous** curves use a single kernel type in all four quadrants
+  (Definition III.1: "built from one and only one Hilbert curve of order k-1");
+* **inhomogeneous** curves mix at least two kernel types (Definition VI.1).
+
+Homogeneous curves split further into *proper* (kernel = the Hilbert curve ``0H``)
+and *improper* (kernel = the Liu-4 curve ``5H``).
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+
+__all__ = [
+    "Family",
+    "QuadrantRule",
+    "CurveSpec",
+    "SPECS",
+    "spec_by_index",
+]
+
+
+class Family(enum.Enum):
+    """The three families the forty curves fall into."""
+
+    HOMOGENEOUS_PROPER = "homogeneous-proper"
+    HOMOGENEOUS_IMPROPER = "homogeneous-improper"
+    INHOMOGENEOUS = "inhomogeneous"
+
+    @property
+    def is_homogeneous(self) -> bool:
+        return self is not Family.INHOMOGENEOUS
+
+
+@dataclass(frozen=True)
+class QuadrantRule:
+    """How one quadrant of an order ``k`` curve is built from an order ``k-1`` curve.
+
+    Parameters
+    ----------
+    base:
+        Index of the *kernel* curve supplying this quadrant's sub-curve.  Only the
+        homogeneous building blocks ``{0, 1, 3, 4, 5}`` (and never ``2``) ever
+        appear here, exactly as proved in the paper.
+    morphism:
+        Single-letter morphism code (see :data:`hilbertplot._core.symmetry.MORPHISMS`).
+    reverse:
+        Whether the reversion :math:`\\bar p` is applied after the morphism.
+    """
+
+    base: int
+    morphism: str
+    reverse: bool = False
+
+    def __str__(self) -> str:
+        inner = f"{self.base}H"
+        if self.morphism != "e":
+            inner = f"d_{self.morphism}({inner})"
+        return f"rev({inner})" if self.reverse else inner
+
+
+@dataclass(frozen=True)
+class CurveSpec:
+    """Immutable description of one of the forty curves.
+
+    Attributes
+    ----------
+    index:
+        The curve number ``nu`` in ``0..39`` (the paper's :math:`{}_\\nu H`).
+    name:
+        Human-readable name (``"Hilbert"``, ``"Moore"``, ``"Liu1"``, ..., ``"I1"``,
+        ``"IH12"`` ...).
+    family:
+        Which :class:`Family` the curve belongs to.
+    quadrants:
+        The four :class:`QuadrantRule` s, in quadrant order ``0, 1, 2, 3``.
+    combination:
+        Short label of the kernel mix (e.g. ``"0H"``, ``"5H"``, ``"3H+5H"``), matching
+        the paper's grouping of the inhomogeneous curves.
+    closed:
+        ``True`` if the curve's entry and exit lie in adjacent sub-squares so that the
+        infinite curve closes into a loop (Moore, Liu1, I1, I4; Table 3 of the paper).
+    """
+
+    index: int
+    name: str
+    family: Family
+    quadrants: tuple[QuadrantRule, QuadrantRule, QuadrantRule, QuadrantRule]
+    combination: str
+    closed: bool = False
+    #: Optional free-form geometric notes lifted from Table 3 of the paper.
+    notes: str = field(default="", compare=False)
+
+    @property
+    def kernels(self) -> frozenset[int]:
+        """The set of distinct kernel curve indices used across the four quadrants."""
+        return frozenset(q.base for q in self.quadrants)
+
+    @property
+    def is_homogeneous(self) -> bool:
+        return self.family.is_homogeneous
+
+    def rule_str(self) -> str:
+        """Reconstruct the paper's tag-system line for this curve."""
+        q0, q1, q2, q3 = self.quadrants
+        return f"{self.index}h(k) = {q0} u {q1} r {q2} d {q3}"
+
+
+def _q(base: int, morphism: str = "e", reverse: bool = False) -> QuadrantRule:
+    return QuadrantRule(base, morphism, reverse)
+
+
+# ---------------------------------------------------------------------------
+# The forty curves.
+#
+# Transcribed directly from the tag systems in sections V and VII of the paper.
+# Homogeneous proper curves are built over the Hilbert kernel 0H; improper curves
+# over the Liu-4 kernel 5H; inhomogeneous curves mix kernels.  A bar over a term in
+# the paper (reversion) is recorded as ``reverse=True``.
+# ---------------------------------------------------------------------------
+
+_PROPER: tuple[CurveSpec, ...] = (
+    CurveSpec(
+        0,
+        "Hilbert",
+        Family.HOMOGENEOUS_PROPER,
+        (_q(0, "o"), _q(0), _q(0), _q(0, "a")),
+        "0H",
+        notes="corner-corner; the original Hilbert curve",
+    ),
+    CurveSpec(
+        1,
+        "Moore",
+        Family.HOMOGENEOUS_PROPER,
+        (_q(0, "g"), _q(0, "g"), _q(0, "x"), _q(0, "x")),
+        "0H",
+        closed=True,
+        notes="edge-edge shared; Moore's closed curve",
+    ),
+    CurveSpec(
+        2,
+        "Liu1",
+        Family.HOMOGENEOUS_PROPER,
+        (_q(0, "f"), _q(0), _q(0), _q(0, "f")),
+        "0H",
+        closed=True,
+        notes="interior-interior; cannot serve as a building block",
+    ),
+    CurveSpec(
+        3,
+        "Liu2",
+        Family.HOMOGENEOUS_PROPER,
+        (_q(0, "m"), _q(0, "g"), _q(0, "x"), _q(0, "m")),
+        "0H",
+        notes="edge-edge opposed",
+    ),
+    CurveSpec(
+        4,
+        "Liu3",
+        Family.HOMOGENEOUS_PROPER,
+        (_q(0, "o"), _q(0), _q(0), _q(0, "f")),
+        "0H",
+        notes="corner-interior",
+    ),
+    CurveSpec(
+        5,
+        "Liu4",
+        Family.HOMOGENEOUS_PROPER,
+        (_q(0, "m"), _q(0, "g"), _q(0, "x"), _q(0, "x")),
+        "0H",
+        notes="edge-edge adjacent; kernel of every improper curve",
+    ),
+)
+
+_IMPROPER: tuple[CurveSpec, ...] = (
+    CurveSpec(
+        6,
+        "I1",
+        Family.HOMOGENEOUS_IMPROPER,
+        (_q(5, "f"), _q(5, "y", True), _q(5), _q(5, "m", True)),
+        "5H",
+        closed=True,
+        notes="interior-interior",
+    ),
+    CurveSpec(
+        7,
+        "I2",
+        Family.HOMOGENEOUS_IMPROPER,
+        (_q(5, "f"), _q(5, "y", True), _q(5), _q(5, "a")),
+        "5H",
+        notes="interior-edge",
+    ),
+    CurveSpec(
+        8,
+        "I3",
+        Family.HOMOGENEOUS_IMPROPER,
+        (_q(5, "x", True), _q(5, "y", True), _q(5), _q(5, "a")),
+        "5H",
+        notes="edge-edge opposed",
+    ),
+    CurveSpec(
+        9,
+        "I4",
+        Family.HOMOGENEOUS_IMPROPER,
+        (_q(5, "a", True), _q(5, "g"), _q(5, "o", True), _q(5, "x")),
+        "5H",
+        closed=True,
+        notes="interior-interior",
+    ),
+    CurveSpec(
+        10,
+        "I5",
+        Family.HOMOGENEOUS_IMPROPER,
+        (_q(5, "m"), _q(5, "g"), _q(5, "o", True), _q(5, "f", True)),
+        "5H",
+        notes="edge-edge opposed",
+    ),
+    CurveSpec(
+        11,
+        "I6",
+        Family.HOMOGENEOUS_IMPROPER,
+        (_q(5, "m"), _q(5, "g"), _q(5, "o", True), _q(5, "x")),
+        "5H",
+        notes="edge-interior",
+    ),
+)
+
+# Inhomogeneous curves 12-39.  Grouped exactly as in the paper (Figures 6-9).
+_INHOMOGENEOUS: tuple[CurveSpec, ...] = (
+    # 3H + 5H  (Figure 6): two 3H + two 5H, then one 3H + three 5H.
+    CurveSpec(
+        12, "IH12", Family.INHOMOGENEOUS, (_q(3, "o"), _q(5, "y", True), _q(5), _q(3, "a")), "3H+5H"
+    ),
+    CurveSpec(
+        13,
+        "IH13",
+        Family.INHOMOGENEOUS,
+        (_q(3, "g"), _q(5, "g"), _q(5, "o", True), _q(3, "x")),
+        "3H+5H",
+    ),
+    CurveSpec(
+        14, "IH14", Family.INHOMOGENEOUS, (_q(3, "o"), _q(5, "y", True), _q(5), _q(5, "a")), "3H+5H"
+    ),
+    CurveSpec(
+        15,
+        "IH15",
+        Family.INHOMOGENEOUS,
+        (_q(3, "g"), _q(5, "g"), _q(5, "o", True), _q(5, "f", True)),
+        "3H+5H",
+    ),
+    CurveSpec(
+        16,
+        "IH16",
+        Family.INHOMOGENEOUS,
+        (_q(3, "o"), _q(5, "y", True), _q(5), _q(5, "m", True)),
+        "3H+5H",
+    ),
+    CurveSpec(
+        17,
+        "IH17",
+        Family.INHOMOGENEOUS,
+        (_q(3, "g"), _q(5, "g"), _q(5, "o", True), _q(5, "x")),
+        "3H+5H",
+    ),
+    # 0H + 4H  (Figure 7): fourteen curves.
+    CurveSpec(
+        18, "IH18", Family.INHOMOGENEOUS, (_q(4, "x", True), _q(0), _q(0), _q(4, "a")), "0H+4H"
+    ),
+    CurveSpec(
+        19, "IH19", Family.INHOMOGENEOUS, (_q(4, "m", True), _q(0), _q(0), _q(4, "f")), "0H+4H"
+    ),
+    CurveSpec(
+        20, "IH20", Family.INHOMOGENEOUS, (_q(4, "x", True), _q(0), _q(0), _q(4, "f")), "0H+4H"
+    ),
+    CurveSpec(
+        21,
+        "IH21",
+        Family.INHOMOGENEOUS,
+        (_q(4, "f", True), _q(0, "g"), _q(0, "x"), _q(4, "m")),
+        "0H+4H",
+    ),
+    CurveSpec(
+        22,
+        "IH22",
+        Family.INHOMOGENEOUS,
+        (_q(4, "a", True), _q(0, "g"), _q(0, "x"), _q(4, "x")),
+        "0H+4H",
+    ),
+    CurveSpec(
+        23,
+        "IH23",
+        Family.INHOMOGENEOUS,
+        (_q(4, "a", True), _q(0, "g"), _q(0, "x"), _q(4, "m")),
+        "0H+4H",
+    ),
+    CurveSpec(
+        24, "IH24", Family.INHOMOGENEOUS, (_q(0, "m"), _q(0, "g"), _q(0, "x"), _q(4, "x")), "0H+4H"
+    ),
+    CurveSpec(
+        25, "IH25", Family.INHOMOGENEOUS, (_q(0, "g"), _q(0, "g"), _q(0, "x"), _q(4, "m")), "0H+4H"
+    ),
+    CurveSpec(
+        26, "IH26", Family.INHOMOGENEOUS, (_q(0, "g"), _q(0, "g"), _q(0, "x"), _q(4, "x")), "0H+4H"
+    ),
+    CurveSpec(27, "IH27", Family.INHOMOGENEOUS, (_q(0, "f"), _q(0), _q(0), _q(4, "f")), "0H+4H"),
+    CurveSpec(28, "IH28", Family.INHOMOGENEOUS, (_q(0, "f"), _q(0), _q(0), _q(4, "a")), "0H+4H"),
+    CurveSpec(29, "IH29", Family.INHOMOGENEOUS, (_q(0, "o"), _q(0), _q(0), _q(4, "f")), "0H+4H"),
+    CurveSpec(30, "IH30", Family.INHOMOGENEOUS, (_q(0, "o"), _q(0), _q(0), _q(4, "a")), "0H+4H"),
+    CurveSpec(
+        31, "IH31", Family.INHOMOGENEOUS, (_q(0, "m"), _q(0, "g"), _q(0, "x"), _q(4, "m")), "0H+4H"
+    ),
+    # 1H + 5H  (Figure 8): two 1H + two 5H, then one 1H + three 5H.
+    CurveSpec(
+        32, "IH32", Family.INHOMOGENEOUS, (_q(1, "f"), _q(5, "y", True), _q(5), _q(1, "f")), "1H+5H"
+    ),
+    CurveSpec(
+        33,
+        "IH33",
+        Family.INHOMOGENEOUS,
+        (_q(1, "m"), _q(5, "g"), _q(5, "o", True), _q(1, "m")),
+        "1H+5H",
+    ),
+    CurveSpec(
+        34, "IH34", Family.INHOMOGENEOUS, (_q(5, "f"), _q(5, "y", True), _q(5), _q(1, "f")), "1H+5H"
+    ),
+    CurveSpec(
+        35,
+        "IH35",
+        Family.INHOMOGENEOUS,
+        (_q(5, "a", True), _q(5, "g"), _q(5, "o", True), _q(1, "m")),
+        "1H+5H",
+    ),
+    CurveSpec(
+        36,
+        "IH36",
+        Family.INHOMOGENEOUS,
+        (_q(5, "x", True), _q(5, "y", True), _q(5), _q(1, "f")),
+        "1H+5H",
+    ),
+    CurveSpec(
+        37,
+        "IH37",
+        Family.INHOMOGENEOUS,
+        (_q(5, "m"), _q(5, "g"), _q(5, "o", True), _q(1, "m")),
+        "1H+5H",
+    ),
+    # 1H + 3H + 5H  (Figure 9): two curves.
+    CurveSpec(
+        38,
+        "IH38",
+        Family.INHOMOGENEOUS,
+        (_q(3, "o"), _q(5, "y", True), _q(5), _q(1, "f")),
+        "1H+3H+5H",
+    ),
+    CurveSpec(
+        39,
+        "IH39",
+        Family.INHOMOGENEOUS,
+        (_q(3, "g"), _q(5, "g"), _q(5, "o", True), _q(1, "m")),
+        "1H+3H+5H",
+    ),
+)
+
+# Friendly, human-readable names.  Proper curves keep their established names
+# (Hilbert, Moore, Liu1-4); improper curves become Improper1-6; and each
+# inhomogeneous curve is named by the curves it mixes plus an index within the
+# group, e.g. "Liu2+Liu4 #1" -- so the name states the recipe.
+_PROPER_NAME = {0: "Hilbert", 1: "Moore", 2: "Liu1", 3: "Liu2", 4: "Liu3", 5: "Liu4"}
+
+
+def _with_friendly_names(specs: tuple[CurveSpec, ...]) -> tuple[CurveSpec, ...]:
+    counters: dict[str, int] = {}
+    out = []
+    for s in specs:
+        if s.family is Family.HOMOGENEOUS_IMPROPER:
+            s = replace(s, name=f"Improper{s.index - 5}")
+        elif s.family is Family.INHOMOGENEOUS:
+            recipe = "+".join(_PROPER_NAME[k] for k in sorted(s.kernels))
+            counters[recipe] = counters.get(recipe, 0) + 1
+            s = replace(s, name=f"{recipe} #{counters[recipe]}")
+        out.append(s)
+    return tuple(out)
+
+
+#: All forty specifications, ordered by index.
+SPECS: tuple[CurveSpec, ...] = _with_friendly_names(_PROPER + _IMPROPER + _INHOMOGENEOUS)
+
+_BY_INDEX: Mapping[int, CurveSpec] = {s.index: s for s in SPECS}
+
+
+def spec_by_index(index: int) -> CurveSpec:
+    """Return the :class:`CurveSpec` for curve number ``index`` (0..39)."""
+    try:
+        return _BY_INDEX[index]
+    except KeyError:
+        raise KeyError(
+            f"curve index {index!r} out of range; expected an integer in 0..39"
+        ) from None
+
+
+# --- internal consistency checks (cheap, run once at import) ----------------
+# These guard against typos in the table above: the declared family must agree
+# with what the kernels imply, and only valid building blocks may appear.
+def _self_check() -> None:
+    assert len(SPECS) == 40, f"expected 40 curves, found {len(SPECS)}"
+    assert [s.index for s in SPECS] == list(range(40)), "curve indices must be 0..39"
+    valid_kernels = {0, 1, 3, 4, 5}  # never 2 (Liu1 cannot connect quadrants)
+    for s in SPECS:
+        assert len(s.quadrants) == 4, f"curve {s.index} needs four quadrants"
+        assert s.kernels <= valid_kernels, (
+            f"curve {s.index} uses invalid kernel(s) {s.kernels - valid_kernels}"
+        )
+        implied_homogeneous = len(s.kernels) == 1
+        assert implied_homogeneous == s.is_homogeneous, (
+            f"curve {s.index}: family {s.family} disagrees with kernels {set(s.kernels)}"
+        )
+        if s.family is Family.HOMOGENEOUS_PROPER:
+            assert s.kernels == {0}, f"proper curve {s.index} must use kernel 0H"
+        elif s.family is Family.HOMOGENEOUS_IMPROPER:
+            assert s.kernels == {5}, f"improper curve {s.index} must use kernel 5H"
+
+
+_self_check()