FastMapy 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastMapy
-Version: 0.2.0
+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:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: FastMapy
-Version: 0.2.0
+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:

{fastmapy-0.2.0 → 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:

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

@@ -34,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):
@@ -45,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 {}))
@@ -52,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
@@ -66,6 +79,7 @@ class FastMap:
         iters=5,
         cores=1,
         pair_retries=10,
+        cache_distances=False,
     ):
         """Fit several distinct models while avoiding repeated pivot pairs.
 
@@ -85,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)
@@ -108,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
@@ -249,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)
@@ -299,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.2.0 → 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.2.0 → fastmapy-0.3.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "FastMapy"
-version = "0.2.0"
+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.2.0 → 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.2.0 → 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"):