From 5e0dbe825dab01e470865111516ef765500e403d Mon Sep 17 00:00:00 2001
From: Jan Eitzinger <jan.treibig@gmail.com>
Date: Tue, 7 Feb 2023 14:06:08 +0100
Subject: [PATCH] Update README.md

---
 README.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 67 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a933811..4deb07f 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,69 @@
 # NuSiF-Solver
 
-A fluid simulator toolbox for teaching purposes
\ No newline at end of file
+This is a broad collection of C implementations of Navier-Stokes Fluid simulator as
+described in [this
+book](https://epubs.siam.org/doi/book/10.1137/1.9780898719703) by Michael
+Griebel et al.
+
+## Build
+
+Every variant comes with a makefile. First configure the toolchain by editing
+the variabel `TAG` in `config.mk`. For the Intel tool chain set it to `ICC`, for
+LLVM clang using Open MPI set it to `CLANG`. If required adapt the respective
+flags and include and library paths in `include_[CLANG|ICC].mk`.
+
+You can uncomment the `-DVERBOSE` line for additional dignostic output.
+
+Build the code with:
+```
+$ make
+```
+
+Clean intermediate build products with:
+```
+$ make clean
+```
+
+Clean all build products with:
+```
+$ make distclean
+```
+
+The makefile provides the additional build targets:
+* `$ make info`: Output CFLAGS and the compiler version for documentation
+purposes.
+* `$ make tags`: Run `ctags -R`.
+* `$ make format`: Run `clang-format` on all source files.
+
+## Run
+
+All examples come with two test cases:
+* dcavity: Lid driven cavity.
+* canal: Channel flow with inflow on one side.
+
+To start a simulation for sequential implementations execute (here for CLANG toolchain):
+```
+$ ./exe-CLANG dcavity.par|canal.par
+```
+
+To start a simulation for parallel implementations execute (here for CLANG toolchain):
+```
+$ mpirun -np <NUMPROC> ./exe-CLANG dcavity.par|canal.par
+```
+
+## Configuration options 
+
+Important option in the test case parameter files:
+* `re`: Desired reynolds number. Higher for a less viscous fluid and lower for a
+more viscous fluid.
+* `imax`, `jmax`, `kmax`: The resolution of the grid. Increase resolution for
+higher Reynolds numbers.
+* `te`: The final simulation time.
+* `itermax`: The number of maximum iterations performed in every Poisson
+pressure equation step.
+* `eps`: Stopping tolerance for the pressure equation solver.
+* `omg`: Relaxation parameter for SOR solver. Default is 1.7 to 1.9. For MPI
+parallel runs omega needs to be reduced to 1.3 to guarantee convergence.
+
+The other parameter should not be changed.
+