hilbertplot 0.0.0__tar.gz → 0.2.0__tar.gz

hilbertplot-0.2.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to **hilbertplot** are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to adhere to
+[Semantic Versioning](https://semver.org/).
+
+Released versions below are generated automatically by python-semantic-release;
+new entries are inserted at the marker.
+
+## Migrating from 0.1.0
+
+`hilbertplot` is on `0.x`, where [semver §4](https://semver.org/#spec-item-4) allows the
+interface to change in a minor release. Two spellings changed; both fail loudly rather
+than silently, and nothing else in the 0.1.0 surface was removed.
+
+| 0.1.0 | now | why |
+| --- | --- | --- |
+| `curve.plot(order)` | `curve.draw(order)` | one verb for "render onto axes", shared with `HilbertPlot.draw` |
+| `curve.save(order, path)` | `curve.save(path, order)` | matches `HilbertPlot.save(path, ...)`; the old order raises a `TypeError` naming the fix |
+| `repr(curve)` → `'Hilbert'` | `repr(curve)` → `'<Curve 0H Hilbert (proper)>'` | `repr` is now unambiguous; `str(curve)` is still `'Hilbert'` |
+
+Behaviour that was buggy and is now stricter: `curve(True)` and `curve(3.0)` raise
+`TypeError` instead of silently meaning `curve(1)` / `curve(3)`; an out-of-range index
+raises `IndexError` rather than `KeyError` (both are `LookupError`); `plot.data` is
+genuinely immutable rather than merely flagged; and `image(order=..., fit=...)` now
+validates `fit` instead of ignoring it.
+
+<!-- version list -->
+
+## v0.2.0 (2026-07-25)
+
+### Bug Fixes
+
+- Close the gaps found by the second review round
+  ([`9df64f4`](https://github.com/El3ssar/hilbertplot/commit/9df64f463b2619d0d19ca7d3d818a16e2c25d7d8))
+
+- Keep the new guards from costing more than they save
+  ([`bbaa464`](https://github.com/El3ssar/hilbertplot/commit/bbaa4646af8ca401aa27174277cbae22910cd34f))
+
+### Continuous Integration
+
+- Bump actions, exempt dependabot from title check, curb ruff bumps
+  ([`aa74d78`](https://github.com/El3ssar/hilbertplot/commit/aa74d7810fa542e259dfcee77c23ad9aa491374a))
+
+- Stop Dependabot from bumping ruff
+  ([`f639fc0`](https://github.com/El3ssar/hilbertplot/commit/f639fc0aa5ab67c615bf31470cfd1bd10f5248b5))
+
+- Stop the floors job re-resolving the pins it exists to test
+  ([`106b08f`](https://github.com/El3ssar/hilbertplot/commit/106b08f8bedcf0d6c2c0ff023a60c2ff020265e4))
+
+### Documentation
+
+- Add status badges and tidy the 0.1.0 changelog entry
+  ([`7d967ca`](https://github.com/El3ssar/hilbertplot/commit/7d967caae998903d0885a81c4801b50b974aef62))
+
+- Illustrate the README with generated figures
+  ([`0f245b9`](https://github.com/El3ssar/hilbertplot/commit/0f245b941fbb933141b10d60ee16157c463b8501))
+
+- Streamline the README to install + two examples
+  ([`fb53eab`](https://github.com/El3ssar/hilbertplot/commit/fb53eab38129a8e60c42160d5bfa3959677a37db))
+
+### Features
+
+- Make the arbitrary-square path fast, harden the public surface, add encode/decode
+  ([`a6ce0da`](https://github.com/El3ssar/hilbertplot/commit/a6ce0da3463acaacc6c69d349a1ef06804a817f4))
+
+
+## v0.1.0 (2026-07-25)
+
+First public release — the complete set of 40 two-dimensional Hilbert curves,
+with fast numpy generation and data-visualisation tooling.
+
+### Added
+- The complete set of **40** two-dimensional Hilbert curves (Estevez-Rams et al., 2017):
+  `curve(i)` by index, name or symbol; `points(order)`, `word(order)`; family groups
+  `homogeneous` / `inhomogeneous` / `proper` / `improper` / `closed` / `by_kernels`,
+  returned as a `CurveList` that prints as a table.
+- Fast numpy stroke-code generation (no per-stroke Python loop); order-10 curve (~1M
+  points) in tens of milliseconds.
+- Curve rendering: `curve.show/save/plot(order)` with automatic line→fill mode by order,
+  colour-graded traversal, and `gallery()` for grids of curves.
+- **Data visualisation** ("Hilbert plots", Estevez-Rams et al., 2015): `hilbert_plot`
+  / `curve.plot_data` return a `HilbertPlot` that maps a 1-D vector onto 2-D on demand,
+  with colormap-by-name or colour-list interpolation, the `l`-granularity transform,
+  and `pad` / `truncate` fits.
+- **Difference map** overlay (`difference=True`, tunable threshold) marking where a curve
+  breaks locality (Pérez-Demydenko et al., 2014); `curve.difference_map(order)`.
+- **2-D Fourier map** (`fourier=True`; `HilbertPlot.fourier()`) revealing hidden periodic
+  and self-similar structure.
+- **`unroll`**: read a 2-D square array back into a 1-D vector in curve order.
+- **Arbitrary `n x n` squares** for the eight curves that support it
+  (`curve.grid(n)`, `curve.generalizes`, `hilbertplot.generalizing()`); the data mapping
+  square-fits to a tight `ceil(sqrt(N))` grid by default for those curves. The full
+  feasibility classification and impossibility proofs are in `research/quasisquares/`.
+
+### Notes
+- Requires Python 3.10+. `numpy` is the only runtime dependency; `matplotlib` is the
+  optional `[plot]` extra.

hilbertplot-0.2.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: hilbertplot
+Version: 0.2.0
+Summary: The complete set of 40 two-dimensional Hilbert curves, and data plots on them.
+Project-URL: Homepage, https://github.com/El3ssar/hilbertplot
+Project-URL: Source, https://github.com/El3ssar/hilbertplot
+Project-URL: Issues, https://github.com/El3ssar/hilbertplot/issues
+Project-URL: Changelog, https://github.com/El3ssar/hilbertplot/blob/main/CHANGELOG.md
+Author-email: Daniel Estevez <kemossabee@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dimensionality-reduction,hilbert-curve,locality,moore-curve,space-filling-curve,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.21
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff==0.15.13; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# hilbertplot
+
+[![PyPI version](https://img.shields.io/pypi/v/hilbertplot.svg)](https://pypi.org/project/hilbertplot/)
+[![CI](https://github.com/El3ssar/hilbertplot/actions/workflows/ci.yml/badge.svg)](https://github.com/El3ssar/hilbertplot/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/hilbertplot.svg)](https://pypi.org/project/hilbertplot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/El3ssar/hilbertplot/blob/main/LICENSE)
+
+The **complete set of 40 two-dimensional Hilbert curves** — and a fast way to plot long
+1-D data on any of them.
+
+Most software knows one Hilbert curve. In fact there are **forty** distinct space-filling
+curves of Hilbert type in two dimensions (up to rotation, reflection and reversion), as
+proved by Estevez-Rams et al., *"Hilbert curves in two dimensions"*, Rev. Cub. Fís. **34**,
+9 (2017). `hilbertplot` implements all forty with pure-numpy generation and uses them to lay
+long 1-D vectors onto 2-D images.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/curve.png"
+       width="440" alt="The Hilbert curve at order 4, drawn as a colour-graded path">
+</p>
+
+## Install
+
+```bash
+pip install "hilbertplot[plot]"   # drop [plot] for a numpy-only core (no matplotlib)
+```
+
+## Draw a curve
+
+```python
+import hilbertplot
+
+c = hilbertplot.curve(0)     # by index 0–39, by name ("Moore"), or by symbol
+c.show(4)                    # draw order 4 in a window
+pts = c.points(4)            # (256, 2) integer lattice points, in visit order
+```
+
+The forty curves come in named groups — `hilbertplot.proper()`, `.improper()`,
+`.homogeneous()`, `.inhomogeneous()`, `.generalizing()` — each of which prints as a table,
+and which compose:
+
+```python
+import hilbertplot
+
+print(hilbertplot.proper())                       # a table of the six proper curves
+hilbertplot.catalog().closed().names              # ['Moore', 'Liu1', 'Improper1', 'Improper4']
+hilbertplot.by_kernels(3, 5).gallery(order=3)     # draw a group as a grid of panels
+```
+
+In a Jupyter notebook a `Curve` renders itself — put `hilbertplot.curve("Moore")` in a cell
+and you get the picture, not a `repr`.
+
+## One cell at a time
+
+`points(order)` builds all `4**order` cells. When you only need *where step `i` lands*,
+`encode` answers in `O(order)` — so it works at orders no machine could materialise, and it
+does so for **all forty** curves, not just the classic one:
+
+```python
+import hilbertplot
+
+c = hilbertplot.curve(0)
+c.encode(5, 2)                     # (0, 3) — the cell visited at step 5, order 2
+c.decode(0, 3, 2)                  # 5      — and back again
+c.encode(10**18, 40)               # (751054336, 346100736) — a 2**80-cell curve
+```
+
+## Plot data
+
+Walk a curve and drop `data[i]` on the *i*-th cell it visits: a locality-preserving
+1-D → 2-D map where nearby values stay nearby.
+
+```python
+import numpy as np, hilbertplot
+
+plot = hilbertplot.hilbert_plot(0, np.arange(1, 257))
+plot.show("viridis")          # a matplotlib colormap name, or a list of colours to blend
+```
+
+![The same data laid on two different curves](https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/data_two_curves.png)
+
+*The same numbers on curve 0 and curve 32 — one reason to have all forty.*
+
+## Seeing more than the data
+
+**Coarse-grain it.** `plot.show(granularity=4)` replaces each block of values by its mean.
+Below, a binary sequence interleaves stretches of two periodic patterns with identical
+density — invisible in the faithful plot, obvious once averaged.
+
+![Periodic regions revealed by coarse-graining](https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/granularity.png)
+
+**Find where locality breaks.** `plot.show(difference=True)` marks the cells that are
+neighbours in the plane but far apart along the curve. A higher threshold keeps only the
+worst offenders.
+
+![The difference map at two thresholds](https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/difference.png)
+
+**Transform it.** `plot.show(fourier=True)` renders the 2-D Fourier map, exposing periodic
+and self-similar structure — here, a Thue–Morse sequence.
+
+![A Thue–Morse sequence and its Fourier map](https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/thue_morse.png)
+
+## Also
+
+- `curve.unroll(img)` — read a 2-D array back into 1-D, in curve order
+- `curve.grid(n)` — the eight `generalizing()` curves tile **any** `n×n` square, not just `2ᵏ`
+- `curve.label_map(order)` — the grid of visit indices, as an image
+- `curve.difference_map(order)` — where the curve breaks locality, as a field
+- `plot.draw(colorbar=True)`, or `norm=LogNorm()` for heavy-tailed data
+- `hilbertplot.is_space_filling` / `canonical_form` — check a path yourself; the same tools
+  the test suite uses to prove all forty curves are distinct Hamiltonian paths
+- `hilbertplot.clear_cache()` / `cache_info()` — generated curves are memoised; this frees them
+- `hilbertplot.set_cell_limit(n)` — raise the guard that refuses absurdly large orders
+
+Every figure above is reproducible: `python examples/readme_figures.py`. More runnable
+demos are in
+[`examples/`](https://github.com/El3ssar/hilbertplot/tree/main/examples);
+the arbitrary-square classification and its impossibility proofs are in the repository's
+`research/quasisquares/`.
+
+## License
+
+MIT © Daniel Estevez —
+[LICENSE](https://github.com/El3ssar/hilbertplot/blob/main/LICENSE)

hilbertplot-0.2.0/README.md

@@ -0,0 +1,124 @@
+# hilbertplot
+
+[![PyPI version](https://img.shields.io/pypi/v/hilbertplot.svg)](https://pypi.org/project/hilbertplot/)
+[![CI](https://github.com/El3ssar/hilbertplot/actions/workflows/ci.yml/badge.svg)](https://github.com/El3ssar/hilbertplot/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/hilbertplot.svg)](https://pypi.org/project/hilbertplot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/El3ssar/hilbertplot/blob/main/LICENSE)
+
+The **complete set of 40 two-dimensional Hilbert curves** — and a fast way to plot long
+1-D data on any of them.
+
+Most software knows one Hilbert curve. In fact there are **forty** distinct space-filling
+curves of Hilbert type in two dimensions (up to rotation, reflection and reversion), as
+proved by Estevez-Rams et al., *"Hilbert curves in two dimensions"*, Rev. Cub. Fís. **34**,
+9 (2017). `hilbertplot` implements all forty with pure-numpy generation and uses them to lay
+long 1-D vectors onto 2-D images.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/curve.png"
+       width="440" alt="The Hilbert curve at order 4, drawn as a colour-graded path">
+</p>
+
+## Install
+
+```bash
+pip install "hilbertplot[plot]"   # drop [plot] for a numpy-only core (no matplotlib)
+```
+
+## Draw a curve
+
+```python
+import hilbertplot
+
+c = hilbertplot.curve(0)     # by index 0–39, by name ("Moore"), or by symbol
+c.show(4)                    # draw order 4 in a window
+pts = c.points(4)            # (256, 2) integer lattice points, in visit order
+```
+
+The forty curves come in named groups — `hilbertplot.proper()`, `.improper()`,
+`.homogeneous()`, `.inhomogeneous()`, `.generalizing()` — each of which prints as a table,
+and which compose:
+
+```python
+import hilbertplot
+
+print(hilbertplot.proper())                       # a table of the six proper curves
+hilbertplot.catalog().closed().names              # ['Moore', 'Liu1', 'Improper1', 'Improper4']
+hilbertplot.by_kernels(3, 5).gallery(order=3)     # draw a group as a grid of panels
+```
+
+In a Jupyter notebook a `Curve` renders itself — put `hilbertplot.curve("Moore")` in a cell
+and you get the picture, not a `repr`.
+
+## One cell at a time
+
+`points(order)` builds all `4**order` cells. When you only need *where step `i` lands*,
+`encode` answers in `O(order)` — so it works at orders no machine could materialise, and it
+does so for **all forty** curves, not just the classic one:
+
+```python
+import hilbertplot
+
+c = hilbertplot.curve(0)
+c.encode(5, 2)                     # (0, 3) — the cell visited at step 5, order 2
+c.decode(0, 3, 2)                  # 5      — and back again
+c.encode(10**18, 40)               # (751054336, 346100736) — a 2**80-cell curve
+```
+
+## Plot data
+
+Walk a curve and drop `data[i]` on the *i*-th cell it visits: a locality-preserving
+1-D → 2-D map where nearby values stay nearby.
+
+```python
+import numpy as np, hilbertplot
+
+plot = hilbertplot.hilbert_plot(0, np.arange(1, 257))
+plot.show("viridis")          # a matplotlib colormap name, or a list of colours to blend
+```
+
+![The same data laid on two different curves](https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/data_two_curves.png)
+
+*The same numbers on curve 0 and curve 32 — one reason to have all forty.*
+
+## Seeing more than the data
+
+**Coarse-grain it.** `plot.show(granularity=4)` replaces each block of values by its mean.
+Below, a binary sequence interleaves stretches of two periodic patterns with identical
+density — invisible in the faithful plot, obvious once averaged.
+
+![Periodic regions revealed by coarse-graining](https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/granularity.png)
+
+**Find where locality breaks.** `plot.show(difference=True)` marks the cells that are
+neighbours in the plane but far apart along the curve. A higher threshold keeps only the
+worst offenders.
+
+![The difference map at two thresholds](https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/difference.png)
+
+**Transform it.** `plot.show(fourier=True)` renders the 2-D Fourier map, exposing periodic
+and self-similar structure — here, a Thue–Morse sequence.
+
+![A Thue–Morse sequence and its Fourier map](https://raw.githubusercontent.com/El3ssar/hilbertplot/main/assets/thue_morse.png)
+
+## Also
+
+- `curve.unroll(img)` — read a 2-D array back into 1-D, in curve order
+- `curve.grid(n)` — the eight `generalizing()` curves tile **any** `n×n` square, not just `2ᵏ`
+- `curve.label_map(order)` — the grid of visit indices, as an image
+- `curve.difference_map(order)` — where the curve breaks locality, as a field
+- `plot.draw(colorbar=True)`, or `norm=LogNorm()` for heavy-tailed data
+- `hilbertplot.is_space_filling` / `canonical_form` — check a path yourself; the same tools
+  the test suite uses to prove all forty curves are distinct Hamiltonian paths
+- `hilbertplot.clear_cache()` / `cache_info()` — generated curves are memoised; this frees them
+- `hilbertplot.set_cell_limit(n)` — raise the guard that refuses absurdly large orders
+
+Every figure above is reproducible: `python examples/readme_figures.py`. More runnable
+demos are in
+[`examples/`](https://github.com/El3ssar/hilbertplot/tree/main/examples);
+the arbitrary-square classification and its impossibility proofs are in the repository's
+`research/quasisquares/`.
+
+## License
+
+MIT © Daniel Estevez —
+[LICENSE](https://github.com/El3ssar/hilbertplot/blob/main/LICENSE)

{hilbertplot-0.0.0 → hilbertplot-0.2.0}/examples/plot_catalog.py

@@ -35,7 +35,7 @@ def main() -> None:
         title="All 40 two-dimensional Hilbert curves (order 3)",
         save=os.path.join(OUT, "all40.png"),
     )
-    hp.curve(0).save(6, os.path.join(OUT, "hilbert_order6.png"))
+    hp.curve(0).save(os.path.join(OUT, "hilbert_order6.png"), 6)
     print(f"wrote plots to {OUT}")
 
 

hilbertplot-0.2.0/examples/readme_figures.py

@@ -0,0 +1,128 @@
+"""Regenerate the figures shown in the README.
+
+    python examples/readme_figures.py
+
+Writes to assets/:
+* curve.png            -- curve 0 at order 4, drawn as a colour-graded path
+* data_two_curves.png  -- the numbers 1-256 laid on curve 0 and on curve 32
+* difference.png       -- the difference-map overlay at two thresholds
+* thue_morse.png       -- a Thue-Morse sequence and its 2-D Fourier map
+* granularity.png      -- periodic regions that only appear once coarse-grained
+"""
+
+import os
+
+import numpy as np
+
+import hilbertplot as hp
+
+OUT = os.path.join(os.path.dirname(__file__), "..", "assets")
+
+
+def thue_morse(n):
+    """The first ``n`` terms of the Thue-Morse sequence."""
+    s = [0]
+    while len(s) < n:
+        s = s + [1 - x for x in s]
+    return np.array(s[:n], dtype=float)
+
+
+def interleaved_periodic(n, seed=3):
+    """A random interleaving of two periodic patterns of *equal* density.
+
+    ``.1001.`` (period 4) and ``.110100.`` (period 6) both have density 1/2, so no
+    stretch is brighter than another and the faithful plot is featureless noise.  Every
+    chunk length is a multiple of 12, which keeps chunk starts aligned to the
+    granularity-4 block grid -- so 4-granularity collapses the period-4 stretches to a
+    constant (solid blocks) while the period-6 ones keep varying.
+    """
+    p4, p6 = [1, 0, 0, 1], [1, 1, 0, 1, 0, 0]
+    rng = np.random.default_rng(seed)
+    seq = []
+    while len(seq) < n:
+        p = p4 if rng.integers(2) else p6
+        length = 12 * int(rng.integers(16, 110))
+        seq += (p * (-(-length // len(p))))[:length]
+    return np.array(seq[:n], dtype=float)
+
+
+def main() -> None:
+    import matplotlib
+
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    os.makedirs(OUT, exist_ok=True)
+    plt.rcParams.update({"figure.facecolor": "white", "savefig.facecolor": "white"})
+
+    def save(fig, name, dpi=140):
+        fig.savefig(os.path.join(OUT, name), dpi=dpi, bbox_inches="tight")
+        plt.close(fig)
+
+    # 1) the curve itself, colour-graded along the traversal
+    fig, ax = plt.subplots(figsize=(5.2, 5.2))
+    hp.curve(0).draw(4, ax=ax, cmap="viridis", title="The Hilbert curve (curve 0), order 4")
+    save(fig, "curve.png")
+
+    # 2) the same data laid on two different curves
+    data = np.arange(1, 257)
+    fig, axes = plt.subplots(1, 2, figsize=(9.2, 4.9))
+    hp.hilbert_plot(0, data).draw("viridis", ax=axes[0], title="curve 0 — Hilbert")
+    hp.hilbert_plot(32, data).draw("viridis", ax=axes[1], title="curve 32 — Moore+Liu4 #1")
+    fig.suptitle("The same data (1–256) laid on two different curves", fontsize=13, y=1.02)
+    save(fig, "data_two_curves.png")
+
+    # 3) where the curve breaks locality, at two thresholds
+    plot = hp.hilbert_plot(0, np.arange(4**5))
+    fig, axes = plt.subplots(1, 3, figsize=(12.6, 4.6))
+    plot.draw("gray", ax=axes[0], title="Hilbert plot")
+    for ax, thr in ((axes[1], 1.5), (axes[2], 0.5)):
+        plot.draw(
+            "gray",
+            ax=ax,
+            difference=True,
+            difference_threshold=thr,
+            difference_color="#ff3b30",
+            title=f"difference map (threshold {thr})",
+        )
+    fig.suptitle(
+        "Where the curve breaks locality — a higher threshold marks fewer, worse sites",
+        fontsize=13,
+        y=1.02,
+    )
+    save(fig, "difference.png")
+
+    # 4) a Thue-Morse sequence and its Fourier map (paper-style: light ground)
+    plot = hp.hilbert_plot(0, thue_morse(4**8))
+    fig, axes = plt.subplots(1, 2, figsize=(9.2, 4.9))
+    plot.draw("gray", ax=axes[0], title="Thue–Morse sequence")
+    lo, hi = np.percentile(plot.fourier(window=True), [2.0, 99.5])
+    plot.draw(
+        "gray_r",
+        ax=axes[1],
+        fourier=True,
+        window=True,
+        vmin=lo,
+        vmax=hi,
+        title="its 2-D Fourier map",
+    )
+    fig.suptitle("A Thue–Morse sequence and its self-similar Fourier map", fontsize=13, y=1.02)
+    save(fig, "thue_morse.png")
+
+    # 5) periodic regions that only show up once you coarse-grain
+    plot = hp.hilbert_plot(0, interleaved_periodic(4**7))
+    fig, axes = plt.subplots(1, 2, figsize=(9.2, 4.9))
+    plot.draw("gray", ax=axes[0], title="faithful — featureless noise")
+    plot.draw("gray", ax=axes[1], granularity=4, title="granularity 4 — regions appear")
+    fig.suptitle(
+        "Periodic regions hidden in a binary sequence, exposed by coarse-graining",
+        fontsize=13,
+        y=1.02,
+    )
+    save(fig, "granularity.png")
+
+    print(f"wrote README figures to {os.path.normpath(OUT)}")
+
+
+if __name__ == "__main__":
+    main()

{hilbertplot-0.0.0 → hilbertplot-0.2.0}/examples/show_curve.py

@@ -38,7 +38,7 @@ def main() -> None:
     )
 
     if args.save:
-        c.save(args.order, args.save, **style)
+        c.save(args.save, args.order, **style)
         print(f"saved -> {args.save}")
     else:
         c.show(args.order, **style)

{hilbertplot-0.0.0 → hilbertplot-0.2.0}/pyproject.toml

@@ -4,11 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hilbertplot"
-version = "0.0.0"
+version = "0.2.0"
 description = "The complete set of 40 two-dimensional Hilbert curves, and data plots on them."
 readme = "README.md"
 requires-python = ">=3.10"
-license = { text = "MIT" }
+# PEP 639: a license expression plus the file, instead of the deprecated
+# `license = { text = ... }` + `License ::` classifier pair.
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [{ name = "Daniel Estevez", email = "kemossabee@gmail.com" }]
 keywords = [
     "hilbert-curve",
@@ -19,10 +22,14 @@ keywords = [
     "visualization",
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Mathematics",
     "Topic :: Scientific/Engineering :: Visualization",
     "Typing :: Typed",
@@ -31,12 +38,14 @@ dependencies = ["numpy>=1.21"]
 
 [project.optional-dependencies]
 plot = ["matplotlib>=3.5"]
-dev = ["matplotlib>=3.5", "pytest>=7.0", "ruff==0.15.13"]
+# dev composes [plot] rather than restating matplotlib, so the two cannot drift.
+dev = ["hilbertplot[plot]", "pytest>=7.0", "ruff==0.15.13"]
 
 [project.urls]
 Homepage = "https://github.com/El3ssar/hilbertplot"
 Source = "https://github.com/El3ssar/hilbertplot"
 Issues = "https://github.com/El3ssar/hilbertplot/issues"
+Changelog = "https://github.com/El3ssar/hilbertplot/blob/main/CHANGELOG.md"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/hilbertplot"]
@@ -49,11 +58,16 @@ include = [
     "/tests",
     "/examples/*.py",
     "/README.md",
+    "/CHANGELOG.md",
     "/LICENSE",
 ]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# `-W error::RuntimeWarning` turns any numpy RuntimeWarning raised during the suite into a
+# failure: an "invalid value encountered in divide" during ordinary use is a defect, not
+# noise.  (The README's own snippets are executed by tests/test_readme.py.)
+addopts = "-W error::RuntimeWarning"
 
 [tool.ruff]
 line-length = 100
@@ -62,19 +76,15 @@ line-length = 100
 extend-exclude = ["research/"]
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B", "W"]
+# RUF/SIM/C4/RET/PERF/NPY/PT are all near-zero-noise on this codebase and catch the
+# classes of drift that actually bit us: unsorted __all__, stale noqa, over-broad
+# pytest.raises, and numpy-specific footguns.  ANN/D are deliberately NOT enabled --
+# they would flag 390 sites without improving anything.
+select = ["E", "F", "I", "UP", "B", "W", "RUF", "SIM", "C4", "RET", "PERF", "NPY", "PT"]
 
 [tool.ruff.lint.per-file-ignores]
-# intentional compact hot-loop: allow one-line compound statements
-"src/hilbertplot/_core/arbitrary.py" = ["E701", "E702"]
-# the paper's parameter name `l` (ambiguous-variable-name)
-"src/hilbertplot/_data/mapping.py" = ["E741"]
-
-[tool.ruff.format]
-# arbitrary.py's `_fill` is a deliberately dense, hand-tuned hot loop; keep it
-# linted (with E701/E702 ignored above) but exempt from the formatter so its
-# compact one-liners survive.
-exclude = ["src/hilbertplot/_core/arbitrary.py"]
+# examples use en dashes in figure titles on purpose (RUF001 ambiguous-unicode)
+"examples/*.py" = ["RUF001"]
 
 [tool.semantic_release]
 # pyproject keeps a STATIC version = "0.1.0"; PSR stamps BOTH files in sync on