Skip to content

GitLab

Commit 6cac033c authored by Davis King's avatar Davis King
Browse files

updated the spec

parent 7249a275
Hide whitespace changes
Inline Side-by-side
Showing with 165 additions and 14 deletions
dlib/optimization/find_map_nmplp_abstract.h
View file @ 6cac033c
...@@ -15,25 +15,110 @@ namespace dlib ...@@ -15,25 +15,110 @@ namespace dlib
{ {
/*! /*!
WHAT THIS OBJECT REPRESENTS WHAT THIS OBJECT REPRESENTS
This object represents a factor graph or graphical model. In
particular, this document defines the interface a MAP problem on
a factor graph must implement if it is to be solved using the
find_map_nmplp() routine defined at the bottom of this file.
!*/ !*/
public: public:
class node_iterator class node_iterator
{ {
/*!
WHAT THIS OBJECT REPRESENTS
This is a simple forward iterator for iterating over
the nodes/variables in this factor graph.
Note that you can't dereference the iterator and
obtain a value. The iterator is opaque to the user.
It is used only as arguments to the other methods
defined in this interface.
!*/
public: public:
node_iterator(); node_iterator(
bool operator== (const node_iterator& item) const; );
bool operator!= (const node_iterator& item) const; /*!
node_iterator& operator++(); ensures
- constructs an iterator in an undefined state
!*/
bool operator== (
const node_iterator& item
) const;
/*!
ensures
- returns true if *this and item both reference
the same node in the factor graph and false
otherwise.
!*/
bool operator!= (
const node_iterator& item
) const;
/*!
ensures
- returns false if *this and item both reference
the same node in the factor graph and true
otherwise.
!*/
node_iterator& operator++(
);
/*!
ensures
- advances *this to the next node in the factor graph.
- returns a reference to the updated *this
(i.e. this is the ++object form of operator++)
!*/
}; };
class neighbor_iterator class neighbor_iterator
{ {
neighbor_iterator(); /*!
bool operator== (const neighbor_iterator& item) const; WHAT THIS OBJECT REPRESENTS
bool operator!= (const neighbor_iterator& item) const; This is a simple forward iterator for iterating over
neighbor_iterator& operator++(); the nodes/variables in this factor graph. This version
of the iterator is used for iterating over the neighbors
of another node in the graph.
!*/
neighbor_iterator(
);
/*!
ensures
- constructs an iterator in an undefined state
!*/
bool operator== (
const neighbor_iterator& item
) const;
/*!
ensures
- returns true if *this and item both reference
the same node in the factor graph and false
otherwise.
!*/
bool operator!= (
const neighbor_iterator& item
) const;
/*!
ensures
- returns false if *this and item both reference
the same node in the factor graph and true
otherwise.
!*/
neighbor_iterator& operator++(
);
/*!
ensures
- advances *this to the next node in the factor graph.
- returns a reference to the updated *this
(i.e. this is the ++object form of operator++)
!*/
}; };
unsigned long number_of_nodes ( unsigned long number_of_nodes (
...@@ -46,36 +131,75 @@ namespace dlib ...@@ -46,36 +131,75 @@ namespace dlib
node_iterator begin( node_iterator begin(
) const; ) const;
/*!
ensures
- returns an iterator to the first node in the graph. If no such
node exists then returns end().
!*/
node_iterator end( node_iterator end(
) const; ) const;
/*!
ensures
- returns an iterator to one past the last node in the graph.
!*/
neighbor_iterator begin( neighbor_iterator begin(
const node_iterator& it const node_iterator& it
) const; ) const;
/*!
requires
- it == a valid iterator (i.e. it must be in the range [begin(), end()))
ensures
- returns an iterator to the first neighboring node of the node
referenced by it. If no such node exists then returns end(it).
!*/
neighbor_iterator begin( neighbor_iterator begin(
const neighbor_iterator& it const neighbor_iterator& it
) const; ) const;
/*!
requires
- it == a valid iterator. (i.e. it must be in the range
[begin(i), end(i)) where i is some valid iterator. )
ensures
- returns an iterator to the first neighboring node of the node
referenced by it. If no such node exists then returns end(it).
!*/
neighbor_iterator end( neighbor_iterator end(
const node_iterator& it const node_iterator& it
) const; ) const;
/*!
requires
- it == a valid iterator (i.e. it must be in the range [begin(), end()))
ensures
- returns an iterator to one past the last neighboring node of the node
referenced by it.
!*/
neighbor_iterator end( neighbor_iterator end(
const neighbor_iterator& it const neighbor_iterator& it
) const; ) const;
/*!
requires
- it == a valid iterator. (i.e. it must be in the range
[begin(i), end(i)) where i is some valid iterator. )
ensures
- returns an iterator to one past the last neighboring node of the node
referenced by it.
!*/
unsigned long node_id ( unsigned long node_id (
const node_iterator& it const node_iterator& it
) const; ) const;
/*! /*!
requires requires
- it == a valid iterator - it == a valid iterator (i.e. it must be in the range [begin(), end()))
ensures ensures
- returns a number ID such that: - returns a number ID such that:
- 0 <= ID < number_of_nodes() - 0 <= ID < number_of_nodes()
- ID == a number which uniquely identifies the node pointed to by it. - ID == a number which uniquely identifies the node pointed to by it.
!*/ !*/
unsigned long node_id ( unsigned long node_id (
...@@ -83,25 +207,52 @@ namespace dlib ...@@ -83,25 +207,52 @@ namespace dlib
) const; ) const;
/*! /*!
requires requires
- it == a valid iterator - it == a valid iterator. (i.e. it must be in the range
[begin(i), end(i)) where i is some valid iterator. )
ensures ensures
- returns a number ID such that: - returns a number ID such that:
- 0 <= ID < number_of_nodes() - 0 <= ID < number_of_nodes()
- ID == a number which uniquely identifies the node pointed to by it. - ID == a number which uniquely identifies the node pointed to by it.
!*/ !*/
unsigned long num_states ( unsigned long num_states (
const node_iterator& it const node_iterator& it
) const; ) const;
/*!
requires
- it == a valid iterator (i.e. it must be in the range [begin(), end()))
ensures
- returns the number of states attainable by the node/variable referenced by it.
!*/
unsigned long num_states ( unsigned long num_states (
const neighbor_iterator& it const neighbor_iterator& it
) const; ) const;
/*!
requires
- it == a valid iterator. (i.e. it must be in the range
[begin(i), end(i)) where i is some valid iterator. )
ensures
- returns the number of states attainable by the node/variable referenced by it.
!*/
// The next four functions all have the same contract.
double factor_value (const node_iterator& it1, const node_iterator& it2, unsigned long s1, unsigned long s2) const; double factor_value (const node_iterator& it1, const node_iterator& it2, unsigned long s1, unsigned long s2) const;
double factor_value (const neighbor_iterator& it1, const node_iterator& it2, unsigned long s1, unsigned long s2) const; double factor_value (const neighbor_iterator& it1, const node_iterator& it2, unsigned long s1, unsigned long s2) const;
double factor_value (const node_iterator& it1, const neighbor_iterator& it2, unsigned long s1, unsigned long s2) const; double factor_value (const node_iterator& it1, const neighbor_iterator& it2, unsigned long s1, unsigned long s2) const;
double factor_value (const neighbor_iterator& it1, const neighbor_iterator& it2, unsigned long s1, unsigned long s2) const; double factor_value (const neighbor_iterator& it1, const neighbor_iterator& it2, unsigned long s1, unsigned long s2) const;
/*!
requires
- it1 == a valid iterator
- it2 == a valid iterator
- 0 <= s1 < num_states(it1)
- 0 <= s2 < num_states(it2)
- it1 and it2 reference nodes which are neighbors in the factor graph
ensures
- returns the value of the factor/potential function for the given pair of
nodes, defined by it1 and it2, for the case where they take on the values
s1 and s2 respectively.
!*/
}; };
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment