Reference states by jwboth · Pull Request #1696 · pmgbergen/porepy

jwboth · 2026-06-19T09:24:16Z

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

IvarStefansson · 2026-06-19T10:27:17Z

+    """
+    try:
+        value = data[pp.REFERENCE_SOLUTIONS][name].copy()
+    except KeyError as err:


Are we sure we want to have fallback?

I would say no, I prefer to have the code crash on me. @jwboth what do you think?

Update after a chat with @jwboth: A default value will make it possible to take the perturbations of general operators, without having to explicitly set a zero reference on all leaves (in the operator tree sense). This seems like a nice feature to have and will be useful for the initialization. The original implementation will not work, since under parsing this may lead to arithmetic operations with incompatible operands. The solution we ended up with for now is implemented below; this is not elegant and could have been less computationally expensive, but it should do the job for now.

Which types of leaves will this be invoked for? I'm not certain I grasp all possible consequences of this.

@jwboth could you please comment on this one.

IvarStefansson · 2026-06-19T10:28:28Z

        A copy of the values stored at the passed index.

    """
+    if reference:


I think this precedence makes sense. But we need to document the rules for previous time steps and iterates and references somewhere.

Moved all get and set methods to a new module, will document at the module level there.

keileg · 2026-06-29T08:26:35Z

+  - ReferenceOperator: The operator represents a reference value and will evaluate this
+    reference.
+
+When combining the mixins, their behavior is prioritized as follows:


This list, which hopefully is complete, defines the prioritization logic of various operator states. Please review carefully and keep in mind when assessing the rest of the code.

keileg · 2026-06-29T08:29:24Z

        return Scalar(self.solid.porosity, "porosity")


+class CompressibleRockPorosity(pp.PorePyModel):


@IvarStefansson I have not taken a stand on what to do with this class. My initial thought is, do we really need it, or is it 'nice to have'? If its main purpose is as a testing ground for initialization routines, there is information in that.

keileg · 2026-06-29T08:30:24Z

@@ -0,0 +1,353 @@
+"""This module contains helper functions for setting, getting and shifting values in the


This module is the new home for get and set methods (moved from ad_utils). I think that making a move was the right decision, whether this is the right placement is less clear.

keileg · 2026-06-29T08:36:03Z

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

Iterate, TimeDependent and Reference operators are now mixin classes. They have been moved to a separate module, operator_states.
The test suite for these mixin classes has been reworked. The test coverage should be better, as should test documentation.
The get- and set-methods for variable states were moved out of ad_utils to a separate file.
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.

…ion operators

…iables).

…ate module Also make these mixins to be added to operators

…terate

…operators These have been replaced with a more refined suite of tests

jwboth requested review from IvarStefansson and keileg as code owners June 19, 2026 09:24

IvarStefansson reviewed Jun 19, 2026

View reviewed changes

keileg force-pushed the reference-states branch from f854035 to 701148d Compare June 26, 2026 11:40

jwboth mentioned this pull request Jun 27, 2026

Initialization of reference states #1708

Open

13 tasks

keileg force-pushed the reference-states branch from 709f05b to 2a933b4 Compare June 29, 2026 07:42

keileg reviewed Jun 29, 2026

View reviewed changes

keileg force-pushed the reference-states branch from 94e5d80 to b06a169 Compare June 29, 2026 08:31

keileg requested a review from IvarStefansson June 29, 2026 12:27

keileg mentioned this pull request Jun 30, 2026

Fix NameError: pp not defined at runtime in _operator_states.py #1709

Closed

6 tasks

jwboth and others added 17 commits July 2, 2026 09:08

TST: Add tests indicating target behavior for reference and perturbat…

377a641

…ion operators

MAINT: Add new constants for reference solutions

399fdb0

FEAT: Provide getter and setter method for reference states.

d9fad92

MAINT: Connect equation system to getter/setter for references

681902a

FEAT: Add functionality for definining references of ad operators

d91eb2e

MAINT: Correctly parse references of variables

068dde3

FEAT: Add porosity model (serving as example for use of reference var…

cecfead

…iables).

TST: Add test for constitutive laws involving reference values

f204e99

STY: ruff, mypy

deb6408

MAINT: Docs and minor fixes of reference operators

9d41415

DOC: Rules of get_reference helper for operators

83e6a92

MAINT: Move TimeDependent, Iterative and Reference operators to separ…

b70d510

…ate module Also make these mixins to be added to operators

DOC: Improved documentation of mixins for Ad Operator class

08b7344

REFACT: Move Ad Operator helper methods to derived operator module

493ddb5

REFACT: Separate module for Ad Operator get-set methods

3c44e41

DOC: Documentation of Ad operator get-set methods

301a428

TST: Reworked test of time dependent and iterative Ad operators

3a49fc0

keileg added 10 commits July 2, 2026 09:08

TST: Started rework of tests for operator references

f38ebd0

MAINT: Ad operator reference applies also to previous time step and i…

db9dcfa

…terate

TST: Documented test of ad operator reference values

e7930a0

TST: Cleanup of tests for time depnedent and iterative ad operators

7dc3891

TST: Delete old tests for iterative, time dependent and reference ad …

648a7b2

…operators These have been replaced with a more refined suite of tests

MAINT: Documentation, cleanup, typing in derived ad operators

87cc538

MAINT: Renamed derived_operators -> operator_states

d974a6d

STY: Isort, typing

6e80628

MAINT: Import error in operator states module

1899a31

TST: Document tests of reference operators

597109a

keileg force-pushed the reference-states branch from fcc1843 to 597109a Compare July 2, 2026 07:08

		return Scalar(self.solid.porosity, "porosity")


		class CompressibleRockPorosity(pp.PorePyModel):

		@@ -0,0 +1,353 @@
		"""This module contains helper functions for setting, getting and shifting values in the

Uh oh!

Conversation

jwboth commented Jun 19, 2026

Proposed changes

Types of changes

Checklist

Uh oh!

IvarStefansson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

keileg Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

keileg commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

keileg Jun 19, 2026 •

edited

Loading

keileg commented Jun 29, 2026 •

edited

Loading