MatchBin.hpp

A container that supports flexible tag-based lookup. .

template<typename Val, typename Metric, typename Selector, typename Regulator> class MatchBin

#include <MatchBin.hpp>

A data container that allows lookup by tag similarity. It can be templated on different tag types and is configurable on construction for (1) the distance metric used to compute similarity between tags and (2) the selector that is used to select which matches to return. Regulation functionality is also provided, allowing dynamically adjustment of match strength to a particular item (i.e., making all matches stronger/weaker). A unique identifier is generated upon tag/item placement in the container. This unique identifier can be used to view or edit the stored items and their corresponding tags. Tag-based lookups return a list of matched unique identifiers.

Public Types

using base_t = BaseMatchBin<Val, typename Metric::query_t, typename Metric::tag_t, Regulator>

using query_t = typename base_t::query_t

using tag_t = typename base_t::tag_t

using uid_t = typename base_t::uid_t

using state_t = typename base_t::state_t

Public Functions

MatchBin() = default

inline MatchBin(Random &rand)

inline MatchBin(const MatchBin &other)

inline MatchBin(MatchBin &&other)

inline MatchBin &operator=(const MatchBin &other)

inline MatchBin &operator=(MatchBin &&other)

inline vector<uid_t> Match(const query_t &query, size_t n = std::numeric_limits<size_t>::max()) override: Compare a query tag to all stored tags using the distance metric function and return a vector of unique IDs chosen by the selector function. Calling with n = std::numeric_limits<size_t>::max() means delegate choice for how many values to return to the Selector.

inline vector<uid_t> MatchRaw(const query_t &query, size_t n = std::numeric_limits<size_t>::max()) override: Compare a query tag to all stored tags using the distance metric function and return a vector of unique IDs chosen by the selector function. Ignore regulators. Calling with n = std::numeric_limits<size_t>::max() means delegate choice for how many values to return to the Selector.

inline uid_t Put(const Val &v, const tag_t &t) override: Put an item and associated tag in the container. Returns the uid for that entry.

inline uid_t Set(const Val &v, const tag_t &t, const uid_t uid) override: Put with a manually-chosen UID. (Caller is responsible for ensuring UID is unique or calling Delete beforehand.)

inline void Delete(const uid_t uid) override: Delete an item and its associated tag.

inline void Clear() override: Clear all items and tags.

inline void ClearCache() override: Reset the Selector caches.

inline bool ActivateCaching() override

Attempt to activate result caching.

Returns:: true if caching activated

inline void DeactivateCaching() override

inline Val &GetVal(const uid_t uid) override: Access a reference single stored value by uid.

inline const tag_t &GetTag(const uid_t uid) const override: Access a const reference to a single stored tag by uid.

inline void SetTag(const uid_t uid, const tag_t tag) override: Change the tag at a given uid and clear the cache.

inline vector<Val> GetVals(const vector<uid_t> &uids) override: Generate a vector of values corresponding to a vector of uids.

inline vector<tag_t> GetTags(const vector<uid_t> &uids) override: Generate a vector of tags corresponding to a vector of uids.

inline size_t Size() const override: Get the number of items stored in the container.

inline void AdjRegulator(const uid_t uid, const typename Regulator::adj_t &amt) override: Adjust an item’s regulator value.

inline void SetRegulator(const uid_t uid, const typename Regulator::set_t &set) override: Set an item’s regulator value.

inline void SetRegulator(const uid_t uid, const Regulator &set) override: Set an item’s regulator value.

inline const Regulator::view_t &ViewRegulator(const uid_t uid) const override: View an item’s regulator value.

inline const Regulator &GetRegulator(const uid_t uid) override: Get a regulator.

inline void DecayRegulator(const uid_t uid, const int steps) override: Apply decay to a regulator.

inline void DecayRegulators(const int steps = 1) override: Apply decay to all regulators.

inline void ImprintRegulators(const BaseMatchBin<Val, query_t, tag_t, Regulator> &target) override

Set up regulators to match target MatchBin

Parameters:: target – MatchBin to match

inline void ImprintRegulators(const state_t &target) override

Set up regulators to match target state

Parameters:: target – State to match

inline vector<uid_t> ViewUIDs() const override: View UIDs associated with this MatchBin.

inline std::string name() const override: Get selector, metric name.

inline const state_t &GetState() const override: Extract MatchBin state.

inline void SetState(const state_t &state_): Load MatchBin state.

inline size_t GetRegulatedCacheSize(): Returns size of regulated cache.

inline size_t GetRawCacheSize(): Returns size of raw cache.

Protected Attributes

state_t state

uid_t uid_stepper = {}

internal::MatchBinCache<query_t, Selector> cache

Selector selector

template<typename Val, typename Tag, typename Regulator> struct MatchBinState

#include <MatchBin.hpp>

Internal state packet for MatchBin.

Public Types

using tag_t = Tag 

using uid_t = size_t

Public Members

robin_hood::unordered_flat_map<uid_t, entry> data

struct entry

#include <MatchBin.hpp>

Public Functions

template<class Archive> inline void serialize(Archive &ar)

Public Members

Val val

Regulator regulator

Tag tag

template<typename Val, typename Query, typename Tag, typename Regulator> class BaseMatchBin

#include <MatchBin.hpp>

Abstract base class for MatchBin.

Public Types

using query_t = Query 

using tag_t = Tag 

using uid_t = size_t

using state_t = MatchBinState<Val, tag_t, Regulator>

Public Functions

inline virtual ~BaseMatchBin()

virtual vector<uid_t> Match(const query_t &query, size_t n = 0) = 0

virtual vector<uid_t> MatchRaw(const query_t &query, size_t n = 0) = 0

virtual uid_t Put(const Val &v, const tag_t &t) = 0

virtual uid_t Set(const Val &v, const tag_t &t, const uid_t uid) = 0

virtual void Delete(const uid_t uid) = 0

virtual void Clear() = 0

virtual void ClearCache() = 0

virtual bool ActivateCaching() = 0

virtual void DeactivateCaching() = 0

virtual Val &GetVal(const uid_t uid) = 0

virtual const tag_t &GetTag(const uid_t uid) const = 0

virtual void SetTag(const uid_t uid, tag_t tag) = 0

virtual vector<Val> GetVals(const vector<uid_t> &uids) = 0

virtual vector<tag_t> GetTags(const vector<uid_t> &uids) = 0

virtual size_t Size() const = 0

virtual void DecayRegulator(const uid_t uid, const int steps) = 0

virtual void DecayRegulators(const int steps = 1) = 0

virtual void AdjRegulator(const uid_t uid, const typename Regulator::adj_t &amt) = 0

virtual void SetRegulator(const uid_t uid, const typename Regulator::set_t &set) = 0

virtual void SetRegulator(const uid_t uid, const Regulator &set) = 0

virtual const Regulator &GetRegulator(const uid_t uid) = 0

virtual const Regulator::view_t &ViewRegulator(const uid_t uid) const = 0

virtual const state_t &GetState() const = 0

virtual void ImprintRegulators(const BaseMatchBin &target) = 0

virtual void ImprintRegulators(const BaseMatchBin::state_t &target) = 0

virtual std::string name() const = 0

virtual vector<uid_t> ViewUIDs() const = 0

template<typename Val, typename Metric, typename Selector, typename Regulator> class MatchBin

#include <MatchBin.hpp>

A data container that allows lookup by tag similarity. It can be templated on different tag types and is configurable on construction for (1) the distance metric used to compute similarity between tags and (2) the selector that is used to select which matches to return. Regulation functionality is also provided, allowing dynamically adjustment of match strength to a particular item (i.e., making all matches stronger/weaker). A unique identifier is generated upon tag/item placement in the container. This unique identifier can be used to view or edit the stored items and their corresponding tags. Tag-based lookups return a list of matched unique identifiers.

Public Types

using base_t = BaseMatchBin<Val, typename Metric::query_t, typename Metric::tag_t, Regulator>

using query_t = typename base_t::query_t

using tag_t = typename base_t::tag_t

using uid_t = typename base_t::uid_t

using state_t = typename base_t::state_t

Public Functions

MatchBin() = default

inline MatchBin(Random &rand)

inline MatchBin(const MatchBin &other)

inline MatchBin(MatchBin &&other)

inline MatchBin &operator=(const MatchBin &other)

inline MatchBin &operator=(MatchBin &&other)

inline vector<uid_t> Match(const query_t &query, size_t n = std::numeric_limits<size_t>::max()) override: Compare a query tag to all stored tags using the distance metric function and return a vector of unique IDs chosen by the selector function. Calling with n = std::numeric_limits<size_t>::max() means delegate choice for how many values to return to the Selector.

inline vector<uid_t> MatchRaw(const query_t &query, size_t n = std::numeric_limits<size_t>::max()) override: Compare a query tag to all stored tags using the distance metric function and return a vector of unique IDs chosen by the selector function. Ignore regulators. Calling with n = std::numeric_limits<size_t>::max() means delegate choice for how many values to return to the Selector.

inline uid_t Put(const Val &v, const tag_t &t) override: Put an item and associated tag in the container. Returns the uid for that entry.

inline uid_t Set(const Val &v, const tag_t &t, const uid_t uid) override: Put with a manually-chosen UID. (Caller is responsible for ensuring UID is unique or calling Delete beforehand.)

inline void Delete(const uid_t uid) override: Delete an item and its associated tag.

inline void Clear() override: Clear all items and tags.

inline void ClearCache() override: Reset the Selector caches.

inline bool ActivateCaching() override

Attempt to activate result caching.

Returns:: true if caching activated

inline void DeactivateCaching() override

inline Val &GetVal(const uid_t uid) override: Access a reference single stored value by uid.

inline const tag_t &GetTag(const uid_t uid) const override: Access a const reference to a single stored tag by uid.

inline void SetTag(const uid_t uid, const tag_t tag) override: Change the tag at a given uid and clear the cache.

inline vector<Val> GetVals(const vector<uid_t> &uids) override: Generate a vector of values corresponding to a vector of uids.

inline vector<tag_t> GetTags(const vector<uid_t> &uids) override: Generate a vector of tags corresponding to a vector of uids.

inline size_t Size() const override: Get the number of items stored in the container.

inline void AdjRegulator(const uid_t uid, const typename Regulator::adj_t &amt) override: Adjust an item’s regulator value.

inline void SetRegulator(const uid_t uid, const typename Regulator::set_t &set) override: Set an item’s regulator value.

inline void SetRegulator(const uid_t uid, const Regulator &set) override: Set an item’s regulator value.

inline const Regulator::view_t &ViewRegulator(const uid_t uid) const override: View an item’s regulator value.

inline const Regulator &GetRegulator(const uid_t uid) override: Get a regulator.

inline void DecayRegulator(const uid_t uid, const int steps) override: Apply decay to a regulator.

inline void DecayRegulators(const int steps = 1) override: Apply decay to all regulators.

inline void ImprintRegulators(const BaseMatchBin<Val, query_t, tag_t, Regulator> &target) override

Set up regulators to match target MatchBin

Parameters:: target – MatchBin to match

inline void ImprintRegulators(const state_t &target) override

Set up regulators to match target state

Parameters:: target – State to match

inline vector<uid_t> ViewUIDs() const override: View UIDs associated with this MatchBin.

inline std::string name() const override: Get selector, metric name.

inline const state_t &GetState() const override: Extract MatchBin state.

inline void SetState(const state_t &state_): Load MatchBin state.

inline size_t GetRegulatedCacheSize(): Returns size of regulated cache.

inline size_t GetRawCacheSize(): Returns size of raw cache.

Protected Attributes

state_t state

uid_t uid_stepper = {}

internal::MatchBinCache<query_t, Selector> cache

Selector selector

namespace cereal

Functions

template<class Archive, class T> void save(Archive &archive, robin_hood::unordered_flat_map<size_t, T> const &m)

template<class Archive, class T> void load(Archive &archive, robin_hood::unordered_flat_map<size_t, T> &m)