[SofaImplicitOdeSolver] Rewrite of the static Newton-Raphson ODE solver

[jnbrunet]

This commit rewrites the static ODE solver, implements two additional convergence criteria, improves the documentation of every step found in the "solve" method, and adds useful doxygen documentation of the Newton algorithms executed by the component.

Up until this commit, the only convergence criteria of the static ODE solver were absolute force residual norms, and absolute (displacement) increment norm. Using absolute values for convergence criteria means that the value set by the user is dependent on the simulation scale. For example, setting an absolute displacement norm of 1e-5 might seem enough for a liver mesh set in millimetres, but is definitely not adequate for the same liver using this time a mesh scaled in metres. This is a source of user error, and is probably why many FEM software will use relative convergence criteria.

The two additional criteria are:

1. The relative residual norm |R|/|R0| where |R| is the norm of the force vector after the last Newton iteration, and |R0| is the norm of the force vector after the first Newton iteration.
2. The relative displacement norm |dx|/|U| where |dx| is the norm of the latest solution vector, and |U| is the norm of the sum over all previous solution vectors of the current time step.

To remove any confusion between absolute and relative criteria, the convergence data field "correction_tolerance_threshold" and "residual_tolerance_threshold" were renamed for "absolute_correction_tolerance_threshold" and "absolute_residual_tolerance_threshold", respectively. Note that to keep a compatibility layer with older scene files, these old data field names are still available, but a deprecated warning is shown to the user, inviting him to update its scene.

[ci-depends-on https://github.com/sofa-framework/SofaPython3/pull/147]

EDIT: Fix #224

---

By submitting this pull request, I acknowledge that
I have read, understand, and agree SOFA Developer Certificate of Origin (DCO).

---

Reviewers will merge this pull-request only if

• it builds with SUCCESS for all platforms on the CI.
• it does not generate new warnings.
• it does not generate new unit test failures.
• it does not generate new scene test failures.
• it does not break API compatibility.
• it is more than 1 week old (or has fast-merge label).

[jnbrunet]

Setting back to WIP after a quick review

1. absolute and relative residual are inverted in the convergence checks
2. Missing the divergence test when the residual is growing
3. I will add unit tests for relative norms

[jnbrunet]

[ci-build][with-all-tests]

[alxbilger]

Excellent PR. Thanks a lot for all the details you wrote in the comment. It helps a lot to understand all the steps of a solver, and how to execute them in Sofa.

I am really concerned about this operator. It hides a lot of steps, and it is easy to miss it. So thanks again to highlight it in the comments.

Cosmetic: use Allman style (brace associated with a control statement on the next line)

[jnbrunet]

Thanks a lot for the review @alxbilger

I am really concerned about this operator. It hides a lot of steps, and it is easy to miss it.

Totally agree with you here.

[jnbrunet]

[ci-build][with-all-tests]

[fredroy]

Seems OK, could you just rebase/merge with master to remove the failed CUDA/whatever scenes? Just to be in the clear.

[jnbrunet]

[ci-build][with-all-tests]

[sofabot]

[ci-depends-on] detected during build #10.

To unlock the merge button, you must

• Merge or close [Examples] Update the advanced timer scene following changes made in the Static ODE solve SofaPython3#147
  For this build, SofaPython3/ExternalProjectConfig.cmake.in will be edited by builders with
  GIT_REPOSITORY https://github.com/sofa-framework/SofaPython3
  GIT_TAG 56f8258ff0b6d1f19d24f2231eb3868d7b10fa31

[sofabot]

[ci-depends-on] detected during build #11.

To unlock the merge button, you must

• Merge or close [Examples] Update the advanced timer scene following changes made in the Static ODE solve SofaPython3#147
  For this build, SofaPython3/ExternalProjectConfig.cmake.in will be edited by builders with
  GIT_REPOSITORY https://github.com/sofa-framework/SofaPython3
  GIT_TAG 56f8258ff0b6d1f19d24f2231eb3868d7b10fa31

[sofabot]

[ci-depends-on] detected during build #12.

To unlock the merge button, you must

• Merge or close [Examples] Update the advanced timer scene following changes made in the Static ODE solve SofaPython3#147
  For this build, SofaPython3/ExternalProjectConfig.cmake.in will be edited by builders with
  GIT_REPOSITORY https://github.com/sofa-framework/SofaPython3
  GIT_TAG 56f8258ff0b6d1f19d24f2231eb3868d7b10fa31

[sofabot]

[ci-depends-on] detected during build #13.

To unlock the merge button, you must

• Merge or close [Examples] Update the advanced timer scene following changes made in the Static ODE solve SofaPython3#147
  For this build, SofaPython3/ExternalProjectConfig.cmake.in will be edited by builders with
  GIT_REPOSITORY https://github.com/sofa-framework/SofaPython3
  GIT_TAG 56f8258ff0b6d1f19d24f2231eb3868d7b10fa31

[sofabot]

[ci-depends-on] detected during build #14.

To unlock the merge button, you must

• Merge or close [Examples] Update the advanced timer scene following changes made in the Static ODE solve SofaPython3#147
  For this build, SofaPython3/ExternalProjectConfig.cmake.in will be edited by builders with
  GIT_REPOSITORY https://github.com/sofa-framework/SofaPython3
  GIT_TAG 56f8258ff0b6d1f19d24f2231eb3868d7b10fa31

[jnbrunet]

[ci-build]

[guparan]

[ci-build]

[sofabot]

[ci-depends-on] detected during build #20.

All dependencies are merged/closed and all ExternalProject pointers are up-to-date. Congrats! 👍