MDDManager (MDD manipulation toolkit 0.4.1 API)

All Known Subinterfaces:

MDDStore

All Known Implementing Classes:

MDDManagerProxy, MDDStoreImpl
```
public interface MDDManager
```
A MDD manager is responsible for the creation, storage, retrieval, combination and cleanup of a collection of multi-valued decision diagrams (MDDs).

The manager has:
- a set of leaves, defined from start and that can not be changed,
- a list of variables. New ones can be added afterwards, and the names can be changed but changing max values resets the manager
A number of leaves are defined when creating the manager. They are numbered [0...nbleaves[. Negative leaves or holes in the values are not allowed, but you are free to map indices to the values of your choice (including inside custom operators).
The same leaf can thus refer to different values, depending on the context.
Nodes can be created using the get_bnode and get_mnode methods (for Boolean and multi-valued nodes respectively), which create them if needed and return the bloc ID.
Nodes can also be created by combining existing nodes, using the merge method. This method uses MDDOperations to decide how to do the merging. MDDOperation for the common operations are provided (see MDDOperation.ACTION_*), but it was designed to help creating custom ones. A group-merging method allows to efficiently merge many nodes using the same operation.
Nodes also have reference counter, which allows to reuse the space when nodes are no longer used. For this, call the free method with a node ID when you stop using it. Make sure to forget the ID as any further use would result in unexpected results.
Author:

Aurelien Naldi

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean[]`	`collectDecisionVariables(int node)` Collect variables on which a MDD depends.
`String`	`dumpMDD(int node)` Write a raw text representation of the MDD
`MDDVariable`	`ensureVariable(Object key, byte nbval)` get a variable, create it if needed.
`void`	`free(int pos)` Free a node.
`MDDVariable[]`	`getAllVariables()` Get all MDDVariables in this manager.
`int`	`getChild(int node, int value)` Get a specific child for a node.
`int[]`	`getChildren(int node)` Get all the children of a given node.
`int`	`getLeafCount()` Get the number of leaves
`MDDManager`	`getManager(List<?> order)` Get a new manager for this MDD Store, using a custom variable order.
`VariableEffect[]`	`getMultivaluedVariableEffect(MDDVariable var, int node)` Determine the effect of a given variable on a MDD.
`int`	`getNodeCount()`
`MDDVariable`	`getNodeVariable(int n)` Get the variable associated to a given node.
`NodeRelation`	`getRelation(int first, int other)` Determine the relation between two nodes.
`int`	`getSign(int node, MDDVariable pivot)` Infer the effect of a variable in a given MDD.
`VariableEffect`	`getVariableEffect(MDDVariable var, int node)` Determine the effect of a given variable on a MDD.
`MDDVariable`	`getVariableForKey(Object key)` Get the MDDVariable associated to a given key.
`int`	`getVariableIndex(MDDVariable var)` Get the position of a given variable in this manager's list of variables.
`byte`	`groupReach(int node, byte[] path)` Get the value reached by a group of paths.
`boolean`	`isleaf(int node)`
`boolean`	`isView(MDDManager ddm)`
`int`	`mnot(int node, int v)` Multi-valued not: flip leaves 0 and v.
`int`	`nodeFromState(byte[] state, int value)` Create a MDD representing a state.
`int`	`nodeFromStates(Collection<byte[]> states, int value)` Create a MDD representing a group of states.
`int`	`not(int node)` Logical not, performed by flipping leaves 0 and 1.
`int`	`parseDump(String s)` Create a MDD from a dumped structure
`byte`	`reach(int node, byte[] values)` Find the leaf reached for a given variable assignment
`int`	`use(int node)` Mark a node as used.

- Method Detail
  - getManager
```
MDDManager getManager(List<?> order)
```
    Get a new manager for this MDD Store, using a custom variable order. The new manager will use the same MDDStore as backend: it is just a different view of the same MDD dataset.
    
    Parameters:
    
    order - requested variable order.
    
    Returns:
    
    a new manager (this if the order is the same)
  - getNodeVariable
```
MDDVariable getNodeVariable(int n)
```
    Get the variable associated to a given node.
    
    Parameters:
    
    n - the node ID
    
    Returns:
    
    the variable of null if the node is a leaf.
  - getVariableForKey
```
MDDVariable getVariableForKey(Object key)
```
    Get the MDDVariable associated to a given key.
    
    Parameters:
    
    key -
    
    Returns:
    
    the associated MDDVariable
  - getVariableIndex
```
int getVariableIndex(MDDVariable var)
```
    Get the position of a given variable in this manager's list of variables.
    
    Parameters:
    
    var -
    
    Returns:
    
    the position in getAllVariables().
  - getAllVariables
```
MDDVariable[] getAllVariables()
```
    Get all MDDVariables in this manager.
    
    Returns:
    
    the ordered list of available MDDVariables.
  - ensureVariable
```
MDDVariable ensureVariable(Object key,
                           byte nbval)
```
    get a variable, create it if needed.
    
    Parameters:
    
    key -
    
    nbval -
    
    Returns:
  - free
```
void free(int pos)
```
    Free a node. If it is not used at all anymore, it will be removed from the data structure.
    This should be used for each node id that was obtained through one of the get_?node() method, or for the one explicitly marked as used.
    Note that the space will be made available for new nodes, but it will NOT be returned to the garbage collector.
    
    Parameters:
    
    pos -
    
    See Also:
    
    use(int), get_bnode(int, int, int), get_mnode(int, int[])
  - use
```
int use(int node)
```
    Mark a node as used. This is done automatically when creating or reusing a node. In most cases, manually calling this should not be necessary. If you do call it, remember to call free(int) when you release it.
    
    Parameters:
    
    node -
    
    Returns:
    
    the ID of the node (yes, the same as the parameter, just as convenience)
  - isleaf
```
boolean isleaf(int node)
```
    Parameters:
    
    node - the ID of the tested node.
    
    Returns:
    
    true if id denotes a leaf in this manager
  - getChild
```
int getChild(int node,
             int value)
```
    Get a specific child for a node. Note: the child is not counted as used, do not free it (or call manager.use() before)
    
    Parameters:
    
    node - id of a node
    
    value - assignment value
    
    Returns:
    
    the id of the child node reached when assigning this value to the variable of the provided node.
  - getChildren
```
int[] getChildren(int node)
```
    Get all the children of a given node. Node: this will create a new array to hold the children. Children are not counted as used, do not free them (or call manager.use() before)
    
    Parameters:
    
    node -
    
    Returns:
    
    an array holding all the children, or null if it is a leaf.
  - not
```
int not(int node)
```
    Logical not, performed by flipping leaves 0 and 1.
    
    Parameters:
    
    node -
    
    Returns:
    
    the ID of the flipped MDD root
  - mnot
```
int mnot(int node,
         int v)
```
    Multi-valued not: flip leaves 0 and v.
    
    Parameters:
    
    node -
    
    v - the positive value
    
    Returns:
  - getRelation
```
NodeRelation getRelation(int first,
                         int other)
```
    Determine the relation between two nodes. Mainly used by operators to select the appropriate code path.
    
    Parameters:
    
    first -
    
    other -
    
    Returns:
    
    an NodeRelation value denoting which node is a leaf or has the highest ranked variable
  - getNodeCount
```
int getNodeCount()
```
    Returns:
    
    the number of non-leaf nodes stored in the manager.
  - getLeafCount
```
int getLeafCount()
```
    Get the number of leaves
    
    Returns:
    
    the number of possible leaves (i.e. max leaf index)
  - getSign
```
int getSign(int node,
            MDDVariable pivot)
```
    Infer the effect of a variable in a given MDD.
    
    Parameters:
    
    node - the MDD
    
    pivot - the variable of interest
    
    Returns:
    
    0 for no effect, 1 for positive effect, -1 for negative effect or 2 for dual effect
  - reach
```
byte reach(int node,
           byte[] values)
```
    Find the leaf reached for a given variable assignment
    
    Parameters:
    
    node -
    
    values -
    
    Returns:
    
    the leaf reached for this assignment
  - groupReach
```
byte groupReach(int node,
                byte[] path)
```
    Get the value reached by a group of paths.
    
    Parameters:
    
    node -
    
    path -
    
    Returns:
    
    the leaf reached for this assignment
  - collectDecisionVariables
```
boolean[] collectDecisionVariables(int node)
```
    Collect variables on which a MDD depends.
    
    Parameters:
    
    node -
    
    Returns:
    
    a boolean array indicating for each variable if it affects the given MDD.
  - getVariableEffect
```
VariableEffect getVariableEffect(MDDVariable var,
                                 int node)
```
    Determine the effect of a given variable on a MDD. To find variables of interest, use collectDecisionVariables(node).
    
    Parameters:
    
    var -
    
    node -
    
    Returns:
    
    the effect of this variable.
  - getMultivaluedVariableEffect
```
VariableEffect[] getMultivaluedVariableEffect(MDDVariable var,
                                              int node)
```
    Determine the effect of a given variable on a MDD. To find variables of interest, use collectDecisionVariables(node).
    
    Parameters:
    
    var -
    
    node -
    
    Returns:
    
    the effects of each level switch for this variable
  - isView
```
boolean isView(MDDManager ddm)
```
  - nodeFromState
```
int nodeFromState(byte[] state,
                  int value)
```
    Create a MDD representing a state.
    
    Parameters:
    
    state -
    
    value -
    
    Returns:
  - nodeFromStates
```
int nodeFromStates(Collection<byte[]> states,
                   int value)
```
    Create a MDD representing a group of states.
    
    Parameters:
    
    states -
    
    value -
    
    Returns:
  - dumpMDD
```
String dumpMDD(int node)
```
    Write a raw text representation of the MDD
    
    Parameters:
    
    node -
    
    Returns:
    
    a string representing the MDD structure
  - parseDump
```
int parseDump(String s)
       throws ParseException
```
    Create a MDD from a dumped structure
    
    Parameters:
    
    s - the string representing the MDD structure
    
    Returns:
    
    the corresponding MDD
    
    Throws:
    
    ParseException

Interface MDDManager

Method Summary

Method Detail

getManager

getNodeVariable

getVariableForKey

getVariableIndex

getAllVariables

ensureVariable

free

use

isleaf

getChild

getChildren

not

mnot

getRelation

getNodeCount

getLeafCount

getSign

reach

groupReach

collectDecisionVariables

getVariableEffect

getMultivaluedVariableEffect

isView

nodeFromState

nodeFromStates

dumpMDD

parseDump