Damping refactor and enhancement - #2008
Draft
mbkuhn wants to merge 32 commits into
Draft
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
mbkuhn
commented
Aug 13, 2026
mbkuhn
commented
Aug 13, 2026
Contributor
Author
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a generalized near-boundary damping capability by adding a DampingLayer physics module to generate damping-coefficient fields and a DampingLayerSource source term to relax supported PDE fields toward configurable targets, replacing/avoiding the prior awkward coupling in terrain-drag damping.
Changes:
- Added
DampingLayerphysics for constructing per-boundary damping coefficient fields for arbitrary solved fields. - Added
DampingLayerSourcesource term supporting constant/profile/function/field targets with optional per-component damping masks. - Updated legacy TerrainDrag damping handling and added unit/regression tests plus Sphinx input documentation.
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| unit_tests/physics/test_damping_layer.cpp | Adds unit tests for blending/damping math helpers. |
| unit_tests/physics/CMakeLists.txt | Registers new physics unit test source. |
| unit_tests/equation_systems/test_damping_layer_source.cpp | Adds unit tests for target-type parsing and traits. |
| unit_tests/equation_systems/CMakeLists.txt | Registers new equation-system unit test source. |
| unit_tests/CMakeLists.txt | Adds physics unit-test subdirectory. |
| test/test_files/abl_damping_layer_source/abl_damping_layer_source.inp | Adds regression input covering multiple DampingLayer/Source configurations. |
| test/CMakeLists.txt | Registers new regression test. |
| src/physics/TerrainDragDamping.H | Extracts legacy terrain damping computation into a reusable helper. |
| src/physics/TerrainDrag.H | Makes terrain damping field optional (pointer) for legacy inputs. |
| src/physics/TerrainDrag.cpp | Declares/initializes terrain damping field only when legacy inputs exist; calls extracted helper. |
| src/physics/DampingLayer.H | Declares DampingLayer API and device-side damping/blending math utilities. |
| src/physics/DampingLayer.cpp | Implements parsing and construction of damping coefficient fields. |
| src/physics/CMakeLists.txt | Adds DampingLayer compilation unit to physics library. |
| src/equation_systems/source_terms/DampingLayerSource.H | Introduces generic damping source-term implementation and configuration parsing. |
| src/equation_systems/source_terms/DampingLayerSource.cpp | Explicit template instantiations for supported PDE source types. |
| src/equation_systems/source_terms/CMakeLists.txt | Adds new source-terms compilation unit to the library. |
| src/equation_systems/CMakeLists.txt | Adds top-level source_terms subdirectory to equation-systems build. |
| docs/sphinx/user/inputs.rst | Adds DampingLayer inputs page to user docs toctree. |
| docs/sphinx/user/inputs_Temperature_Sources.rst | Documents how to configure DampingLayerSource for temperature. |
| docs/sphinx/user/inputs_Momentum_Sources.rst | Documents how to configure DampingLayerSource for momentum. |
| docs/sphinx/user/inputs_incflo.rst | Adds DampingLayer to the list of available physics modules. |
| docs/sphinx/user/inputs_DampingLayer.rst | Adds full documentation for DampingLayer and DampingLayerSource parameters. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+244
to
+256
| const amrex::Real distance_from_zhi = | ||
| prob_hi[2] - z; | ||
| const amrex::Real vertical_thickness = | ||
| prob_hi[2] - min_height; | ||
| const amrex::Real vertical_blending_fraction = | ||
| vertical_blending_thickness / distance_from_zhi; | ||
| const amrex::Real vertical_damping_coeff = | ||
| damping_calc( | ||
| distance_from_zhi, vertical_thickness, | ||
| vertical_blending_fraction, | ||
| vertical_blending_function_type); | ||
| damping_coeff = | ||
| std::min(damping_coeff, vertical_damping_coeff); |
Comment on lines
+19
to
+20
| AMREX_GPU_HOST_DEVICE AMREX_FORCE_INLINE BlendingFunctionType | ||
| string_to_blending_function_type(const std::string& op_str) |
Comment on lines
+67
to
+79
| const amrex::Real length_full_damp = | ||
| layer_thickness * (1.0_rt - blending_fraction); | ||
| const amrex::Real blend_position_nondim = | ||
| (distance_from_boundary - length_full_damp) / | ||
| (layer_thickness * blending_fraction); | ||
| if (blend_position_nondim <= 0.0_rt) { | ||
| return 1.0_rt; | ||
| } | ||
| if (blend_position_nondim <= 1.0_rt) { | ||
| return blending_function(blend_position_nondim, function_type); | ||
| } | ||
| return 0.0_rt; | ||
| } |
Comment on lines
+27
to
+28
| AMREX_GPU_HOST_DEVICE AMREX_FORCE_INLINE TargetType | ||
| string_to_target_type(const std::string& target_type_str) |
Comment on lines
+202
to
+203
|
|
||
| if (target_type == TargetType::Constant) { |
| problo[1] + ((j + 0.5_rt) * dx[1]); | ||
| const amrex::Real z = | ||
| problo[2] + ((k + 0.5_rt) * dx[2]); | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The near-boundary damping implementation in TerrainDrag + DragForcing is awkward and did not align well with the other kinds of damping in the code (e.g., RayleighDamping, TemperatureFreeAtmosphereForcing). This PR provides a better, more generalized approach to damping fields in a simulation. The damping coefficient is set up through the Physics class Damping Layer, and the damping is applied through a source term DampingLayerSource. There is a unified set of inputs, and any field (that has a governing equation) can be damped in a region adjacent to any boundary, with each boundary allowed to have a different target of the damping. There are several options for the setup of the damping coefficient field and for the damping target.
Pull request type
Please check the type of change introduced:
Checklist
The following is included:
This PR was tested by running:
Additional background
Issue Number: