<< Click to Display Table of Contents >> Navigation:  Reference Manual > DSL_network

Header file: network.h

DSL_network manages the lifetime of its nodes. Nodes should be created with DSL_network::AddNode and deleted with DSL_network::DeleteNode.

---

DSL_network();

DSL_network(const DSL_network &src, int reserved = 0);

~DSL_network();
DSL_network& operator=(const DSL_network &src);

Implement the default constructor, copy constructor, destructor and operator =.

---

void Clear();

Removes all content from the network (nodes, submodels, extended functions, properties, etc).

---

int ReadFile(const char *filename, int fileType=0, void *reserved=NULL);

Reads the network contents from the file specified by filename. If fileType is set to zero, the type of file is determined based on file’s extension retrieved from the filename. The supported file type identifiers are:

Returns DSL_OKAY on success or negative error code otherwise. If the reason for failure is a syntax error in the file or the file is not found, the error message is logged to DSL_errorH().

---

int WriteFile(const char *filename, int fileType=0, void *reserved=NULL);

Writes the network contents to the file system. Returns DSL_OKAY on success, or a negative error code on failure.

---

int ReadString(const char *xdslString, void *reserved=NULL);

Read the network content from xdslString, only XDSL format is supported. Returns DSL_OKAY on success, or a negative error code on failure.

---

int WriteString(std::string &xdslOut, void *reserved=NULL);

Writes the network content to xdslOut as XDSL. Returns DSL_OKAY on success, or a negative error code on failure.

---

int UpdateBeliefs();

Executes inference algorithm to update node values. Returns DSL_OKAY on success, or a negative error code on failure.

---

bool IsUpdateImmediate() const;

int SetUpdateImmediate(bool immediate);

Returns/sets the immediate update flag. If the flag is set to true, UpdateBeliefs will be called after changes in the network structure, parameters or evidence.

---

void SetDefaultBNAlgorithm(int algorithm);

Sets the algorithm used for inference in Bayesian networks. Available algorithm identifiers are:

---

void SetDefaultIDAlgorithm(int algorithm);

Sets the algorithm used for inference in influence diagrams. Available algorithm identifiers are:

---

int InvalidateAllBeliefs();

Invalidates values in all of network’s nodes. Returns DSL_OKAY on success, or a negative error code on failure.

---

bool CalcProbEvidence(double &pe, bool forceChainRule = false);

Calculates the probability of evidence currently set in the network and stores the result in the pe argument. By default this method runs a modified clustering algorithm to efficiently obtain the P(e). Set forceChainRule to true to enforce the slower chain rule algorithm. Returns true on success, false on error.

---

int CalcConfidenceIntervals(const std::vector<int> &nodeHandles, 

 const DSL_instanceCounts &counts, double percentage, int iterations,

 std::vector<std::vector<std::pair<double, double> > > &intervals);

Calculates the confidence intervals for nodes specified by nodeHandles. The algorithm performs a specified number of iterations. In each iteration, the CPTs in the network are modified using the Dirichlet distribution parametrized by original CPT values and instance counts specified by the counts parameter. After CPTs have been modified, the inference is performed and posterior probabilities for the specified nodes are collected. When the loop is finished, the percentage of posteriors for each node is used to get the lower and upper bound. The bounds are returned in the intervals output parameter. Each node in nodeHandles has its corresponding entry in intervals - it is a vector with the size equal to node's outcome count. For each outcome count, there is a std::pair with lower and upper bound.

See DSL_instanceCounts reference for information on instance counts. Instance counts (especially derived from the data) may be precalculated if intervals will be required for different sets of evidence.

The algorithm uses network's DSL_randGen pseudo random generator for sampling. For repeatable results, use DSL_network::GetRandGen and DSL_randGen::Init to seed the generator.

Returns DSL_OKAY on success, or a negative error code on failure. Original CPTs are preserved, regardless of the exit status.

---

int GetRandSeed() const;

void SetRandSeed(int seed);

Gets/sets the seed for random generator used by sampling algorithms applied to the network, including discretization. The default is zero, which causes the generator to be initialized with system time.

---

int GetNumberOfSamples() const;

int SetNumberOfSamples(int numSamples);

Gets/sets the number of samples generated by sampling inference algorithms.

---

bool IsNoisyDecompEnabled() const;

void EnableNoisyDecomp(bool enable);

Gets/sets the flag enabling noisyMAX decomposition.

---

int GetNoisyDecompLimit() const;

void SetNoisyDecompLimit(int limit);

Gets/sets the limit on the number of noisyMAX parent nodes as the result of noisyMAX decomposition runs. The number of parents applies to temporary data structures managed by the inference algorithm and does not modify the DSL_network or its nodes.

---

bool IsRejectOutlierSamplesEnabled() const

int EnableRejectOutlierSamples(bool enable);

Gets/sets the flag controlling the sample rejection during stochastic inference in continuous and hybrid models.

---

void GetExtFunctions(std::vector<std::string> &functions, 

 bool includeDistributions = true) const;

Returns the extended functions defined for the network. By default, functions that use (explicitly and implicitly) random number generators are returned. Pass includeDistributions parameter set to false to retrieve only deterministic functions.

---

int SetExtFunctions(const std::vector<std::string> &functions, 

 int &errFxnIdx, int &errPos, std::string &errMsg);

Sets the extended functions. On success, returns DSL_OKAY. On failure, the error code is returned and errFxnIdx contains the index of invalid function definition, errPos contains the position of the error within the definition and errMsg is the error message. See the custom functions reference section for details.

---

int GetNumberOfDiscretizationSamples() const;

void SetNumberOfDiscretizationSamples(int numSamples);

Gets/sets the number of samples to be generated for each CPT column during the discretization of continuous nodes.

---

bool IsZeroAvoidanceEnabled() const;

void EnableZeroAvoidance(bool enable);

Gets/sets the flag controlling the discretization of non-deterministic continuous nodes. If set, the node discretization algorithm adds one artificial sample to each empty discretization bin. This only applies to nodes with equations explicitly including probability distribution functions.

---

int ClearAllEvidence();

Clears all evidence in the network.

---

int GetAllEvidenceNodes(DSL_intArray &evHandles);

Returns the handles of all evidence nodes in evHandles.

---

DSL_node* GetNode(int handle);

DSL_node* GetNode(const char *nodeId);
const DSL_node* GetNode(int handle) const;

const DSL_node* GetNode(const char *nodeId) const;

Returns a pointer to the node identifier by handle or nodeId, NULL otherwise.

---

int FindNode(const char *nodeId) const;

Returns a handle for the node with identifier equal to nodeId, negative with error code otherwise.

---

int GetFirstNode() const;

Returns a handle for the first node in the network, DSL_OUT_OF_RANGE if network has no nodes.

---

int GetNextNode(int handle) const;

Returns node handle following the specified handle. If the specified handle represented the last node in the network, returns DSL_OUT_OF_RANGE.

---

int GetLastNode() const;

Returns the last node handle. If the network is empty, returns DSL_OUT_OF_RANGE.

---

int GetNumberOfNodes() const;

Returns the number of nodes in the network.

---

int GetAllNodes(DSL_intArray &handles) const;
int GetAllNodeIds(DSL_idArray &ids) const;

Return all node handles/ids in their output parameters.

---

const DSL_intArray& PartialOrdering() const;

Returns reference to an array containing all node handles in partial order (the ancestor handles always precede their descendant handles). Performs actual ordering only if it could change since last PartialOrdering call.

---

int AddNode(int nodeType, const char *nodeId);

Creates a new node and returns its handle. If nodeId is NULL, the unique identifier will be created by the network. Supported node types are listed in the Node types section.

Returns DSL_OKAY on success, or a negative error code on failure.

---

int DeleteNode(int handle);

Deletes the node specified by handle. Returns DSL_OKAY on success, or a negative error code on failure.

---

int DeleteAllNodes();

Deletes all nodes in the network.

---

int AddArc(int parentHandle, int childHandle,

 dsl_arcType layer = dsl_normalArc);

Adds an arc between nodes specified by parentHandle and childHandle. By default, the arcs are created on the 'normal' arc layer, which represents the conditional probabilities (layer is set to dsl_normalArc). Additionally, the network can include conditional observation cost, which influences the output from diagnostic algorithms. To create the observation cost arc, set layer to dsl_costObserve.

Returns DSL_OKAY on success, or a negative error code on failure. If adding an arc would result in cycle in the network, the status code is DSL_CYCLE_DETECTED.

---

int RemoveArc(int parentHandle, int childHandle,

 dsl_arcType layer = dsl_normalArc);

Removes an arc. The default arc layer is dsl_normalArc. To remove conditional observation cost arc, use dsl_costObserve as the layer parameter. Returns DSL_OKAY on success, or a negative error code on failure.

---

const DSL_intArray& GetParents(int nodeHandle) const;

Returns reference to the DSL_intArray containing handles of parent nodes of a node specified by nodeHandle. If nodeHandle is invalid, the return value is undefined.

---

const DSL_intArray& GetChildren(int nodeHandle) const;

Returns a reference to the DSL_intArray containing handles of child nodes of a node specified by nodeHandle. If nodeHandle is invalid, the return value is undefined.

---

int GetDescendants(int nodeHandle, DSL_intArray &descendants); 

Copies all handles of node's descendants to the descendants output array.

---

int GetAncestors(int nodeHandle, DSL_intArray &ancestors); 

Copies all handles of node's ancestors to the ancestors output array.

---

const DSL_intArray& GetCostParents(int nodeHandle) const;

Returns a reference to a DSL_intArray containing handles of cost parent nodes of a node specifed by nodeHandle. If nodeHandle is invalid, the return value is undefined.

---

const DSL_intArray& GetCostChildren(int nodeHandle) const;

Returns a reference to a DSL_intArray containing handles of cost children nodes of a node specifed by nodeHandle. If nodeHandle is invalid the return value is undefined.

---

int ReverseArc(int parentHandle, int childHandle);

Reverses an arc, preserving the joint probability distribution in the network. Returns DSL_OKAY on success, or a negative error code on failure.

---

int IsArcNecessary(int parentHandle, int childHandle,

    double epsilon, bool &necessary) const;

Checks if the arc between parentHandle and childHandle is necessary. The arc is considered to be necessary when child’s conditional probability distributions for different parent states are different. The check is performed using Hellinger’s distance with specified epsilon. The output of the check is returned in the necessary parameter. Returns DSL_OKAY on success, or a negative error code on failure.

---

int RemoveAllArcs();

Removes all arcs in the network.

---

int MarginalizeNode(int nodeHandle, DSL_progress *progress = NULL);

Removes the node specified by nodeHandle, but preserves the joint probability distribution over the remaining nodes. The marginalization may take a significant amount of time, therefore the caller may specify an instance of object derived from the DSL_progress class to monitor the progress and optionally cancel the operation. Returns DSL_OKAY on success, or a negative error code on failure. If canceled, the function returns the DSL_INTERRUPTED error code.

---

int MakeUniform(const std::vector<int> *nodeFilter=NULL);

Uniformizes the parameters for all nodes in the network, or, if nodeFilter vector is specified, only nodes with handles in the vector.

---

int MakeRandom(DSL_randGen *extRandGen=NULL, 

    const std::vector<int> *nodeFilter=NULL););

Randomizes the parameters of all node definitions in the network, or, if nodeFilter vector is specified, only nodes with handles in the vector. Uses extRandGen if specified, or network's internal random generator.

---

int GetNumberOfTargets() const;

Returns the number of target nodes in the network.

---

int IsTarget(int nodeHandle);

For a valid node handle, returns nonzero if the node was set as target, zero otherwise. If the handle is invalid, returns a negative status code.

---

int SetTarget(int nodeHandle, bool target);

Sets the target flag on node specified by nodeHandle. Returns DSL_OKAY if nodeHandle is valid and the flag has actually changed. Returns DSL_INVALID_VALUE if nodeHandle was valid, but the value of target is the same as the value of the current target flag of the node (i.e., when trying to set the target flag of a node that is already a target or when trying to clear the target flag of a node that is not a target).

---

int ClearAllTargets();

Resets the target flags on all nodes. With no explicit target nodes all nodes in the network are updated.

---

DSL_case* AddCase(const std::string & name);

Adds new case with a specified name. Returns the pointer to the newly created case.

---

DSL_case* GetCase(int index) const;

Returns the pointer to the case specified by the zero-based case index. If the index is negative or greater or equal to the number of cases, returns NULL.

---

DSL_case* GetCase(const std::string & name) const;

Returns a pointer to the case specified by name. If the case is not found, returns NULL.

---

int DeleteCase(int index);

Deletes the case specified by the index. Returns DSL_OKAY on success, or a negative error code on failure.

---

void DeleteAllCases();

Removes all cases from the network.

---

int GetNumberOfCases() const;

Returns the number of cases defined for the network

---

void EnableSyncCases(bool sync);

Enables or disables case synchronization. If enabled, structural changes in node definitions, like creation or removal of node outcomes, will be reflected in the data stored in cases. The case synchronization mode is enabled by default.

---

bool IsEnableSyncCases() const;

Returns true if case synchronization is enabled, false otherwise.

---

int UnrollNetwork(DSL_network &unrolled, std::vector<int> &unrollMap) const;

Creates unrolled network from a DBN. The unrollMap output parameter contains a mapping from unrolled network to the original DBN. Node with the handle h in the unrolled network represents the original node with handle unrollMap[h]. Returns DSL_OKAY on success, or a negative error code on failure.

---

int GetMaxTemporalOrder() const;

int GetMaxTemporalOrder(int nodeHandle) const;

Returns the maximum order of temporal arcs in the entire network or for a specific node.

---

int GetTemporalOrders(int nodeHandle, DSL_intArray &orders) const;

Gets all temporal orders for the specified node.

---

int GetNumberOfSlices() const;

int SetNumberOfSlices(int slices);

Gets/sets the number of slices in the unrolled DBN.

---

int AddTemporalArc(int parent, int child, int order);

Adds a temporal arc of a specified order between nodes specified by the parent and child handles. Returns DSL_OKAY on success, or a negative error code on failure.

---

int RemoveTemporalArc(int parent, int child, int order);

Removes a temporal arc of a specified order between nodes specified by the parent and child handles. Returns DSL_OKAY on success, or a negative error code on failure.

---

bool TemporalArcExists(int parent, int child, int order) const;

Returns true if a temporal arc of a specified order exists between the nodes specified by the parent and child handles.

---

int IsTemporalArcNecessary(int parent, int child, 

    int order, double epsilon, bool &necessary) const;

Checks if the temporal arc with a specified order between the nodes specified by the parent and child handles is necessary. The arc is considered necessary when child’s conditional distributions for different parent states are different. The check is performed using Hellinger’s distance with a specified epsilon. The output of the check is returned in the necessary parameter. Returns DSL_OKAY on success, or a negative error code on failure.

---

dsl_temporalType GetTemporalType(int nodeHandle) const;

Gets the temporal type of node. The temporal type is defined by the following enumeration:

enum dsl_temporalType { dsl_normalNode, dsl_anchorNode, dsl_terminalNode, dsl_plateNode };

---

int SetTemporalType(int nodeHandle, dsl_temporalType type);

Sets the temporal type of node. Returns DSL_OKAY on success, or a negative error code on failure.

The following temporal type transitions are forbidden and result in an error:

1.From dsl_plateNode to another type when the node has incoming or outgoing temporal arcs.

2.To dsl_plateNode when the node has dsl_terminalNode parents, or dsl_anchorNode children.

3.To dsl_anchorNode when the node has dsl_plateNode or dsl_terminalNode parents.

4.To dsl_terminalNode when the node has dsl_plateNode, dsl_normalNode or dsl_anchorNode children.

5.To dsl_normalNode when the node has dsl_plateNode or dsl_terminalNode parents.

---

int GetTemporalChildren(int parent, 

    std::vector<std::pair<int, int> > &children) const;

Retrieves information about the temporal children of a specified parent node. Each temporal arc originating in the parent has one corresponding element in the output vector. The element is the std::pair<int,int>, where first element is a child node handle, and second element is a temporal order. Returns DSL_OKAY on success, or a negative error code on failure.

---

int GetTemporalParents(int child, int order, DSL_intArray &parents) const;

Retrieves the handles of temporal parents of the specified temporal order. Note that parents with order x are in general only the subset of nodes which index temporal definition of order x. Use GetUnrolledParents to get all parents indexing the temporal definition. Returns DSL_OKAY on success, or a negative error code on failure.

---

int GetUnrolledParents(int child, int order, 

    std::vector<std::pair<int, int> > &parents) const;

Retrieves the handles and orders of temporal parents indexing the temporal definition of a specified order. Returns DSL_OKAY on success, or a negative error code on failure.

---

int GetUnrolledParents(int child, 

    std::vector<std::pair<int, int> > &parents) const;

Retrieves the handles and orders of temporal parents. Returns DSL_OKAY on success, or a negative error code on failure.