Tutorial fluid modelling #1385

vlipovac · 2025-03-27T23:39:33Z

Proposed changes

Adding a tutorial for modeling of multiphase and multicomponent fluids.

Changing the configuration of phases to omit the default EquationOfState and hence simplifying the setup for models not relying on EoS computations.

Types of changes

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: Tutorial

Checklist

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.

review-notebook-app · 2025-03-27T23:39:38Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

mariusnevland · 2025-04-03T14:08:16Z

Some high-level comments after the first readthrough:

As a complete newbie to multiphase, multicomponent flow, I do not know e.g. the difference between overall fractions and partial fractions, as well as some other technical terms. Maybe it is a good idea to state some "prerequisites" for the tutorial?
It is unclear to me how to use the heuristic approach in the case of multiple phases and/or components. Did I understand correctly that the default constitutive laws will stop working if I add more phases/components? If so, how can they be redefined?
Regarding the EoS classes, I do not understand how the return_dummy_properties() function should look like in the case of non-trivial phase properties. But otherwise, this code block was very helpful in understanding how to use the EoS framework.
It would be very nice to have an actual runable model in the very end, but would this significantly increase the complexity of the tutorial? Is it possible to construct some "minimal working example" that still introduces most/all of the important functionality, e.g. some relatively simple two-phase, two-component setup?

keileg · 2025-04-03T18:00:01Z

Thanks for the feedback @mariusnevland. I'll have a look and keep your comments in mind.

keileg · 2025-04-04T13:19:42Z

tutorials/fluid_modeling.ipynb

@@ -0,0 +1,935 @@
+{


I think a bit more context will be useful here. Rough ideas (not complete):
What do you mean by a component?
Why do we need to care about the fluid properties (they are part of the transport equations etc.)
This should not take much space, and giving references to more information is certainly fair, but give a bit more context could be very useful for readers.

Would it be an idea to introduce one physical system, say, two-phase two-component water-CO2 that can be followed throughout the tutorial? Sorry if the answer is obviously not.

Question: What is meant by 'respective functionalities'?

Reply via ReviewNB

I have amended this section keeping with regards to your comments.

About the accompanying model, that would require to introduce quite a bit which is not yet part of the core code, essentially I would need a thermodynamic model (either an EoS, or couple of new mixins as some heuristic, simple fluid properties). Then I need to know whether you want something like that being part of a tutorial.

keileg · 2025-04-04T13:19:42Z

tutorials/fluid_modeling.ipynb

@@ -0,0 +1,935 @@
+{


If it is important that the user understands the notion of reference components/phases, more information is needed. If not, can it go?

Reply via ReviewNB

I tried to explain that in the following sentences.

keileg · 2025-04-04T13:19:42Z

tutorials/fluid_modeling.ipynb

@@ -0,0 +1,935 @@
+{


Perhaps move some of this towards the top, to gather such information when natural. Also 'overall fraction' must be defined somewhere.

Reply via ReviewNB

I have introduced links to the respective quantities implemented in the code. The docstring contain sufficient information to make it clear what it is.
Is that fine?

Since this tutorial is a bit extensive, I am trying to not burden it further with formulas and definitions, but focus on the application of the code and link to the respective parts. The documentation of the compositional framework is very extensive, I want to make use of it.

I agree with the overall idea, we are not Wikipedia. Since the links just bring me to the top of the file, perhaps it is better to give this as an instruction, such as 'an explanation can be found in the documentation, see here'.

The link should lead directly to the respective line. Have you tried that in vs code or online?
On my machine, locally in VS code, it leads to the correct line.

keileg · 2025-04-04T13:19:42Z

tutorials/fluid_modeling.ipynb

@@ -0,0 +1,935 @@
+{


How is this class meant to be used?

Reply via ReviewNB

As a pure mixin. Added some extra explanation, here and for MyFluid.

keileg · 2025-04-04T13:19:42Z

tutorials/fluid_modeling.ipynb

@@ -0,0 +1,935 @@
+{


The first paragraph here is a partial answer to the question 'how can we simulate such systems', or 'what happens under the hood in such simulations' - but not necessary to answer how a non-trivial fluid can be modeled in PorePy. Both types of information is relevant, and both can be fit here, but the plan for when to communicate which type is not clear to me.

Reply via ReviewNB

Let's discuss in person.

keileg · 2025-04-04T13:22:23Z

Most important: This will become extremely useful for everyone as we introduce more advanced fluid modeling.

I only managed to read half the tutorial before I had to run, will try to cover the second half no later than Monday. I tried to keep the comments on a high level, it seems to me we should focus on getting the context and general disposition of the tutorial right before getting into details.

keileg · 2025-04-07T06:54:51Z

tutorials/fluid_modeling.ipynb

@@ -0,0 +1,935 @@
+{


Here it should be clearer that the 'EoS approach' refers to the particular implementation in PorePy that wraps the cubic EoS and similar, and not the modeling choice of using an EoS.

Reply via ReviewNB

I am not sure what you mean, because it is made for the choice of using an EoS.

Should I emphasize that in theory it can be used for any computations?

keileg · 2025-04-07T06:54:51Z

tutorials/fluid_modeling.ipynb

@@ -0,0 +1,935 @@
+{


This cell gives a broad answer to the question 'how can I can invoke the EoS framework'? It does not so much answer the related question 'what do I need to do to invoke the EoS framework?' The difference to me is that there are a few contracts I have to fulfill and concepts I have to deal with (some keywords are 'dependencies_of_phase_properties', 'PhysicalState', 'PhaseProperties', and a few others), that are not really introduced, let alone explained. I am not asking for an explanation of the full architecture of the representation of fluids, even if that turns out to be needed it should not be done her. On the other hand, is there a way to explain on a very high lever what are the main components involved in the above code, and how do they interact?

This is also a place where a concrete example would be good to explain how to go from a bunch of zero arrays (cf. the last return statement) to something representing a fluid. However, I realize now that such an example risks being contrived - let's discuss.

Reply via ReviewNB

I have added comments in various code blocks introducing the dependencies, the physical state and the phase properties, with focus on explaining what needs to be done.

keileg · 2025-04-07T06:56:00Z

I left a few more comments. @vlipovac I suggest we discuss how to approach this PR at some point.

vlipovac · 2025-04-10T11:44:58Z

Some high-level comments after the first readthrough:

As a complete newbie to multiphase, multicomponent flow, I do not know e.g. the difference between overall fractions and partial fractions, as well as some other technical terms. Maybe it is a good idea to state some "prerequisites" for the tutorial?

It is unclear to me how to use the heuristic approach in the case of multiple phases and/or components. Did I understand correctly that the default constitutive laws will stop working if I add more phases/components? If so, how can they be redefined?

Regarding the EoS classes, I do not understand how the return_dummy_properties() function should look like in the case of non-trivial phase properties. But otherwise, this code block was very helpful in understanding how to use the EoS framework.

It would be very nice to have an actual runable model in the very end, but would this significantly increase the complexity of the tutorial? Is it possible to construct some "minimal working example" that still introduces most/all of the important functionality, e.g. some relatively simple two-phase, two-component setup?

@mariusnevland

I have added some links in the tutorial to the implementation of various fractions. The docstring take care of the formal definition.
There are a couple of notes after the implementation of FluiDensityFromPressure is discussed, They cover your concerns. It does not stop working, but all phases get the same properties assigned. for more phases, you need to define more functions inside the factory method, and then return the right one depending on the argument phase. Please have a look again and let me know if it is still not clear.
The return dummy is just a placeholder to return some values so that prepare_simulation() can be called. In essence you just have to return a filled PhaseProperties instance with all the values from your computation.
Yes it would, it's not a trivial task to set a thermodynamic model for multiphase flow. I am not sure we want to have that as part of a tutorial, if there is nothing in the source code (so far).

vlipovac added 6 commits March 6, 2025 14:59

TUT: Introducing fluid modeling tutorial.

409bd91

WIP fluid modeling tutorial.

0060d14

Merge branch 'develop' into tutorial_fluid_modelling

6e0bc5d

MOD: Changing the default behavior of get_phase_configurations.

c689015

Merge branch 'develop' into tutorial_fluid_modelling

72dca41

TUT: Finalizing tutorial on fluid modeling.

75fbc66

vlipovac self-assigned this Mar 27, 2025

vlipovac requested review from keileg, IvarStefansson and jwboth as code owners March 27, 2025 23:39

vlipovac and others added 7 commits March 28, 2025 10:16

TUT: Adding another section to fluid modeling tutorial.

774727f

TUT: Fixing minor typos.

d2098c9

TUT: Fixing minor typos.

cc53660

TUT: Fixing minor typos.

6d936ba

TUT: Fix typos in tutorials/Readme.

6171dff

Merge branch 'develop' into tutorial_fluid_modelling

047acb9

Merge branch 'develop' into tutorial_fluid_modelling

9fdf081

IvarStefansson requested a review from mariusnevland April 2, 2025 12:37

Merge branch 'develop' into tutorial_fluid_modelling

86eab7a

keileg reviewed Apr 4, 2025

View reviewed changes

keileg reviewed Apr 7, 2025

View reviewed changes

Merge branch 'develop' into tutorial_fluid_modelling

54eac43

vlipovac added 2 commits April 10, 2025 13:52

TUT: Amending fluid modeling tutorial according review remarks.

487c10a

TUT: Amending fluid modeling tutorial according review remarks.

910b61c

vlipovac added 2 commits April 10, 2025 15:31

Merge branch 'develop' into tutorial_fluid_modelling

3cadec7

Merge branch 'develop' into tutorial_fluid_modelling

7e56ece

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tutorial fluid modelling #1385

Tutorial fluid modelling #1385

vlipovac commented Mar 27, 2025

review-notebook-app bot commented Mar 27, 2025

mariusnevland commented Apr 3, 2025

keileg commented Apr 3, 2025

keileg Apr 4, 2025 •

edited

Loading

vlipovac Apr 10, 2025 •

edited

Loading

keileg Apr 4, 2025 •

edited

Loading

vlipovac Apr 10, 2025

keileg Apr 4, 2025 •

edited

Loading

vlipovac Apr 10, 2025

keileg Apr 29, 2025

vlipovac Apr 29, 2025

keileg Apr 4, 2025 •

edited

Loading

vlipovac Apr 10, 2025

keileg Apr 4, 2025 •

edited

Loading

vlipovac Apr 10, 2025

keileg commented Apr 4, 2025

keileg Apr 7, 2025 •

edited

Loading

vlipovac Apr 10, 2025

keileg Apr 7, 2025 •

edited

Loading

vlipovac Apr 10, 2025

keileg commented Apr 7, 2025

vlipovac commented Apr 10, 2025

Tutorial fluid modelling #1385

Are you sure you want to change the base?

Tutorial fluid modelling #1385

Conversation

vlipovac commented Mar 27, 2025

Proposed changes

Types of changes

Checklist

review-notebook-app bot commented Mar 27, 2025

mariusnevland commented Apr 3, 2025

keileg commented Apr 3, 2025

keileg Apr 4, 2025 • edited Loading

Choose a reason for hiding this comment

vlipovac Apr 10, 2025 • edited Loading

Choose a reason for hiding this comment

keileg Apr 4, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keileg Apr 4, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keileg Apr 4, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keileg Apr 4, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keileg commented Apr 4, 2025

keileg Apr 7, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keileg Apr 7, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keileg commented Apr 7, 2025

vlipovac commented Apr 10, 2025

keileg Apr 4, 2025 •

edited

Loading

vlipovac Apr 10, 2025 •

edited

Loading

keileg Apr 4, 2025 •

edited

Loading

keileg Apr 4, 2025 •

edited

Loading

keileg Apr 4, 2025 •

edited

Loading

keileg Apr 4, 2025 •

edited

Loading

keileg Apr 7, 2025 •

edited

Loading

keileg Apr 7, 2025 •

edited

Loading