ValueCache< T > Class Template Reference

ValueCache is a generic helper template to implement an unstructured data cache, where arbitrary result types can be placed in an n-dimensional space of real numbers. More...

#include <ValueCache.h>

Public Member Functions
	ValueCache (std::size_t in_dim, std::size_t max_leaf_size=10)
	Construct a ValueCache with indices in in_dim dimensions. More...
	ValueCache (const std::string &file_name, std::size_t in_dim, std::size_t max_leaf_size=10)
	Same as above, but provide a filename for storing/restoring the cache content between runs. More...
	~ValueCache ()
	Object destructor. If the cache was constructed with a file name, it gets written here. More...
void	insert (const std::vector< Real > &in_val, const T &out_val)
	insert a new value out_value at the position in_val More...
std::tuple< const std::vector< Real > &, const T &, Real >	getNeighbor (const std::vector< Real > &in_val)
	get a single neighbor of in_val along with stored values and distances More...
std::vector< std::tuple< const std::vector< Real > &, const T &, Real > >	getNeighbors (const std::vector< Real > &in_val, const std::size_t k)
	get a list of up to k neighbors of in_val along with stored values and distances More...
std::size_t	size ()
	return the number of cache entries More...
void	clear ()
	remove all data from the cache More...
std::size_t	kdtree_get_point_count () const
	Nanoflann interface functions. More...
Real	kdtree_get_pt (const std::size_t idx, const std::size_t dim) const
template<class BBOX >
bool	kdtree_get_bbox (BBOX &bb) const

Protected Types
using	KdTreeT = nanoflann::KDTreeSingleIndexDynamicAdaptor< nanoflann::L2_Simple_Adaptor< Real, ValueCache< T > >, ValueCache< T >, -1, std::size_t >

Protected Member Functions
void	rebuildTree ()
	rebuild the kd-tree from scratch and update the bounding box More...

Protected Attributes
std::vector< std::pair< std::vector< Real >, T > >	_location_data
std::unique_ptr< KdTreeT >	_kd_tree
const std::size_t	_in_dim
const std::size_t	_max_leaf_size
const std::size_t	_max_subtrees
std::optional< std::string >	_persistent_storage_file
	file name for persistent store/restore of the cache More...
std::vector< std::pair< Real, Real > >	_bbox
	bounding box (updated upon insertion) More...

Friends
void	dataStore (std::ostream &stream, ValueCache< T > &c, void *context)
void	dataLoad (std::istream &stream, ValueCache< T > &c, void *context)

Detailed Description

template<typename T>
class ValueCache< T >

ValueCache is a generic helper template to implement an unstructured data cache, where arbitrary result types can be placed in an n-dimensional space of real numbers.

Upon lookup the closest result to a given point in n-space is returned. Applications include caching reasonable initial guesses for local Newton solves as found in certain phase field models as well as thermodynamic Gibbs energy minimization.

Definition at line 27 of file ValueCache.h.

Member Typedef Documentation

KdTreeT

template<typename T>

using ValueCache< T >::KdTreeT = nanoflann::KDTreeSingleIndexDynamicAdaptor<nanoflann::L2_Simple_Adaptor<Real, ValueCache<T> >, ValueCache<T>, -1, std::size_t>

protected

Definition at line 86 of file ValueCache.h.

Constructor & Destructor Documentation

ValueCache() [1/2]

template<typename T >

ValueCache< T >::ValueCache	(	std::size_t	in_dim,
		std::size_t	max_leaf_size = 10
	)

Construct a ValueCache with indices in in_dim dimensions.

Definition at line 106 of file ValueCache.h.

  : _kd_tree(nullptr), _in_dim(in_dim), _max_leaf_size(max_leaf_size), _max_subtrees(100)
{
}

ValueCache() [2/2]

template<typename T >

ValueCache< T >::ValueCache	(	const std::string &	file_name,
		std::size_t	in_dim,
		std::size_t	max_leaf_size = 10
	)

Same as above, but provide a filename for storing/restoring the cache content between runs.

Definition at line 112 of file ValueCache.h.

  : ValueCache(in_dim, max_leaf_size)
{
  _persistent_storage_file = file_name;

  // if the persistent storage file exists and is readable, load it
  if (MooseUtils::checkFileReadable(*_persistent_storage_file,
                                    /*check_line_endings =*/false,
                                    /*throw_on_unreadable =*/false))
  {
    std::ifstream in_file(_persistent_storage_file->c_str());
    if (!in_file)
      mooseError("Failed to open '", *_persistent_storage_file, "' for reading.");
    dataLoad(in_file, *this, nullptr);
  }
}

~ValueCache()

template<typename T >

ValueCache< T >::~ValueCache

(

)

Object destructor. If the cache was constructed with a file name, it gets written here.

Definition at line 132 of file ValueCache.h.

{
  // if a persistent storage file was specified, write results back to it
  if (_persistent_storage_file.has_value())
  {
    std::ofstream out_file(_persistent_storage_file->c_str());
    if (!out_file)
      mooseWarning("Failed to open '", *_persistent_storage_file, "' for writing.");
    dataStore(out_file, *this, nullptr);
  }
}

Member Function Documentation

clear()

template<typename T >

void ValueCache< T >::clear

(

)

remove all data from the cache

Definition at line 243 of file ValueCache.h.

{
  _location_data.clear();
  _kd_tree = nullptr;
}

getNeighbor()

template<typename T >

std::tuple< const std::vector< Real > &, const T &, Real > ValueCache< T >::getNeighbor

(

const std::vector< Real > &

in_val

)

get a single neighbor of in_val along with stored values and distances

Retrieve a single closest neighbor to in_val.

Throws an exception if no values are stored.

Definition at line 184 of file ValueCache.h.

{
  // throw an exception if this is called on an empty cache
  if (_location_data.empty())
    throw std::runtime_error("Attempting to retrieve a neighbor from an empty ValueCache.");

  // buffers for the kNN search
  nanoflann::KNNResultSet<Real> result_set(1);
  std::size_t return_index;
  Real distance;

  // kNN search
  result_set.init(&return_index, &distance);
  _kd_tree->findNeighbors(result_set, in_val.data());

  const auto & [location, data] = _location_data[return_index];
  return {std::cref(location), std::cref(data), distance};
}

getNeighbors()

template<typename T >

std::vector< std::tuple< const std::vector< Real > &, const T &, Real > > ValueCache< T >::getNeighbors	(	const std::vector< Real > &	in_val,
		const std::size_t	k
	)

get a list of up to k neighbors of in_val along with stored values and distances

This function performs a search on the value cache and returns either the k-nearest neighbors or the neighbors available if the cache size is less than k.

Definition at line 209 of file ValueCache.h.

{
  // return early if no points are stored
  if (_location_data.empty())
    return {};

  // buffers for the kNN search
  nanoflann::KNNResultSet<Real> result_set(std::min(k, size()));
  std::vector<std::size_t> return_indices(std::min(k, size()));
  std::vector<Real> distances(std::min(k, size()));

  // kNN search
  result_set.init(return_indices.data(), distances.data());
  _kd_tree->findNeighbors(result_set, in_val.data());

  // prepare results to be returned
  std::vector<std::tuple<const std::vector<Real> &, const T &, Real>> nearest_neighbors;
  for (const auto i : index_range(result_set))
  {
    const auto & [location, data] = _location_data[return_indices[i]];
    nearest_neighbors.emplace_back(std::cref(location), std::cref(data), distances[i]);
  }
  return nearest_neighbors;
}

insert()

template<typename T >

void ValueCache< T >::insert	(	const std::vector< Real > &	in_val,
		const T &	out_val
	)

insert a new value out_value at the position in_val

Definition at line 146 of file ValueCache.h.

{
  mooseAssert(in_val.size() == _in_dim, "Key dimensions do not match cache dimensions");

  auto id = size();
  _location_data.emplace_back(in_val, out_val);

  // update bounding box
  if (id == 0)
  {
    // first item is inserted
    _bbox.resize(_in_dim);
    for (const auto i : make_range(_in_dim))
      _bbox[i] = {in_val[i], in_val[i]};
  }
  else
    for (const auto i : make_range(_in_dim))
      _bbox[i] = {std::min(_bbox[i].first, in_val[i]), std::max(_bbox[i].second, in_val[i])};

  // do we have too many subtrees?
  if (_kd_tree && _kd_tree->getAllIndices().size() > _max_subtrees)
    _kd_tree = nullptr;

  // rebuild tree or add point
  if (!_kd_tree)
  {
    _kd_tree = std::make_unique<KdTreeT>(_in_dim, *this, _max_leaf_size);
    mooseAssert(_kd_tree != nullptr, "KDTree was not properly initialized.");
  }
  else
    _kd_tree->addPoints(id, id);
}

kdtree_get_bbox()

template<typename T >

template<class BBOX >

bool ValueCache< T >::kdtree_get_bbox

(

BBOX &

bb

)

const

Definition at line 291 of file ValueCache.h.

{
  if (_location_data.empty())
    return false;

  // return the bounding box incrementally built upon insertion
  for (const auto i : make_range(_in_dim))
    bb[i] = {_bbox[i].first, _bbox[i].second};
  return true;
}

kdtree_get_point_count()

template<typename T >

std::size_t ValueCache< T >::kdtree_get_point_count

(

)

const

Nanoflann interface functions.

Definition at line 276 of file ValueCache.h.

{
  return _location_data.size();
}

kdtree_get_pt()

template<typename T >

Real ValueCache< T >::kdtree_get_pt	(	const std::size_t	idx,
		const std::size_t	dim
	)		const

Definition at line 283 of file ValueCache.h.

{
  return _location_data[idx].first[dim];
}

rebuildTree()

template<typename T >

void ValueCache< T >::rebuildTree ( )

protected

rebuild the kd-tree from scratch and update the bounding box

Definition at line 251 of file ValueCache.h.

Referenced by dataLoad().

{
  if (_location_data.empty())
    return;

  // reset bounding box (must be done before the tree is built)
  _bbox.resize(_in_dim);
  const auto & location0 = _location_data[0].first;
  for (const auto i : make_range(_in_dim))
    _bbox[i] = {location0[i], location0[i]};

  for (const auto & pair : _location_data)
  {
    const auto & location = pair.first;
    for (const auto i : make_range(_in_dim))
      _bbox[i] = {std::min(_bbox[i].first, location[i]), std::max(_bbox[i].second, location[i])};
  }

  // build kd-tree
  _kd_tree = std::make_unique<KdTreeT>(_in_dim, *this, _max_leaf_size);
  mooseAssert(_kd_tree != nullptr, "KDTree was not properly initialized.");
}

size()

template<typename T >

std::size_t ValueCache< T >::size

(

)

return the number of cache entries

Definition at line 236 of file ValueCache.h.

{
  return kdtree_get_point_count();
}

Friends And Related Function Documentation

dataLoad

template<typename T>

void dataLoad ( std::istream &  stream, ValueCache< T > &  c, void *  context  )

friend

Definition at line 311 of file ValueCache.h.

Referenced by ValueCache< T >::ValueCache().

{
  loadHelper(stream, c._location_data, context);
  c.rebuildTree();
}

dataStore

template<typename T>

void dataStore ( std::ostream &  stream, ValueCache< T > &  c, void *  context  )

friend

Definition at line 304 of file ValueCache.h.

{
  storeHelper(stream, c._location_data, context);
}

Member Data Documentation

_bbox

template<typename T>

std::vector<std::pair<Real, Real> > ValueCache< T >::_bbox

protected

bounding box (updated upon insertion)

Definition at line 99 of file ValueCache.h.

_in_dim

template<typename T>

const std::size_t ValueCache< T >::_in_dim

protected

Definition at line 91 of file ValueCache.h.

_kd_tree

template<typename T>

std::unique_ptr<KdTreeT> ValueCache< T >::_kd_tree

protected

Definition at line 89 of file ValueCache.h.

_location_data

template<typename T>

std::vector<std::pair<std::vector<Real>, T> > ValueCache< T >::_location_data

protected

Definition at line 88 of file ValueCache.h.

Referenced by dataLoad(), and dataStore().

_max_leaf_size

template<typename T>

const std::size_t ValueCache< T >::_max_leaf_size

protected

Definition at line 92 of file ValueCache.h.

_max_subtrees

template<typename T>

const std::size_t ValueCache< T >::_max_subtrees

protected

Definition at line 93 of file ValueCache.h.

_persistent_storage_file

template<typename T>

std::optional<std::string> ValueCache< T >::_persistent_storage_file

protected

file name for persistent store/restore of the cache

Definition at line 96 of file ValueCache.h.

Referenced by ValueCache< T >::ValueCache().

---

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

• include/utils/ValueCache.h