diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 61ec7b7..5b9c40b 100644 --- a/.gitlab-ci.yml +++ b/.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 diff --git a/CMakeLists.txt b/CMakeLists.txt index ab192af..de6009f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,7 +1,7 @@ #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() diff --git a/README.org b/README.org index 4a1db52..2909fb8 100644 --- a/README.org +++ b/README.org @@ -1,33 +1,33 @@ -#+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]] + +=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 diffusion problems using the -backward Euler method (BTCS) implemented in C++. +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. -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. +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. -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. - -Also we provide basic parallelization by using [[https://www.openmp.org/][OpenMP]], which can be easily -turned on/off during generation of makefiles. - -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:mluebke/diffusion.git + $ git clone git@git.gfz-potsdam.de:sec34/tug.git + #+END_SRC + + - with =https=: + #+BEGIN_SRC + $ 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! diff --git a/doc/ADI_scheme.org b/doc/ADI_scheme.org index 654d5e8..6529522 100644 --- a/doc/ADI_scheme.org +++ b/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 diff --git a/doc/grid_pqc.pdf b/doc/images/grid_pqc.pdf similarity index 100% rename from doc/grid_pqc.pdf rename to doc/images/grid_pqc.pdf diff --git a/doc/images/tug_logo.svg b/doc/images/tug_logo.svg new file mode 100644 index 0000000..aa2c860 --- /dev/null +++ b/doc/images/tug_logo.svg @@ -0,0 +1,2629 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/images/tug_logo_crop.png b/doc/images/tug_logo_crop.png new file mode 100644 index 0000000..db53d86 Binary files /dev/null and b/doc/images/tug_logo_crop.png differ diff --git a/doc/images/tug_logo_small.png b/doc/images/tug_logo_small.png new file mode 100644 index 0000000..7a9b402 Binary files /dev/null and b/doc/images/tug_logo_small.png differ diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 68b71ae..080739a 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -1,9 +1,9 @@ -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) diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index 2426d77..b8d52e3 100644 --- a/test/CMakeLists.txt +++ b/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)