Equation- and variable-based convergence checks

[mariusnevland]

Proposed changes

Regarding issue #1441. This PR introduces the option to filter residual and increment norms by equations and variables, respectively, to be used in the convergence checks. This PR introduces a separate mixin allowing to switch between the standard convergence check and a multiphysics one.

Minor breaking change: reference_residual is removed from the signature of the check_convergence method. Upstream adaptations are made to cleanup.

Types of changes

What types of changes does this PR introduce to PorePy?
Put an x in the boxes that apply.

• Minor change (e.g., dependency bumps, broken links).
• Bugfix (non-breaking change which fixes an issue).
• New feature (non-breaking change which adds functionality).
• Breaking change (fix or feature that would cause existing functionality to not work as expected).
• Testing (contribution related to testing of existing or new functionality).
• Documentation (contribution related to adding, improving, or fixing documentation).
• Maintenance (e.g., improve logic and performance, remove obsolete code).
• Other:

Checklist

Put an x in the boxes that apply or explain briefly why the box is not relevant.

• The documentation is up-to-date.
• Static typing is included in the update.
• This PR does not duplicate existing functionality.
• The update is covered by the test suite (including tests added in the PR).
• If new skipped tests have been introduced in this PR, pytest was run with the --run-skipped flag.

[jwboth]

Next steps:

• Extend one multiphysics tutorial (e.g. poromechanics) and add a section on multiphysics convergence checks/norms. Showcase how to setup the model and run with mulitphysics norms by using mixins and assigning tolerances. This will help both to provide a structure for how to extend some tests in the suite, as well as provide a documentation/introduction.
• Extend the docstrings of check_convergence and provide a description of the relative norm concept and how it manages the convergence check, including hints what keywords to use in the parameter dictionary.
• Remove the use of a reference residual in old and new check_convergence (and upstream). The choice of the relative residual etc. is not taken care of by check_convergence.
• Apply multiphysics norms to an existing test. I suggest test_pull_south_positive_reference_pressure as it aims at non-trivial solution state.
• Fix typing and mypy issues.
• Synchronize with latest addition of divergence criterion.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[Copilot]

Pull Request Overview

This PR refactors convergence checking in PorePy by introducing multiphysics norms that allow filtering of residual and increment norms by equations and variables while removing the redundant reference_residual argument. Key changes include:

• Updating the convergence check to use multiphysics-specific norms by introducing a new mixin.
• Removing the reference_residual parameter from the signature of check_convergence throughout the code and tests.
• Enhancing tutorial notebooks and tests to compare solver statistics (e.g., nonlinear iterations) and residual norms for the two convergence approaches.

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tutorials/poromechanics.ipynb	Adds markdown cells and examples illustrating multiphysics convergence checks with plots and iteration comparisons.
tests/numerics/test_time_step_control.py	Removes the reference_residual parameter from check_convergence.
tests/numerics/nonlinear/test_nonlinear_solvers.py	Updates the check_convergence signature accordingly.
tests/models/test_solution_strategy.py	Updates check_convergence calls to remove reference_residual.
tests/models/test_poromechanics.py	Adds a new test to compare model outputs with multiphysics norms.
src/porepy/numerics/nonlinear/nonlinear_solvers.py	Removes extraction and passing of reference_residual in the Newton solver routine.
src/porepy/numerics/linear_solvers.py	Adjusts the check_convergence call to eliminate the unnecessary reference_residual.

Comments suppressed due to low confidence (2)

tutorials/poromechanics.ipynb:513

• The printed iteration counts (original model: 9, tailored criteria: 2) appear inconsistent with the accompanying explanation stating that the multiphysics norms lead to additional iterations. Please verify the intended behavior and update either the print output or the explanatory text to ensure consistency.

    "print(f\"Number of iterations (original model): {model.nonlinear_solver_statistics.num_iteration}\")\n",

src/porepy/numerics/nonlinear/nonlinear_solvers.py:101

• The removal of the 'reference_residual' argument from the check_convergence call appears correct; please ensure that all related documentation and usage examples across the codebase reflect this update to avoid potential confusion.

                nonlinear_increment, residual, self.params

[IvarStefansson]

Partial review. This is going to be great! Main concern: The new check_convergence method is quite long and has a somewhat convoluted logic. I'll return to this in a separate review. In the meantime, please consider my other comments.

[jwboth]

@keileg if you are still motivated that the division by the size dissappears in the definition of the norms, please take a look at the corresponding issue description #1441 The links will guide you to alternative computations of norms using L2 integrals.

[jwboth]

@keileg if you are still motivated that the division by the size dissappears in the definition of the norms, please take a look at the corresponding issue description #1441 The links will guide you to alternative computations of norms using L2 integrals.

The recent updates extend the code to use L2 norms. One needs to discuss whether these should fully replace Euclidean norms. I left both options for now, requiring input from the user in form of providing the right mixin defining norm definitions.

[jwboth]

Remaining discussion points for discussion with @IvarStefansson @keileg:

• Design of NewtonSolver.__init__()
• How to start counting from 0 across PP
• Implications of norms on the use of LineSearch

Now may be the best timing to also consider the right names for some of the central objects introduced in this PR:

• metric vs norm
• Lebesgue vs L2
• Euclidean vs ???
• ConvergenceStatus?
• SimulationStatus?
• Flags for status?