mirror of
https://git.gfz-potsdam.de/naaice/tug.git
synced 2025-12-15 10:28:23 +01:00
feat: Update CMake configuration and add README documentation
This commit is contained in:
Max Lübke
parent
bed888d1fc
commit
636fcfaec3
@ -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)
|
||||
|
||||
103
README.md
Normal file
103
README.md
Normal file
@ -0,0 +1,103 @@
|
||||
|
||||
|
||||
`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!
|
||||
123
README.org
123
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!
|
||||
Loading…
x
Reference in New Issue
Block a user