Merge branch 'update-readme' into 'master'

Update the readme and the getting-started document

See merge request amdis/amdis!205

README.md

@@ -37,7 +37,7 @@ The `dunecontrol` script searches for the required
 
 (See the file `dune.module` for an up-to-date list of dependencies). The dune modules
 can be obtained from https://gitlab.dune-project.org and need to be found in a
-subdirectory of `DUNE_CONTROL_PATH`. See also https://dune-project.org/doc/installation
+subdirectory of `DUNE_CONTROL_PATH`. See also https://dune-project.org/installation/installation-buildsrc/
 for details about the installation of dune modules. You can use the script
 
 ```
@@ -51,7 +51,7 @@ Additionally the following optional libraries can be used:
 - [MTL4](https://gitlab.math.tu-dresden.de/spraetor/mtl4) (use this fork to get up-to-date changes)
 - [Eigen3](http://eigen.tuxfamily.org) >= 3.3
 - [SuiteSparse](http://faculty.cse.tamu.edu/davis/suitesparse.html)
-- [PETSc](https://www.mcs.anl.gov/petsc)
+- [PETSc](https://petsc.org)
 - libalberta >= 3.0 (For Alberta-Grids)
 
 And a compiler that supports the C++17 standard, e.g. g++ >= 9.0 and clang >= 10.0, and cmake >= 3.16.
@@ -67,3 +67,23 @@ where the file `MTLConfig.cmake` is found, here called `MTL_ROOT`. Then simply u
 CMAKE_FLAGS="-DBACKEND=MTL -DMTL_ROOT:PATH=[MTL_ROOT]" dunecontrol --current configure
 cmake --build build-cmake
 ```
+
+How to Cite AMDiS
+=================
+If you are using AMDiS as part of your research and in publication, we kindly ask you to cite AMDiS.
+As it is a Dune module, your are asked to cite a corresponding Dune paper, see [dune-project.org/about/publications/](https://dune-project.org/about/publications/), e.g.,
+```
+P. Bastian, M. Blatt, A. Dedner, N.-A. Dreier, C. Engwer, R. Fritze, C. Gräser, C. Grüninger, D. Kempf, R. Klöfkorn, M. Ohlberger, O. Sander. The DUNE framework: Basic concepts and recent developments. Computers & Mathematics with Applications 81, 2021, pp. 75-112
+```
+
+In addition, cite the source repository, including the release version of the library that you are using, e.g.
+```
+@misc{AMDiS:2.10,
+  key    = {AMDiS},
+  title  = {Adaptive Multi-Dimensional Simulations},
+  note   = {v2.10},
+  howpublished = {\url{https://gitlab.com/amdis/amdis}},
+}
+```
+
+Please note that other Dune modules might require citation of further papers, such as Dune-ALUGRid, Dune-FEM, Dune-PDELab, Dune-CurvedGrid, or Dune-FoamGrid. See their corresponding README for how to cite their publications, or the [dune-project.org/about/publications/](https://dune-project.org/about/publications/) page for an overview of some modules.
\ No newline at end of file

docs/getting-started.md

@@ -3,55 +3,40 @@
 [TOC]
 
 ## Download and Install
-AMDiS is a Finite-Element discretization library implemented as a
-[Dune](https://www.dune-project.org) module. This means, it depends on several
-other Dune modules, mainly the core modules and some staging modules. And it
-means that it can be extended by other Dune modules.
+AMDiS is a finite element discretization library implemented as a [Dune](https://www.dune-project.org) module. This means that it depends on several other Dune modules, mainly the core modules and some staging modules. And it means that it can be extended by other Dune modules.
 
-Additionally, it depends on external libraries, like linear solvers, graph
-partitioners, multi-precision arithmetic, or parallel communication libraries.
-Those dependencies are often optional and may be installed when needed, but
-sometimes require the Dune modules to be rebuild. So, we start with a common
-set of external libraries here.
+It also depends on external libraries, such as linear solvers, graph partitioners, multi-precision arithmetic, or parallel communication libraries. These dependencies are often optional and can be installed if needed, but sometimes they require rebuilding the Dune modules. So we start here with a common set of external libraries.
 
 ### Installing External Libraries
-A recommended collection of external packages include a direct solver, the message
-passing interface and sequential/parallel graph partitioner. Additionally, we
-recommend to install a package that defines an external grid type to be used with
-Dune.
+A recommended collection of external packages includes a direct solver, the message passing interface, and a sequential/parallel graph partitioner. In addition, we recommend installing a package that defines an external grid type to be used with Dune.
 
-- [Alberta](http://www.alberta-fem.de/download.html)
+- [SuiteSparse](http://faculty.cse.tamu.edu/davis/suitesparse.html)
+- [OpenMPI](https://www.open-mpi.org) (or any other MPI implementation conforming to some recent standard)
 - [METIS](http://glaros.dtc.umn.edu/gkhome/metis/metis/overview)
-- [OpenMPI](https://www.open-mpi.org)
 - [ParMETIS](http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview)
-- [SuiteSparse](http://faculty.cse.tamu.edu/davis/suitesparse.html)
+- [PETSc](https://petsc.org)
+- [Alberta](http://www.alberta-fem.de/download.html)
 
-On recent Linux distributions, all of these libraries are available as prebuild
-package. As an example, on a recent Debian based system, you can simply use `apt-get`:
+On recent Linux distributions, all of these libraries are available as prebuild package. As an example, on a recent Debian based system, you can simply use `apt-get`:
 
 ```bash
 sudo apt-get install \
-  libalberta-dev \
-  libmetis-dev \
+  libsuitesparse-dev \
   libopenmpi-dev \
+  libmetis-dev \
   libparmetis-dev \
-  libsuitesparse-dev
+  petsc-dev \
+  libalberta-dev
 ```
 
-Other distributions may have similar packages. For an installation from source,
-visit the corresponding website of the library.
+Other distributions may have similar packages. For an installation from source, visit the corresponding website of the library.
 
 ### Installing Dune
-The Dune modules can be installed as a prebuild package in your (Linux) distribution,
-by downloading source packages, or by cloning a Git repository. See the following
-resources for information of getting and installing Dune
+The Dune modules can be installed as a prebuild package in your (Linux) distribution, by downloading source packages, or by cloning a Git repository. See the following resources for information of getting and installing Dune
 
-- <https://www.dune-project.org/doc/beginners-resources>
-- <https://www.dune-project.org/doc/installation>
+- <https://dune-project.org/doc/gettingstarted>
 
-One way is described here: Cloning a Git repository. The easiest way to organize
-your Dune dependencies is to create a new directory, call it `DUNE_DIR`, and to
-download all modules into this directory
+One way is described here: Cloning a Git repository and compiling from source. The easiest way to organize your Dune dependencies is: create a new directory, e.g. called `DUNE_DIR` in the following, and download all modules into this directory
 
 ```bash
 mkdir DUNE_DIR
@@ -66,14 +51,9 @@ git clone https://gitlab.dune-project.org/staging/dune-typetree
 git clone https://gitlab.dune-project.org/staging/dune-uggrid
 ```
 
-Building the Dune modules can be done using the shipped `dunecontrol` script. It
-resolves the inter-module dependencies and calls *cmake* and *make* in the Dune
-sources directories.
+Building the Dune modules can be done using the shipped `dunecontrol` script. It resolves the inter-module dependencies and calls *cmake* and *make* in the Dune source/build directories.
 
-To control the building parameters (e.g. cmake parameters or make parameters),
-you may pass a config file with the `--opts=` parameter, or by setting environment
-variables. Here, the second option is explained. Option files are documented in
-the links above.
+To control the building parameters (e.g. cmake parameters or make parameters), you may pass a config file with the `--opts=` parameter, or by setting environment variables. Here, the second option is explained. Option files are documented in the links above.
 
 ```bash
 cd DUNE_DIR
@@ -111,10 +91,7 @@ variables as above.
 
 
 ## Starting a new Project
-Creating a new project that uses AMDiS is fairly simple, by using the shipped
-`amdisproject` script. It expects to find the Dune modules and AMDiS is the
-`DUNE_CONTROL_PATH` directories and gets a name of the new project as first
-argument. All other (optional) information is asked by the script.
+Creating a new project that uses AMDiS is fairly simple, by using the shipped `amdisproject` script. It expects to find the Dune modules and AMDiS is the `DUNE_CONTROL_PATH` directories and gets a name of the new project as first argument. All other (optional) information is asked by the script.
 
 ```bash
 cd PROJECT_DIR
@@ -122,10 +99,7 @@ export DUNE_CONTROL_PATH=AMDIS_DIR:DUNE_DIR
 AMDIS_DIR/bin/amdisproject my_first_project
 ```
 
-This will create a new folder `PROJECT_DIR/my_first_project` and fills it with
-some commonly used files and directory structure, especially a `CMakeLists.txt`
-file, a `dune.module` file and some example source code. This allows to build
-your project with the `dunecontrol` script from Dune.
+This will create a new folder `PROJECT_DIR/my_first_project` and fills it with some commonly used files and directory structure, especially a `CMakeLists.txt` file, a `dune.module` file and some example source code. This allows to build your project with the `dunecontrol` script from Dune.
 
 ```bash
 cd PROJECT_DIR/my_first_project

docs/workshop/2021.md

@@ -36,7 +36,7 @@ In order to participate in the tutorials by writing code, please install some re
 - Code editor, e.g., vim, emacs, vscode, Sublime Text, CLion, ....
 
 If your linux distribution does not provide the corresponding version, please also check the FAQ
-section on [dune-project.org/doc/installation](https://dune-project.org/doc/installation/) for some hints.
+section on [dune-project.org/installation/installation-faq](https://dune-project.org/installation/installation-faq/) for some hints.
 
 ## Material for the workshop