gridity 0.2.2__tar.gz → 0.3.0__tar.gz

{gridity-0.2.2 → gridity-0.3.0}/.idea/modules.xml

@@ -2,7 +2,7 @@
 <project version="4">
   <component name="ProjectModuleManager">
     <modules>
-      <module fileurl="file://$PROJECT_DIR$/.idea/GRiD.iml" filepath="$PROJECT_DIR$/.idea/GRiD.iml" />
+      <module fileurl="file://$PROJECT_DIR$/.idea/gridity.iml" filepath="$PROJECT_DIR$/.idea/gridity.iml" />
     </modules>
   </component>
 </project>

{gridity-0.2.2 → gridity-0.3.0}/Cargo.lock

@@ -25,7 +25,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "gridity"
-version = "0.2.2"
+version = "0.3.0"
 dependencies = [
  "approx",
  "ndarray",

gridity-0.3.0/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "gridity"
+# keep in step with pyproject.toml: `gridity.__version__` is read from here
+version = "0.3.0"
+edition = "2021"
+readme = "README.md"
+
+[lib]
+name = "gridity"
+# rlib alongside cdylib so `cargo test` can link the unit tests against the crate
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+# `extension-module` is NOT enabled here on purpose. With it on, the library
+# leaves Python's symbols to be resolved by the interpreter at load time, which
+# is right for the wheel but means `cargo test` cannot link. maturin turns it on
+# via the `features` list in pyproject.toml when it builds the extension.
+pyo3 = { version = "0.22" }
+numpy = "0.22"
+ndarray = "0.16"
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+
+[dev-dependencies]
+approx = "0.5"
+
+[[bin]]
+name = "grid_sim_demo"
+path = "src/main.rs"

gridity-0.3.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: gridity
+Version: 0.3.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Operating System :: OS Independent
+Requires-Dist: numpy>=1.21
+Summary: Compress a distance matrix down to the handful of distances that actually pin the geometry, using rigidity theory.
+Keywords: compression,distance-matrix,distance-geometry,rigidity,rigidity-theory,point-cloud,multidimensional-scaling,mds,trilateration,sensor-localization
+Author: Sezer Aptourachman
+Requires-Python: >=3.8, <3.14
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/JuL-sezaR/grid
+Project-URL: Issues, https://github.com/JuL-sezaR/grid/issues
+Project-URL: Repository, https://github.com/JuL-sezaR/grid
+
+# gridity
+
+**Compress a distance matrix down to the handful of distances that actually pin the geometry.**
+
+If you have `n` points, there are `n(n-1)/2` distances between them — but the points
+themselves only have `n·d` coordinates. Most of that matrix is redundant. `gridity` works out
+which distances carry the shape and which are implied by the others, then writes only the
+first group to a file.
+
+Rust core, Python API, no runtime dependencies beyond NumPy.
+
+```bash
+pip install gridity
+```
+
+---
+
+## The short version
+
+```python
+import numpy as np
+import gridity
+
+# 1000 points in 3D, and the distances between every pair of them
+pts = np.random.rand(1000, 3) * 10
+D = np.linalg.norm(pts[:, None] - pts[None], axis=-1)
+
+gridity.compress(D, "cloud.gridity", d=3, bits=0)   # 27,952 bytes
+back = gridity.decompress("cloud.gridity")          # the full 1000x1000 matrix
+
+np.abs(back - D).max()                              # ~1e-13
+```
+
+That matrix is 3,996,000 bytes as float64. `lzma` gets it to 3,654,072. `gridity` gets it to
+27,952 — and decompresses back to the same matrix.
+
+---
+
+## Why not just zip it?
+
+Because distance data is nearly incompressible. The mantissa bits of a float64 distance are
+effectively random, so a general-purpose compressor has almost nothing to find. Measured on
+uniform 3D clouds, same matrices, all lossless:
+
+| n | float64 triangle | `+ lzma -9` | `.gridity` | vs lzma |
+|---|---|---|---|---|
+| 100 | 39,600 B | 36,428 B | **2,721 B** | 13× smaller |
+| 300 | 358,800 B | 328,996 B | **8,240 B** | 40× smaller |
+| 1000 | 3,996,000 B | 3,654,072 B | **27,952 B** | 131× smaller |
+
+The gap widens with `n`, because the matrix grows as O(n²) while the geometry only grows
+as O(n). `gridity` stores the geometry.
+
+A general-purpose compressor sees a bag of numbers. `gridity` knows they are distances
+between points in `d` dimensions, and that is the entire trick.
+
+---
+
+## Where this is the right tool
+
+The target case is **you have distances and never had coordinates**:
+
+- wireless sensor localisation — time-of-flight or signal strength between nodes, no GPS
+- molecular structure from NMR — inter-atomic distances, not positions
+- any distance-geometry problem where the O(n²) matrix is the thing you must store or send
+
+If you already have coordinates, store those instead; see *Honest limits* below.
+
+---
+
+## Spending fewer bits
+
+Rigidity is a threshold. Below a certain number of distances the shape comes apart
+completely, so there is no point asking for "slightly fewer distances". What you can trade
+is **precision per distance**:
+
+```python
+gridity.compress_to_bytes(D, d=3, bits=8)    #  6,994 B,  error 8.2e-03
+gridity.compress_to_bytes(D, d=3, bits=12)   #  8,491 B,  error 6.0e-04
+gridity.compress_to_bytes(D, d=3, bits=16)   #  9,988 B,  error 4.3e-05
+gridity.compress_to_bytes(D, d=3, bits=0)    # 27,952 B,  exact
+```
+
+Every two extra bits cuts the error roughly fourfold. If you would rather state the error
+than guess the budget, say so and let the encoder find it:
+
+```python
+blob = gridity.compress_to_bytes(D, d=3, target_error=1e-3)
+```
+
+That bound is **measured, not predicted** — the encoder decodes its own output and checks
+before settling on a budget.
+
+---
+
+## How it works
+
+`max_rank = n·d − d(d+1)/2` distances are enough to make a point cloud *rigid*. That is the
+classical result, and it is where the O(1/n) compression ratio comes from.
+
+But rigid is not the same as *uniquely determined*. A minimal rigid edge set is satisfied by
+many different point clouds — about twenty for a ten-point cloud — because each point can
+reflect across the plane through its anchors. Storing only those distances would give you a
+file that decodes to the wrong shape.
+
+So the edges are picked as a **trilateration**: a small seed simplex first, then every
+remaining point tied to exactly `d` points already placed. That is exactly `max_rank` edges,
+and it makes the ambiguity explicit — each point has precisely two possible positions, so
+**one bit per point** says which. The result:
+
+```
+max_rank distances  +  n bits  =  unique reconstruction
+```
+
+`n` bits against an O(n²) matrix costs nothing, so the ratio survives intact.
+
+Two modes are available. `minimal` (the default) is the above. `redundant` ties each point
+to `d+1` anchors instead, which needs no sign bits and averages quantisation error down
+rather than letting it land on one coordinate — larger files, better accuracy per bit.
+
+---
+
+## Honest limits
+
+Worth knowing before you adopt this.
+
+**If your matrix is exactly Euclidean, storing coordinates beats storing distances.** Run
+MDS, keep the `n·d` coordinates, and you are about 1.8× smaller than `.gridity` at the same
+accuracy (at n=300, d=3: 1,374 B against 2,429 B, both at ~3e-04). The reason is structural
+rather than a missing optimisation: naming *which* distances you kept costs about as much as
+the distances themselves, and that is already near the information-theoretic floor for
+choosing a subset. `gridity.explain()` shows the split.
+
+So `gridity` earns its place when:
+
+- the matrix is **not** exactly embeddable in `d` dimensions — measured data never is — and
+  you want the measurements kept rather than projected away. At `bits=0` every retained
+  distance is reproduced *exactly*, because each point is placed to satisfy its own anchor
+  distances by construction. On a noisy 300-point matrix that is 3e-16 against 1.7e-02 for
+  MDS coordinates.
+- you want to know which distances matter, not just a smaller file.
+
+The flip side of the same fact: MDS fits all `n²` distances at once and averages noise down,
+so on a noisy matrix it wins on *all-pairs* error even while losing on the retained ones.
+Which of those you care about decides the tool.
+
+**Other limits.** `d` must be 2 or 3. The encoder runs an MDS pass, so it is O(n²) in memory
+and wants the full matrix up front; the decoder is O(n·pool). Reconstruction is up to a
+rigid motion, so the recovered coordinates may be rotated, translated or reflected relative
+to the originals — the distances are what is preserved.
+
+---
+
+## API
+
+| Call | What it does |
+|---|---|
+| `compress(D, path, d=3, bits=12, mode="minimal", pool=64, target_error=None)` | matrix → file; returns the same dict as `inspect` |
+| `decompress(path, return_coords=False)` | file → matrix (and coordinates, if asked) |
+| `compress_to_bytes(D, ...)` | same as `compress`, returns `bytes` |
+| `decompress_from_bytes(data, return_coords=False)` | same as `decompress`, takes `bytes` |
+| `inspect(path_or_bytes)` | header only: `n`, `d`, `bits`, `n_edges`, `mode`, `ratio`, … |
+| `explain(path_or_bytes)` | byte budget: header / seed / edge index / sign bits / distances |
+
+Arguments: `d` is the dimension the points live in (2 or 3). `bits` is the quantiser width
+per distance, `0` meaning raw float64. `mode` is `"minimal"` or `"redundant"`. `pool` is how
+many nearby points the encoder considers as anchors — raise it for odd geometry, lower it
+for speed. `target_error` overrides `bits`.
+
+Bad input raises `ValueError` with a specific message — not square, asymmetric, negative,
+NaN, non-zero diagonal, too few points, bad `d`. Every file carries a CRC-32, so a truncated
+or corrupted file is refused rather than quietly decoded into the wrong shape.
+
+### The rigidity core
+
+The compression is built on a rigidity engine that is also exposed directly:
+
+| Call | What it does |
+|---|---|
+| `max_independent(n, d)` | `n·d − d(d+1)/2`, the number of distances that pin `n` points |
+| `simulate(coords, d, tol=None)` | which edges are independent, by Gaussian elimination on the rigidity matrix |
+| `pebble_game(coords, d)` | the same question combinatorially, O(n²), `d=2` only |
+| `reconstruct(D, d, tol=None)` | classical MDS (see the caveat below) |
+| `gram_from_dist(D)` | Gram matrix by double-centring |
+
+Two notes on these. `simulate` and `pebble_game` agree exactly on points in general
+position; on degenerate inputs they will not, and that is correct rather than a bug — the
+pebble game decides *generic* rigidity from the graph alone and never looks at the
+coordinates. And `reconstruct` is accurate only to about n=50; the container does not use
+it, it runs its own MDS.
+
+---
+
+## Building from source
+
+```bash
+pip install maturin
+maturin develop --release
+cargo test                      # 119 unit tests
+python python/test_gridity_rust.py
+```
+
+Prebuilt wheels cover CPython 3.11–3.13 on Linux, Windows and macOS. Other versions in range
+build from the sdist and need a Rust toolchain.
+

gridity-0.3.0/README.md

@@ -0,0 +1,204 @@
+# gridity
+
+**Compress a distance matrix down to the handful of distances that actually pin the geometry.**
+
+If you have `n` points, there are `n(n-1)/2` distances between them — but the points
+themselves only have `n·d` coordinates. Most of that matrix is redundant. `gridity` works out
+which distances carry the shape and which are implied by the others, then writes only the
+first group to a file.
+
+Rust core, Python API, no runtime dependencies beyond NumPy.
+
+```bash
+pip install gridity
+```
+
+---
+
+## The short version
+
+```python
+import numpy as np
+import gridity
+
+# 1000 points in 3D, and the distances between every pair of them
+pts = np.random.rand(1000, 3) * 10
+D = np.linalg.norm(pts[:, None] - pts[None], axis=-1)
+
+gridity.compress(D, "cloud.gridity", d=3, bits=0)   # 27,952 bytes
+back = gridity.decompress("cloud.gridity")          # the full 1000x1000 matrix
+
+np.abs(back - D).max()                              # ~1e-13
+```
+
+That matrix is 3,996,000 bytes as float64. `lzma` gets it to 3,654,072. `gridity` gets it to
+27,952 — and decompresses back to the same matrix.
+
+---
+
+## Why not just zip it?
+
+Because distance data is nearly incompressible. The mantissa bits of a float64 distance are
+effectively random, so a general-purpose compressor has almost nothing to find. Measured on
+uniform 3D clouds, same matrices, all lossless:
+
+| n | float64 triangle | `+ lzma -9` | `.gridity` | vs lzma |
+|---|---|---|---|---|
+| 100 | 39,600 B | 36,428 B | **2,721 B** | 13× smaller |
+| 300 | 358,800 B | 328,996 B | **8,240 B** | 40× smaller |
+| 1000 | 3,996,000 B | 3,654,072 B | **27,952 B** | 131× smaller |
+
+The gap widens with `n`, because the matrix grows as O(n²) while the geometry only grows
+as O(n). `gridity` stores the geometry.
+
+A general-purpose compressor sees a bag of numbers. `gridity` knows they are distances
+between points in `d` dimensions, and that is the entire trick.
+
+---
+
+## Where this is the right tool
+
+The target case is **you have distances and never had coordinates**:
+
+- wireless sensor localisation — time-of-flight or signal strength between nodes, no GPS
+- molecular structure from NMR — inter-atomic distances, not positions
+- any distance-geometry problem where the O(n²) matrix is the thing you must store or send
+
+If you already have coordinates, store those instead; see *Honest limits* below.
+
+---
+
+## Spending fewer bits
+
+Rigidity is a threshold. Below a certain number of distances the shape comes apart
+completely, so there is no point asking for "slightly fewer distances". What you can trade
+is **precision per distance**:
+
+```python
+gridity.compress_to_bytes(D, d=3, bits=8)    #  6,994 B,  error 8.2e-03
+gridity.compress_to_bytes(D, d=3, bits=12)   #  8,491 B,  error 6.0e-04
+gridity.compress_to_bytes(D, d=3, bits=16)   #  9,988 B,  error 4.3e-05
+gridity.compress_to_bytes(D, d=3, bits=0)    # 27,952 B,  exact
+```
+
+Every two extra bits cuts the error roughly fourfold. If you would rather state the error
+than guess the budget, say so and let the encoder find it:
+
+```python
+blob = gridity.compress_to_bytes(D, d=3, target_error=1e-3)
+```
+
+That bound is **measured, not predicted** — the encoder decodes its own output and checks
+before settling on a budget.
+
+---
+
+## How it works
+
+`max_rank = n·d − d(d+1)/2` distances are enough to make a point cloud *rigid*. That is the
+classical result, and it is where the O(1/n) compression ratio comes from.
+
+But rigid is not the same as *uniquely determined*. A minimal rigid edge set is satisfied by
+many different point clouds — about twenty for a ten-point cloud — because each point can
+reflect across the plane through its anchors. Storing only those distances would give you a
+file that decodes to the wrong shape.
+
+So the edges are picked as a **trilateration**: a small seed simplex first, then every
+remaining point tied to exactly `d` points already placed. That is exactly `max_rank` edges,
+and it makes the ambiguity explicit — each point has precisely two possible positions, so
+**one bit per point** says which. The result:
+
+```
+max_rank distances  +  n bits  =  unique reconstruction
+```
+
+`n` bits against an O(n²) matrix costs nothing, so the ratio survives intact.
+
+Two modes are available. `minimal` (the default) is the above. `redundant` ties each point
+to `d+1` anchors instead, which needs no sign bits and averages quantisation error down
+rather than letting it land on one coordinate — larger files, better accuracy per bit.
+
+---
+
+## Honest limits
+
+Worth knowing before you adopt this.
+
+**If your matrix is exactly Euclidean, storing coordinates beats storing distances.** Run
+MDS, keep the `n·d` coordinates, and you are about 1.8× smaller than `.gridity` at the same
+accuracy (at n=300, d=3: 1,374 B against 2,429 B, both at ~3e-04). The reason is structural
+rather than a missing optimisation: naming *which* distances you kept costs about as much as
+the distances themselves, and that is already near the information-theoretic floor for
+choosing a subset. `gridity.explain()` shows the split.
+
+So `gridity` earns its place when:
+
+- the matrix is **not** exactly embeddable in `d` dimensions — measured data never is — and
+  you want the measurements kept rather than projected away. At `bits=0` every retained
+  distance is reproduced *exactly*, because each point is placed to satisfy its own anchor
+  distances by construction. On a noisy 300-point matrix that is 3e-16 against 1.7e-02 for
+  MDS coordinates.
+- you want to know which distances matter, not just a smaller file.
+
+The flip side of the same fact: MDS fits all `n²` distances at once and averages noise down,
+so on a noisy matrix it wins on *all-pairs* error even while losing on the retained ones.
+Which of those you care about decides the tool.
+
+**Other limits.** `d` must be 2 or 3. The encoder runs an MDS pass, so it is O(n²) in memory
+and wants the full matrix up front; the decoder is O(n·pool). Reconstruction is up to a
+rigid motion, so the recovered coordinates may be rotated, translated or reflected relative
+to the originals — the distances are what is preserved.
+
+---
+
+## API
+
+| Call | What it does |
+|---|---|
+| `compress(D, path, d=3, bits=12, mode="minimal", pool=64, target_error=None)` | matrix → file; returns the same dict as `inspect` |
+| `decompress(path, return_coords=False)` | file → matrix (and coordinates, if asked) |
+| `compress_to_bytes(D, ...)` | same as `compress`, returns `bytes` |
+| `decompress_from_bytes(data, return_coords=False)` | same as `decompress`, takes `bytes` |
+| `inspect(path_or_bytes)` | header only: `n`, `d`, `bits`, `n_edges`, `mode`, `ratio`, … |
+| `explain(path_or_bytes)` | byte budget: header / seed / edge index / sign bits / distances |
+
+Arguments: `d` is the dimension the points live in (2 or 3). `bits` is the quantiser width
+per distance, `0` meaning raw float64. `mode` is `"minimal"` or `"redundant"`. `pool` is how
+many nearby points the encoder considers as anchors — raise it for odd geometry, lower it
+for speed. `target_error` overrides `bits`.
+
+Bad input raises `ValueError` with a specific message — not square, asymmetric, negative,
+NaN, non-zero diagonal, too few points, bad `d`. Every file carries a CRC-32, so a truncated
+or corrupted file is refused rather than quietly decoded into the wrong shape.
+
+### The rigidity core
+
+The compression is built on a rigidity engine that is also exposed directly:
+
+| Call | What it does |
+|---|---|
+| `max_independent(n, d)` | `n·d − d(d+1)/2`, the number of distances that pin `n` points |
+| `simulate(coords, d, tol=None)` | which edges are independent, by Gaussian elimination on the rigidity matrix |
+| `pebble_game(coords, d)` | the same question combinatorially, O(n²), `d=2` only |
+| `reconstruct(D, d, tol=None)` | classical MDS (see the caveat below) |
+| `gram_from_dist(D)` | Gram matrix by double-centring |
+
+Two notes on these. `simulate` and `pebble_game` agree exactly on points in general
+position; on degenerate inputs they will not, and that is correct rather than a bug — the
+pebble game decides *generic* rigidity from the graph alone and never looks at the
+coordinates. And `reconstruct` is accurate only to about n=50; the container does not use
+it, it runs its own MDS.
+
+---
+
+## Building from source
+
+```bash
+pip install maturin
+maturin develop --release
+cargo test                      # 119 unit tests
+python python/test_gridity_rust.py
+```
+
+Prebuilt wheels cover CPython 3.11–3.13 on Linux, Windows and macOS. Other versions in range
+build from the sdist and need a Rust toolchain.

gridity-0.3.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["maturin>=1.5,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "gridity"
+version = "0.3.0"
+description = "Compress a distance matrix down to the handful of distances that actually pin the geometry, using rigidity theory."
+readme = "README.md"
+requires-python = ">=3.8,<3.14"
+authors = [{ name = "Sezer Aptourachman" }]
+keywords = [
+    "compression",
+    "distance-matrix",
+    "distance-geometry",
+    "rigidity",
+    "rigidity-theory",
+    "point-cloud",
+    "multidimensional-scaling",
+    "mds",
+    "trilateration",
+    "sensor-localization",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: System :: Archiving :: Compression",
+    "Operating System :: OS Independent",
+]
+dependencies = ["numpy>=1.21"]
+
+# The upper Python bound is real: the PyO3 version this builds against supports
+# CPython up to 3.13. Without the bound, installing on 3.14 fails from source
+# with a confusing linker-level message instead of a clean "requires Python".
+
+[project.urls]
+Homepage = "https://github.com/JuL-sezaR/grid"
+Repository = "https://github.com/JuL-sezaR/grid"
+Issues = "https://github.com/JuL-sezaR/grid/issues"
+
+[tool.maturin]
+# Enabled only for the wheel. It is deliberately NOT a default feature in
+# Cargo.toml, because with it on the crate leaves Python's symbols to the
+# interpreter and `cargo test` cannot link.
+features = ["pyo3/extension-module"]