Fixing stat collection
[charm.git] / examples / charm++ / state_space_searchengine / README
1 Steps to use the search engine:
2
3 (1) build state space searchengine in charm++ libs
4   (1) cd charm/<build dir>/tmp/libs/ck-libs/state_space_searchengine
5   (2) type 'make OPTS=-O3'
6
7       If you are using priority, add -DUSEBITPRIORITY to OPTS,
8       and type 'make OPTS="-O3 -DUSEBITPRIORITY"'
9
10     this will build two search engine libraries: libmodulesearchEngine.a and libmodulesearchEngine_bound.a (for branch-and-bound).
11
12 (2) Go to your own application directory. For example, 
13    type 'cd NQueens'
14
15    and then type 'make OPTS=-O3'.  Make sure to use the same macro as in step (1)/(2) above.
16
17
18 *Files to be changed. 
19
20    All files in template/ are not supposed to be changed.
21    
22    You can modify main.C main.ci as you need.
23    The main changes are in searchEngineAPI.C
24
25    *****************************************************
26   *The following functions must be implemented:
27
28   (1) SE_Register(QueenStateBase, createInitialChildren, createChildren, parallelLevel, searchDepthLimit);
29    
30    This line is important, put it in the end of the file
31    The first parameter is your own state class name, the four others are function names that must be implemented)
32
33   (2) void createInitialChildren(Solver *solver) 
34     create the root node of search tree. 
35   (3) inline void createChildren( StateBase *_base , Solver* solver, bool parallel);
36   Expand children from the _base state.
37   
38   (4) int parallelLevel(); 
39   // static parallel search depth
40
41    (5) int searchDepthLimit();
42    // If it is a IDA* problem, define the depth. Othersize, set it to 1;In Hamiltonian problem, just return 1;
43     
44    *******************************************
45    *Interface search engine provides:
46
47     (1.1) StateBase* Solver::registerRootState(int sizeofstate, int childIndex, int totalChildren )
48     (1.2) StateBase* Solver::registerState(int sizeofstate, int childIndex, int totalChildren )
49
50     Use this function to allocate memory for a newly generated child (or root). Note: If in your state class, there is array data structure, you are responsible to set the pointer correctly.
51
52     (2)solver->deleteState(child); solver->reportSolution();
53      If the node is a solution, free the memory of child and report this solution.
54
55     (3) solver->process(child);
56         If the node is not a solution and also the depth is less than the parallel search depth threshold, call this function.
57
58     (4) solver->deleteState(child);
59     If it is a leaf node but not a solution, free the memory if you have used registerState() to allocate it.
60
61
62
63     Notes:
64
65   (1)  In this search engine, for the sequential part you can let the search engine do it or you can implement your own.
66
67     If you are letting the search engine do it, all you have to do is to implement the above functions. 
68
69     If you are implementing your own sequential part, in the createChildren(...) function, you can write code like this:
70
71     if(!parallel)
72     {
73         myown_sequential(....)
74         // in this function, you need to pass 'solver' as a parameter to report the solution.
75     }
76
77 (2)  About allocating memory for children and setting the correct pointer. 
78
79     Here is an example.
80
81     class mystate: public StateBase{
82
83         int  intarray_length;
84         int  doublearray_length;
85         int  *my_intarray;
86         double *my_doublearray;
87
88         void setPointer()
89         {
90             int offset = sizeof(mystate);
91             my_intarray = (int*)((char*)this + offset);
92             offset += intarray_length*sizeof(int);
93             my_doublearray = (double*)((char*)this + offset);
94
95         }
96     }
97
98    ...
99    
100   mystate *child = (mystate*) solver-> registerRootState(...);
101   child->setPointer();
102