feat: Update CMake configuration and add README documentation

CMakeLists.txt

@@ -6,35 +6,18 @@ project(
   VERSION 0.4
   LANGUAGES CXX)
 
-set(CMAKE_CXX_STANDARD 17)
+find_package(Eigen3 3.4 REQUIRED NO_MODULE)
-
-find_package(Eigen3 REQUIRED NO_MODULE)
 find_package(OpenMP)
 
 include(GNUInstallDirs)
 
-# find_package(easy_profiler) option(EASY_OPTION_LOG "Verbose easy_profiler" 1)
-
-# SET(CMAKE_CXX_FLAGS  "${CMAKE_CXX_FLAGS} -O2 -mfma")
 option(TUG_USE_OPENMP "Compile tug with OpenMP support" ON)
 
-set(CMAKE_CXX_FLAGS_GENERICOPT
-    "-O3 -march=native"
-    CACHE STRING "Flags used by the C++ compiler during opt builds." FORCE)
-
-set(CMAKE_BUILD_TYPE
-    "${CMAKE_BUILD_TYPE}"
-    CACHE
-      STRING
-      "Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel GenericOpt."
-      FORCE)
-
 option(
   TUG_USE_UNSAFE_MATH_OPT "Use compiler options to break IEEE compliances by
     oenabling reordering of instructions when adding/multiplying of floating
     points." OFF)
 
-
 option(TUG_ENABLE_TESTING "Run tests after succesfull compilation" OFF)
 
 option(TUG_HANNESPHILIPP_EXAMPLES "Compile example applications" OFF)

README.md

@@ -0,0 +1,103 @@
+![tug boat](./doc/images/tug_logo_small.png)
+
+`tug` implements different numerical approaches for transport
+problems, notably diffusion with implicit BTCS (Backward Time, Central
+Space) Euler and parallel 2D ADI (Alternating Direction Implicit).
+
+# About
+
+This project aims to provide a library for solving transport problems -
+diffusion, advection - on uniform grids implemented in C++. The library
+is built on top of
+[Eigen](https://eigen.tuxfamily.org/index.php?title=Main_Page),
+providing easy access to its optimized data structures and linear
+equation solvers.
+
+We designed the API to be as flexible as possible. Nearly every
+built-in, framework or third-party data structure can be used to model a
+problem, as long a pointer to continuous memory can be provided. We also
+provide parallelization using [OpenMP](https://www.openmp.org/), which
+can be easily turned on/off at compile time.
+
+At the current state, both 1D and 2D diffusion problems on a regular
+grid with constant alpha for all grid cells can be solved reliably.
+
+# Requirements
+
+- C++17 compliant compiler
+- [CMake](https://cmake.org/) >= 3.18
+- [Eigen](https://eigen.tuxfamily.org/) >= 3.4.0
+
+# Getting started
+
+`tug` is designed as a framework library and it relies on
+[CMake](https://cmake.org/) for building. If you already use
+`CMake` as your build toolkit for your application, you\'re
+good to go. If you decide not to use `CMake`, you need to
+manually link your application/library to `tug`.
+
+1. Create project directory.
+
+```bash
+mkdir sample_project && cd sample_project
+```
+
+2. Clone this repository into path of choice project directory
+
+3. Add the following line into `CMakeLists.txt` file:
+
+```bash
+add_subdirectory(path_to_tug EXCLUDE_FROM_ALL)
+```
+
+4. Write application/library using `tug`\'s API, notably
+    including relevant headers (see examples).
+
+5. Link target application/library against `tug`. Do this by
+    adding into according `CMakeLists.txt` file:
+
+```bash
+target_link_libraries(<your_target> tug)
+```
+
+6. Build your application/library with `CMake`.
+
+# Usage in an application
+
+Using `tug` can be summarized into the following steps:
+
+1. Define problem dimensionality
+2. Set grid sizes for each dimension
+3. Set the timestep
+4. Define boundary conditions
+5. Run the simulation!
+
+This will run a simulation on the defined grid for one species. See the
+source code documentation of `tug` and the examples in the
+`examples/` directory for more details.
+
+# Contributing
+
+In this early stage of development every help is welcome. To do so,
+there are currently the following options:
+
+Given you have an account for GFZ\'s `gitlab` instance:
+
+1. Fork this project, create a branch and push your changes. If your
+    changes are done or you feel the need for some feedback create a
+    merge request with the destination set to the **main** branch of
+    this project.
+2. Ask for access to this repository. You most likely will get access
+    as a developer which allows you to create branches and merge
+    requests inside this repository.
+
+If you can\'t get access to this `gitlab` instance:
+
+- Download this repository and note down the SHA of the downloaded commit. Apply
+    your changes and send a mail to <mluebke@gfz-potsdam.de> or
+    <delucia@gfz-potsdam.de> with the patch/diff compared to your starting
+    point. Please split different patch types (feature, fixes, improvements ...)
+    into seperate files. Also provide us the SHA of the commit you\'ve
+    downloaded.
+
+Thank you for your contributions in advance!

README.org

@@ -1,123 +0,0 @@
-#+TITLE: TUG: a C++ framework to solve Transport on Uniform Grids
-
-[[./doc/images/tug_logo_small.png]]
-
-=tug= implements different numerical approaches for transport
-problems, notably diffusion with implicit BTCS (Backward Time, Central
-Space) Euler and parallel 2D ADI (Alternating Direction Implicit).
-
-* About
-
-This project aims to provide a library for solving transport
-problems - diffusion, advection - on uniform grids implemented in C++.
-The library is built on top of [[https://eigen.tuxfamily.org/index.php?title=Main_Page][Eigen]], providing easy access to its
-optimized data structures and linear equation solvers.
-
-We designed the API to be as flexible as possible. Nearly every
-built-in, framework or third-party data structure can be used to model
-a problem, as long a pointer to continuous memory can be provided. We
-also provide parallelization using [[https://www.openmp.org/][OpenMP]], which can be easily turned
-on/off at compile time.
-
-At the current state, both 1D and 2D diffusion problems on a regular
-grid with constant alpha for all grid cells can be solved reliably.
-
-* Getting started
-
-=tug= is designed as a framework library and it relies on [[https://cmake.org/][CMake]] for
-building. If you already use =CMake= as your build toolkit for your
-application, you're good to go. If you decide not to use =CMake=, you
-need to manually link your application/library to =tug=.
-
-1. Create project directory.
-
-   #+BEGIN_SRC
-   $ mkdir sample_project && cd sample_project
-   #+END_SRC
-
-2. Clone this repository into path of choice project directory
-   - with =ssh=:
-
-   #+BEGIN_SRC
-   $ git clone git@git.gfz-potsdam.de:naaice/tug.git
-   #+END_SRC
-
-   - with =https=: 
-   #+BEGIN_SRC
-   $ git clone https://git.gfz-potsdam.de/naaice/tug.git
-   #+END_SRC
-
-3. Add the following line into =CMakeLists.txt= file:
-
-   #+BEGIN_SRC
-   add_subdirectory(path_to_tug EXCLUDE_FROM_ALL)
-   #+END_SRC
-
-4. Write application/library using =tug='s API, notably including
-   relevant headers (see examples).
-
-5. Link target application/library against =tug=. Do this by adding
-   into according =CMakeLists.txt= file:
-
-   #+BEGIN_SRC
-   target_link_libraries(<your_target> tug)
-   #+END_SRC
-
-6. Build your application/library with =CMake=.
-
-
-* Usage in an application
-
-Using =tug= can be summarized into the following steps:
-
-1. Define problem dimensionality
-2. Set grid sizes for each dimension
-3. Set the timestep 
-4. Define boundary conditions
-5. Run the simulation!
-
-This will run a simulation on the defined grid for one species. See
-the source code documentation of =tug= and the examples in the
-=examples/= directory for more details.
-
-* Roadmap
-
-- [X] 1D diffusion using BTCS
-- [X] 2D diffusion with ADI
-- [ ] 3D diffusion (?)
-- [X] R-API (see [[https://git.gfz-potsdam.de/naaice/rcppbtcs][RcppBTCS]])
-- [-] Python-API (?)
-- [X] Testing
-
-* Contributing
-** *PLEASE NOTE*
-
-Starting from version v0.2 we would like to use more meaningful commit
-messages. An overview of good practices and conventions can be found
-[[https://www.conventionalcommits.org/en/v1.0.0/][here]].
-
-** Workflow
-
-In this early stage of development every help is welcome. To do so,
-there are currently the following options:
-
-Given you have an account for GFZ's =gitlab= instance:
-
-1. Fork this project, create a branch and push your changes. If your
-   changes are done or you feel the need for some feedback create a
-   merge request with the destination set to the *main* branch of this
-   project.
-2. Ask for access to this repository. You most likely will get access
-   as a developer which allows you to create branches and merge
-   requests inside this repository.
-
-If you can't get access to this =gitlab= instance:
-
-3. Download this repository and note down the SHA of the downloaded
-   commit. Apply your changes and send a mail to
-   [[mailto:mluebke@gfz-potsdam.de][mluebke@gfz-potsdam.de]] or [[mailto:delucia@gfz-potsdam.de][delucia@gfz-potsdam.de]] with the
-   patch/diff compared to your starting point. Please split different
-   patch types (feature, fixes, improvements ...) into seperate files.
-   Also provide us the SHA of the commit you've downloaded.
-
-Thank you for your contributions in advance!