270 efficient hwbb and ibb

[MaxBille]

Description

(ready for review)

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/
    edit Philipp: won't add a test for these, since it's part of the advanced examples and not yet part of the lettuce core
• 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 project contains a folder with reference data in .csv format for average velocity and Reynolds stress profiles (/profile_reference_data). This data is loaded and plotted, by the respective functionalities in auxiliary_code/data_processing_and_plotting.py.
• 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

additions and changes in lettuce-code:

• 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 symmetrically placed circular 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.

nice-to-knows and further features:

• at this point, the flow class calculates all interpolation constants (for the IBB) 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 (or index lists) from it. The use of the solid_boundary_data class enables unified and efficient 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! (up to lettuce version 0.2.3 post-streaming was the standard for boundary conditions)
• 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 to suppress artificial observable values inside the solid). The VTKsliceReporter allows easy capture of 2D-slices for efficient visualization.
• 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.

[MaxBille]

@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]

@MaxBille nice job so far!
Could you

• Mirror the folder structure of /lettuce/.. for any files which are non-executables? (Flow/obstacle_cylinder.py, Boundary/solid_boundary_data.py, boundary/linear_interpolated_bounce_back_boundary.py, etc.). This will make it easier to review and to later merge into the corresponding structure within lettuce/
• Typo: parameterize should be parametrize
• Remove all lines containing OLD
• change default arguments to the values you suggested above
• since TODOs are already here as issues, you could remove those lines
• Do you need torch.autograd?
• Since you are using so many args, this could be useful to save all the overloads into local variables (should be simple enough to refactor): https://docs.python.org/3/library/argparse.html#the-namespace-object
• Remove redundant if True https://github.com/MaxBille/lettuce/blob/ea1705f8bce28146723efd2359d8f9ba8b81b185/examples/advanced_projects/efficient_bounce_back_obstacle/01a_script_cylinder_lowRe.py#L279
• Since you have so much input-parsing, wouldn't it make sense to create a separate file / function for this?
• I like the idea of saving the output in the Jupyter notebook. However, it is currently a bit out of place. I'd suggest naming only master-files xy_[...]. So, if we keep the notebooks, move the scripts into a subfolder. That could look quite nice, too.
• I do not get the last lines of 01a[...]. Could you move those comments to the corresponding lines of code or into the file head? https://github.com/MaxBille/lettuce/blob/ea1705f8bce28146723efd2359d8f9ba8b81b185/examples/advanced_projects/efficient_bounce_back_obstacle/01a_script_cylinder_lowRe.py#L320C3-L320C10

[MaxBille]

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

[MaxBille]

@McBs PR is ready for review.
This contains the major content of MP2 (efficient bounce back boundaries, cylinder flow, force coefficients, some reporters,...).

@PhiSpel I applied most of your change-requests from Nov 26, 26

• I left '#TODO' in the code in some cases, because it marks the location and describes possible implementations for additional and optional features. But these features should be implemented in a separate PR (and separate issue) to not bloat this one further. The code does not need these features to run.
• Some of the requests from Nov 26, 26 are very good ideas and worth looking into with enough time and priority -> could be separate issues and/or PRs as well:
  • namespace object for parsing
  • separate file/function for parsing arguments to the namespace object

[PhiSpel]

Some of the requests from Nov 26, 26 are very good ideas and worth looking into with enough time and priority -> could be separate issues and/or PRs as well:

* namespace object for parsing

* separate file/function for parsing arguments to the namespace object

@MaxBille should I create issues for these points for you to do later, or is this outside of your capacities?

[MaxBille]

Some of the requests from Nov 26, 26 are very good ideas and worth looking into with enough time and priority -> could be separate issues and/or PRs as well:

* namespace object for parsing

* separate file/function for parsing arguments to the namespace object

@MaxBille should I create issues for these points for you to do later, or is this outside of your capacities?

Doing this is out of my capacities, because of other priorities. Do you want to write an issue for these, or should I do that?
Likely it would make sense to write an issue, after this PR is merged, right?

[PhiSpel]

lgtm, congratulations!!! 😃