1490-Distributed-Octree-Mesh-Example.md

+# Dynamic Distributed Octree Mesh Example
+
+The code for this example is located in `examples/Octree`
+
+## Brief
+
+This example creates distributed octree mesh with dynamical modification.
+
+## Description
+
+Example contains the grid, which can refine and coarse by some user defined rule.
+This example may run in both serial and parallel modes with `NP` processes. For parallel run the dynamic load balancing is used.
+
+The main feature of this example is user-defined function, which determines how grid should split and unite.
+In this example, grid refines around mouse cursor. 
+User should define the function
+```
+int cell_should_split(struct grid * g, Cell cell, int level)
+```
+which returns 1 if this cell must split to 8 children cells.
+In addition, user should define the function
+```
+int cell_should_unite(struct grid * g, Cell cell)
+```
+which returns 1 if cell must unite with 7 neighbors.
+
+After that user must create "struct grid thegrid" object and makes next assignments
+```
+thegrid.cell_should_split = cell_should_split;
+thegrid.cell_should_unite = cell_should_unite;
+```
+
+Main function of Octree is `gridAMR`. 
+This function makes all changes with the grid. 
+First it's check all cells to unite, next check to split.
+Example contains the graphic representation of it's workflow. 
+User must install and configure the `OpenGL` library.
+
+## Arguments
+
+Run with no arguments produces a brief help of example arguments and hotkeys available:
+```
+$ ./Octree
+Command arguments:
+   -n=10x10x1 - grid size
+   -r=0.01    - refine radius
+   -l=2       - refine level
+
+Hotkeys:
+   Space - refine grid around mouse cursor
+       f - dump grid to file (see grids folder)
+       x - redistribute grid
+```
+as well as the run of the example with the specified default set of parameters.
+
+## Running example
+
+First go to the Octree folder
+```
+$ cd Examples/Octree
+```
+
+### Single process run:
+
+Example runs with following command:
+```
+$ ./Octree
+```
+In this case example runs on single process and all cells will locate on one process. 
+User can use 'spacebar' key to calls `gridAMR` function, which changes the grid.
+
+### Parallel processes run:
+
+User can use mpi to run distribute version of example:
+```
+$ mpirun -np 3 ./Octree.
+```
+User must activate `USE_MPI` key in `cmake` configuration.
+In this case grid splits to `NP` parts. 
+Each part located on separate process. Graphic representation draws each part with unique color. 
+Before redrawing, example transfers information about grid from all processes (slaves) to one process (master). 
+After that master can redraw the grid.
+User still use 'spacebar' key to calls `gridAMR`.
+
+But in this case user can use 'x' key to make redistribution of grid.
+User can adjust redistribution settings.
+