Built-In Distance Functors

This section describes concrete implementations of distance functors. For utilities and concepts related to abstract distance computation, refer to distance concepts.

struct DistanceL2

Functor for computing the square Euclidean distance.

This is the primary functor for implementing the square Euclidean distance between two vectors in R^n. This functor uses the externally defined compute method and is thus capable of being extended externally.

Public Types

using compare = std::less<>: Vectors are more similar if their distance is smaller.

Public Static Attributes

static constexpr bool implicit_broadcast = true: This functor does not use any local scratch space to assist in computation and thus may be shared across threads and queries safely.

struct DistanceIP

Functor for computing the Inner Product.

This is the primary functor for implementing the Inner Product similarity between two vectors in R^n. This functor uses the externally defined compute method and is thus capable of being extended externally.

Public Types

using compare = std::greater<>: Vectors are more similar if their similarity is greater.

Public Static Attributes

static constexpr bool implicit_broadcast = true: This functor does not use any local scratch space to assist in computation and thus may be shared across threads and queries safely.

struct DistanceCosineSimilarity

Functor for computing Cosine Similarity.

This is the primary functor for implementing the Cosine similarity between two vectors in R^n. This functor uses the externally defined compute method and is thus capable of being extended externally.

Public Types

using compare = std::greater<>: Vectors are more similar if their similarity is greater.

Public Functions

template<typename T, size_t Extent> inline void fix_argument(const std::span<T, Extent> &x): Compute and store the norm of x

Public Static Attributes

static constexpr bool must_fix_argument = true: Fix-argument is required.

static const bool implicit_broadcast = false: This functor uses fix_argument to compute the norm of the left-hand argument. As such, it is stateful and not implicitly broadcastable.

Built-in Distance Overloads

template<Arithmetic Ea, Arithmetic Eb, size_t Da, size_t Db> float compute(DistanceCosineSimilarity distance, std::span<Ea, Da> a, std::span<Eb, Db> b)

Compute the Cosine simmilarity between two vectors in R^n.

The base pointers for a and b need not be aligned. Mixed types for Ea and Eb are supported.

Performance Tips

Specifying the size parameters Da and Db can greatly improve performance.
Compiling and executing on an Intel(R) AVX-512 system will improve performance.

Template Parameters:

Ea – The element type for each component of the left-hand argument.
Eb – The element type for each component of the right-hand argument.
Da – The compile-time length of left-hand argument. May be svs::Dynamic if this is to be discovered during runtime.
Db – The compile-time length of right-hand argument. May be svs::Dynamic if this is to be discovered during runtime.

Parameters:

distance – The cosine similarity distance functor. Must have had fix_argument called previously with left-hand argument a.
a – The left-hand vector. Typically, this position is used for the query.
b – The right-hand vector. Typically, this position is used for a dataset vector.

template<Arithmetic Ea, Arithmetic Eb, size_t Da, size_t Db> float compute(DistanceL2, std::span<Ea, Da> a, std::span<Eb, Db> b)

Compute the squared Euclidean distance between two vectors in R^n.

The base pointers for a and b need not be aligned. Mixed types for Ea and Eb are supported.

Performance Tips

Specifying the size parameters Da and Db can greatly improve performance.
Compiling and executing on an Intel(R) AVX-512 system will improve performance.

Template Parameters:

Ea – The element type for each component of the left-hand argument.
Eb – The element type for each component of the right-hand argument.
Da – The compile-time length of left-hand argument. May be svs::Dynamic if this is to be discovered during runtime.
Db – The compile-time length of right-hand argument. May be svs::Dynamic if this is to be discovered during runtime.

Parameters:

a – The left-hand vector. Typically, this position is used for the query.
b – The right-hand vector. Typically, this position is used for a dataset vector.

template<Arithmetic Ea, Arithmetic Eb, size_t Da, size_t Db> float compute(DistanceIP, std::span<Ea, Da> a, std::span<Eb, Db> b)

Compute the Inner Product similarity between two vectors in R^n.

The base pointers for a and b need not be aligned. Mixed types for Ea and Eb are supported.

Performance Tips

Specifying the size parameters Da and Db can greatly improve performance.
Compiling and executing on an Intel(R) AVX-512 system will improve performance.

Template Parameters:

Ea – The element type for each component of the left-hand argument.
Eb – The element type for each component of the right-hand argument.
Da – The compile-time length of left-hand argument. May be svs::Dynamic if this is to be discovered during runtime.
Db – The compile-time length of right-hand argument. May be svs::Dynamic if this is to be discovered during runtime.

Parameters:

a – The left-hand vector. Typically, this position is used for the query.
b – The right-hand vector. Typically, this position is used for a dataset vector.

Public Distance Utilities

enum svs::DistanceType

Runtime selector for built-in distance functions.

Values:

enumerator L2: Minimize squared L2 distance. See: svs::distance::DistanceL2.

enumerator MIP: Maximize inner product. See: svs::distance::DistanceIP.

enumerator Cosine: Minimize cosine similarity. See: svs::distance::DistanceCosineSimilarity.

template<typename Distance> constexpr DistanceType svs::distance_type_v = detail::DistanceTypeEnumMap<Distance>::value: Return the runtime enum for the built-in distance functor.

class DistanceDispatcher

Dynamically dispatch from an distance enum to a distance functor.

Most methods in the library require a distance functor to be given directly. However, the decision of which functor to use is often a runtime decision.

This class provides a method of converting a svs::DistanceType enum to one of the built-in functor types.

NOTE: Using a DistanceDispatcher will instantiate code-paths for all built-in functors, which may have an impact on compile-time and binary size.

Public Functions

inline explicit DistanceDispatcher(DistanceType distance_type)

Construct a new DistanceDispatcher.

Parameters:: distance_type – The distance type to use.

template<typename F, typename ...Args> inline auto operator()(F &&f, Args&&... args)

Dynamically dispatch to the correct distance functor.

All other arguments will be forwarded to f beginning at argument position 2.

Parameters:

f – A function who takes distance functor for its first argument. The dispatcher will call f with the functor corresponding to the enum used to construct the dispatcher.
args – Arguements to forward to f.