Add flow-over-heated-plate-particles tutorial by mike-tree-corvid · Pull Request #834 · precice/tutorials

mike-tree-corvid · 2026-06-12T19:40:02Z

add flow-over-heated-plate/fluid-openfoam-basicReactingMultiphaseCloud tutorial case to show verification of implicit coupling of Lagrangian particles

TODO: Summarize and motivate the changes, link to issues, remove the checklist entries that are not relevant.

Checklist

I added a summary of any user-facing changes (compared to the last release) in the changelog-entries/<PRnumber>.md.

For new tutorials or tutorial cases:

I followed the tutorial folder structure
I added/updated the tutorial README.md
I added/updated the tutorial metadata.yaml
I added tests in tools/tests/tests.yaml
I submitted a pull request to the website with:
- An entry in _config.yaml
- A sidebar entry
- An entry in the tutorials overview

…d tutorial case to show verification of implicit coupling of Lagrangian particles

mike-tree-corvid · 2026-06-12T19:41:55Z

corresponds with precice/openfoam-adatper pull request here:

precice/openfoam-adapter#405

precice-bot · 2026-06-12T19:46:06Z

This pull request has been mentioned on preCICE Forum on Discourse. There might be relevant details there:

https://precice.discourse.group/t/does-openfoam-adapter-support-lagrangian-particle-checkpointing/2947/11

MakisH · 2026-06-13T09:43:20Z

Thanks for contributing the tutorial as well! I have not yet looked closer, but the problem setup is different than the current flow-over-heated-plate tutorial, right? In that case, the convention would be to make a separate tutorial directory (e.g., flow-over-heated-plate-particles or similar, whatever describes it best) and describe the case in the respective README.md.

mike-tree-corvid · 2026-06-13T15:34:35Z

Thanks for contributing the tutorial as well! I have not yet looked closer, but the problem setup is different than the current flow-over-heated-plate tutorial, right? In that case, the convention would be to make a separate tutorial directory (e.g., flow-over-heated-plate-particles or similar, whatever describes it best) and describe the case in the respective README.md.

The problem setup is the exact same as the flow-over-heated-plate tutorial with the exception that the necessary files / settings are such that 100 Lagrangian parcels / particles (1 particle per parcel) are injected at time = 0 and are left to propagate through the domain. The intent was to give the particles the same properties as the fluid so that they simply follow the flow rather than affect it, thus making any changes in the solution potential flags for something being wrong with the Lagrangian particle implicit coupling implementation.

I debated whether to slide this contribution under the flow-over-heated-plate tutorial, or make it a stand alone tutorial. I'm happy to do either. Do you want to wait to decide what should be done until you take a closer look, or are you pretty decided that it should be a separate tutorial and I should go ahead and make the change?

MakisH · 2026-06-14T07:11:01Z

I will take a closer look to this tutorial, the adapter PR, and the related discussion in ~a week.

For comparison, we have:

as separate tutorials.

…o" instead of explicit lib for patch injection

…eCloud as its own tutorial flow-over-heated-plate-particles

which are created when openfoam collated file format is used

mike-tree-corvid · 2026-07-07T17:48:46Z

I will take a closer look to this tutorial, the adapter PR, and the related discussion in ~a week.

For comparison, we have:
* [channel transport](https://precice.org/tutorials-channel-transport.html)

* [channel transport with particles](https://precice.org/tutorials-channel-transport-particles.html)
as separate tutorials.

I reformatted this contribution as its own tutorial rather than being a subset of the flow-over-heated-plate tutorial.

Anything else you see that's needed before we can take this off draft status?

MakisH · 2026-07-12T17:48:12Z

@mike-tree-corvid with a quick look, it seems like the structure is fine and I have everything I need to do a review. I am in a different context than OpenFOAM these days, but I will eventually do a detailed review together with the changes in the adapter.

Regarding the CI failure:

flow-over-heated-plate-particles/images/temperature_with_particles.pvsm: 1308 kb exceeds the limit of 750 kb. 
flow-over-heated-plate-particles/images/temperature_with_particles.gif: 3716 kb exceeds the limit of 2200 kb.

if you could reduce a bit the size of the GIF file (e.g., lower frequency), it would be great, otherwise I will see how we can better handle that. The .pvsm file is not something we typically have, but it could be useful. If portable, I will add an exception.

…up less storage space

…articles/images

mike-tree-corvid · 2026-07-13T22:12:31Z

@mike-tree-corvid with a quick look, it seems like the structure is fine and I have everything I need to do a review. I am in a different context than OpenFOAM these days, but I will eventually do a detailed review together with the changes in the adapter.

Regarding the CI failure:
flow-over-heated-plate-particles/images/temperature_with_particles.pvsm: 1308 kb exceeds the limit of 750 kb. 
flow-over-heated-plate-particles/images/temperature_with_particles.gif: 3716 kb exceeds the limit of 2200 kb.
if you could reduce a bit the size of the GIF file (e.g., lower frequency), it would be great, otherwise I will see how we can better handle that. The .pvsm file is not something we typically have, but it could be useful. If portable, I will add an exception.

I coarsened the .gif file so it takes up less space. I removed the .pvsm file.

MakisH

Thank you for all the updates, I think I now understand enough to catch up with the progress here. I added a few minor points and started a thread to discuss where to actually host and render this in the end.

MakisH · 2026-07-14T11:31:45Z

+
+stopAt          endTime;
+
+endTime         20;


Is the t=20 important (here and in the precice-config.xml)? Does it already show clear-enough results earlier? The tutorials are meant to run in <1-2min, unless there is a good reason.

I ran it for 20 seconds to make sure some particles make it from one end of the domain to the other. The particles don't reach the fluid next to the heated plate until t=5. The first particles make it all the way across the heated plate by about t=12. t=20 ran in about 5-6 minutes wall clock time on my setup, but I understand that run times can vary wildly. With that said, I'll set the endTime to whatever you suggest.

MakisH · 2026-07-14T11:39:58Z

This image needs to be updated for the current tutorial, to show the particles. I can do that.

MakisH · 2026-07-14T11:46:08Z

If nothing changes in the preCICE or adapter configuration, there is a question on whether this is best published as a preCICE tutorial, or as an application case, which will later be showcased on the preCICE website. @uekerman what do you think?

Tradeoffs:

as a tutorial:

we maintain it easily, directly here

it is visible next to other tutorials as a regular tutorial

we misuse a bit the role of the tutorials: the user does not learn how to do something different, but that the adapter can handle a certain type of simulations.

as an application case:

you/we maintain it in another repository

it is visible next to other application cases, with your name and details (but that list has not yet been created, besides what we have as examples on the website and under review)

more freedom to shape it as you wish (e.g., longer, more complex, more auxiliary files)

either way:

we showcase that the feature works

we can integrate it into the system tests

it has the same structure, and the only difference is where we render it and who maintains it.

Note that we already discussed the "specialization of the flow-over-heated-plate/fluid-openfoam vs dedicated tutorial", and I still think that this is too complex to be just a specialization.

In any case, the same review process is needed for both, and making it ready for the tutorials is also making it ready to publish as an application case. So I suggest that we continue with the review normally here for now.

MakisH · 2026-07-14T11:54:11Z

 			fi
 		done
-		if [ -d processor0 ]; then
+		if [ -d processor0 ] || [ -d processor* ]; then


What is the motivation for this change? In which situation will processor0 not be there, but other processor* directories will be?

OpenFOAM has the option to collate its file output. By default, OpenFOAM creates a single directory for every processor on which it's run. The system administrator on the systems where I run OpenFOAM didn't like this very much because of the number of small files created by my large simulations, so I run sims using OptimisationSwitches { fileHandler collated; } in my system/controlDict file. This results in a SINGLE processor directory, but the name of the directory changes depending on the number of processors on which the simulation is run. For example, if I run a simulation using 64 procs, the name of the directory is "processors64". If I run a simulation using 128 processors, the name of the directory is "processors128". If one is running with collated file handling they will never have a "processor0" directory.

Ah, I didn't know that, thanks! Then, I guess that renaming processor0 to processor* would cover all cases. I will bring that directly to develop. -> Does not, I will find a more general solution.

MakisH · 2026-07-14T15:32:42Z

+
+The test case is two-dimensional and a serial-implicit coupling with Aitken underrelaxation is used for the coupling.
+
+Proper implicit coupling of Lagrangian particles involves not only accounting for existing particles in the domain during checkpointing, but also adjusting the particle injection logic for implicit coupling loops within time-windows as well. Particle injection is handled in OpenFOAM via injectionModels. injectionModels lie outside the OpenFOAM solver objectRegistry, so they cannot be directly modified by the existing OpenFOAM preCICE adapter functionObject. Therefore, the OpenFOAM preCICE adapter source code was modified to build an additional library, `libImplicitInjectors.so`. `libImplicitInjectors.so` contains "implicit" versions of the following existing OpenFOAM-native injectionModel types: patchInjection, coneNozzleInjection, and manualInjection. In practice, the user simply needs to make sure they have the `libImplicitInjectors.so` library loaded in their `system/ControlDict` file (alongside `libpreciceAdapterFunctionObject.so`) and then swap a native OpenFOAM injectionModel type (like patchInjection) for an "implicit" version (implicitPatchInjection) in the injectionModels sub-dictionary of their particle cloud file. The following table maps native OpenFOAM injectionModels to their corresponding "implicit" version:


This reads a bit like a pull request description. Assuming that the feature would be merged in the OpenFOAM adapter, this could be written from the perspective of "this type of OpenFOAM simulation works as well".

Some of this information (including the table) could go into the feature README.md (see adapter PR) and/or to the adapter documentation.

But these are details that I could also directly sort out at the end of the review.

add flow-over-heated-plate/fluid-openfoam-basicReactingMultiphaseClou…

d462aff

…d tutorial case to show verification of implicit coupling of Lagrangian particles

mike-tree-corvid mentioned this pull request Jun 12, 2026

Add support for implicit coupling of Lagrangian particles precice/openfoam-adapter#405

Draft

2 tasks

change controlDict to use refactored lib file "libimplicitInjectors.s…

d0ff8da

…o" instead of explicit lib for patch injection

MakisH added the new-tutorial-case label Jun 23, 2026

mtree22 added 4 commits July 7, 2026 13:27

reformat flow-over-heated-plate/fluid-openfoam-basicReactingMultiphas…

942f9cd

…eCloud as its own tutorial flow-over-heated-plate-particles

update tools/openfoam-remove-empty-dirs.sh to support processor* dirs,

b73e2f4

which are created when openfoam collated file format is used

moved images dir location and added metadata.yaml

4ed4683

added 834.md to changelog-entries summarizing user-facing changes

ca7e9d2

MakisH reviewed Jul 12, 2026

View reviewed changes

Comment thread flow-over-heated-plate-particles/solid-openfoam/0/T Outdated

mtree22 added 3 commits July 13, 2026 17:41

removed OpenFOAM header from solid-openfoam/0/T file

f892578

replace temperature_with_particles.gif with coarser .gif so it takes …

ab88492

…up less storage space

removed temperature_with_particles.pvsm from flow-over-heated-plate-p…

5db2025

…articles/images

MakisH added 3 commits July 14, 2026 13:19

Merge branch 'develop' into flow-over-heated-plate-lagrangian-particles

54af0ff

Fix image names

2534244

Remove remaining OpenFOAM comment headers and separators

840d836

MakisH changed the title ~~add flow-over-heated-plate/fluid-openfoam-basicReactingMultiphaseClou…~~ Add flow-over-heated-plate-particles tutorial Jul 14, 2026

MakisH added new-tutorial and removed new-tutorial-case labels Jul 14, 2026

MakisH added 2 commits July 14, 2026 13:28

Make solid-openfoam directories identical

fe004fb

Port latest changes to the fluid-openfoam/clean.sh script

42391c1

MakisH reviewed Jul 14, 2026

View reviewed changes

MakisH mentioned this pull request Jul 15, 2026

Simplify the openfoam_remove_empty_dirs.sh script #879

Open

1 task


		The test case is two-dimensional and a serial-implicit coupling with Aitken underrelaxation is used for the coupling.

		Proper implicit coupling of Lagrangian particles involves not only accounting for existing particles in the domain during checkpointing, but also adjusting the particle injection logic for implicit coupling loops within time-windows as well. Particle injection is handled in OpenFOAM via injectionModels. injectionModels lie outside the OpenFOAM solver objectRegistry, so they cannot be directly modified by the existing OpenFOAM preCICE adapter functionObject. Therefore, the OpenFOAM preCICE adapter source code was modified to build an additional library, `libImplicitInjectors.so`. `libImplicitInjectors.so` contains "implicit" versions of the following existing OpenFOAM-native injectionModel types: patchInjection, coneNozzleInjection, and manualInjection. In practice, the user simply needs to make sure they have the `libImplicitInjectors.so` library loaded in their `system/ControlDict` file (alongside `libpreciceAdapterFunctionObject.so`) and then swap a native OpenFOAM injectionModel type (like patchInjection) for an "implicit" version (implicitPatchInjection) in the injectionModels sub-dictionary of their particle cloud file. The following table maps native OpenFOAM injectionModels to their corresponding "implicit" version:

Uh oh!

Uh oh!

Conversation

mike-tree-corvid commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

mike-tree-corvid commented Jun 12, 2026

Uh oh!

precice-bot commented Jun 12, 2026

Uh oh!

MakisH commented Jun 13, 2026

Uh oh!

mike-tree-corvid commented Jun 13, 2026

Uh oh!

MakisH commented Jun 14, 2026

Uh oh!

mike-tree-corvid commented Jul 7, 2026

Uh oh!

MakisH commented Jul 12, 2026

Uh oh!

Uh oh!

mike-tree-corvid commented Jul 13, 2026

Uh oh!

MakisH left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MakisH Jul 15, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mike-tree-corvid commented Jun 12, 2026 •

edited

Loading

MakisH Jul 15, 2026 •

edited

Loading