Reference states

[jwboth]

Proposed changes

This PR introduces an additional state of Variable and TimeDependentDenseArray following the style of previous_iteration and previous_time_step. These now also are able to hold reference values which can be obtained in AD operator form through call of the method op.reference() for any AD operator op, e.g., model.pressure(subdomains).reference(). In addition, perturbations to reference states can be conventiently fetched by op.perturbation_from_reference(). If not set, reference values are 0. No optimization in terms of emtpy operators has been implemented but could be foreseen in near future.

The API for setting values has been extended aiming at canonical extension of current workflows (EquationSystem.set/get_variable_values and pp.set/get_solution_values). An additional keyword reference needs to be set true.

As an example (hopefully of actual value) is added utilizing perturbations from reference states: Porosity with mere rock compressibility simplifying standard two-way coupled poromechanics. It currently mainly serves for testing the potential integration of reference states in models.

NOTE: This PR does not integrate reference states in models and variables like currently proposed in #1686 (initialization). The aim is to base further work on initialization on the current PR.

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.

[IvarStefansson]

Main comment: Think about precendence for reference - time step - iteration

[keileg]

I have done a partial re-implementation of this PR. Main points:

1. Iterate, TimeDependent and Reference operators are now mixin classes. They have been moved to a separate module, operator_states.
2. The test suite for these mixin classes has been reworked. The test coverage should be better, as should test documentation.
3. The get- and set-methods for variable states were moved out of ad_utils to a separate file.
4. The rules of precedence for taking reference, previous iterate and previous time step have been revised and documented at the module level in operator states. I believe the rules are implemented consistently throughout the code base, but this should be carefully examined in the review.

[IvarStefansson]

Mainly very good. Not a huge fan of the new tests, though. Please have a look, then we can discuss if needed.