Package com.apple.foundationdb.linear

Enum Metric

java.lang.Object
java.lang.Enum<Metric>
com.apple.foundationdb.linear.Metric
All Implemented Interfaces:
Serializable, Comparable<Metric>, java.lang.constant.Constable
public enum Metric extends Enum<Metric>
Represents various distance calculation strategies (metrics) for vectors.

Each enum constant holds a specific metric implementation, providing a type-safe way to calculate the distance between two points in a multidimensional space.

See Also:
  • MetricDefinition

  • Enum Constant Details

    • MANHATTAN_METRIC

      public static final Metric MANHATTAN_METRIC
      Represents the Manhattan distance metric, implemented by MetricDefinition.ManhattanMetric.

      This metric calculates a distance overlaying the multidimensional space with a grid-like structure only allowing orthogonal lines. In 2D this resembles the street structure in Manhattan where one would have to go x blocks north/south and y blocks east/west leading to a total distance of x + y.

      See Also:
      • MetricDefinition.ManhattanMetric

    • EUCLIDEAN_METRIC

      public static final Metric EUCLIDEAN_METRIC
      Represents the Euclidean distance metric, implemented by MetricDefinition.EuclideanMetric.

      This metric calculates the "ordinary" straight-line distance between two points in Euclidean space. The distance is the square root of the sum of the squared differences between the corresponding coordinates of the two points.

      See Also:
      • MetricDefinition.EuclideanMetric

    • EUCLIDEAN_SQUARE_METRIC

      public static final Metric EUCLIDEAN_SQUARE_METRIC
      Represents the squared Euclidean distance metric, implemented by MetricDefinition.EuclideanSquareMetric.

      This metric calculates the sum of the squared differences between the coordinates of two vectors, defined as sum((p_i - q_i)^2). It is computationally less expensive than the standard Euclidean distance because it avoids the final square root operation.

      This is often preferred in algorithms where comparing distances is more important than the actual distance value, such as in clustering algorithms, as it preserves the relative ordering of distances.

      See Also:

    • COSINE_METRIC

      public static final Metric COSINE_METRIC
      Represents the Cosine distance metric, implemented by MetricDefinition.CosineMetric.

      This metric calculates a "distance" between two vectors v1 and v2 that ranges between 0.0d and 2.0d that corresponds to 1 - cos(v1, v2), meaning that if v1 == v2, the distance is 0 while if v1 is orthogonal to v2 it is 1.

      See Also:
      • MetricDefinition.CosineMetric

    • DOT_PRODUCT_METRIC

      public static final Metric DOT_PRODUCT_METRIC
      Dot product similarity, implemented by MetricDefinition.DotProductMetric

      This metric calculates the inverted dot product of two vectors. It is not a true metric as several properties of true metrics do not hold, for instance this metric can be negative.

      See Also:

  • Method Details

    • values

      public static Metric[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.
      Returns:
      an array containing the constants of this enum type, in the order they are declared

    • valueOf

      public static Metric valueOf(String name)
      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum type has no constant with the specified name
      NullPointerException - if the argument is null

    • satisfiesZeroSelfDistance

      public boolean satisfiesZeroSelfDistance()

    • satisfiesPositivity

      public boolean satisfiesPositivity()

    • satisfiesSymmetry

      public boolean satisfiesSymmetry()

    • satisfiesTriangleInequality

      public boolean satisfiesTriangleInequality()

    • distance

      public double distance(@Nonnull double[] vectorData1, @Nonnull double[] vectorData2)

    • distance

      public double distance(@Nonnull RealVector vector1, @Nonnull RealVector vector2)
      Calculates a distance between two n-dimensional vectors.

      The two vectors are represented as arrays of Double and must be of the same length (i.e., have the same number of dimensions).

      Parameters:
      vector1 - the first vector. Must not be null.
      vector2 - the second vector. Must not be null and must have the same length as vector1.
      Returns:
      the calculated distance as a double.
      Throws:
      IllegalArgumentException - if the vectors have different lengths.
      NullPointerException - if either vector1 or vector2 is null.

    • toString

      public String toString()
      Overrides:
      toString in class Enum<Metric>

    • isTrueMetric

      default boolean isTrueMetric()
      Convenience method that returns if all properties of a metric required to be a true metric are satisfied.
      Returns:
      true iff this metric is a true metric.