knncolle::DistanceMetric< Data_, Distance_ > Class Template Reference

Interface for a distance metric. More...

#include <distances.hpp>

Inheritance diagram for knncolle::DistanceMetric< Data_, Distance_ >:

Public Member Functions
virtual Distance_	raw (std::size_t num_dimensions, const Data_ *x, const Data_ *y) const =0
virtual Distance_	normalize (Distance_ raw) const =0
virtual Distance_	denormalize (Distance_ norm) const =0
virtual void	save (const std::filesystem::path &dir) const

Detailed Description

template<typename Data_, typename Distance_>
class knncolle::DistanceMetric< Data_, Distance_ >

Interface for a distance metric.

Template Parameters

Data_	Numeric type for the input data.
Distance_	Numeric type for the output distance, usually floating-point.

Member Function Documentation

denormalize()

template<typename Data_ , typename Distance_ >

virtual Distance_ knncolle::DistanceMetric< Data_, Distance_ >::denormalize ( Distance_ norm ) const

pure virtual

Parameters

norm	Normalized distance (i.e., the output of normalize()).

Returns

The denormalized distance (i.e., the input to normalize()).

normalize()

template<typename Data_ , typename Distance_ >

virtual Distance_ knncolle::DistanceMetric< Data_, Distance_ >::normalize ( Distance_ raw ) const

pure virtual

Parameters

raw	Raw distance.

Returns

The normalized distance.

raw()

template<typename Data_ , typename Distance_ >

virtual Distance_ knncolle::DistanceMetric< Data_, Distance_ >::raw ( std::size_t num_dimensions, const Data_ * x, const Data_ * y ) const

pure virtual

The raw distance r for a distance d is defined so that r(x, y) > r(x, z) iff d(x, y) > d(x, z). r(x, y) is converted to d(x, z) via a monotonic transform in normalize(), and vice versa for denormalize(). We separate out these two steps to avoid, e.g., a costly root operation for a Euclidean distance when only the relative values are of interest.

Parameters

x	Pointer to the array containing the first vector.
y	Pointer to the array containing the second vector.
num_dimensions	Length of both vectors.

Returns

The raw distance between x and y.

save()

template<typename Data_ , typename Distance_ >

virtual void knncolle::DistanceMetric< Data_, Distance_ >::save ( const std::filesystem::path & dir ) const

inlinevirtual

Save the distance metric to disk, to be reloaded with load_distance_metric_raw() and friends.

An implementation of this method should create a DISTANCE file inside dir that contains the distance metric's name. This should be an ASCII file with no newlines, where the metric name should follow the <library>::<distance> format, e.g., knncolle::Euclidean. This will be used by load_distance_metric_raw() to determine the exact loader function to call.

Other than the DISTANCE file, each implementation may create any number of additional files of any format in dir. We recommend that the name of each file/directory immediately starts with an upper case letter and is in all-capitals. This allows applications to add more custom files without the risk of conflicts, e.g., by naming them without an upper-case letter.

An implementation of this method is not required to use portable file formats. load_distance_metric_raw() is only expected to work on the same system (i.e., architecture, compiler, compilation settings) that was used for the save() call. Any additional portability is at the discretion of the implementation, e.g., it is common to assume IEEE floating-point and two's-complement integers.

An implementation of this method is not required to create files that are readable by different versions of the implementation. Thus, the files created by this method are generally unsuitable for archival storage. However, implementations are recommended to at least provide enough information to throw an exception if an incompatible version of load_distance_metric_raw() is used.

If a subclass does not implement this method, an error is thrown by default.

Parameters

dir	Path to a directory in which to save the index. This should already exist.

---

The documentation for this class was generated from the following file:

• knncolle/distances.hpp