Commit f9a75482 authored by Florian Wittkamp's avatar Florian Wittkamp
Browse files

Added contribution guide and adjusted some README

parent e728f227
# Contributing Guidelines
**All contributions to this project are warmly welcome!**
In the following some guidelines are given which ensure a smooth and hassle-free cooperation.
## Write and adjust the source code
The source code itself is written in object-oriented C++11. This means, all features of the C++11 standard can be used and the used compilers have to be compatible to the C++11 standard. However, to increase compatibility, features of newer standards, such as C++14 or C++17, should not be used.
To ensure that the code will stay easy to maintain and extend, all developers are requested to stick to the five **SOLID principles**. More information on this principles can be found eg. on [Wikipedia](https://en.wikipedia.org/wiki/SOLID_(object-oriented_design).
#### Code formatting
For consistent source code formatting a clang-format style file is provided.
Please config your integrated development environment (IDE) to format source code according to the style file given by the `.clang-format` file located within the `src/` folder.
All major IDEs (e.g. Kdevelop, XCode, emacs, vim) support this file type.
You may be required to install the clang-format tool on your machine.
Since clang-format is part of llvm project, more information are given on [llvm.org](llvm.org) or [https://clang.llvm.org/docs/ClangFormat.html](https://clang.llvm.org/docs/ClangFormat.html).
#### Code documentation
The `doxygen` tool is used for automatic generation of source code documentation.
Thus, it is required that the whole code is annotated in `doxygen` syntax.
A detailed and complete source code documentation is of particular importance for new developers, since it allows to access and understand the interfaces and classes quickly.
More information on the `doxygen` syntax can be found on [www.doxygen.org](www.doxygen.org).
#### Code testing
Before you commit your changes make sure all tests pass without errors.
Two kinds of tests are provided:
1. Unit tests (based on the [Google Test framework](https://github.com/google/googletest))
2. Full integration tests
The unit tests will verify the functionality of individual functions and classes, while the integration tests will run the whole forward code and verify that the obtained result is identical to a reference solution.
......@@ -10,9 +10,12 @@ Get started:
Documentation:
- Type `make` in `doc/`
Contributing:
- See the contributing guidelines provided in `CONTRIBUTING.md`
Requirement:
- Framework [LAMA](https://www.libama.org) (Development-Version)
- Compiler with C++11 support recommended
- Framework [LAMA](https://www.libama.org)
- Compiler with C++11 support
Tested with:
- Compiler: g++ (4.9.3), clang++ (3.9)
......
## Preparatory steps
To start the modelling code, you have to set the paths to the LAMA framework:
- `export SCAI_ROOT=[PATH_TO_LAMA_BUILD]`
- `export DYLD_LIBRARY_PATH=${SCAI_ROOT}/lib:${DYLD_LIBRARY_PATH}`
- `export LD_LIBRARY_PATH=${SCAI_ROOT}/lib:${LD_LIBRARY_PATH}`
## Using OpenMP
- Set `export OMP_NUM_THREADS=1`
## Start the simulation
The simulation can be started by the example start file:
## Using OpenMPI/IntelMPI
- Modify `start_FDSimulation.sh` to e.g. `mpirun -np 4 ./../SOFI3Dacoustic`
``source start_FDSimulation.sh``
## Data pre-processing
- to partition a single vector-file `~/WAVE/scai_lama/build/lama/examples/io/vectorRepartition.exe filename.mtx 1 filename_%r.mtx {NProcessors}`
Different kinds of parallelization are possible:
## Start the simulation
- `source start_FDSimulation.sh`
- Using OpenMP:
- Set `export OMP_NUM_THREADS=1`
- Using OpenMPI/IntelMPI:
- Modify `start_FDSimulation.sh` to e.g. `mpirun -np 4 ./../SOFI3Dacoustic`
## Data processing
Since the modelling code supports parallel I/O operations some pre- and post-processing steps maybe required to split or merge data.
#### Data pre-processing
- to partition a single vector-file `~/WAVE/scai_lama/build/lama/examples/io/vectorRepartition.exe filename.mtx 1 filename_%r.mtx {NProcessors}`
## Data post-processing
#### Data post-processing
- Merge to a single vector-file `~/WAVE/scai_lama/build/lama/examples/io/vectorRepartition.exe filename_%r.mtx {NProcessors} filename.mtx 1`
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment