README.md 5.64 KB
Newer Older
jannick.wolters's avatar
jannick.wolters committed
1
2
[![pipeline status](https://git.scc.kit.edu/rtsn/rtsn/badges/master/pipeline.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master) [![coverage report](https://git.scc.kit.edu/rtsn/rtsn/badges/master/coverage.svg)](https://git.scc.kit.edu/rtsn/rtsn/-/commits/master)

3
# KiT-RT - an HPC Radio Therapy $`S_n`$ framework
4
TBD 
5
## What KiT-RT is capable of
6
7
8
9
### Theory
TBD
### Examples
TBD
jannick.wolters's avatar
jannick.wolters committed
10

11
12
---

13
## Build
14
### Required dependencies
15
 - Compiler with C++17 support
16
 - cmake >= v3.12.4
17
18
19
 - LAPACK
 - OpenMP
 - MPI
20
 - VTK
21
22
 - git
 - ninja or make
23
24
25
26
27
 - gmsh

### Python dependencies
- pygmsh version 6.1.1 'pip install pygmsh==6.1.1' (note that newer versions are not yet supported)

28
29
30
31
32
33

### Obtain submodules
Note that an **active internet connection is required for the first build** in order to download the latest versions of the required submodules!
For the first build only, download all submodules:

```bash
34
git submodule update --init --recursive
35
36
```

37
### Compile the code
38
39
40
41
**Make** build system (available on most systems)
 
```bash 
cd code/build/release
Jannick Wolters's avatar
Jannick Wolters committed
42
cmake -DCMAKE_BUILD_TYPE=Release ../../
43
44
45
46
47
48
49
50
make 
```
If building in parallel is desired, change the last line to `make -jN`, where `N` optimally is equal to the number of available threads+1.

**Ninja** build system:

```bash 
cd code/build/release
Jannick Wolters's avatar
Jannick Wolters committed
51
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ../../
52
53
54
55
56
ninja
```


The resulting executable will automatically be placed in the `code/bin` folder.
57
58
59

---

60
61
## Run
### Local
jannick.wolters's avatar
jannick.wolters committed
62
Execute the compiled binary from the `bin` folder and hand over a valid *TOML*-styled config file.
63
Example from inside the `code` directory:
64
65

```bash
jannick.wolters's avatar
jannick.wolters committed
66
./KiT-RT ../input/example.cfg
67
68
69
70
71
```

In order to run the code in parallel execute:

```bash
jannick.wolters's avatar
jannick.wolters committed
72
OMP_NUM_THREADS=N mpirun -np J ./KiT-RT ../input/example.cfg
73
74
75
76
77
```

with `N` equal to the number of shared memory threads and `J` equal to the number of distrubuted memory threads.

### BwUniCluster
78
79
80
81
82
83
84
85
86
As VTK is not available on the bwUniCluster, it needs to be installed first. This just needs to be done once. Example:
```bash
module load devel/cmake/3.16
module load compiler/gnu/9.2
wget --no-check-certificate --quiet https://www.vtk.org/files/release/8.2/VTK-8.2.0.tar.gz
tar xzf VTK-8.2.0.tar.gz 
mkdir VTK-build
cd VTK-build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_DOCUMENTATION=OFF -DBUILD_TESTING=OFF -DCMAKE_INSTALL_PREFIX=~/VTK-install ../VTK-8.2.0
87
make -j
88
89
90
91
92
93
94
make install
cd -
rm -r VTK-8.2.0 VTK-build
```

Example for build and run on bwUniCluster:
Get the code
Vavrines's avatar
Vavrines committed
95
```bash
96
97
git clone https://git.scc.kit.edu/rtsn/rtsn.git KiT-RT
cd KiT-RT/
Vavrines's avatar
Vavrines committed
98
99
git submodule init
git submodule update
100
101
102
103
104
105
```
Append `HINTS VTK_INSTALL_DIR` to the `find_package( VTK ... )` line in the CMakeLists.txt. E.g.:
```bash
find_package( VTK REQUIRED COMPONENTS vtkIOGeometry vtkFiltersCore HINTS ~/VTK-install )
```

106
Compile it (make sure you use GCC as compiler: module load compiler/gnu/10.2) 
107
```bash
Vavrines's avatar
Vavrines committed
108
109
110
111
112
module load devel/cmake/3.16
module load compiler/gnu/9.2
module load mpi/openmpi/4.0
cd code/build/release/
cmake -DCMAKE_BUILD_TYPE=Release ../../
113
make -j
Vavrines's avatar
Vavrines committed
114
```
115

116
117
118
---

## Tests
119
After compiling the framework as described above just run:
120
121

```bash
122
make test
123
124
```

125
The `unit_tests` executable will also be placed in in the build folder.
126
127

## Continuous Integration (CI)
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
Every commit on the master branch will trigger a build test and unit tests.
If either of the tests fail you will get an email, telling you the 'pipeline' has failed. If this happens, visit the 'CI/CD' tab and check what went wrong and try to fix the error as soon as possible.
Creating a merge request from a branch into the master branch will (not tested yet) also trigger the tests and your merge will be rejected in case any test fails.
As a temporary solution, these tests will currently be done on a low power virtual machine running on a 24/7 online PC at Jannick's place (i.e. don't create computationally expensive tests right now as they will fail if exceeding 1GB of memory).
If you add additional libraries to the code, these also need to be added to the test environment, i.e. the respective docker container.
Little guide:
Test the library installation in the docker container
```bash
docker run -it --rm rtsn/test:latest bash
```
Note the steps required and add them to the `Dockerfile` in the `scripts` folder.
Build the new container (takes some time)
```bash
cd docker build -t rtsn/test:latest .
```
or commit your changes to the image (google that procedure).
Push the new image to `hub.docker.com`
```bash
docker push rtsn/test:latest
```
This last step requires a preceeding `docker login`. Ask Jannick for login credentials.
149
150
151

---

152
## Code structure
153
154
**WARNING: is not created automatically - might be out of date!**
Reverse engineered plantuml diagram of the current code structure: 
155
![Can't load image](doc/KiT-RT.svg "UML diagram")
Jannick Wolters's avatar
Jannick Wolters committed
156
<br/><br/>
157
158
Was created using [hpp2plantuml](https://github.com/thibaultmarin/hpp2plantuml) and [plantuml](https://plantuml.com/), e.g.:
```bash
jannick.wolters's avatar
jannick.wolters committed
159
cd doc 
160
161
hpp2plantuml -i "../code/include/*.h" -i "../code/include/*/*.h" -o KiT-RT.puml
plantuml KiT-RT.puml -tsvg
162
```
163

164
165
---

166
167
168
169
170
171
## Coding style
Please stick to the following coding style for easier code readability:

 - class variables start with an underscore and lowercase letters e.g. `_foo`
 - functions start with a capital letter e.g. `GetSettings()`
 - any variable/function names have capital letters at each individual word e.g. `GetAllCellsAdjacentTo(Cell i)`
172
173
 - Abstract base classes for inheritance structures end with the suffix "Base" e.g. QuadratureBase, whith child classes 
   QGaussLegendre or QProduct
174
175

Please also use the provided `code/.clang-format` style format to format your code before pushing your latest commits.
Jannick Wolters's avatar
Jannick Wolters committed
176
Some editors offer to automatically apply the style format upon saving a file (e.g. `Qtcreator`).