Examples

The actual simulation programs or scenarios that make use of opendihu as software framework are called examples. They are stored in the examples folder, organized in subdirectories.

Directory structure

An example consists of the following files, as illustrated using the electrophysiology/cellml example.

$ tree -L 2 cellml/
cellml/
├── build_debug
│   └── cellml
├── build_release
│   └── cellml
├── SConscript
├── SConstruct
├── settings.py
└── src
    └── cellml.cpp

The following explanation starts from the bottom.

The src subdirectory contains the source file of the example. This is the short C++ file, that instantiates the solver and runs the simulation. In this case, src/cellml.cpp is only 22 lines, other examples are slightly longer.
settings.py is a python script that specifies the settings to the simulation. The script will be parsed by the simulation program, the settings have to be present in the config variable, a Python dict.
SConstruct is the file that tells scons how to build everything, similar to a Makefile for make. Every example has a copy of this file. Note the line
```
# get the directory where opendihu is installed (the top level directory of opendihu)
opendihu_home = os.environ.get('OPENDIHU_HOME') or "../../.."
```
This determines the home directory of the opendihu installation. It tries to read the path from the environment variable OPENDIHU_HOME. If this fails, because the variable is not set, it uses the relative path ../../... This has the following consequences. First, if you want to have your own examples stored somewhere else and their SConstruct file looks the same, because you copied it from an other example, you should set the environment variable OPENDIHU_HOME such that the base directory of opendihu can be found. But a line similar to the following to your ~/.bashrc.
```
export OPENDIHU_HOME=/your-absolute-path-to/opendihu
```
Second, if you create a new example under the examples folder, make sure that the relative path match the depth of the example directory, e.g. ../../.. or ../...
The SConscript file contains the executable names and the corresponding source files. You can define multiple executables. The following is a schematic example for two executables with names executable-name and other-executable and different source files:
```
env.Program(target = "executable-name", source = ["src/source.cpp"])
env.Program(target = "other-executable", source = ["src/other_source.cpp"])
```
The folders build_debug and build_release will contain the compiled executable. They can be deleted, because after compilation they will be created again.

To compile an example, change into its base directory (where SConstruct is located) and execute

sd

to build the debug target or

sr

to build the release target. This will create the build_debug or build_release subdirectories if they didn’t exist yet. (Note, you need the aliases sd and sr as described in Define aliases and environment variables).

Create your own example

Copy any existing example and delete everything except SConscript, SConstruct, settings.py and the src folder. Adjust these files depending on your need. Notice the comments above concerning finding of the opendihu home directory.

Input files

Sometimes, additional input files are required. If they are big, they are not included in the git repository, but hosted somewhere else. This is the case for all electrophysiology examples. These have an opendihu/examples/electrophysiology/input directory with binary data. There is a readme file that contains a link where to download these files.

For a description of existing example, see Existing examples.