docs: Update and extending README

build: Set internal variables to new project name

ci: Use new CMake variables as basis

.gitlab-ci.yml

@@ -15,7 +15,7 @@ build_release:
       expire_in: 100s
   script:
       - mkdir build && cd build
-      - cmake -DCMAKE_BUILD_TYPE=Release -DBTCS_ENABLE_TESTING=ON ..
+      - cmake -DCMAKE_BUILD_TYPE=Release -DTUG_ENABLE_TESTING=ON ..
       - make -j$(nproc)
 
 test:
@@ -29,5 +29,5 @@ lint:
   stage: static_analyze
   script:
     - mkdir lint && cd lint
-    - cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_CXX_CLANG_TIDY="clang-tidy;-checks=cppcoreguidelines-*,clang-analyzer-*,performance-*,readability-*, modernize-*" -DBTCS_ENABLE_TESTING=OFF ..
-    - make BTCSDiffusion
+    - cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_CXX_CLANG_TIDY="clang-tidy;-checks=cppcoreguidelines-*,clang-analyzer-*,performance-*,readability-*, modernize-*" -DTUG_ENABLE_TESTING=OFF ..
+    - make tug

CMakeLists.txt

 #debian stable (currently bullseye)
 cmake_minimum_required(VERSION 3.18)
 
-project(BTCSDiffusion CXX)
+project(tug CXX)
 
 set(CMAKE_CXX_STANDARD 17)
 
@@ -9,7 +9,7 @@ find_package(Eigen3 REQUIRED NO_MODULE)
 find_package(OpenMP)
 
 ## SET(CMAKE_CXX_FLAGS  "${CMAKE_CXX_FLAGS} -O2 -mfma")
-option(BTCS_USE_OPENMP "Compile with OpenMP support" ON)
+option(TUG_USE_OPENMP "Compile with OpenMP support" ON)
 
 set(CMAKE_CXX_FLAGS_GENERICOPT "-O3 -march=native" CACHE STRING
  "Flags used by the C++ compiler during opt builds."
@@ -19,22 +19,22 @@ set(CMAKE_BUILD_TYPE "${CMAKE_BUILD_TYPE}" CACHE STRING
   "Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel GenericOpt."
   FORCE)
 
-option(BTCS_USE_UNSAFE_MATH_OPT
+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)
 
-if(BTCS_USE_UNSAFE_MATH_OPT)
+if(TUG_USE_UNSAFE_MATH_OPT)
   add_compile_options(-ffast-math)
 endif()
 
-option(BTCS_ENABLE_TESTING
+option(TUG_ENABLE_TESTING
   "Run tests after succesfull compilation"
   OFF)
 
 add_subdirectory(src)
 
-if(BTCS_ENABLE_TESTING)
+if(TUG_ENABLE_TESTING)
   add_subdirectory(test)
 endif()

README.org

-#+TITLE: BTCSDiffusion
+#+TITLE: TUG: a C++ framework to solve Transport on Uniform Grids
 
-#+BEGIN_CENTER
-A framework solving diffusion problems using BTCS approach.
-#+END_CENTER
+[[./doc/images/tug_logo_small.png]]
 
-* About
-
-This project aims to provide a library for solving diffusion problems using the
-backward Euler method (BTCS) implemented in C++.
+=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).
 
-The library is built on top of [[https://eigen.tuxfamily.org/index.php?title=Main_Page][Eigen]], providing easy access to data structures
-and the linear equation solver.
+* About
 
-We designed the API to be as much 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 continious memory can be providided.
+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.
 
-Also we provide basic parallelization by using [[https://www.openmp.org/][OpenMP]], which can be easily
-turned on/off during generation of makefiles.
+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 @D diffusion problems on a regular grid with
-constant alpha for all grid cells can be solved reliably.
+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
 
-As this diffusion module is designed as a framework library and makefile
-generation is done by [[https://cmake.org/][CMake]], you're good to go to also use CMake as your build
-toolkit. If you decide to not use CMake, you need to manually link your
-application/library to BTCSDiffusion.
+=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.
 
@@ -36,48 +36,54 @@ application/library to BTCSDiffusion.
    #+END_SRC
 
 2. Clone this repository into path of choice project directory
+   - with =ssh=:
+
+   #+BEGIN_SRC
+   $ git clone git@git.gfz-potsdam.de:sec34/tug.git
+   #+END_SRC
 
+   - with =https=: 
    #+BEGIN_SRC
-   $ git clone git@git.gfz-potsdam.de:mluebke/diffusion.git
+   $ git clone https://git.gfz-potsdam.de/sec34/tug.git
    #+END_SRC
 
 3. Add the following line into =CMakeLists.txt= file:
 
    #+BEGIN_SRC
-   add_subdirectory(path_to_diffusion_module EXCLUDE_FROM_ALL)
+   add_subdirectory(path_to_tug EXCLUDE_FROM_ALL)
    #+END_SRC
 
-4. Write application/library using API of =BTCSDiffusion=.
+4. Write application/library using =tug='s API, notably including
+   relevant headers (see examples).
 
-5. Link target application/library against =BTCSDiffusion=. Do this by adding
+5. Link target application/library against =tug=. Do this by adding
    into according =CMakeLists.txt= file:
 
    #+BEGIN_SRC
-   target_link_libraries(your_libapp BTCSDiffusion)
+   target_link_libraries(your_libapp tug)
    #+END_SRC
 
-6. Build your application/library with CMake.
+6. Build your application/library with =CMake=.
 
 
-* Usage
+* Usage in an application
 
-Setting up an enviroment to use the =BTCSDiffusion= module is divided into the
-following steps:
+Using =tug= can be summarized into the following steps:
 
-1. Defining dimension of diffusion problem.
-2. Set grid sizes in according dimensions.
-3. Set the timestep to simulate.
-4. Defining boundary conditions.
+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 =BTCSDiffusion= and the examples in the =app/= directory
-for more information.
+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
-- [X] 2D diffusion
+- [X] 1D diffusion using BTCS
+- [X] 2D diffusion with ADI
 - [ ] 3D diffusion (?)
 - [X] R-API (see [[https://git.gfz-potsdam.de/sec34/rcppbtcs][RcppBTCS]])
 - [-] Python-API (?)
@@ -86,30 +92,33 @@ for more information.
 * Contributing
 ** *PLEASE NOTE*
 
-Starting with the preparations of v0.2 we would like to use more meaningful
-commit messages. A good practice can be found [[https://www.conventionalcommits.org/en/v1.0.0/][here]].
+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:
+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 this GFZ git instance:
+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 likelz will get access as a
-   developer which allows you to create branches and merge requests inside this
-   repository.
+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 can't get access to this git instance:
+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.
+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!
 

doc/ADI_scheme.org

@@ -19,7 +19,7 @@ The 1D diffusion equation is:
 
 We aim at numerically solving [[eqn:1]] on a spatial grid such as:
 
-[[./grid_pqc.pdf]]
+[[./images/grid_pqc.pdf]]
 
 The left boundary is defined on $x=0$ while the center of the first
 cell - which are the points constituting the finite difference nodes -
@@ -94,7 +94,6 @@ C_n^{t+1} = C_n^{t} + \frac{\alpha \cdot \Delta t}{\Delta x^2} \cdot (C^t_{n-1}
 \end{equation}
 
 
-
 A similar treatment can be applied to the BTCS implicit scheme.
 
 ** Implicit BTCS scheme

src/CMakeLists.txt

-add_library(BTCSDiffusion BTCSDiffusion.cpp grid/BoundaryCondition.cpp)
+add_library(tug BTCSDiffusion.cpp grid/BoundaryCondition.cpp)
 
-target_link_libraries(BTCSDiffusion Eigen3::Eigen)
+target_link_libraries(tug Eigen3::Eigen)
 
-if(BTCS_USE_OPENMP AND OpenMP_CXX_FOUND)
-  target_link_libraries(BTCSDiffusion OpenMP::OpenMP_CXX)
+if(TUG_USE_OPENMP AND OpenMP_CXX_FOUND)
+  target_link_libraries(tug OpenMP::OpenMP_CXX)
 endif()
 
-target_include_directories(BTCSDiffusion PUBLIC ../include)
+target_include_directories(tug PUBLIC ../include)

test/CMakeLists.txt

@@ -12,4 +12,4 @@ FetchContent_MakeAvailable(DocTest)
 #target_include_directories(doctest INTERFACE doctest)
 
 add_executable(test setup.cpp testBoundaryCondition.cpp testDiffusion.cpp)
-target_link_libraries(test doctest BTCSDiffusion)
+target_link_libraries(test doctest tug)