118 lines
3.8 KiB
Org Mode
118 lines
3.8 KiB
Org Mode
#+TITLE: BTCSDiffusion
|
|
|
|
#+BEGIN_CENTER
|
|
A framework solving diffusion problems using BTCS approach.
|
|
#+END_CENTER
|
|
|
|
* About
|
|
|
|
This project aims to provide a library for solving diffusion problems using the
|
|
backward Euler method (BTCS) implemented in C++.
|
|
|
|
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 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.
|
|
|
|
* 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.
|
|
|
|
1. Create project directory.
|
|
|
|
#+BEGIN_SRC
|
|
$ mkdir sample_project && cd sample_project
|
|
#+END_SRC
|
|
|
|
2. Clone this repository into path of choice project directory
|
|
|
|
#+BEGIN_SRC
|
|
$ git clone git@git.gfz-potsdam.de:mluebke/diffusion.git
|
|
#+END_SRC
|
|
|
|
3. Add the following line into =CMakeLists.txt= file:
|
|
|
|
#+BEGIN_SRC
|
|
add_subdirectory(path_to_diffusion_module EXCLUDE_FROM_ALL)
|
|
#+END_SRC
|
|
|
|
4. Write application/library using API of =BTCSDiffusion=.
|
|
|
|
5. Link target application/library against =BTCSDiffusion=. Do this by adding
|
|
into according =CMakeLists.txt= file:
|
|
|
|
#+BEGIN_SRC
|
|
target_link_libraries(your_libapp BTCSDiffusion)
|
|
#+END_SRC
|
|
|
|
6. Build your application/library with CMake.
|
|
|
|
|
|
* Usage
|
|
|
|
Setting up an enviroment to use the =BTCSDiffusion= module is divided 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.
|
|
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.
|
|
|
|
* Roadmap
|
|
|
|
- [X] 1D diffusion
|
|
- [X] 2D diffusion
|
|
- [ ] 3D diffusion (?)
|
|
- [X] R-API (see [[https://git.gfz-potsdam.de/sec34/rcppbtcs][RcppBTCS]])
|
|
- [-] Python-API (?)
|
|
- [X] Testing
|
|
|
|
* 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]].
|
|
|
|
** 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 this GFZ git 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.
|
|
|
|
If can't get access to this git 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!
|
|
|
|
* License
|
|
TODO?
|