FastMapy 0.1.1__tar.gz → 0.3.0__tar.gz

{fastmapy-0.1.1 → fastmapy-0.3.0}/FastMapy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastMapy
-Version: 0.1.1
+Version: 0.3.0
 Summary: Python implementation of the FastMap multidimensional-scaling technique.
 Author-email: Shawn Davis <shawndavis.lomod@gmail.com>
 License-Expression: Apache-2.0
@@ -9,12 +9,10 @@ Project-URL: Repository, https://github.com/shawn-davis/FastMapy
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.22
@@ -130,6 +128,12 @@ repeatability should control Python's random-number generator before fitting.
 `cores` enables threaded fitting and transformation. It defaults to `1`; any speedup depends on the distance metric and
 runtime.
 
+For immutable training objects with an expensive distance metric, pass
+`cache_distances=True` to `FastMap` or `FastMap.fit_many`. It memoizes exact
+object-pair metric values by identity, avoiding repeated pivot comparisons while
+keeping the cache linear in the number of comparisons rather than materializing a
+pairwise distance matrix. Do not enable it for objects that may change in place.
+
 ### Fitting a batch of distinct models
 
 Use `FastMap.fit_many` to fit several models with identical settings against one training collection:
@@ -154,5 +158,18 @@ objects.
 
 FastMapy is licensed under the [Apache License, Version 2.0](LICENSE).
 
+## Model persistence
+
+Save a fitted model and restore it later with the versioned persistence API:
+
+```python
+model.save("jaccard.fastmap")
+restored = fastmap.FastMap.load("jaccard.fastmap")
+embedding = restored.transform(new_strings)
+```
+
+Model files use Python pickle and must only be loaded from trusted sources. Custom distance classes and object
+transformers must be importable module-level objects in the environment that loads the model.
+
 ## References
 <b id="f1">1</b> Proceedings of the 1995 ACM SIGMOD international conference on Management of data  - SIGMOD  ’95. (1995). doi:10.1145/223784 [↩](#a1)

{fastmapy-0.1.1 → fastmapy-0.3.0}/FastMapy.egg-info/SOURCES.txt

@@ -23,5 +23,6 @@ fastmap/distances/_lev.py
 tests/test_distances.py
 tests/test_fastmap.py
 tests/test_metrics.py
+tests/test_persistence.py
 utils/__init__.py
 utils/_tools.py

{fastmapy-0.1.1 → fastmapy-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastMapy
-Version: 0.1.1
+Version: 0.3.0
 Summary: Python implementation of the FastMap multidimensional-scaling technique.
 Author-email: Shawn Davis <shawndavis.lomod@gmail.com>
 License-Expression: Apache-2.0
@@ -9,12 +9,10 @@ Project-URL: Repository, https://github.com/shawn-davis/FastMapy
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.22
@@ -130,6 +128,12 @@ repeatability should control Python's random-number generator before fitting.
 `cores` enables threaded fitting and transformation. It defaults to `1`; any speedup depends on the distance metric and
 runtime.
 
+For immutable training objects with an expensive distance metric, pass
+`cache_distances=True` to `FastMap` or `FastMap.fit_many`. It memoizes exact
+object-pair metric values by identity, avoiding repeated pivot comparisons while
+keeping the cache linear in the number of comparisons rather than materializing a
+pairwise distance matrix. Do not enable it for objects that may change in place.
+
 ### Fitting a batch of distinct models
 
 Use `FastMap.fit_many` to fit several models with identical settings against one training collection:
@@ -154,5 +158,18 @@ objects.
 
 FastMapy is licensed under the [Apache License, Version 2.0](LICENSE).
 
+## Model persistence
+
+Save a fitted model and restore it later with the versioned persistence API:
+
+```python
+model.save("jaccard.fastmap")
+restored = fastmap.FastMap.load("jaccard.fastmap")
+embedding = restored.transform(new_strings)
+```
+
+Model files use Python pickle and must only be loaded from trusted sources. Custom distance classes and object
+transformers must be importable module-level objects in the environment that loads the model.
+
 ## References
 <b id="f1">1</b> Proceedings of the 1995 ACM SIGMOD international conference on Management of data  - SIGMOD  ’95. (1995). doi:10.1145/223784 [↩](#a1)

{fastmapy-0.1.1 → fastmapy-0.3.0}/README.md

@@ -93,6 +93,12 @@ repeatability should control Python's random-number generator before fitting.
 `cores` enables threaded fitting and transformation. It defaults to `1`; any speedup depends on the distance metric and
 runtime.
 
+For immutable training objects with an expensive distance metric, pass
+`cache_distances=True` to `FastMap` or `FastMap.fit_many`. It memoizes exact
+object-pair metric values by identity, avoiding repeated pivot comparisons while
+keeping the cache linear in the number of comparisons rather than materializing a
+pairwise distance matrix. Do not enable it for objects that may change in place.
+
 ### Fitting a batch of distinct models
 
 Use `FastMap.fit_many` to fit several models with identical settings against one training collection:
@@ -117,5 +123,18 @@ objects.
 
 FastMapy is licensed under the [Apache License, Version 2.0](LICENSE).
 
+## Model persistence
+
+Save a fitted model and restore it later with the versioned persistence API:
+
+```python
+model.save("jaccard.fastmap")
+restored = fastmap.FastMap.load("jaccard.fastmap")
+embedding = restored.transform(new_strings)
+```
+
+Model files use Python pickle and must only be loaded from trusted sources. Custom distance classes and object
+transformers must be importable module-level objects in the environment that loads the model.
+
 ## References
 <b id="f1">1</b> Proceedings of the 1995 ACM SIGMOD international conference on Management of data  - SIGMOD  ’95. (1995). doi:10.1145/223784 [↩](#a1)

{fastmapy-0.1.1 → fastmapy-0.3.0}/fastmap/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 from ._distances import Distance, InputError
 from ._fastmap import FastMap

{fastmapy-0.1.1 → fastmapy-0.3.0}/fastmap/_fastmap.py

@@ -1,8 +1,13 @@
 import multiprocessing
+import os
+import pickle
 import random
 from concurrent.futures import ThreadPoolExecutor as Executor
 from dataclasses import dataclass
 from math import sqrt
+from numbers import Real
+from pathlib import Path
+from tempfile import NamedTemporaryFile
 
 import numpy as np
 
@@ -13,6 +18,10 @@ class ModelError(Exception):
     """Raised when a FastMap model cannot be fitted or used."""
 
 
+_MODEL_FORMAT = "fastmapy.model"
+_MODEL_FORMAT_VERSION = 1
+
+
 @dataclass
 class Pivots:
     left: object
@@ -25,7 +34,16 @@ class Pivots:
 
 
 class FastMap:
-    def __init__(self, dim, distance, dist_args=None, obj_transformer=None, iters=5, cores=1):
+    def __init__(
+        self,
+        dim,
+        distance,
+        dist_args=None,
+        obj_transformer=None,
+        iters=5,
+        cores=1,
+        cache_distances=False,
+    ):
         if not isinstance(dim, int) or isinstance(dim, bool) or dim < 1:
             raise ValueError("dim must be a positive integer")
         if not callable(distance):
@@ -36,6 +54,8 @@ class FastMap:
             raise TypeError("obj_transformer must be callable or None")
         if not isinstance(iters, int) or isinstance(iters, bool) or iters < 1:
             raise ValueError("iters must be a positive integer")
+        if not isinstance(cache_distances, bool):
+            raise TypeError("cache_distances must be a boolean")
 
         self._dim = dim
         self._distance = distance(**(dist_args or {}))
@@ -43,6 +63,8 @@ class FastMap:
         self._iters = iters
         self._pivots: list[Pivots] = []
         self._pivot_pair_collisions: list[int] = []
+        self._cache_distances = cache_distances
+        self._distance_cache = {}
         self.cores = cores
 
     @classmethod
@@ -57,6 +79,7 @@ class FastMap:
         iters=5,
         cores=1,
         pair_retries=10,
+        cache_distances=False,
     ):
         """Fit several distinct models while avoiding repeated pivot pairs.
 
@@ -76,7 +99,8 @@ class FastMap:
             raise ValueError("count cannot exceed the number of training objects")
 
         models = [
-            cls(dim, distance, dist_args, obj_transformer, iters, cores) for _ in range(count)
+            cls(dim, distance, dist_args, obj_transformer, iters, cores, cache_distances)
+            for _ in range(count)
         ]
         for model in models:
             model._validate_training_data(X)
@@ -99,6 +123,11 @@ class FastMap:
     def iters(self):
         return self._iters
 
+    @property
+    def cache_distances(self):
+        """Whether this model memoizes exact object-pair metric evaluations."""
+        return self._cache_distances
+
     @property
     def cores(self):
         return self._cores
@@ -115,6 +144,113 @@ class FastMap:
         """Dimensions where batch fitting exhausted its distinct-pair retries."""
         return tuple(self._pivot_pair_collisions)
 
+    def save(self, path):
+        """Persist a fitted model to ``path``.
+
+        The model is stored with Python pickle in a versioned FastMapy envelope. Only
+        load files from trusted sources. Custom distance classes and object transformers
+        must be importable module-level objects when the model is loaded.
+        """
+        if len(self._pivots) != self._dim:
+            raise ModelError("Only a fully fitted model can be saved")
+
+        destination = Path(path)
+        if destination.exists() and destination.is_dir():
+            raise IsADirectoryError(f"Model path is a directory: {destination}")
+
+        temporary_path = None
+        try:
+            with NamedTemporaryFile("wb", dir=destination.parent, delete=False) as temporary:
+                temporary_path = Path(temporary.name)
+                pickle.dump(
+                    {
+                        "format": _MODEL_FORMAT,
+                        "format_version": _MODEL_FORMAT_VERSION,
+                        "model": self,
+                    },
+                    temporary,
+                    protocol=pickle.HIGHEST_PROTOCOL,
+                )
+                temporary.flush()
+                os.fsync(temporary.fileno())
+            os.replace(temporary_path, destination)
+        except (OSError, pickle.PickleError, TypeError, AttributeError) as error:
+            raise ModelError(f"Unable to save model to {destination}") from error
+        finally:
+            if temporary_path is not None and temporary_path.exists():
+                temporary_path.unlink()
+        return self
+
+    @classmethod
+    def load(cls, path):
+        """Load a model saved with :meth:`save`.
+
+        Pickle loading can execute code, so ``path`` must refer to a model file from a
+        trusted source. The persisted format version is checked before returning it.
+        """
+        source = Path(path)
+        try:
+            with source.open("rb") as model_file:
+                payload = pickle.load(model_file)
+        except (OSError, EOFError, pickle.UnpicklingError, AttributeError, ImportError) as error:
+            raise ModelError(f"Unable to load model from {source}") from error
+
+        if not isinstance(payload, dict) or payload.get("format") != _MODEL_FORMAT:
+            raise ModelError("File is not a FastMapy model")
+        if payload.get("format_version") != _MODEL_FORMAT_VERSION:
+            raise ModelError("Unsupported FastMapy model format version")
+
+        model = payload.get("model")
+        if not isinstance(model, cls):
+            raise ModelError("Persisted model has an invalid type")
+        cls._validate_loaded_model(model)
+        return model
+
+    @staticmethod
+    def _validate_loaded_model(model):
+        """Reject persisted state that cannot safely support transformation."""
+        if not isinstance(getattr(model, "_dim", None), int) or isinstance(model._dim, bool):
+            raise ModelError("Persisted model has an invalid dimension")
+        if model._dim < 1:
+            raise ModelError("Persisted model has an invalid dimension")
+        if not isinstance(getattr(model, "_iters", None), int) or model._iters < 1:
+            raise ModelError("Persisted model has invalid iteration settings")
+        if not isinstance(getattr(model, "_cores", None), int) or model._cores < 1:
+            raise ModelError("Persisted model has invalid core settings")
+        if not callable(getattr(getattr(model, "_distance", None), "calculate", None)):
+            raise ModelError("Persisted model has an invalid distance metric")
+        transformer = getattr(model, "_obj_transformer", None)
+        if transformer is not None and not callable(transformer):
+            raise ModelError("Persisted model has an invalid object transformer")
+        if not isinstance(getattr(model, "_pivots", None), list):
+            raise ModelError("Persisted model is not fully fitted")
+        if len(model._pivots) != model._dim:
+            raise ModelError("Persisted model is not fully fitted")
+        if not isinstance(getattr(model, "_pivot_pair_collisions", None), list):
+            raise ModelError("Persisted model has invalid collision data")
+
+        for pivot in model._pivots:
+            if not isinstance(pivot, Pivots):
+                raise ModelError("Persisted model has an invalid pivot")
+            if not all(
+                isinstance(index, int) and not isinstance(index, bool) and index >= 0
+                for index in (pivot.left_index, pivot.right_index)
+            ):
+                raise ModelError("Persisted model has invalid pivot indexes")
+            if not isinstance(pivot.distance, Real):
+                raise ModelError("Persisted model has an invalid pivot distance")
+            if not all(
+                isinstance(projection, np.ndarray) and projection.shape == (model._dim,)
+                for projection in (pivot.left_proj, pivot.right_proj)
+            ):
+                raise ModelError("Persisted model has invalid pivot projections")
+
+        if not all(
+            isinstance(index, int) and not isinstance(index, bool) and 0 <= index < model._dim
+            for index in model._pivot_pair_collisions
+        ):
+            raise ModelError("Persisted model has invalid collision data")
+
     def _compute_proj_i(self, index, pivots, obj, obj_proj):
         if pivots.distance == 0:
             return 0.0
@@ -133,10 +269,34 @@ class FastMap:
         return x_proj
 
     def _dist(self, x, x_proj, y, y_proj, index):
-        d_sq = pow(self._distance.calculate(x, y), 2)
+        d_sq = pow(self._metric_distance(x, y), 2)
         diff_sq = sum([pow(x_i - y_i, 2) for (x_i, y_i) in zip(x_proj[0:index], y_proj[0:index])])
         return sqrt(max(d_sq - diff_sq, 0))
 
+    def _metric_distance(self, x, y):
+        """Return a symmetric metric value, optionally memoized by object identity.
+
+        FastMap repeatedly compares training objects with the same pivots while
+        fitting and transforming them. Identity keys support unhashable objects
+        and avoid assuming equality is inexpensive. Cached entries retain both
+        objects so their ids cannot be recycled while the cache is live. This is
+        opt-in because callers with mutable objects may want fresh measurements.
+        """
+        if not self._cache_distances:
+            return self._distance.calculate(x, y)
+        x_id, y_id = id(x), id(y)
+        key = (x_id, y_id) if x_id <= y_id else (y_id, x_id)
+        cached = self._distance_cache.get(key)
+        if cached is not None:
+            return cached[2]
+        value = self._distance.calculate(x, y)
+        self._distance_cache[key] = (x, y, value)
+        return value
+
+    def clear_distance_cache(self):
+        """Discard memoized metric values to release their retained objects."""
+        self._distance_cache.clear()
+
     def fit(self, X):
         try:
             X = list(X)
@@ -183,6 +343,7 @@ class FastMap:
             X = [self._obj_transformer(x) for x in X]
         self._pivots = []
         self._pivot_pair_collisions = []
+        self.clear_distance_cache()
         return X
 
     def _fit_with_reservations(self, X, reserved_pairs, used_starts, pair_retries):

{fastmapy-0.1.1 → fastmapy-0.3.0}/fastmap/distances/_jaccard.py

@@ -1,14 +1,22 @@
+from functools import lru_cache
+
 from fastmap._distances import Distance, InputError
 from utils import shingler
 
 
+@lru_cache(maxsize=32_768)
+def _string_shingles(value, shingle_size):
+    """Memoize immutable shingle sets for repeated string comparisons."""
+    return frozenset(shingler(value, shingle_size=shingle_size))
+
+
 def _weight_set(x):
     return {el: 1 for el in x}
 
 
 def _to_set(value, shingle_size):
     if isinstance(value, str):
-        return shingler(value, shingle_size=shingle_size)
+        return _string_shingles(value, shingle_size)
     if isinstance(value, set):
         return value
     raise InputError("Jaccard distance needs strings, sets, or dictionaries")

{fastmapy-0.1.1 → fastmapy-0.3.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "FastMapy"
-version = "0.1.1"
+version = "0.3.0"
 description = "Python implementation of the FastMap multidimensional-scaling technique."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [
@@ -17,8 +17,6 @@ classifiers = [
   "Development Status :: 2 - Pre-Alpha",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.9",
-  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
@@ -60,7 +58,7 @@ testpaths = ["tests"]
 addopts = "-ra"
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py311"
 line-length = 100
 
 [tool.ruff.lint]

{fastmapy-0.1.1 → fastmapy-0.3.0}/tests/test_distances.py

@@ -45,6 +45,25 @@ def test_jaccard_handles_empty_and_mixed_weighted_inputs():
     assert metric.calculate("ab", {"a": 1, "b": 1}) == 0
 
 
+def test_jaccard_reuses_cached_string_shingles(monkeypatch):
+    import fastmap.distances._jaccard as module
+
+    module._string_shingles.cache_clear()
+    calls = []
+    original = module.shingler
+
+    def counting_shingler(value, shingle_size):
+        calls.append(value)
+        return original(value, shingle_size)
+
+    monkeypatch.setattr(module, "shingler", counting_shingler)
+    metric = Jaccard(shingle_size=2)
+    metric.calculate("abcd", "abce")
+    metric.calculate("abce", "abcd")
+
+    assert calls == ["abcd", "abce"]
+
+
 def test_distance_names_are_public_and_stable():
     assert L1().get_name() == "L1"
     assert L2().get_name() == "L2"

{fastmapy-0.1.1 → fastmapy-0.3.0}/tests/test_fastmap.py

@@ -65,6 +65,25 @@ def test_fit_handles_identical_objects():
     assert np.allclose(embedding, 0)
 
 
+def test_distance_cache_reuses_symmetric_metric_evaluations():
+    calls = []
+
+    class CountingDistance(L2):
+        def calculate(self, left, right):
+            calls.append((id(left), id(right)))
+            return super().calculate(left, right)
+
+    vectors = [[0.0], [1.0], [2.0]]
+    model = FastMap(dim=1, distance=CountingDistance, iters=1, cache_distances=True)
+    model.fit(vectors)
+    model._metric_distance(vectors[0], vectors[1])
+    before_reverse = len(calls)
+    model._metric_distance(vectors[1], vectors[0])
+
+    assert len(calls) == before_reverse
+    assert model.cache_distances
+
+
 @pytest.mark.parametrize("dim", [0, -1, 1.5, True])
 def test_dimension_must_be_a_positive_integer(dim):
     with pytest.raises(ValueError, match="positive integer"):

fastmapy-0.3.0/tests/test_persistence.py

@@ -0,0 +1,68 @@
+import pickle
+
+import numpy as np
+import pytest
+
+from fastmap import FastMap
+from fastmap._fastmap import _MODEL_FORMAT, _MODEL_FORMAT_VERSION, ModelError
+from fastmap.distances import L2, Jaccard
+
+
+def test_save_and_load_preserves_a_fitted_model(monkeypatch, tmp_path):
+    vectors = [[0.0, 0.0], [3.0, 4.0], [6.0, 8.0]]
+    monkeypatch.setattr("fastmap._fastmap.random.randrange", lambda count: 0)
+    model = FastMap(dim=1, distance=L2, iters=2).fit(vectors)
+    path = tmp_path / "model.fastmap"
+
+    assert model.save(path) is model
+    loaded = FastMap.load(path)
+
+    assert loaded.dim == model.dim
+    assert loaded.distance == model.distance
+    assert np.allclose(loaded.transform(vectors), model.transform(vectors))
+
+
+def test_save_and_load_preserves_distance_configuration(monkeypatch, tmp_path):
+    strings = ["abcd", "abce", "xyz"]
+    monkeypatch.setattr("fastmap._fastmap.random.randrange", lambda count: 0)
+    model = FastMap(dim=1, distance=Jaccard, dist_args={"shingle_size": 2}).fit(strings)
+    path = tmp_path / "jaccard.fastmap"
+
+    loaded = model.save(path).load(path)
+
+    assert loaded._distance.shingle_size == 2
+    assert np.allclose(loaded.transform(strings), model.transform(strings))
+
+
+def test_save_rejects_an_unfitted_model(tmp_path):
+    with pytest.raises(ModelError, match="fully fitted"):
+        FastMap(dim=1, distance=L2).save(tmp_path / "model.fastmap")
+
+
+def test_load_rejects_non_fastmapy_data(tmp_path):
+    path = tmp_path / "not-a-model.fastmap"
+    with path.open("wb") as model_file:
+        pickle.dump({"format": "something-else"}, model_file)
+
+    with pytest.raises(ModelError, match="not a FastMapy model"):
+        FastMap.load(path)
+
+
+def test_load_rejects_malformed_fitted_model(monkeypatch, tmp_path):
+    vectors = [[0.0, 0.0], [3.0, 4.0], [6.0, 8.0]]
+    monkeypatch.setattr("fastmap._fastmap.random.randrange", lambda count: 0)
+    model = FastMap(dim=1, distance=L2, iters=2).fit(vectors)
+    model._pivots[0] = object()
+    path = tmp_path / "malformed.fastmap"
+    with path.open("wb") as model_file:
+        pickle.dump(
+            {
+                "format": _MODEL_FORMAT,
+                "format_version": _MODEL_FORMAT_VERSION,
+                "model": model,
+            },
+            model_file,
+        )
+
+    with pytest.raises(ModelError, match="invalid pivot"):
+        FastMap.load(path)