Domain

class Domain : public NetworkModel

A domain is the HUGIN representation of a network

Inheritance:

Public Methods
Domain() throw(ExceptionHugin): Construct a new, empty Domain object
Domain(const std::string& filename) throw( ExceptionHugin ): Construct a domain by loading the corresponding Hugin Knowledge Base from file
Domain(const std::string& filename, ParseListener *pl) throw(ExceptionHugin): Construct a domain by reading a NET file description
virtual ~Domain() throw(): Destruct a Domain object
void adapt() throw(HAPI::ExceptionHugin): Adapts this Domain according to the evidence entered
double approximate(double epsilon) throw( HAPI::ExceptionHugin ): Remove "near-zero" probabilities from the clique probability tables
bool cgEvidenceIsPropagated() const throw( HAPI::ExceptionHugin ): Test if CG evidence has been propagated for this Domain
void compile() throw( HAPI::ExceptionHugin ): Compile this Domain using the default triangulation method
double compress() throw( HAPI::ExceptionHugin ): Remove the zero entries from the clique and separator tables of the junction trees in this Domain
bool equilibriumIs(Equilibrium eq) const throw( HAPI::ExceptionHugin ): Test for Equilibrium type
bool evidenceIsPropagated() const throw( HAPI::ExceptionHugin ): Test if evidence has been propagated for this Domain
bool evidenceModeIs(EvidenceMode ev) const throw( HAPI::ExceptionHugin ): Test for evidence mode
double getApproximationConstant() const throw( HAPI::ExceptionHugin ): Return the approximation constant
std::string getAttribute(std::string& key) const throw( HAPI::ExceptionHugin ): Return an attrubute value
long getCaseCount(long config): Retrieve the case count associate with the case config in this domain
unsigned int getConcurrencyLevel() const throw( HAPI::ExceptionHugin ): Get the current level of concurrency
double getConflict() const throw( HAPI::ExceptionHugin ): Return the conflict value
NodeList getEliminationOrder() const throw( HAPI::ExceptionHugin ): Return the triangulation order
std::string getFileName() throw( HAPI::ExceptionHugin ): Return the file name most recently used for loading or saving this Domain
unsigned int getGrainSize() const throw( HAPI::ExceptionHugin ): Return the current value of the grain size parameter
JunctionTreeList getJunctionTrees() const throw( HAPI::ExceptionHugin ): Return the JunctionTrees of this Domain
double getLogLikelihood() throw(HAPI::ExceptionHugin): Get the log-likelihood of the domain
double getLogLikelihoodTolerance() throw(HAPI::ExceptionHugin): Get current setting of the log-likelihood tolerance in this domain
double getSignificanceLevel() throw(HAPI::ExceptionHugin): Get current setting of the significance level in this domain
double getLogNormalizationConstant() throw(HAPI::ExceptionHugin): Get the logarithm to the normalization constant
Table* getMarginal(const NodeList& nodes) const throw( HAPI::ExceptionHugin ): Compute the marginal distribution
int getMaxNumberOfEMIterations() throw(HAPI::ExceptionHugin): Retrieve the current maximum number of iterations for the EM algorithm
int getMaxNumberOfSeparators() throw(HAPI::ExceptionHugin): Retrieve the current maximum number of separators allowed during triangulation
Node* getNodeByName(const std::string &) const throw( HAPI::ExceptionHugin ): Get Node by name
NodeList getNodes() const throw( HAPI::ExceptionHugin ): Return the Nodes of this Domain
std::pair <unsigned int,unsigned int> getNodeSize() throw(ExceptionHugin): Return the size of the displayed nodes
double getNormalizationConstant() const throw( ExceptionHugin ): Retrieve the normalization constant
long getNumberOfCases() throw(HAPI::ExceptionHugin): Return the number of cases currently allocated for this domain
bool hasAttribute(const std::string& key) throw(ExceptionHugin): Test if this Domain contains an attribute with the specified key
bool hasEvidenceToPropagate() const throw(ExceptionHugin): Test if evidence has been entered since last propagation
bool hasTablesToPropagate() const throw( ExceptionHugin ): Test for new node tables
void initialize() throw( ExceptionHugin ): Establish the initial values for all tables
void learnStructure() throw( ExceptionHugin ): Learn the structure of a net from a text file
bool isCompiled() const throw( ExceptionHugin ): Test whether this Domain is compiled
bool isCompressed() const throw( ExceptionHugin ): Test whether this Domain is compressed
void learnTables() throw(HAPI::ExceptionHugin): Learn the conditional probability tables for each node in this domain that has an experience table
bool likelihoodIsPropagated() const throw( ExceptionHugin ): Test if likelihood eveidence has been propagated
long newCase() throw(HAPI::ExceptionHugin): Allocate storage within this domain to a new case
void propagate(Equilibrium eq = H_EQUILIBRIUM_SUM, EvidenceMode ev = H_MODE_NORMAL) throw( ExceptionHugin ): Establish the specified equilibrium
void resetInferenceEngine() throw( ExceptionHugin ): Establish the initial state of the inference engine
void retractFindings() throw( ExceptionHugin ): Retract (all) findings for all nodes
void save(const std::string& filename, Endian format = H_ENDIAN_HOST) throw( ExceptionHugin ): Save this Domain as a Hugin Knowledge Base
void saveToMemory() throw( ExceptionHugin ): Create a copy in memory of the belief and junction tree tables of this Domain (which is compiled)
void setAttribute(std::string& key, std::string& value) throw(ExceptionHugin): Insert the key/value pair in the attribute list for this Domain
void setCaseCount(long config, double count) throw(HAPI::ExceptionHugin): Set the case count for the configuration config to count
void setConcurrencyLevel(unsigned int level) throw( HAPI::ExceptionHugin ): Set the level of concurrency
void setGrainSize(unsigned int size) throw( HAPI::ExceptionHugin ): Set the grains size parameter
void setLogFile(FILE* log) throw( HAPI::ExceptionHugin ): Set the file to be used for logging by subsequent compilation and triangulation operations
void setLogLikelihoodTolerance(double tolerance) throw(HAPI::ExceptionHugin): Specify the tolerance of the log-likelihood
void setSignificanceLevel(double significancelevel) throw(HAPI::ExceptionHugin): Specify the Significance Level used for the structurel learning aglorithm
void setMaxNumberOfEMIterations(int iterations) throw(HAPI::ExceptionHugin): Set the maximal number of iterations allowed for the EM algorithm
void setMaxNumberOfSeparators(int separators) throw(HAPI::ExceptionHugin): Set the maximal number of separators allowed during triangulation
void setNodeSize(unsigned int width, unsigned int height) throw(ExceptionHugin): Set the size of the nodes
void setNumberOfCases(long number) throw(HAPI::ExceptionHugin): Adjust the storage capacity for cases in this domain
void setUserData(void *data) throw(HAPI::ExceptionHugin): Set the user data field of this Domain
void simulate() throw( ExceptionHugin ): Sample a configuration for this Domain with respect to the current distribution
void triangulate(TriangulationMethod tm = H_TM_FILL_IN_WEIGHT) throw(ExceptionHugin): Transforms a network into a triangulated graph
void triangulateWithOrder(const NodeList& order) throw( ExceptionHugin ): Transforms a network into a triangulated graph using a specified elimination order
void uncompile() throw( ExceptionHugin ): Remove the data structures of this Domain
void writeNet(const std::string& filename) throw(ExceptionHugin): Write a NET description of the Domain to a file
void saveAsNet(const std::string& filename) throw(ExceptionHugin): Write a NET description of the Domain to a file
void generateTables( ) throw(ExceptionHugin): Generate tables for all applicable Nodes in this Domain
void seedRandom( unsigned long seed ) throw( ExceptionHugin ): The random number generator used by HUGIN, generates a set of numbers, which look random, but are in fact deterministic
std::vector <Attribute*> getAttributes() throw( ExceptionHugin ): getAttributes
void saveCase(const std::string& filename) throw(ExceptionHugin): Saves all evidence entered in this Domain in file <fileName> (if the file exists, it is overwritten)
void parseCase(const std::string& filename, ParseListener* pl) throw(ExceptionHugin): Parses the case stored in file <fileName> and enters the associated findings into this Domain

Public
: Return the value stored within the user data slot of this Domain

Inherited from NetworkModel:

Public Methods
void* getUserData() throw(ExceptionHugin)

Documentation

A domain is the HUGIN representation of a network. It is one of the principal structures in HUGIN. It must be constructed before any nodes belonging to the network.

Domain() throw(ExceptionHugin)

Construct a new, empty Domain object

Domain(const std::string& filename) throw( ExceptionHugin )

Construct a domain by loading the corresponding Hugin Knowledge Base from file

Parameters:: filename - A Standard C++ Library string.

Domain(const std::string& filename, ParseListener *pl) throw(ExceptionHugin)

Construct a domain by reading a NET file description

Parameters:: filename - Standard C++ Library string containing the name of the NET file.
pl - Pointer to object derived from class ParseListener.

virtual ~Domain() throw()

Destruct a Domain object

void adapt() throw(HAPI::ExceptionHugin)

Adapts this Domain according to the evidence entered

double approximate(double epsilon) throw( HAPI::ExceptionHugin )

Remove "near-zero" probabilities from the clique probability tables. For each Clique object in this domain, a value delta is computed such that the sum of all elements less than delta in the (discrete part) of the clique table is less than epsilon. These elements (less than delta) are then set to 0.

Returns:: A double value which is the sum of all entries in clique probability tables that have been zeroed.
Parameters:: epsilon - The threshold value. Maximal probability mass to eradicate from each clique.

bool cgEvidenceIsPropagated() const throw( HAPI::ExceptionHugin )

Test if CG evidence has been propagated for this Domain

Returns:: boolean

void compile() throw( HAPI::ExceptionHugin )

Compile this Domain using the default triangulation method. If the domain already is triangulated, nothing is changed. The domain must contain at least one chance or decision node.

double compress() throw( HAPI::ExceptionHugin )

Remove the zero entries from the clique and separator tables of the junction trees in this Domain. Compression can only be applied to (compiled) ordinary belief networks. Continuous nodes are allowed, but compression only applies to configurations of states of the discrete nodes.

Returns:: A double value which indicates a measure of compression achieved. The measure should be less than 1, indicating that the compressed domain requires less space than the uncompressed domain. An output greater than 1 means that the "compressed " domain�requires more space than the uncompressed domain.

bool equilibriumIs(Equilibrium eq) const throw( HAPI::ExceptionHugin )

Test for Equilibrium type. If the equilibrium of all junction trees of this Domain is eq, return true.

Returns:: A boolean.
Parameters:: eq - Type of Equilibrium to test for.

bool evidenceIsPropagated() const throw( HAPI::ExceptionHugin )

Test if evidence has been propagated for this Domain.

Returns:: A boolean.

bool evidenceModeIs(EvidenceMode ev) const throw( HAPI::ExceptionHugin )

Test for evidence mode. Test if the equilibrium of all junction trees of this Domain could have been obtained through a propagation using ev as the evidence incorporation mode.

Returns:: boolean
Parameters:: ev - Type of EvidenceMode to test for.

double getApproximationConstant() const throw( HAPI::ExceptionHugin )

Return the approximation constant. The number returned is based on the most recent (explicit or implicit) approximation operation. An implicit approximation takes place when you change some conditional probability tables of acompressed domain, and then perform a propagation operation. Since some (discree) state configurations have been removed from a compressed domain, the probability mass of the remaining configurations will typically be less than 1. This probability mass is returned by getApproximationConstant().

Returns:: A double expressing the probability mass remaining in the approximated domain.

std::string getAttribute(std::string& key) const throw( HAPI::ExceptionHugin )

Return an attrubute value. Return the value associated with key in the attribute list for this Domain.

Returns:: A Standard C++ Library string containing the attribute value.
Parameters:: key - A Standard C++ Library string.

long getCaseCount(long config)

Retrieve the case count associate with the case config in this domain.

Parameters:: config - long.

unsigned int getConcurrencyLevel() const throw( HAPI::ExceptionHugin )

Get the current level of concurrency.

Returns:: Unsigned integer.
See Also:

double getConflict() const throw( HAPI::ExceptionHugin )

Return the conflict value. The conflict value is valid for this Domain computed during the most recent propagation. If no propagation has been performed, 1 is returned.

Returns:: A double-precision real value expressing the conflict measure in the domain.

NodeList getEliminationOrder() const throw( HAPI::ExceptionHugin )

Return the triangulation order. A NodeList containing a list of nodes in the order used to triangulate the network of this Domain is returned.

Returns:: NodeList containing Nodes representing the elimination order used.

std::string getFileName() throw( HAPI::ExceptionHugin )

Return the file name most recently used for loading or saving this Domain

Returns:: A Standard C++ Library string.

unsigned int getGrainSize() const throw( HAPI::ExceptionHugin )

Return the current value of the grain size parameter.

Returns:: Positive integer.

JunctionTreeList getJunctionTrees() const throw( HAPI::ExceptionHugin )

Return the JunctionTrees of this Domain.

Returns:: JunctionTreeList .

double getLogLikelihood() throw(HAPI::ExceptionHugin)

Get the log-likelihood of the domain

double getLogLikelihoodTolerance() throw(HAPI::ExceptionHugin)

Get current setting of the log-likelihood tolerance in this domain

double getSignificanceLevel() throw(HAPI::ExceptionHugin)

Get current setting of the significance level in this domain

double getLogNormalizationConstant() throw(HAPI::ExceptionHugin)

Get the logarithm to the normalization constant

Table* getMarginal(const NodeList& nodes) const throw( HAPI::ExceptionHugin )

Compute the marginal distribution. for the Nodes provided as arguments (which must all be chance nodes) with respect to the (imaginary) joint potential, determined by the current potentials on the junction tree(s) of this Domain. If <em>nodes</em> contains continuous nodes, they must be last in the list. This operation is not allowed on compressed domains.

Returns:: A Table which contains the marginal distribution over the nodes provided.
Parameters:: nodes - NodeList containing the Node objects over which to compute the marginal.

int getMaxNumberOfEMIterations() throw(HAPI::ExceptionHugin)

Retrieve the current maximum number of iterations for the EM algorithm

int getMaxNumberOfSeparators() throw(HAPI::ExceptionHugin)

Retrieve the current maximum number of separators allowed during triangulation

Node* getNodeByName(const std::string &) const throw( HAPI::ExceptionHugin )

Get Node by name.

Parameters:: name - A Standard C++ string containing the name of the node to be found in this Domain. @output Reference to a node in the domain carrying the name specified by the input. On error an exception will be thrown.

NodeList getNodes() const throw( HAPI::ExceptionHugin )

Return the Nodes of this Domain. No ordering can be inferred by the user.

Returns:: NodeList containing the Nodes of this Domain.

std::pair <unsigned int,unsigned int> getNodeSize() throw(ExceptionHugin)

Return the size of the displayed nodes.

throw(ExceptionHugin)@return Standard C++ Library pair<int,int>.

double getNormalizationConstant() const throw( ExceptionHugin )

Retrieve the normalization constant. from the most recent propagation. For sum-propagation, the normalization constant is equal to the probability of the evidence propagated. For max-propagation, the normalization constant is the probability of the most probable configuration with the evidence incorporated.

Returns:: A double-precision real number.

long getNumberOfCases() throw(HAPI::ExceptionHugin)

Return the number of cases currently allocated for this domain

Return the value stored within the user data slot of this Domain. If the stored value is NULL, or if no value has been stored, NULL is returned. It is the responsibility of the application programmer to ensure that the data is valid, that pointers are accessed correctly, etc.

Also note that when you delete a domain, Hugin does not attempt to delete the data pointed to by the user data slot. It is the responsibility of the user.

Returns:: Pointer stored within the Domain object as a reference to user data associated with this Domain.

bool hasAttribute(const std::string& key) throw(ExceptionHugin)

Test if this Domain contains an attribute with the specified key

Returns:: boolean
Parameters:: key - A Standar C++ Library string.

bool hasEvidenceToPropagate() const throw(ExceptionHugin)

Test if evidence has been entered since last propagation.

Returns:: A boolean.

bool hasTablesToPropagate() const throw( ExceptionHugin )

Test for new node tables. Are there any nodes in this Domain having (a conditional probability or utility) table that has changed since the most recent compilation or propagation.

Returns:: boolean

void initialize() throw( ExceptionHugin )

Establish the initial values for all tables. of this Domain (which must be compiled). Using this method will erase all evidence previously entered.

void learnStructure() throw( ExceptionHugin )

Learn the structure of a net from a text file

bool isCompiled() const throw( ExceptionHugin )

Test whether this Domain is compiled.

Returns:: bool

bool isCompressed() const throw( ExceptionHugin )

Test whether this Domain is compressed.

Returns:: bool

void learnTables() throw(HAPI::ExceptionHugin)

Learn the conditional probability tables for each node in this domain that has an experience table

bool likelihoodIsPropagated() const throw( ExceptionHugin )

Test if likelihood eveidence has been propagated. for this Domain.

Returns:: bool

long newCase() throw(HAPI::ExceptionHugin)

Allocate storage within this domain to a new case.

Returns:: New case index.

void propagate(Equilibrium eq = H_EQUILIBRIUM_SUM, EvidenceMode ev = H_MODE_NORMAL) throw( ExceptionHugin )

Establish the specified equilibrium. using the evidence mode indicated for incorporation of evidence on all junction trees in this Domain. Also, revised beliefs will be computed for all nodes.

Parameters:: eq - Equilibrium type. Defaults to EQ_SUM.
ev - EvidenceMode type. Defaults to EV_NORMAL

void resetInferenceEngine() throw( ExceptionHugin )

Establish the initial state of the inference engine.: sum-equilibrium with no evidence incorporated. Any propagated findings will thus be removed from the junction tree potentials, but entered findings will still be "registred" (i.e., they will be incorporated in the next propagation).

void retractFindings() throw( ExceptionHugin )

Retract (all) findings for all nodes. in this Domain.

void save(const std::string& filename, Endian format = H_ENDIAN_HOST) throw( ExceptionHugin )

Save this Domain as a Hugin Knowledge Base. to a file named by the parameter. The byte order of the Hugin KB is determined by <format>. If <tt>*this</tt> domain is compiled, it can only be saved if the current equilibrium is "sum", and the current evidence incorporation mode is "normal".

Parameters:: filename - Name of the file to save the knowledge base into.
format - Byte-order in the saved file.

void saveToMemory() throw( ExceptionHugin )

Create a copy in memory of the belief and junction tree tables of this Domain (which is compiled). This operation can only be performed if the current equilibrium is "sum", the current evidence mode is "normal", and no CG evidence has been incorporated.

void setAttribute(std::string& key, std::string& value) throw(ExceptionHugin)

Insert the key/value pair in the attribute list for this Domain. If the key is already defined, the value is updated. If no value is provided, the attribute is removed.

Parameters:: key - A Standard C++ Library string.
value - A Standard C++ Library string.

void setCaseCount(long config, double count) throw(HAPI::ExceptionHugin)

Set the case count for the configuration config to count

Parameters:: config - long.
count - double.

void setConcurrencyLevel(unsigned int level) throw( HAPI::ExceptionHugin )

Set the level of concurrency. The level of concurrency specifies the maximum number of threads to create when performing a specific table operation. Setting the level of concurrency to 1 will cause all table operations to be performed sequentially. The initial parameter value is 1.

Parameters:: level - Unsigned integer.

void setGrainSize(unsigned int size) throw( HAPI::ExceptionHugin )

Set the grains size parameter. The grain size parameter specifies a lower limit of the tasks to be performed by each thread. The size of a task is approximately equal to the number of floating-point operations needed to perform the task (e.g. the number of elements to sum when performing a marginalization task).

The initial value of the grain size parameter is 10000.

Parameters:: size - Unsigned integer.

void setLogFile(FILE* log) throw( HAPI::ExceptionHugin )

Set the file to be used for logging by subsequent compilation and triangulation operations.

Parameters:: log - File pointer to an opened file to be used as log. log must be a text file opened for writing or appending. Writing is done sequentially.

void setLogLikelihoodTolerance(double tolerance) throw(HAPI::ExceptionHugin)

Specify the tolerance of the log-likelihood. Terminate the EM learning when the relative difference between the log-likelihood of two successive iterations becomes less than tolerance.

Parameters:: tolerance - double.

void setSignificanceLevel(double significancelevel) throw(HAPI::ExceptionHugin)

Specify the Significance Level used for the structurel learning aglorithm

Parameters:: significancelevel - double.

void setMaxNumberOfEMIterations(int iterations) throw(HAPI::ExceptionHugin)

Set the maximal number of iterations allowed for the EM algorithm. The algorithm termnates when this number is reached or when the relative improvement becomes lower than the log-likelihood tolerance.

Parameters:: iterations - Maximum allowed number of iterations.

void setMaxNumberOfSeparators(int separators) throw(HAPI::ExceptionHugin)

Set the maximal number of separators allowed during triangulation.

Parameters:: separators - Maximum number of separators allowed durring triangulation .

void setNodeSize(unsigned int width, unsigned int height) throw(ExceptionHugin)

Set the size of the nodes.

Parameters:: width - long
height - long

void setNumberOfCases(long number) throw(HAPI::ExceptionHugin)

Adjust the storage capacity for cases in this domain.

Parameters:: number - Storage capacity.

void setUserData(void *data) throw(HAPI::ExceptionHugin)

Set the user data field of this Domain. The Hugin API provides a slot within each Domain object for use exclusively by the user/application. This slot can hold a pointer to arbitrary data, such as a file, a function pointer, etc. Please note that Hugin does not do anything to the user data. Data is not even copied. Only the pointer to the data is stored.

Parameters:: data - Pointer to user-defined data associated with <tt>*this</tt> domain.

void simulate() throw( ExceptionHugin )

Sample a configuration for this Domain with respect to the current distribution.e The current distribution must be in sum-equilibrium and with evidence incorporated in normal mode.

void triangulate(TriangulationMethod tm = H_TM_FILL_IN_WEIGHT) throw(ExceptionHugin)

Transforms a network into a triangulated graph. First, the network of this Domain is tranformed into its moral graph, and then this moral graph is triangulated using the triangulation method tm.

Parameters:: tm - TriangulationMethod

void triangulateWithOrder(const NodeList& order) throw( ExceptionHugin )

Transforms a network into a triangulated graph using a specified elimination order. First, the network of this Domain is transformed into its moral graph. Second, this moral graph is triangulated using the Nodes in the NodeList order as elimination sequence. order must contain each chance and decision node of this Domain exactly once and it must respect the restrictions for influence diagrams and networks containing continuous chance nodes.

Parameters:: order - NodeList containing the Nodes of the network in the order of elimination.

void uncompile() throw( ExceptionHugin )

Remove the data structures of this Domain. The data structures are produced by Domain::compile(), Domain::triangulate(), and Domain::triangulateWithOrder(). Note that any references to objects within the compiled structure (e.g., Clique and JunctionTree objects) are invalidated by a call to uncompile(). Also note that many of the editing functions automatically performs an uncompile() operation. When this happens, the domain must be compiled (using Domain::compile()) before it can be used for inference.

void writeNet(const std::string& filename) throw(ExceptionHugin)

Write a NET description of the Domain to a file

Parameters:: filename - A Standard C++ Library string containing the name of the file to write.

void saveAsNet(const std::string& filename) throw(ExceptionHugin)

Write a NET description of the Domain to a file

Parameters:: filename - A Standard C++ Library string containing the name of the file to write.
See Also:: NetworkModel::saveAsNet

void generateTables( ) throw(ExceptionHugin)

Generate tables for all applicable Nodes in this Domain

See Also:: NetworkModel::generateTables

void seedRandom( unsigned long seed ) throw( ExceptionHugin )

The random number generator used by HUGIN, generates a set of numbers, which look random, but are in fact deterministic. However, the set of numbers depend on the seed of the random generator. This can be set by this function.

Parameters:: seed - The seed which determines the outcome of the random number generator.

std::vector <Attribute*> getAttributes() throw( ExceptionHugin )

getAttributes

See Also:: NetworkModel::getAttributes

void saveCase(const std::string& filename) throw(ExceptionHugin)

Saves all evidence entered in this Domain in file <fileName> (if the file exists, it is overwritten)

Parameters:: fileName - the name of the file in which the case is going to be saved.

void parseCase(const std::string& filename, ParseListener* pl) throw(ExceptionHugin)

Parses the case stored in file <fileName> and enters the associated findings into this Domain. All existing evidence in the Domain is retracted before entering the case findings.

Parameters:: fileName - the name of the file containing the case.
parseListener - the ParseListener used for handling parse errors.

This class has no child classes.

See Also:: Node
JunctionTree

alphabetic index hierarchy of classes

this page has been generated automatically by doc++

(c)opyright by Malte Zöckler, Roland Wunderling
contact: doc++@zib.de

class Domain : public NetworkModel

Inheritance:

Public Methods

Public

Inherited from NetworkModel:

Public Methods

Documentation