From 4706f96d1e0c65ff6fea48431537a650f0ff1439 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Tue, 2 Apr 2024 15:31:40 +0200 Subject: [PATCH 01/11] Rewrite coupling-data section --- .../configuration-acceleration.md | 24 +++++++++++++------ 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index 2de8468a4b8..084ae6ff2ea 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -26,17 +26,27 @@ All data communicated within a coupling scheme needs to be configured through `e ``` -The acceleration modifies coupling data in `advance()`. This means, what you write to preCICE on the one participant is not the same with what you read on the other participant. The data values are stabilized (or "accelerated") instead. This happens also by using values from previous iterations. Simply think of a linear combination of previous iterations. +The acceleration modifies coupling data in `advance()`, meaning, written values by the one participant are not the same when read by the another participant. The values are stabilized (or "accelerated") based on a linear combination of previous iterations. -* For a **parallel coupling**, all coupling data is post-processed the same way. This means all coupling data use the same coefficients for the linear combination. -* For a **serial coupling** only coupling that is exchanged from the `second` to the `first` participant is post-processed. Coupling data exchanged in the other direction (from `first` to `second`) is not modified. +* For a **parallel coupling**, all coupling data is accelerated the same way. This means all coupling data use the same coefficients for the linear combination. +* For a **serial coupling** only coupling that is exchanged from the `second` to the `first` participant is accelerated. Coupling data exchanged in the other direction (from `first` to `second`) is not modified. -Let's look at an example: For fluid-structure interaction, if we first execute the fluid solver with given interface displacements followed by the structure solver taking forces from the fluid solver and computing new interface displacements, (only) the displacements are post-processed in case of serial coupling. For parallel coupling, both displacements and forces are post-processed. +{% example %} +For fluid-structure interaction, if we first execute the fluid solver with given interface displacements followed by the structure solver taking forces from the fluid solver and computing new interface displacements, (only) the displacements are accelerated in case of serial coupling. For parallel coupling, both displacements and forces are accelerated. +{% endexample %} -Next, we have to configure based on which data the acceleration computes, i.e. how the coefficients in the linear combinations get computed. These data fields are defined within the acceleration as `data` tags (such as `Displacements` in the code example above). Let's call these data fields **primary data**. (Just for completeness: All coupling data that gets post-processed and that is not primary data, is called "secondary data".) +Different acceleration schemes compute these coefficients in different ways, which can be grouped into two categories: -* For **serial coupling**, you can only configure one primary data field, which should correspond to a coupling data field that is exchanged from the `second` to the `first` participant. In the FSI example, the `Displacements`. -* For **parallel coupling**, an arbitrary number of primary data can be configured. For numerical performance reasons, you should define at least one coupling data field of each direction (one from `second` to `first`, one from `first` to `second`). In the FSI example, configure `Displacements` and `Forces`. +* Coefficients are fixed for each iteration, thus independent of the accelerated values. Example being constant under-relaxation. +* Coefficients depend on the values of previous iterations. Example being Interface Quasi-Newton methods. + +Data-dependent acceleration schemes need to select which data to compute these coefficients from by listing them as `data` tags inside the `acceleration` tag. +We call data which influences the coefficients **primary data** and data which is accelerated without influencing the coefficients **secondary data**. +In the code example above, `Displacements` is primary data and `Forces` is secondary data. +Which data may be configured depends on the coupling scheme: + +* For **serial coupling**, you can only configure primary data from coupling data which is exchanged from the `second` to the `first` participant. In the FSI example, the `Displacements`. +* For **parallel coupling**, all coupling data is available as primary data. For numerical performance reasons, you should define at least one coupling data field of each direction (one from `second` to `first`, one from `first` to `second`). In the FSI example, configure `Displacements` and `Forces`. Now, we know the difference between coupling data and primary data. Next, we have a look on how we actually configure the type of acceleration. From e9bac7672a32cf5d0ecda5a40d135f54587a7c43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Tue, 2 Apr 2024 16:29:25 +0200 Subject: [PATCH 02/11] Unblock the example --- pages/docs/configuration/configuration-acceleration.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index 084ae6ff2ea..b070444f9f8 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -31,9 +31,7 @@ The acceleration modifies coupling data in `advance()`, meaning, written values * For a **parallel coupling**, all coupling data is accelerated the same way. This means all coupling data use the same coefficients for the linear combination. * For a **serial coupling** only coupling that is exchanged from the `second` to the `first` participant is accelerated. Coupling data exchanged in the other direction (from `first` to `second`) is not modified. -{% example %} -For fluid-structure interaction, if we first execute the fluid solver with given interface displacements followed by the structure solver taking forces from the fluid solver and computing new interface displacements, (only) the displacements are accelerated in case of serial coupling. For parallel coupling, both displacements and forces are accelerated. -{% endexample %} +**Example:** For fluid-structure interaction, if we first execute the fluid solver with given interface displacements followed by the structure solver taking forces from the fluid solver and computing new interface displacements, (only) the displacements are accelerated in case of serial coupling. For parallel coupling, both displacements and forces are accelerated. Different acceleration schemes compute these coefficients in different ways, which can be grouped into two categories: From 409ceb54370ec94335302f5004b4167a83802934 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Fri, 5 Apr 2024 16:32:16 +0200 Subject: [PATCH 03/11] Rewrote the categories into generally+exception --- pages/docs/configuration/configuration-acceleration.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index b070444f9f8..0309b2e596c 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -33,12 +33,11 @@ The acceleration modifies coupling data in `advance()`, meaning, written values **Example:** For fluid-structure interaction, if we first execute the fluid solver with given interface displacements followed by the structure solver taking forces from the fluid solver and computing new interface displacements, (only) the displacements are accelerated in case of serial coupling. For parallel coupling, both displacements and forces are accelerated. -Different acceleration schemes compute these coefficients in different ways, which can be grouped into two categories: +Different acceleration schemes compute these coefficients in different ways. +They are generally based on the values of previous iterations. +A notable exception is the constant under-relaxation, which used fixed coefficients. -* Coefficients are fixed for each iteration, thus independent of the accelerated values. Example being constant under-relaxation. -* Coefficients depend on the values of previous iterations. Example being Interface Quasi-Newton methods. - -Data-dependent acceleration schemes need to select which data to compute these coefficients from by listing them as `data` tags inside the `acceleration` tag. +Such value-dependent acceleration schemes need to select which data to compute these coefficients from by listing them as `data` tags inside the `acceleration` tag. We call data which influences the coefficients **primary data** and data which is accelerated without influencing the coefficients **secondary data**. In the code example above, `Displacements` is primary data and `Forces` is secondary data. Which data may be configured depends on the coupling scheme: From 579e74feda14f07bcfcc0f8192658f48b0dcfaae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Fri, 5 Apr 2024 16:41:19 +0200 Subject: [PATCH 04/11] Clarify that secondary data is implied --- pages/docs/configuration/configuration-acceleration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index 0309b2e596c..cb30e134ff5 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -39,6 +39,7 @@ A notable exception is the constant under-relaxation, which used fixed coefficie Such value-dependent acceleration schemes need to select which data to compute these coefficients from by listing them as `data` tags inside the `acceleration` tag. We call data which influences the coefficients **primary data** and data which is accelerated without influencing the coefficients **secondary data**. +The former is explicitly listed in the `acceleration` using `data` tags, while the latter is implied by the primary data and the configured coupling scheme. In the code example above, `Displacements` is primary data and `Forces` is secondary data. Which data may be configured depends on the coupling scheme: From 35fb06b46edb78577b66c8df02b87f9460df8631 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Fri, 5 Apr 2024 18:58:14 +0200 Subject: [PATCH 05/11] Fix typo Co-authored-by: Gerasimos Chourdakis --- pages/docs/configuration/configuration-acceleration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index cb30e134ff5..06e2cc17560 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -35,7 +35,7 @@ The acceleration modifies coupling data in `advance()`, meaning, written values Different acceleration schemes compute these coefficients in different ways. They are generally based on the values of previous iterations. -A notable exception is the constant under-relaxation, which used fixed coefficients. +A notable exception is the constant under-relaxation, which uses fixed coefficients. Such value-dependent acceleration schemes need to select which data to compute these coefficients from by listing them as `data` tags inside the `acceleration` tag. We call data which influences the coefficients **primary data** and data which is accelerated without influencing the coefficients **secondary data**. From 6ca30705994cc730f533d656466bc65f1465ae21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Tue, 9 Apr 2024 15:25:24 +0200 Subject: [PATCH 06/11] Add Density to FSI example and reformat config --- pages/docs/configuration/configuration-acceleration.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index 06e2cc17560..3ec32bcafd1 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -17,7 +17,8 @@ All data communicated within a coupling scheme needs to be configured through `e - + + ... @@ -40,12 +41,14 @@ A notable exception is the constant under-relaxation, which uses fixed coefficie Such value-dependent acceleration schemes need to select which data to compute these coefficients from by listing them as `data` tags inside the `acceleration` tag. We call data which influences the coefficients **primary data** and data which is accelerated without influencing the coefficients **secondary data**. The former is explicitly listed in the `acceleration` using `data` tags, while the latter is implied by the primary data and the configured coupling scheme. -In the code example above, `Displacements` is primary data and `Forces` is secondary data. Which data may be configured depends on the coupling scheme: * For **serial coupling**, you can only configure primary data from coupling data which is exchanged from the `second` to the `first` participant. In the FSI example, the `Displacements`. * For **parallel coupling**, all coupling data is available as primary data. For numerical performance reasons, you should define at least one coupling data field of each direction (one from `second` to `first`, one from `first` to `second`). In the FSI example, configure `Displacements` and `Forces`. +In the code example above, `Displacements` is primary data and `Density` is secondary data. `Forces` is not accelerated as the case uses a serial coupling scheme. +Changing the `serial-implicit` to a `parallel-implicit` scheme would turn `Forces` into secondary data. + Now, we know the difference between coupling data and primary data. Next, we have a look on how we actually configure the type of acceleration. ## Constant under-relaxation From 491c7c96c2399423a6cb8c078d75dc961233f987 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Fri, 12 Apr 2024 16:48:27 +0200 Subject: [PATCH 07/11] Typo Co-authored-by: Benjamin Uekermann --- pages/docs/configuration/configuration-acceleration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index 3ec32bcafd1..ccf5566a9e3 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -27,7 +27,7 @@ All data communicated within a coupling scheme needs to be configured through `e ``` -The acceleration modifies coupling data in `advance()`, meaning, written values by the one participant are not the same when read by the another participant. The values are stabilized (or "accelerated") based on a linear combination of previous iterations. +The acceleration modifies coupling data in `advance()`, meaning, written values by the one participant are not the same when read by another participant. The values are stabilized (or "accelerated") based on a linear combination of previous iterations. * For a **parallel coupling**, all coupling data is accelerated the same way. This means all coupling data use the same coefficients for the linear combination. * For a **serial coupling** only coupling that is exchanged from the `second` to the `first` participant is accelerated. Coupling data exchanged in the other direction (from `first` to `second`) is not modified. From 2b07f910434a2f8505498149b382c9cb8c94490d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Fri, 12 Apr 2024 16:50:25 +0200 Subject: [PATCH 08/11] Missing comma Co-authored-by: Benjamin Uekermann --- pages/docs/configuration/configuration-acceleration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index ccf5566a9e3..7efbfa607c6 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -30,7 +30,7 @@ All data communicated within a coupling scheme needs to be configured through `e The acceleration modifies coupling data in `advance()`, meaning, written values by the one participant are not the same when read by another participant. The values are stabilized (or "accelerated") based on a linear combination of previous iterations. * For a **parallel coupling**, all coupling data is accelerated the same way. This means all coupling data use the same coefficients for the linear combination. -* For a **serial coupling** only coupling that is exchanged from the `second` to the `first` participant is accelerated. Coupling data exchanged in the other direction (from `first` to `second`) is not modified. +* For a **serial coupling**, only coupling that is exchanged from the `second` to the `first` participant is accelerated. Coupling data exchanged in the other direction (from `first` to `second`) is not modified. **Example:** For fluid-structure interaction, if we first execute the fluid solver with given interface displacements followed by the structure solver taking forces from the fluid solver and computing new interface displacements, (only) the displacements are accelerated in case of serial coupling. For parallel coupling, both displacements and forces are accelerated. From 61c52e6dd983a43d87264a22001ca9cb16fe619b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Fri, 12 Apr 2024 16:51:33 +0200 Subject: [PATCH 09/11] Replace density with velocities --- pages/docs/configuration/configuration-acceleration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index 7efbfa607c6..97eb530bcd3 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -17,7 +17,7 @@ All data communicated within a coupling scheme needs to be configured through `e - + ... @@ -46,7 +46,7 @@ Which data may be configured depends on the coupling scheme: * For **serial coupling**, you can only configure primary data from coupling data which is exchanged from the `second` to the `first` participant. In the FSI example, the `Displacements`. * For **parallel coupling**, all coupling data is available as primary data. For numerical performance reasons, you should define at least one coupling data field of each direction (one from `second` to `first`, one from `first` to `second`). In the FSI example, configure `Displacements` and `Forces`. -In the code example above, `Displacements` is primary data and `Density` is secondary data. `Forces` is not accelerated as the case uses a serial coupling scheme. +In the code example above, `Displacements` is primary data and `Velocities` is secondary data. `Forces` is not accelerated as the case uses a serial coupling scheme. Changing the `serial-implicit` to a `parallel-implicit` scheme would turn `Forces` into secondary data. Now, we know the difference between coupling data and primary data. Next, we have a look on how we actually configure the type of acceleration. From 3ee915918436347e008e856653a44cc2ffb37525 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Simonis?= Date: Fri, 12 Apr 2024 16:53:45 +0200 Subject: [PATCH 10/11] Ignore velocities --- pages/docs/configuration/configuration-acceleration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index 97eb530bcd3..45b4703af81 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -32,7 +32,7 @@ The acceleration modifies coupling data in `advance()`, meaning, written values * For a **parallel coupling**, all coupling data is accelerated the same way. This means all coupling data use the same coefficients for the linear combination. * For a **serial coupling**, only coupling that is exchanged from the `second` to the `first` participant is accelerated. Coupling data exchanged in the other direction (from `first` to `second`) is not modified. -**Example:** For fluid-structure interaction, if we first execute the fluid solver with given interface displacements followed by the structure solver taking forces from the fluid solver and computing new interface displacements, (only) the displacements are accelerated in case of serial coupling. For parallel coupling, both displacements and forces are accelerated. +**Example:** For fluid-structure interaction ignoring the velocities, if we first execute the fluid solver with given interface displacements followed by the structure solver taking forces from the fluid solver and computing new interface displacements, (only) the displacements are accelerated in case of serial coupling. For parallel coupling, both displacements and forces are accelerated. Different acceleration schemes compute these coefficients in different ways. They are generally based on the values of previous iterations. From e353c8357c9753d322bc74c6cb40cc80e428f471 Mon Sep 17 00:00:00 2001 From: Benjamin Uekermann Date: Mon, 15 Apr 2024 16:26:53 +0200 Subject: [PATCH 11/11] Update pages/docs/configuration/configuration-acceleration.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Frédéric Simonis --- pages/docs/configuration/configuration-acceleration.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pages/docs/configuration/configuration-acceleration.md b/pages/docs/configuration/configuration-acceleration.md index 45b4703af81..2f45bf13e85 100644 --- a/pages/docs/configuration/configuration-acceleration.md +++ b/pages/docs/configuration/configuration-acceleration.md @@ -48,6 +48,8 @@ Which data may be configured depends on the coupling scheme: In the code example above, `Displacements` is primary data and `Velocities` is secondary data. `Forces` is not accelerated as the case uses a serial coupling scheme. Changing the `serial-implicit` to a `parallel-implicit` scheme would turn `Forces` into secondary data. +As mentioned above, this is a theoretical setup as one primary data per direction is highly encouraged. +Hence, `Forces` should be marked primary as well. Now, we know the difference between coupling data and primary data. Next, we have a look on how we actually configure the type of acceleration.