Merge branch 'master' into add-dune-dumux

.gitmodules

@@ -18,3 +18,7 @@
 	path = imported/fmi-runner
 	url = https://github.com/precice/fmi-runner
 	branch = main
+[submodule "imported/su2-adapter"]
+	path = imported/su2-adapter
+	url = https://github.com/precice/su2-adapter
+	branch = develop

README.md

@@ -37,6 +37,36 @@ Do not directly edit the content of the submodules from within the website repos
 
 If you would like to learn more about the preCICE documentation, a good start are the [documentation of the documentation pages](https://precice.org/docs-meta-overview.html).
 
+## Changing the news banner
+
+Edit [`_includes/news_banner.html`](_includes/news_banner.html).
+
+A good starting point is the following:
+
+```html
+<div class="background-light banner-container">
+  <div class="container">
+    <div class="row no-margin">
+      <div class="col-lg-12 banner">
+        <p class="no-margin">
+          This is the text of my news banner.
+        </p>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+Use the following to selectively change appearance.
+
+```html
+{% if include.landing %}
+  Displayed on the landing page.
+{% else %}
+  Displayed on other pages.
+{% endif %}
+```
+
 ## Common issues while building the site
 
 * If you get permission issues to install gems, resist the impulse of `sudo`: you can install the dependencies locally by running `bundle config set --local path 'vendor/bundle'` before `bundle install`.

_config.yml

@@ -174,6 +174,18 @@ defaults:
       topnav: topnav
       toc: true
       github_editme_path: https://github.com/precice/fmi-runner/edit/main/ # ends in /
+  -
+    scope:
+      path: "imported/su2-adapter/"
+      type: "pages"
+    values:
+      layout: "page"
+      comments: false
+      search: true
+      sidebar: docs_sidebar
+      topnav: topnav
+      toc: true
+      github_editme_path: https://github.com/precice/su2-adapter/edit/develop/ # ends in /
   -
     scope:
       path: "pages/community"
@@ -252,6 +264,7 @@ subprojects:
   - imported/micro-manager/docs
   - imported/fmi-runner/docs
   - imported/aste/docs
+  - imported/su2-adapter/docs
 
 # We use these versions to centrally update links
 # and other version-specific information.

_includes/news_banner.html

@@ -1,14 +1,6 @@
-{% comment %}{% raw %}
-
-For landing-only news use:
 {% if include.onlanding %}
-
-For news visible on all pages use:
-{% if true %}.
-
-{% endraw %}{% endcomment %}
-
-{% if true %}
+{% else %}
+{% endif %}
 
 <div class="background-light banner-container">
   <div class="container">
@@ -21,5 +13,3 @@
     </div>
   </div>
 </div>
-
-{% endif %}

_layouts/landing_page.html

@@ -12,7 +12,7 @@
 		<!-- News banner -->
     {% include news_banner.html onlanding=true %}
 
-		<!-- Page Content -->
+    <!-- Page Content -->
 		{{content}}
 	</main>
 

pages/docs/configuration/configuration-coupling.md

@@ -78,11 +78,11 @@ For implicit coupling, you need to specify several additional options:
 </coupling-scheme:parallel-implicit>
 ```
 
-To control the number of sub-iterations within an implicit coupling loop, you can specify the maximum number of iterations, `max-iterations` and you can specify one or several **convergence measures**:
+To control the number of sub-iterations within an implicit coupling loop, you can specify the minimum and maximum number of iterations using `min-iterations` and `max-iterations` and you can specify one or several **convergence measures**:
 
 * `relative-convergence-measure` for a relative criterion
 * `absolute-convergence-measure` for an absolute criterion
-* `min-iteration-convergence-measure` to require a minimum of iterations
+* `absolute-or-relative-convergence-measure` for a combined absolute and relative criterion
 If multiple convergence measure are combined they all need to be fulfilled to go to the next time window. Alternatively, you can specify `suffices="yes"` within any convergence measure.
 The data used for a convergence measure needs to be exchanged within the coupling-scheme (tag `exchange`).
 

pages/docs/configuration/configuration-xml-reference.md

@@ -2,7 +2,7 @@
 title: XML reference
 permalink: configuration-xml-reference.html
 keywords: configuration, xml, reference
-summary: "On this page you find the complete configuration references of preCICE API."
+summary: "This side contains the full reference of the XML configuration of preCICE, containing the tag structure as well as attributes and their types and values."
 ---
 
 {% warning %}

pages/docs/couple-your-code/couple-your-code-time-step-sizes.md

@@ -75,6 +75,48 @@ This procedure is independent of whether a serial or a parallel coupling scheme
 For parallel coupling, both solvers run together and everything happens simultaneously in both participants, while for serial coupling, the first participant needs reach the end of the window before the second one can start.
 {% endnote %}
 
+### Possible subcycling pitfall
+
+If you are using very many small time steps in one window, you might see the following warning:
+
+```txt
+preCICE just returned a maximum time step size of <SOME DT>. Such a small value can happen if you use many sub steps per time window over multiple time windows due to added-up differences of machine precision.
+```
+
+The last time step ended up close to the end of the time-window without reaching it, leading to a very small final time step.
+Such small time steps can lead to problems in the solver.
+
+One strategy to avoid this situation is to extend the last time step of a time window preventing problematic time step sizes.
+The follow example extends the time step negotiation between the solver and preCICE to ensure the next time step size `preciceDt - solverDt` stays over some threshold `minDt`.
+
+```cpp
+...
+solverDt = beginTimeStep(); // e.g. compute adaptive dt
+// Can lead to using a dt that only approximately reaches end of time window
+// dt = min(preciceDt, solverDt);
+
+// Specify a minimal time step size
+double minDt = 10e-14;
+if (preciceDt - solverDt < minDt) {
+  // The next time step would be too small or surpass the end
+  dt = preciceDt;
+} else {
+  dt = solverDt;
+}
+precice.readData("FluidMesh", "Displacements", vertexIDs, dt, displacements);
+setDisplacements(displacements);
+solveTimeStep(dt);
+computeForces(forces);
+precice.writeData("FluidMesh", "Forces", vertexIDs, forces);
+// if dt = preciceDt, we will exactly reach the end of the window when calling advance
+precice.advance(dt);
+...
+```
+
+{% note %}
+The strategy presented above is only one possibility. Generally, the participant knows best how to determine the allowed time step size and there often are additional requirements you might want to consider, depending on the use case and discretization techniques the participant is using.
+{% endnote %}
+
 ## First participant prescribes time step size
 
 The `first` participant sets the time step size. This requires that the `second` participant runs after the `first` one. Thus, as stated above, this option is only applicable for serial coupling.

pages/docs/docs-meta/docs-meta-overview.md

@@ -135,16 +135,19 @@ External repositories are included as Git submodules, specified in the [`.gitmod
 
 To fetch content from an external repository/project (replace the `my-*` with the actual names):
 
-1. Specify the new module: `git submodule add https://github.com/precice/my-project imported/my-project`.
-2. Set the branch to track, if not the default: `git submodule set-branch --default my-branch imported/my-project`. This is particularly useful in case you are adding new documentation via a pull request. However, remember to reset the branch after merging.
-3. The above commands should have modified the `.gitmodules` file and staged changes. Commit the result and push.
-4. Update all submodules with `git submodule update --remote --merge`. If successful, you should see your new project in the `imported/` directory.
-5. In your GitHub pull request to the website, at the "files changed" view, you should see a submodule with a Git reference to your new project in the `imported/` directory.
+1. Switch to a new branch of the website and specify the new module: `git submodule add https://github.com/precice/my-project imported/my-project`.
+2. Set the branch to track, if not the default: `git submodule set-branch --branch my-branch imported/my-project`. This is particularly useful in case you are adding new documentation via a pull request. However, remember to reset the branch after merging.
+3. The above commands should have modified the `.gitmodules` file and staged changes. Commit the result (remember to push later, after testing).
+4. Update all submodules with `git submodule update --remote --merge`. If successful, you should see your new project in the `imported/` directory. Remember that the branch in your external project must already be published.
+5. Update the commit that the module points to: `git add imported/my-project && git commit -m "Update my-project submodule" && git push`. You should only see a `modified: imported/my-project (new commits)` in your `git status`, not the files of that directory.
+6. In your GitHub pull request to the website, at the "files changed" view, you should see a submodule with a Git reference to your new project in the `imported/` directory.
 
 To render the fetched content on the website:
 
 1. In the file [`_config.yml`](https://github.com/precice/precice.github.io/blob/master/_config.yml), specify the newly imported directory in the list of `subprojects:`.
 2. In the same file, add an entry under the `defaults:` list, associating the subproject with some layout, sidebar, a path for the "Edit me" button, and more features.
 3. Remember to make the new pages discoverable, e.g., by adding them to some [sidebar](https://github.com/precice/precice.github.io/tree/master/_data/sidebars), or linking from another page.
 
-To update the content, push to your repository and then [manually trigger the "update submodules" workflow](https://github.com/precice/precice.github.io/actions/workflows/update-submodules.yml). Alternatively, add a GitHub Actions workflows to your repository, to [update the website automatically](https://github.com/precice/tutorials/blob/master/.github/workflows/update-website.yml).
+After you merge the pull request in the external repository, remember to change the brach in the submodule (step 2) and in the `_config.yml` (step 1). If you squash-and-merge the pull request, the commit you were pointing to will not exist anymore. The easiest workaround it to delete the `imported/my-project` folder and update the submodules again (remember to add, commit, and push). You can always check the `git diff` for the commit it will point the submodule to.
+
+To update the content, push to your repository and then [manually trigger the "update submodules" workflow](https://github.com/precice/precice.github.io/actions/workflows/update-submodules.yml). Alternatively, add a GitHub Actions workflows to your repository, to [update the website automatically](https://github.com/precice/tutorials/blob/master/.github/workflows/update-website.yml). You will need to [share the `WORKFLOW_DISPATCH_TOKEN` with the external repository](https://github.com/organizations/precice/settings/secrets/actions).