README.md 5.01 KB
Newer Older
1
# KiT-RT - an HPC Radio Therapy $`S_n`$ framework
2
TBD 
3
## What KiT-RT is capable of
4
5
6
7
### Theory
TBD
### Examples
TBD
jannick.wolters's avatar
jannick.wolters committed
8

9
10
---

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

### 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
27
git submodule update --init --recursive
28
29
```

30
### Compile the code
31
32
33
34
**Make** build system (available on most systems)
 
```bash 
cd code/build/release
Jannick Wolters's avatar
Jannick Wolters committed
35
cmake -DCMAKE_BUILD_TYPE=Release ../../
36
37
38
39
40
41
42
43
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
44
cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ../../
45
46
47
48
49
ninja
```


The resulting executable will automatically be placed in the `code/bin` folder.
50
51
52

---

53
54
55
## Run
### Local
Execute the compiled binary and hand over a valid *TOML*-styled config file.
56
Example from inside the `code` directory:
57
58

```bash
59
./bin/KiT-RT input/example.cfg
60
61
62
63
64
```

In order to run the code in parallel execute:

```bash
65
OMP_NUM_THREADS=N mpirun -np J ./bin/KiT-RT input/example.cfg
66
67
68
69
70
```

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

### BwUniCluster
71
72
73
74
75
76
77
78
79
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
80
make -j
81
82
83
84
85
86
87
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
88
```bash
89
90
git clone https://git.scc.kit.edu/rtsn/rtsn.git KiT-RT
cd KiT-RT/
Vavrines's avatar
Vavrines committed
91
92
git submodule init
git submodule update
93
94
95
96
97
98
99
100
```
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 )
```

Compile it
```bash
Vavrines's avatar
Vavrines committed
101
102
103
104
105
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 ../../
106
make -j
Vavrines's avatar
Vavrines committed
107
```
108

109
110
111
---

## Tests
112
After compiling the framework as described above just run:
113
114

```bash
115
make test
116
117
```

118
The `unit_tests` executable will also be placed in in the build folder.
119
120

## Continuous Integration (CI)
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
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.
142
143
144

---

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

157
158
---

159
160
161
162
163
164
165
166
## 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)`

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
167
Some editors offer to automatically apply the style format upon saving a file (e.g. `Qtcreator`).