summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTavian Barnes <tavianator@tavianator.com>2020-06-29 16:23:11 -0400
committerTavian Barnes <tavianator@tavianator.com>2020-06-29 16:23:11 -0400
commit83ddde4f87ee3642ce1f5de43e9e57c3be6e87a9 (patch)
treed251032d7026fb4059dfd0f7e73be4b317ead9c7
parent31e713e4700a20cce3a8691cd128cf7a072af960 (diff)
downloadacap-83ddde4f87ee3642ce1f5de43e9e57c3be6e87a9.tar.xz
distance: Expand the Distance docs
-rw-r--r--src/distance.rs12
1 files changed, 9 insertions, 3 deletions
diff --git a/src/distance.rs b/src/distance.rs
index 070bac7..e44ed03 100644
--- a/src/distance.rs
+++ b/src/distance.rs
@@ -14,8 +14,8 @@ impl<T: Num + NumAssign + Signed + Copy + PartialOrd> Value for T {}
///
/// An implementation may be an actual numerical distance, or an [order embedding] of the true
/// distance. This allows for optimizations whenever distances can be compared more efficiently
-/// than their exact values can be computed, as is the case for [Euclidean distance]. Implementors
-/// must satisfy, for all distances `$x$` and `$y$`:
+/// than their exact values can be computed. Implementors must satisfy, for all distances `$x$` and
+/// `$y$`:
///
/// ```math
/// \begin{aligned}
@@ -25,8 +25,14 @@ impl<T: Num + NumAssign + Signed + Copy + PartialOrd> Value for T {}
/// \end{aligned}
/// ```
///
+/// Any monotonically increasing function can be used to create an order embedding. For example,
+/// [`EuclideanDistance`] holds a squared distance, rather than the distance itself. Comparisons
+/// still behave correctly because `$x \mapsto x^2$` is an increasing function. This lets us avoid
+/// computing relatively expensive square roots until we need the `value()` itself, at which point
+/// the inverse function `$x \mapsto \sqrt{x}$` must be applied.
+///
/// [order embedding]: https://en.wikipedia.org/wiki/Order_embedding
-/// [Euclidean distance]: crate::euclid::EuclideanDistance
+/// [`EuclideanDistance`]: crate::euclid::EuclideanDistance
pub trait Distance
where
Self: Copy,