270 efficient hwbb and ibb by MaxBille · Pull Request #287 · lettucecfd/lettuce

MaxBille · 2025-10-28T13:15:44Z

Description

(Work in Progress)

Associated to issue #270 and related to feature requests #271 , #273 . See respective issue descriptions.

implementing fwbb, hwbb and ibb boundaries with efficiency improvement
implement cylinder flow as an example and test case

Checklist

This pull request is associated to an issue
This PR contains a description
Did you add a new method? If so, you need to
- add method description
- maybe mention class in the corresponding __init__
- add an example using the method in examples/advanced_flows/ or examples/simple_flows/
- add a test in tests/
Add someone else as reviewer and wait for approval before merging.

relevant files and changes

The advanced project lives in the directory:
examples/advanced_projects/efficient_bounce_back_obstacle/
It contains a Jupyter Notebook 00_run_parameterized_project.ipynb with two examples of parametrized calls of the main simulation-script to run:
- 2D, Re=200 simulation of a circular cylinder with periodic vortex shedding. Coefficients of drag and lift, as well as the Strouhal number are calculated
- 3D, Re=3900 simulation of a circular cylinder with turbulent vortex shedding. Average velocity and Reynolds stress profiles are calculated and compared to reference values
The project writes data to specified output directories.
The profile contains a folder with reference data in .csv format for average velocity and Reynolds stress profiles
The main simulation script 01_script_cylinder_simulation.py contains:
- argument parsing: physics, domain, solver-components, algorithms, reporters, observables, vtk output etc.
- parameter-preprocessing
- assembling of all solver components: stencil, context, flow, collision operator, simulation, reporter
- the simulation run: call of simulation()
- data post-processing and plotting: calculation, plotting, saving data and plots to disk
Efficient bounce back boundary implementations with the ability to calculate the momentum exchange (MEA) between solid and fluid:
- Fullway (FWBB)
- Halfway (HWBB)
- Linearly Interpolated (IBB or IBB1)
adapted simulation class ebb_simulation.py that improves the regular simulation class to use post-streaming boundaries and let boundaries get post-collision but pre-streaming information on populations, needed for their bounce back algorithm (for HWBB and IBB).
flow class obstacle_cylinder.py: advanced obstacle flow with a symmetrical cylinder in 2D or 3D that can be run with periodic or solid boundary channel walls and efficient bounce back boundaries for the solid cylinder itself.
- at this point, the flow class calculates all interpolation constants via an analytical function. In future versions, this might be outsourced to a CAD-kernel to use arbitrary solid geometry and calculate interpolation constants and masks (of index lists) from it. The use of the solid_boundary_data class enables unified containment of bounce back data (masks, population-indices, interpolation-constants,...)
- mind the use of post_streaming_boundaries that are (at the point of writing) not native in lettuce master branch, because the simulation class does not allow them!
observables: coefficients of lift and drag, relying on the MEA-capabilities of the efficient BB boundaries (see above)
- plot_force_coefficients: part of the data_processing_and_plotting.py utility.
- analyze_periodic_timeseries: part of the data_processing_and_plotting.py utility. Gives statistics and frequency of a periodic signal (used for drag and lift in this project)
Advanced vtk reporter: two advanced vtk reporters that allow the selection of start and stop (step) of reporting and pulling observables (velocity and pressure) to 0 on the solid (especially useful when using FWBB). 2D slicing-functionality with the VTKsliceReporter
Average velocity and Reynolds stress profiles
- reporter: The profile reporter reports the spatially averaged velocity profiles at a given position
- ProfilePlotter: part of the data_processing_and_plotting.py utility. It allows the loading of reference data, processing of profile reporter data and plotting of both.

…aster. including: obstacle_cylinder.py, example-Simulation-script, HWBB and IBB boundary conditions, MEA for Bounce back boundaries, drag and lift observables...

… 270-efficient_hwbb_and_ibb

…ed from MP2 and MA). obstacle_cylinder.py implements the flow, the boundary classes are implemented in the respective files under /_boundary WorkInProgress, see ToDOs

…ack boundaries to folder examples/advanced_projects/efficient_bounce_back_obstacle. Includes boundary conditions, obstacle_cylinder.py and placeholders for simulation-scripts for Re40-300 and Re3900, and a jupyter-notebook to run the scripts interactively _simulation.py: added comments for clarification

…pare to MP2 and cylinder2025 results!

MaxBille · 2025-11-26T15:24:07Z

@PhiSpel @McBs
The cylinder flow is now "running" with fwbb, hwbb or ibb boundary condition. Validation of physical correctness pending, because respective observable-reporters have to be implemented in the next step.
See commit: (Commit SHA: ea1705f from 21.11.25).

README:

simulation can be run with:
python 01a_script_cylinder_lowRe --outdir "./datafolder" --char_length_lu 10 --n_steps 1000 --bbbc_type ibb1 --reynolds_number 50 --domain_width_z_in_d 3
ebb_simulation is a child of simulation class which allows post_streaming_boundaries to be used. This is necessary for FWBB, HWBB and IBB in the efficient sparse implementation.
obstacle_cylinder is the flow class
solid_boundary_data is the container class which contains masks, f_index-lists and ibb-d-data
01a_script_cylinder_lowRe.py is the parameterized script to run the simulation.

PhiSpel · 2025-11-26T15:30:10Z

examples/advanced_flows/PorousMedium.ipynb

@MaxBille, could you revert these changes for cleaner history?

of course. Will try to overwrite file back to original from master branch!

PhiSpel · 2025-11-26T15:31:40Z

lettuce/_simulation.py

@MaxBille, these are useful comments! Can you add them in a separate PR, though?

@MaxBille didn't you add these changes separately?

PhiSpel · 2025-11-26T15:33:04Z

uv.lock

@MaxBille @McBs is this due to pyproject.toml requiring notebook? I suggest updating this, too, in a separate PR

PhiSpel · 2025-11-26T15:38:58Z

examples/simple_flows/Obstacle.ipynb

@MaxBille, this, too, should be handled in a separate PR, related to #288

PhiSpel · 2025-11-26T15:58:40Z

examples/advanced_projects/efficient_bounce_back_obstacle/fullway_bounce_back_boundary.py

+            self.f_index_fwbb[:, 1],
+            self.f_index_fwbb[:, 2],
+            self.f_index_fwbb[:, 3]]
+        print("FWBB call, DONE")


remove redundant print? @MaxBille, check for more of those

will do; and will do in final version, together with obsolete comments and "old" code snippets

PhiSpel

@MaxBille nice job so far!
Could you

examples/advanced_projects/efficient_bounce_back_obstacle/helperCode.py

PhiSpel · 2025-11-26T16:00:14Z

...advanced_projects/efficient_bounce_back_obstacle/linear_interpolated_bounce_back_boundary.py

+        self.f_collided_gt = None
+        # will be populated in initialize_f_collided() method
+
+        # DEPRECATED: got moved to method initialize f_collided


remove old code

will be removed in final/release/merge version. I keep sections like this in the code, to remind me of past versions and various ways to do stuff.

PhiSpel · 2025-11-26T16:00:39Z

...advanced_projects/efficient_bounce_back_obstacle/linear_interpolated_bounce_back_boundary.py

+    def make_no_streaming_mask(self, f_shape, context: Context):
+        # no_stream_mask has to be dimensions: (q,x,y,z) (z optional), but CAN be (x,y,z) (z optional).
+        # ...in the latter case, torch.where broadcasts the mask to (q,x,y,z), so ALL q populations of a lattice-node are marked equally
+        # return torch.tensor(self.mask, dtype=torch.bool)


remove old code

PhiSpel · 2025-11-26T16:00:47Z

...advanced_projects/efficient_bounce_back_obstacle/linear_interpolated_bounce_back_boundary.py

+        # ...in the initial solution of your flow, especially if visualization or post-processing uses the field-values
+        # ...in the whole domain (including the boundary region)!
+
+        # return torch.tensor(self.mask, dtype=torch.bool)  # self.context.convert_to_tensor(self.mask)


remove old code

PhiSpel · 2025-11-26T16:01:09Z

...advanced_projects/efficient_bounce_back_obstacle/linear_interpolated_bounce_back_boundary.py

+                                                self.f_index_gt[:, 3]],
+                                            self.flow.stencil.e[self.f_index_gt[:, 0]].float())
+
+    # TODO: find a way to use pre- and post-Streaming Populations for bounce...


isn't this done?

examples/advanced_projects/efficient_bounce_back_obstacle/obstacle_cylinder.py

PhiSpel · 2025-11-26T16:04:30Z

examples/advanced_projects/efficient_bounce_back_obstacle/obstacle_cylinder.py

+            mask=self.in_mask,
+            velocity=self.u_inlet)  # (is this still true??): works with a 1 x D vector or an ny x D vector thanks to einsum-magic in EquilibriumBoundaryPU
+
+        lateral_boundary = None  # stays None if lateral walls are not specified... (NOT IMPLEMENTED YET, see below)


I think we may just remove all channel-related definitions for now. The most interesting part is how the cylinder is handled, right, @MaxBille ?

examples/advanced_projects/efficient_bounce_back_obstacle/obstacle_cylinder.py

PhiSpel · 2025-11-26T16:06:00Z

lettuce/ext/_boundary/equilibrium_outlet_p.py

Do these changes break the old code or fix something? If they just work with everything else, OK. If they are required as a fix, please add this in a separate issue

…ample to validate against MP2 and cylinder-paper data; to be tested...

- comments - print-statements - ToDos - revert changes in .ipynbs (less clutter in later PR)

…to fork/MaxBille/270-efficient_hwbb_and_ibb

…numerically there are diffs. of ~1% in mean Drag... this might be due to the new pre/ost-boundary strategy of lettuce 2025. Needs further investigation (issue already open). Further improvements and corrections: - implemented lateral walls option (for FWBB) - removed some comments and old code sections. NEXT will be output/data/vtk cleaning and example .ipynb script for execution

- methods for force coefficient plotting and analysis were outsourced to data_processing_and_plotting.py - files for NaN-, HighMa-, and Progress-Reporter created (but work in progress)

…finding

…ed profile-data-post-processing und -plotting. implemented advanced vtk reporter (3D with step start and end and 2D for XY-slices)

…al of un-implemented reporter-files.

…r flow with 01_script_cylinder_simulation.py through ipynb: 00_run_parameterized_project.ipynb added "show" parameter to plotting-reporters methods, to not only plot and save but also show the plotted data

…_coefficients.py

…to 270-efficient_hwbb_and_ibb

…leanup

MaxBille · 2025-12-18T14:42:06Z

@McBs @PhiSpel the current commit 8f12b6a is ready for the next review cycle. This is basically a final version so far.

PhiSpel · 2025-12-18T14:57:45Z

uv.lock

@MaxBille did you keep these changes intentionally?

PhiSpel · 2025-12-18T14:58:01Z

pyproject.toml

    "h5py==3.11.0",
    "matplotlib>=3.9.2",
    "mmh3>=4.1.0",
+    "notebook>=7.4.7",


Why was this added?

PhiSpel · 2025-12-18T14:58:23Z

lettuce/_simulation.py

@MaxBille didn't you add these changes separately?

PhiSpel · 2025-12-18T14:58:53Z

examples/advanced_projects/efficient_bounce_back_obstacle/reporter_ProfileReporter.py

+        -> use the ProfilePlotter in post-processing to further process
+        and plot data!
+    """
+


remove double linebreak

PhiSpel · 2025-12-18T14:59:38Z

examples/advanced_projects/efficient_bounce_back_obstacle/reporter_advanced_vtk_reporter.py

+        """
+            output the mask as a vtk-file for visualizatione etc.
+
+        UPDATE 28.08.2024 (MBille: outputs mask as cell data. cell data represents the approx.


Is UPDATE necessary? Can't this be a permanent comment?

MaxBille and others added 3 commits September 4, 2025 18:21

started translating the MP2_release cylinderFlow to current lettuce m…

4b46cf1

…aster. including: obstacle_cylinder.py, example-Simulation-script, HWBB and IBB boundary conditions, MEA for Bounce back boundaries, drag and lift observables...

started translating the MP2_release cylinderFlow to current lettuce m…

4ab3339

…aster. including: obstacle_cylinder.py, example-Simulation-script, HWBB and IBB boundary conditions, MEA for Bounce back boundaries, drag and lift observables...

Merge branch 'lettucecfd:master' into 270-efficient_hwbb_and_ibb

e01d988

MaxBille marked this pull request as draft October 28, 2025 13:15

MaxBille requested review from McBs and PhiSpel October 28, 2025 13:16

MaxBille self-assigned this Oct 28, 2025

MaxBille added the enhancement New feature or request label Oct 28, 2025

MaxBille added 8 commits October 29, 2025 15:03

Merge remote-tracking branch 'origin/270-efficient_hwbb_and_ibb' into…

d0e4074

… 270-efficient_hwbb_and_ibb

progress on cylinder flow with efficient bounce back boundaries (port…

6c1eda1

…ed from MP2 and MA). obstacle_cylinder.py implements the flow, the boundary classes are implemented in the respective files under /_boundary WorkInProgress, see ToDOs

temp_comit: progress of today

555182a

debugging before tests of first cylinder flow

69a2e8a

commit before trying to find error in master regarding solid boundaries

d1e7638

fwbb and hwbb seem to be running now... Ibb1 gives NaN, but code runs...

251abe6

ibb1 seems to work, now has to be tested with observables etc. to com…

ea1705f

…pare to MP2 and cylinder2025 results!

PhiSpel reviewed Nov 26, 2025

View reviewed changes

uv.lock

Copy link

Contributor

PhiSpel Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MaxBille @McBs is this due to pyproject.toml requiring notebook? I suggest updating this, too, in a separate PR

PhiSpel reviewed Nov 26, 2025

View reviewed changes

examples/simple_flows/Obstacle.ipynb

Copy link

Contributor

PhiSpel Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MaxBille, this, too, should be handled in a separate PR, related to #288

PhiSpel reviewed Nov 26, 2025

View reviewed changes

MaxBille and others added 7 commits November 26, 2025 17:14

implemented Drag, Lift and more print-statements for cylinder-flow ex…

a04b42f

…ample to validate against MP2 and cylinder-paper data; to be tested...

Merge branch 'lettucecfd:master' into 270-efficient_hwbb_and_ibb

6b5fd7c

corrected some stuff for better compatibility with master branch:

237c5f9

- comments - print-statements - ToDos - revert changes in .ipynbs (less clutter in later PR)

Merge remote-tracking branch 'MaxBille/270-efficient_hwbb_and_ibb' in…

c2655de

…to fork/MaxBille/270-efficient_hwbb_and_ibb

tidying of 01a_script_cylinder_lowRe.py

4ee0fd6

- methods for force coefficient plotting and analysis were outsourced to data_processing_and_plotting.py - files for NaN-, HighMa-, and Progress-Reporter created (but work in progress)

corrected drag- and lift-plotting, peak-finding and plotting of peak-…

666ea19

…finding

MaxBille and others added 9 commits December 11, 2025 17:19

implemented profile-reporter, added profile-reference-data, implement…

381b6b4

…ed profile-data-post-processing und -plotting. implemented advanced vtk reporter (3D with step start and end and 2D for XY-slices)

minor changes

e5c1ba5

unified cylinder simulation script; minor corrections in files, remov…

b24cb63

…al of un-implemented reporter-files.

final touches and prlimilary test for Re200 and Re3900 run of cylinde…

c3c4062

…r flow with 01_script_cylinder_simulation.py through ipynb: 00_run_parameterized_project.ipynb added "show" parameter to plotting-reporters methods, to not only plot and save but also show the plotted data

minor changes: spelling

60e978a

Merge branch 'master' into 270-efficient_hwbb_and_ibb

6b459bf

minor changes: removed Reporter from import list of observables_force…

60bc032

…_coefficients.py

Merge remote-tracking branch 'MaxBille/270-efficient_hwbb_and_ibb' in…

f5d7ebf

…to 270-efficient_hwbb_and_ibb

FOR REVIEW! code formatting, minor repairs, comments, desctiptions, c…

8f12b6a

…leanup

MaxBille requested a review from PhiSpel December 18, 2025 14:40

PhiSpel reviewed Dec 18, 2025

View reviewed changes

PhiSpel marked this pull request as ready for review December 18, 2025 15:02

Comments

Conversation

MaxBille commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

relevant files and changes

Uh oh!

MaxBille commented Nov 26, 2025

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PhiSpel 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!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MaxBille commented Dec 18, 2025

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MaxBille commented Oct 28, 2025 •

edited

Loading