aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorAdrian Kummerlaender2019-10-27 20:11:36 +0100
committerAdrian Kummerlaender2019-10-27 20:11:36 +0100
commit89f60f39a226bef5ccd8c52dbd57891c3a4d74c7 (patch)
tree2412dccf574cc967031ecbc66c48d5250641da36 /README.md
parenta99edaaa0e9a95354f68614cd2f4ab801179b946 (diff)
downloadboltzgen-89f60f39a226bef5ccd8c52dbd57891c3a4d74c7.tar
boltzgen-89f60f39a226bef5ccd8c52dbd57891c3a4d74c7.tar.gz
boltzgen-89f60f39a226bef5ccd8c52dbd57891c3a4d74c7.tar.bz2
boltzgen-89f60f39a226bef5ccd8c52dbd57891c3a4d74c7.tar.lz
boltzgen-89f60f39a226bef5ccd8c52dbd57891c3a4d74c7.tar.xz
boltzgen-89f60f39a226bef5ccd8c52dbd57891c3a4d74c7.tar.zst
boltzgen-89f60f39a226bef5ccd8c52dbd57891c3a4d74c7.zip
Add README
Diffstat (limited to 'README.md')
-rw-r--r--README.md71
1 files changed, 71 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..679cf90
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# boltzgen
+
+…a framework for symbolically generating optimized implementations of the Lattice Boltzmann Method.
+
+At the moment this is a more structured and cleaned up version of the OpenCL kernel generator employed by [symlbm_playground](https://tree.kummerlaender.eu/projects/symlbm_playground/). The goal is to build upon this foundation to provide an easy way to generate efficient code using a high level description of various collision models and boundary conditions. This should allow for easy comparision between various streaming patterns and memory layouts.
+
+## Features
+
+* BGK collision step
+* D2Q9, D3Q7, D3Q19 and D3Q27 lattices with automatic weight inference
+* momenta and bounce back boundary conditions
+* equilibrilization and moment collection utility functions
+* optimization via common subexpression elimination
+* array-of-structures and structure-of-arrays memory layouts
+* AB streaming pattern
+* C++ and OpenCL targets
+* simple CLI frontend
+
+## Usage
+
+The development and execution environment is described using a Nix expression in `shell.nix`.
+
+```
+> nix-shell
+> ./boltzgen.py --help
+usage: boltzgen.py [-h] --lattice LATTICE --layout LAYOUT --precision
+ PRECISION --geometry GEOMETRY --tau TAU [--disable-cse]
+ [--functions FUNCTIONS [FUNCTIONS ...]]
+ [--extras EXTRAS [EXTRAS ...]]
+ language
+
+Generate LBM kernels in various languages using a symbolic description.
+
+positional arguments:
+ language Target language (currently either "cl" or "cpp")
+
+optional arguments:
+ -h, --help show this help message and exit
+ --lattice LATTICE Lattice type (D2Q9, D3Q7, D3Q19, D3Q27)
+ --layout LAYOUT Memory layout ("AOS" or "SOA")
+ --precision PRECISION
+ Floating precision ("single" or "double")
+ --geometry GEOMETRY Size of the block geometry ("x:y(:z)")
+ --tau TAU BGK relaxation time
+ --disable-cse Disable common subexpression elimination
+ --functions FUNCTIONS [FUNCTIONS ...]
+ Function templates to be generated
+ --extras EXTRAS [EXTRAS ...]
+ Additional generator parameters
+
+> ./boltzgen.py cpp --lattice D2Q9
+\ --geometry 128:128
+\ --layout AOS
+\ --precision double
+\ --tau 0.52
+\ --functions default bounce_back_boundary example
+\ --extras omp_parallel_for moments_vtk | tee kernel.h
+void collide_and_stream( double* f_next,
+ const double* f_prev,
+ std::size_t gid)
+{
+ double* preshifted_f_next = f_next + gid*9;
+ const double* preshifted_f_prev = f_prev + gid*9;
+
+ const double f_curr_0 = preshifted_f_prev[1161];
+ const double f_curr_1 = preshifted_f_prev[1153];
+ const double f_curr_2 = preshifted_f_prev[1145];
+ const double f_curr_3 = preshifted_f_prev[12];
+ const double f_curr_4 = preshifted_f_prev[4];
+[...]
+```