README.md 5.29 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
23
24
25
26
27
28
 - 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
29
git submodule update --init --recursive
30
31
```

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


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

---

55
56
## Run
### Local
jannick.wolters's avatar
jannick.wolters committed
57
Execute the compiled binary from the `bin` folder and hand over a valid *TOML*-styled config file.
58
Example from inside the `code` directory:
59
60

```bash
jannick.wolters's avatar
jannick.wolters committed
61
./KiT-RT ../input/example.cfg
62
63
64
65
66
```

In order to run the code in parallel execute:

```bash
jannick.wolters's avatar
jannick.wolters committed
67
OMP_NUM_THREADS=N mpirun -np J ./KiT-RT ../input/example.cfg
68
69
70
71
72
```

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

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

111
112
113
---

## Tests
114
After compiling the framework as described above just run:
115
116

```bash
117
make test
118
119
```

120
The `unit_tests` executable will also be placed in in the build folder.
121
122

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

---

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

159
160
---

161
162
163
164
165
166
167
168
## 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
169
Some editors offer to automatically apply the style format upon saving a file (e.g. `Qtcreator`).