CF Merger #3: Compositional Flow models

vlipovac commented 1 month ago

Draft PR for the next step in including the branch pmgbergen/porepy/tree/composite-flow

This PR contains the compositional flow model, related mixins, as well as the examples provided by @OmarDuran and @mikeljordan

Brine flow based on Driesner correlations
Brine flow using Pure Water correlations
Simple tracer set-up

Disclaimer

This is a draft because there are some steps missing, which need a discussion after recalling the code to be added.

Testing

I assume @OmarDuran and @mikeljordan have respectively thought about tests for their example models.

Unification of notion of `fluid`

The CF models have a generalized notion of fluid allowing multiple phases and components, currently coded as a model attribute fluid_mixture, based on the recently introduced extension porepy.compositional. The (legacy) models have a data structure for fluid constants, on which various constitutive laws are built. After talking with @keileg , the idea is for me to go ahead and propose a way to wrap the existing fluid constants into a generic 1-phase-1-component mixture, which then hopefully will be integrate into the existing models. It is also worthwhile to consider extending the model attribute fluid to be a general FluidMixture, in order to not have two various concepts

NOTE 31-10-2024: Unification is on the way in #1244 NOTE 5-11-2024: Notion of fluid is unified and scripts were adapted correspondingly (see #1252 )

Code unification and recycling with existing `fluid_mass_balance` and `energy_balance`

There is vast space for code recycling, since the CF model currently does many things on its own, which were to a less general degree implemented in the existing fluid and energy models. My sense is that with some minor refactoring, the existing models can be included in the CF.

This point is mainly connected to the notion of fluid, and how to access relevant members such as fluid density, enthalpy etc. But also some thoughts on the advective flux are required (f.e. a general declaration of the non-linear weight, which is in different forms implemented in the existing energy_balance and fluid_mass_balance).

If I am not mistaken, @IvarStefansson this is most relevant for you.

NOTE 31-10-2024: Unification is planned. First, minor steps were taken in #1252 (see https://github.com/pmgbergen/porepy/pull/1252#discussion_r1822289316), more thought on a general AdvectionEquation or something of that sorts is required.

Proposed changes

The file compositional_flow implements the new model and is the main contribution of this PR, and I think it's structure is self-explanatory as to which model parts are introduced and required for a general CF model.

Browsing through the classes representing PDEs you will realize some familiar, to some degree copy-pasted code from the existing balance equations, which motivates the disclaimer about code unification. Please inspect that part rigorously and feel free to suggest and comment anything.

The sub-package porepy/examples/geothermal_flow contains the example models provided by Omar and Michael. Due to my parental leave I am not aware how much you have discussed about how to include them. I put them in this draft since they serve as excellent examples on what is required to set up a CF model.

Types of changes

[ ] Minor change (e.g., dependency bumps, broken links).
[ ] Bugfix (non-breaking change which fixes an issue).
[X] 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

[X] The documentation is up-to-date.
[X] Static typing is included in the update.
[X] 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.

keileg commented 1 month ago

I can take a first look at this to get an overview, then I suggest @IvarStefansson gets involved as the need arise (but not before).

As I mentioned, @vlipovac, it will take a few days before I can look at this in earnest.

vlipovac commented 1 month ago

I fixed as many mypy issues as possible with the current state of type hints in various mixins. This led to some changes in other files, all related to type annotations.

The things I was not able to fix (and after checking with Eirik should wait for protocols) are related to the following mixed-in methods:

wrap_grid_attribute
outwards_internal_boundary_normals
internal_boundary_normal_to_outwards
_combine_boundary_operators
e_i
domain_boundary_sides
load_data_from_pvd
load_data_from_vtu

Most of it is related to type-hinting kwargs with default arguments, for which Callable does not suffice for mypy standards.

Also, type hinting of mixed-in methods decorated with @property requires a protocol-based solution as well.

All remaining mypy-errors stem from the 3 models in examples/geothermal_flow/model_configuration/*.py

pmgbergen / porepy