Merge pull request #39 from precice/update-deal.II-docs

Update deal.II adapter docs

pages/docs/adapters/deal.II/adapter-dealii-coupling-meshes.md

@@ -5,13 +5,10 @@ keywords: adapter, dealii, meshes
 summary: "The polynomial support points are used to define the coupling mesh."
 ---
 
-Defining a coupling mesh in finite element programs is not trivial and there are multiple solution strategies. We rely here on the support points of the high-order polynomials. There are several reasons to do so: First, we would like to keep the high resolution property for higher-order shape functions. An obvious alternative would be to choose the mesh vertices, but it would lead to a loss of information between grid points. Another reason is the consistency to the deal.II infrastructure during the (rhs) assembly, where we treat the coupling data as global vectors. When reading global vectors, data location is assumed to be at the support points i.e. the actual solution points. The third reason is, that we use (by default) a direct solver and therefore, want to keep the overall number of unknowns rather small, while providing a high accuracy. From a solver perspective, high-order polynomial degrees are in most of the applications superior considering the classical solid mechanics as in the tutorials.
+Defining a coupling mesh in finite element programs is not trivial and there are multiple solution strategies. We rely here on the support points of the high-order polynomials. There are several reasons to do so: First, we would like to keep the high resolution property for higher-order shape functions. An alternative would be to choose the mesh vertices, but it would lead to a loss of information between grid points. Another reason is the consistency to the deal.II infrastructure during the right-hand side assembly, where we treat the coupling data as global vectors. When reading global vectors, data location is assumed to be at the support points i.e. the actual solution points. The third reason is, that we use (by default) a direct solver and therefore, want to keep the overall number of unknowns rather small, while providing a high accuracy. From a solver perspective, high-order polynomial degrees are in most of the applications superior considering the classical solid mechanics as in the tutorials.
 
 However, from a coupling perspective, fewer unknowns are not the best choice, since our mapping methods are restricted to (at most) second order in space. Therefore, having more interface nodes is preferable. Also, using the support points is difficult in case of `conservative` mappings, because data is interpolated to quadrature points and conservation property is not guaranteed. A simple remedy would be to apply collocation techniques, where the interpolation is essentially omitted.
 
 ## Where are support points located?
-The concept of support points is explained in [this glossary entry of the deal.II documentation](https://www.dealii.org/developer/doxygen/deal.II/DEALGlossary.html#GlossSupport). In particular (by default), we use here the standard `FE_Q` finite element, where the support points are located according to [Gauss-Lobatto quadrature points](https://www.dealii.org/developer/doxygen/deal.II/classQGaussLobatto.html). Note that these points are not equidistant. 
-
-[Add link to other Doc page]
-
 
+The concept of support points is explained in [this glossary entry of the deal.II documentation](https://www.dealii.org/developer/doxygen/deal.II/DEALGlossary.html#GlossSupport). In particular (by default), we use here the standard `FE_Q` finite element, where the support points are located according to [Gauss-Lobatto quadrature points](https://www.dealii.org/developer/doxygen/deal.II/classQGaussLobatto.html). Note that these points are not equidistant. A detailed description of the `FE_Q` finite element can be found in the [`FE_Q` deal.II documentation](https://dealii.org/developer/doxygen/deal.II/classFE__Q.html).

pages/docs/adapters/deal.II/adapter-dealii-get.md

@@ -9,15 +9,21 @@ This adapter is a collection of examples of a deal.II solver adapted for preCICE
 
 ## Get deal.II
 
-The adapter currently requires deal.II version 9.2 or later. We also have a [separate branch for version 9.1](https://github.com/precice/dealii-adapter/tree/dealii-9.1), in case you need more time to upgrade.
-
-You can find also [more download options on the deal.II website](https://dealii.org/download.html).
+You can find all [available download options on the deal.II website](https://dealii.org/download.html).
 
 ### Binary packages
 
-deal.II is available in several Linux distribution. For example, if you are using Ubuntu, you can get the [`libdeal.ii-de`](https://packages.ubuntu.com/search?keywords=libdeal.ii-dev) package (see also the [backports ppa](https://launchpad.net/~ginggs/+archive/ubuntu/deal.ii-9.2.0-backports)):
+deal.II is available in several Linux distributions. For example, if you are using Ubuntu, you can get the [`libdeal.ii-dev`](https://packages.ubuntu.com/search?keywords=libdeal.ii-dev) package (see also the [backports ppa](https://launchpad.net/~ginggs/+archive/ubuntu/deal.ii-9.2.0-backports)):
+```bash
+sudo apt install libdeal.ii-dev libdeal.ii-doc cmake make g++
+```
+{% include note.html content="The package libdeal.ii-doc installs the deal.II own tutorials ('steps'), which are not necessarily required for the dealii-adapter. However, they can be helpful in order to test the correct installation of the deal.II library. The following steps copy and test the `step-1` tutorial of deal.II:" %}
+
 ```bash
-sudo apt install libdeal.ii-dev
+cp -r /usr/share/doc/libdeal.ii-doc/examples/step-1 .
+cd step-1
+cmake .
+make run
 ```
 
 ### Building from source
@@ -40,10 +46,11 @@ make -j 4
 The direct solvers in this examples require `UMFPACK`. The nonlinear-solver utilizes a shared-memory parallelization. We disable building the examples only to significantly reduce the building time and storage needs.
 
 
-<details><summary>Click for more options...</summary>
+### Advanced: Building in production
+
 If you want to use deal.II in production, there may be several options you may want to tune. In this case, use ccmake or check the [deal.II CMake documentation](https://www.dealii.org/9.2.0/users/cmake_dealii.html). For example:
 
-```
+```bash
 cmake \
     -D CMAKE_BUILD_TYPE="DebugRelease" \
     -D CMAKE_CXX_FLAGS="-march=native \
@@ -56,13 +63,12 @@ cmake \
 
 make -j 4
 ```
-</details>
 
 Detailed installation instructions are given in the [installation section of the deal.II webpage](https://www.dealii.org/current/readme.html).
 
 ## Get preCICE
 
-[Get preCICE](https://github.com/precice/precice/wiki/Get-preCICE), e.g. from [binary packages](https://github.com/precice/precice/releases/latest), or [build it from source](https://github.com/precice/precice/wiki/Building:-Using-CMake).
+Have a look at our [preCICE installation guide](installation-overview.html).
 
 ## Build the adapter
 
@@ -72,38 +78,42 @@ If you have deal.II and preCICE globally installed in your system and want to ru
    ```bash
    git clone https://github.com/precice/dealii-adapter.git
    ```
-
-2. Each solver in this repository can be built independently. Therefore, get into the directory of a solver (e.g. `cd linear_elasticity/`) and configure it with
-   `cmake`: 
-   - If you have deal.II installed globally in your system:
+
+2. The solvers are compiled into a single executable. Therefore, get into the top-level directory and configure it with `cmake`:
+   - If you have deal.II and preCICE installed globally in your system:
    ```
    cmake .
    ```
-   - If you have deal.II installed in a local directory:
+   - If you have deal.II and preCICE installed in a local directory:
+   ```
+   cmake -DDEAL_II_DIR=/path/to/deal.II -DpreCICE_DIR=/path/to/precice .
    ```
-   cmake -DDEAL_II_DIR=/path/to/deal.II .
+    where `*_DIR` points to your installation (not source) directory. This should be the same as the `CMAKE_INSTALL_PREFIX` you used when installing the respective libraay. If you have set either of these variables globally, you could skip it in the command above.
+3. Run `make` to build the adapter. This will generate the `elasticity` executable.
+4. Ensure that the executable is run-time discoverable by adding it to your `PATH` variable, e.g. for bash
+   ```bash
+   export PATH="/path/to/dealii/adapter/elasticity:${PATH}"
    ```
-    where `DEAL_II_DIR` points to your installation (not source) directory. This should be the same as the `CMAKE_INSTALL_PREFIX` you used when installing deal.II. If you have set the variable `DEAL_II_DIR` globally, you could skip it in the command above.
-3. Run `make` to build the adapter.
+{% include tip.html content="Our [tutorials](tutorials.html) include scripts (`run.sh`) in order to start individual cases. The deal.II adapter scripts accept an option `-e=<executable_to_run>` to locate the executable, in case it is not globally discoverable." %}
 
 ### 2D vs 3D simulations
 
 By default, the adapter is built as a 2D example in release mode.
 If you want to run a 3D example (quasi 2D, meaning that the out-of-plane direction is clamped but we use real cells for the calculation), you can define this when configuring:
 ```bash
 cmake -DDIM=3 .
-``` 
+```
 Note that you need to run `make distclean` if you switch from one to another dimension in order to overwrite the dimension value.
 
 ### Debug vs Release mode
 
-You can switch between debug and release mode using `make debug` or `make release`. By default, programs are build in release mode.
+You can switch between debug and release mode using `make debug` or `make release`. By default, programs are built in release mode.
 
 ## Next steps
 
-To run the deal.II codes, copy the executable and parameter file (`solver.prm`) in your target directory, e.g. `Solid/`. Afterwards, run the executable, e.g. by:
+To run the deal.II codes, copy the parameter file (`parameters.prm`) into your target directory, e.g. `solid-dealii/`. Afterwards, run the executable as
+```
+./elasticity path/to/parameters.prm
 ```
-./nonlinear_elasticity path/to/nonlinear_elasticity.prm
-``` 
-Example cases can be found in the [tutorial cases for deal.II coupled with OpenFOAM](https://github.com/precice/precice/wiki/Tutorial-for-FSI-with-deal.II-and-OpenFOAM). 
+Example cases can be found in our [FSI tutorial cases](tutorials.html).
 {% include note.html content="The deal.II related examples have already a preconfigured parameter file, so that the parameter file doesn't need to be copied." %}

pages/docs/adapters/deal.II/adapter-dealii-limitations.md

@@ -4,9 +4,20 @@ permalink: adapter-dealii-limitations.html
 keywords: adapter, deal.II, limitations, 
 ---
 
-In case you want to use the adapter for your own work, consider the following notes:
+In case you want to use the adapter for your own work, consider the following notes.
 
-- you can only define one `read` and one `write` mesh per deal.II executable. On the one hand, extending this is not in particular difficult and could be done in the `Adapter` class itself, but since we have only FSI (solid part) ready-to-run tutorials and programs, it should be sufficient to summarize different boundary parts into a single mesh (in deal.II terminology `boundary_id()`) for writing and reading respectively. The applied boundary conditions are on each `write` and on each `read` mesh the same. If this is not sufficient, you may want to consider more than one deal.II participant.
-- if you want to couple your own deal.II code, note that we apply here Neumann boundary conditions. In case you would like to couple e.g. a `Fluid` participant, the application of Dirichlet boundary conditions is much more common. The treatment of boundary conditions in general is very specific to the considered application case and cannot be included in the adapter as presented here. Even if you couple your own structure solver, the boundary conditions resulting from the coupling might be different e.g. depending on your configuration (Lagrangian vs Eulerian). However, in this programs we show everything based on coupling the application to other participant by Neumann boundary conditions. The treatment of Dirichlet boundary conditions is dedicated to future work of this adapter (examples). You might find useful information in the deal.II own tutorials. If you have done or are currently doing something similar, let us know.
-- as opposed to preCICE itself, there is currently no option to switch between the coupling data type (i.e. vector data and scalar data). This is triggered by the fact, that we use for FSI purely vector valued data for coupling. Have a look in the extensive source code documentation of the `Adapter` class if you would like to change this in your own project.
-- in order to benefit from the high-order property of finite element methods as applied here, we use the support points of high-order polynomials in the coupling mesh. These points are in general different from the quadrature points, where data is evaluated. Therefore, we define our read mappings (and data) to be `consistent`, since we need to interpolate from the support points to the quadrature points. If we use a `conservative` mapping, we might violate the conservation property due to the interpolation step. In one of the previous implementations, we used a conservative read data, but selected the face-centers of the triangulation as read mesh leading to a loss of the natural subcell resolution property of the finite element methods. A rather simple remedy would be the application of collocation techniques, where the interpolation step vanishes. Another option would be to ensure the conservation property in the interpolation step itself. However, this is not considered in the current implementations. 
+## Number of interface meshes
+
+You can only define one `read` and one `write` mesh per deal.II executable. On the one hand, extending this is not in particular difficult and could be done in the `Adapter` class itself, but since we have only FSI (solid part) ready-to-run tutorials and programs, it should be sufficient to summarize different boundary parts into a single mesh (in deal.II terminology `boundary_id()`) for writing and reading, respectively. The applied boundary conditions are on each `write` and on each `read` mesh the same. If this is not sufficient, you may want to consider more than one deal.II participant.
+
+## Boundary conditions
+
+If you want to couple your own deal.II code, note that we apply here Neumann boundary conditions. In case you would like to couple e.g. a `Fluid` participant, the application of Dirichlet boundary conditions is much more common. The treatment of boundary conditions is very specific to the considered application case and cannot be included in the adapter as presented here. Even if you couple your own structure solver, the boundary conditions resulting from the coupling might be different, e.g. depending on your configuration (Lagrangian vs Eulerian). However, in this code we show everything based on coupling the application to other participant by Neumann boundary conditions. The treatment of Dirichlet boundary conditions is dedicated to future work of this adapter / adapter examples. You might find useful information in the deal.II own tutorials. If you have done or are currently doing something similar, let us know.
+
+## Coupling data
+
+As opposed to preCICE itself, there is currently no option to switch between the coupling data type (i.e. vector data and scalar data). This is triggered by the fact that we use purely vector valued data for (FSI) coupling. Have a look in the extensive source code documentation of the `Adapter` class if you would like to change this in your own project.
+
+## Mapping
+
+In order to benefit from the high-order property of finite element methods as applied here, we use the support points of high-order polynomials in the coupling mesh. These points are in general different from the quadrature points, where data is evaluated. Therefore, we define our read mappings (and data) to be `consistent`, since we need to interpolate from the support points to the quadrature points. If we use a `conservative` mapping, we might violate the conservation property due to the interpolation step. In one of the previous implementations, we used a conservative read data, but selected the face-centers of the triangulation as read mesh leading to a loss of the natural subcell resolution property of the finite element methods. A rather simple remedy would be the application of collocation techniques, where the interpolation step vanishes. Another option would be to ensure the conservation property in the interpolation step itself. However, this is not considered in the current implementations.