NeuralEngine
A Game Engine with embeded Machine Learning algorithms based on Gaussian Processes.
NeuralEngine::MinHeap< KeyType, ValueType > Class Template Reference

Minimum heap binary tree. More...

#include <NeMinHeap.h>

Collaboration diagram for NeuralEngine::MinHeap< KeyType, ValueType >:

Classes

struct  Record
 

Public Member Functions

 MinHeap (MinHeap const &minHeap)
 Copy constructor. More...
 
 MinHeap (int maxElements=0)
 Constructor. More...
 
MinHeapoperator= (MinHeap const &minHeap)
 
void Reset (int maxElements)
 Resets the given maxElements. More...
 
int GetNumElements () const
 Get the remaining number of elements in the min-heap. This number is in the range {0..maxElements}.
More...
 
bool GetMinimum (KeyType &key, ValueType &value) const
 Get the root of the min-heap. The return value is 'true' whenever the min-heap is not empty. This function reads the root but does not
remove the element from the min-heap.
More...
 
RecordInsert (KeyType const &key, ValueType const &value)
 Insert into the min-heap the 'value' that corresponds to the 'key'. More...
 
bool Remove (KeyType &key, ValueType &value)
 Remove the root of the heap and return its 'key' and 'value members. More...
 
void Update (Record *record, ValueType const &value)
 The value of a heap record must be modified through this function call. More...
 
bool IsValid () const
 
Support for debugging. The functions test whether the data structure is a valid min-heap. More...
 

Private Attributes

int mNumElements
 
std::vector< RecordmRecords
 
std::vector< Record * > mPointers
 

Detailed Description

template<typename KeyType, typename ValueType>
class NeuralEngine::MinHeap< KeyType, ValueType >

Minimum heap binary tree.

<note> A min-heap is a binary tree whose nodes have weights and with the constraint that the weight of a parent node is less than or equal to the weights of its children. This data structure may be used as a priority queue. If the std::priority_queue interface suffices for your needs, use that instead. However, for some geometric algorithms, that interface is insufficient for optimal performance. For example, if you have a polyline vertices that you want to decimate, each vertex's weight depends on its neighbors' locations. If the minimum-weight vertex is removed from the min-heap, the neighboring vertex weights must be updated–something that is O(1) time when you store the vertices as a doubly linked list. The neighbors are already in the min-heap, so modifying their weights without removing then from–and then reinserting into–the min-heap requires they must be moved to their proper places to restore the invariant of the min-heap. With std::priority_queue, you have no direct access to the modified vertices, forcing you to search for those vertices, remove them, update their weights, and re-insert them. The min-heap implementation here does support the update without removal and reinsertion.

The ValueType represents the weight and it must support comparisons "<" and "<=". Additional information can be stored in the min-heap for convenient access; this is stored as the KeyType. In the (open) polyline decimation example, the KeyType is a structure that stores indices to a vertex and its neighbors. The following code illustrates the creation and use of the min-heap. The Weight() function is whatever you choose to guide which vertices are removed first from the polyline.

struct Vertex { int previous, current, next; }; int numVertices = <number of polyline vertices>; std::vector<Vector<N, Real>> positions(numVertices); <assign all positions[*]>; MinHeap<Vertex, Real> minHeap(numVertices); std::vector<MinHeap<Vertex, Real>::Record*> records(numVertices); for (int i = 0; i < numVertices; ++i) { Vertex vertex; vertex.previous = (i + numVertices - 1) % numVertices; vertex.current = i; vertex.next = (i + 1) % numVertices; records[i] = minHeap.Insert(vertex, Weight(positions, vertex)); }

while (minHeap.GetNumElements() >= 2) { Vertex vertex; Real weight; minHeap.Remove(vertex, weight); <consume the 'vertex' according to your application's needs>;

// Remove 'vertex' from the doubly linked list. Vertex& vp = records[vertex.previous]->key; Vertex& vc = records[vertex.current]->key; Vertex& vn = records[vertex.next]->key; vp.next = vc.next; vn.previous = vc.previous;

// Update the neighbors' weights in the min-heap. minHeap.Update(records[vertex.previous], Weight(positions, vp)); minHeap.Update(records[vertex.next], Weight(positions, vn)); } </note>

Hmetal T, 04.08.2016.

Definition at line 89 of file NeMinHeap.h.

Constructor & Destructor Documentation

◆ MinHeap() [1/2]

template<typename KeyType , typename ValueType >
MinHeap::MinHeap ( MinHeap< KeyType, ValueType > const &  minHeap)

Copy constructor.

<note> Construction. The record 'value' members are uninitialized for native types chosen for ValueType. If ValueType is of class type, then the default constructor is used to set the 'value' members. </note>

Hmetal T, 04.08.2016.

Parameters
minHeapThe minimum heap.

Definition at line 18 of file NeMinHeap.inl.

◆ MinHeap() [2/2]

template<typename KeyType , typename ValueType >
MinHeap::MinHeap ( int  maxElements = 0)

Constructor.

<note> Construction. The record 'value' members are uninitialized for native types chosen for ValueType. If ValueType is of class type, then the default constructor is used to set the 'value' members. </note>

Hmetal T, 04.08.2016.

Parameters
maxElements(Optional) the maximum elements.

File: NECore/DataTypes/NeMinHeap.inl

Author:
Email:
Site:

Copyright (c) 2016 . All rights reserved.

Definition at line 12 of file NeMinHeap.inl.

Member Function Documentation

◆ operator=()

template<typename KeyType , typename ValueType >
MinHeap< KeyType, ValueType > & MinHeap::operator= ( MinHeap< KeyType, ValueType > const &  minHeap)

Definition at line 24 of file NeMinHeap.inl.

◆ Reset()

template<typename KeyType , typename ValueType >
void MinHeap::Reset ( int  maxElements)

Resets the given maxElements.

<note> Clear the min-heap so that it has the specified max elements, mNumElements is zero, and mPointers are set to the natural ordering of mRecords. </note>

Hmetal T, 04.08.2016.

Parameters
maxElementsThe maximum elements.

Definition at line 37 of file NeMinHeap.inl.

◆ GetNumElements()

template<typename KeyType , typename ValueType >
int MinHeap::GetNumElements ( ) const
inline

Get the remaining number of elements in the min-heap. This number is in the range {0..maxElements}.

Hmetal T, 04.08.2016.

Returns
The number elements.

Definition at line 58 of file NeMinHeap.inl.

◆ GetMinimum()

template<typename KeyType , typename ValueType >
bool MinHeap::GetMinimum ( KeyType &  key,
ValueType &  value 
) const
inline

Get the root of the min-heap. The return value is 'true' whenever the min-heap is not empty. This function reads the root but does not
remove the element from the min-heap.

Hmetal T, 04.08.2016.

Parameters
key[in,out] The key.
value[in,out] The value.
Returns
true if it succeeds, false if it fails.

Definition at line 64 of file NeMinHeap.inl.

◆ Insert()

template<typename KeyType , typename ValueType >
MinHeap< KeyType, ValueType >::Record * MinHeap::Insert ( KeyType const &  key,
ValueType const &  value 
)

Insert into the min-heap the 'value' that corresponds to the 'key'.

<note> The return value is a pointer to the heap record that stores a copy of 'value', and the pointer value is constant for the life of the min-heap. If you must update a member of the min-heap, say, as illustrated in the polyline decimation example, pass the pointer to Update: auto* valueRecord = minHeap.Insert(key, value); <do whatever>; minHeap.Update(valueRecord, newValue). </note>

Hmetal T, 04.08.2016.

Parameters
keyThe key.
valueThe value.
Returns
null if it fails, else a pointer to a Record.

Definition at line 80 of file NeMinHeap.inl.

◆ Remove()

template<typename KeyType , typename ValueType >
bool MinHeap::Remove ( KeyType &  key,
ValueType &  value 
)

Remove the root of the heap and return its 'key' and 'value members.

<note> The root contains the minimum value of all heap elements. The return value is 'true' whenever the min-heap was not empty before the Remove call. </note>

Hmetal T, 04.08.2016.

Parameters
key[in,out] The key.
value[in,out] The value.
Returns
true if it succeeds, false if it fails.

Definition at line 125 of file NeMinHeap.inl.

◆ Update()

template<typename KeyType , typename ValueType >
void MinHeap::Update ( Record record,
ValueType const &  value 
)

The value of a heap record must be modified through this function call.

<note> The side effect is that the heap is updated accordingly to restore the data structure to a min-heap. The input 'record' should be a pointer returned by Insert(value); see the comments for the Insert() function. </note>

Hmetal T, 04.08.2016.

Parameters
record[in,out] If non-null, the record.
valueThe value.

Definition at line 185 of file NeMinHeap.inl.

◆ IsValid()

template<typename KeyType , typename ValueType >
bool MinHeap::IsValid ( ) const


Support for debugging. The functions test whether the data structure is a valid min-heap.

Hmetal T, 04.08.2016.

Returns
true if valid, false if not.

Definition at line 283 of file NeMinHeap.inl.

Member Data Documentation

◆ mNumElements

template<typename KeyType , typename ValueType >
int NeuralEngine::MinHeap< KeyType, ValueType >::mNumElements
private

Definition at line 258 of file NeMinHeap.h.

◆ mRecords

template<typename KeyType , typename ValueType >
std::vector<Record> NeuralEngine::MinHeap< KeyType, ValueType >::mRecords
private

Definition at line 259 of file NeMinHeap.h.

◆ mPointers

template<typename KeyType , typename ValueType >
std::vector<Record*> NeuralEngine::MinHeap< KeyType, ValueType >::mPointers
private

Definition at line 260 of file NeMinHeap.h.


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