diff --git a/CMakeLists.txt b/CMakeLists.txt index bfbb579..76516be 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -6,35 +6,18 @@ project( VERSION 0.4 LANGUAGES CXX) -set(CMAKE_CXX_STANDARD 17) - -find_package(Eigen3 REQUIRED NO_MODULE) +find_package(Eigen3 3.4 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) diff --git a/README.md b/README.md new file mode 100644 index 0000000..54213ac --- /dev/null +++ b/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( 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 or + 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/README.org b/README.org deleted file mode 100644 index 7be9fbf..0000000 --- a/README.org +++ /dev/null @@ -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( 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!