mirror of
https://git.gfz-potsdam.de/naaice/tug.git
synced 2025-12-13 09:28:23 +01:00
124 lines
4.1 KiB
Org Mode
124 lines
4.1 KiB
Org Mode
#+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: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_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/sec34/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!
|