Philosophy of examples and how to run them

TODO(jure): update with standalone execution.

The idea of our examples is to present the functionality of the library in an accessible and incremental manner. The examples present different solutions to problems ranging in difficulty from the simple Poisson's equation to more specific examples, such as Fluid mechanics. Each examples consists of a name, e.g. poisson_implicit_dirichlet_2D and its corresponding

• source code, e.g. poisson_implicit_dirichlet_2D.cpp
• plot script, e.g. poisson_implicit_dirichlet_2D.m

Additional appropriately named input files might be present for more complicated examples and similarly named output files might be produced. The examples and their plot scripts are intended to work out of the box, so the reader can simply run the examples on their machine. The procedure for running examples is simple and the same for all examples. The accompanying plot scripts can be run with Matlab or octave and they produce the figures the reader sees in the Examples category of this wiki.

Let us now illustrate the process of running an example named example_name.

First the example needs to be built (compiled). The building is done in the build/ directory. When you are in the folder where your example (and a CMakeLists.txt file where it is registered) is located, run

mkdir -p build     # creates the directory build, if it does not exist
cd build           # goes to that directory
cmake ..           # creates Makefiles
make example_name  # builds your example (substitute "example_name" with an actual example name)

to compile your example. Note that you only have to run cmake once, after that only make is sufficient. On first compilation, the whole library will compile as well, so it might take longer than usual. Compiled binary used to run the example is placed next to the source file.

To build all examples, you can just run (after running cmake at least once)

make all

To run the built example, go back to the initial folder where the source code for your example was, and run

./example_name

The output will be saved in the same folder as the binary and the source file.

After, just run the corresponding plot script example_name.m and you should see a figure, usually showing the solution.

Some more feature specific examples are found in the technical documentation and in the unit tests.