Skip to content

Add documentation to set methods for bound violation in QN acceleration #861

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Fujikawas wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add documentation to set methods for bound violation in QN acceleration #861

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f7beae3
Add documentation to set methods for bound violation in QN acceleration
Fujikawas Mar 19, 2026
82dacba
explain the options
Fujikawas Mar 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions content/docs/configuration/basics/configuration-acceleration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ For some cases, the default settings are not sufficient and a more detailed conf
For `IQN-ILS`, the complete configuration with all options specified explicitly to the default settings is as follows:

```xml
<acceleration:IQN-ILS reduced-time-grid="true">
<acceleration:IQN-ILS reduced-time-grid="true" on-bound-violation="scale">
<data name="Displacements" mesh="StructureMesh"/>
<data name="Forces" mesh="StructureMesh"/>
<preconditioner type="residual-sum" update-on-threshold="true" freeze-after="-1"/>
Expand All @@ -133,7 +133,7 @@ For `IQN-ILS`, the complete configuration with all options specified explicitly
and for `IQN-IMVJ`, it is:

```xml
<acceleration:IQN-IMVJ always-build-jacobian="false" reduced-time-grid="true">
<acceleration:IQN-IMVJ always-build-jacobian="false" reduced-time-grid="true" on-bound-violation="scale">
<data name="Displacements" mesh="StructureMesh"/>
<data name="Forces" mesh="StructureMesh"/>
<preconditioner type="residual-sum" update-on-threshold="true" freeze-after="-1"/>
Expand All @@ -149,6 +149,13 @@ For the detailed meaning of the various options, please refer to the [configurat

Here are some brief explanations and hints on good combinations of choices for the configuration options:

* The attribute `on-bound-violation` is used to handle the quasi-Newton(QN) acceleration steps that violate the bound configured for scalar or component(s) of vector under the `data` tag. This attribute can be set to different options to constrain the acceleration step to stay in the bound. The options avaiable are:
* `ignore`: default option. preCICE will not check if the accelerated values are violating the bound, thus no warning etc.
* `discard`: preCICE checks the accelerated values against the given bound(s) after a QN update step is computed. If any violation is found, this update step will be discarded, i.e. next iteration will start with the output from last iteration.
* `clamp`: preCICE checks the accelerated values against the given bound(s) after a QN update step is computed. The violating values will be clamped to the bounds respectively. Non-violating values are not influenced by this check.
* `scale`: preCICE checks the accelerated values against the given bound(s) after a QN update step is computed. If any violation is found, the update from this QN step is scaled by a scalar factor between 0 and 1, to fit all the violating values into the bounded range.

While `discard` and `clamp` are convenient options for single value or occasional bound violation, `scale` helps to retain the direction of the QN step by only shortening the step length. The best option for this attribute is problem-dependent.
Copy link
Copy Markdown
Member

@MakisH MakisH Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ad the bottom of this, a version alert would be useful.

* If several primary data fields are configured, e.g. when parallel coupling is used, an equal order of magnitude of them has to be ensured. This is done by defining a `preconditioner`.
* As `type`, we recommend to use `"residual-sum"` as in the default setting.
* The option `update-on-threshold` can be used to avoid updates of the preconditioner in case of small changes of the preconditioning factors.
Expand Down
Loading