add docs

Author: LasNikas

docs/src/refs.bib

@@ -406,6 +406,19 @@ @Article{Li1996
   publisher = {Elsevier BV},
 }
 
+@Article{Liu2006,
+  author    = {Liu, M.B. and Liu, G.R.},
+  journal   = {Applied Numerical Mathematics},
+  title     = {Restoring particle consistency in smoothed particle hydrodynamics},
+  year      = {2006},
+  issn      = {0168-9274},
+  month     = jan,
+  number    = {1},
+  pages     = {19--36},
+  volume    = {56},
+  doi       = {10.1016/j.apnum.2005.02.012},
+  publisher = {Elsevier BV},
+}
 
 @Article{Molteni2009,
   author    = {Molteni, Diego and Colagrossi, Andrea},
@@ -561,6 +574,19 @@ @Article{Negi2020
   publisher = {Elsevier BV},
 }
 
+@Article{Negi2022,
+  author    = {Negi, Pawan and Ramachandran, Prabhu},
+  journal   = {Physics of Fluids},
+  title     = {How to train your solver: Verification of boundary conditions for smoothed particle hydrodynamics},
+  year      = {2022},
+  issn      = {1089-7666},
+  month     = nov,
+  number    = {11},
+  volume    = {34},
+  doi       = {10.1063/5.0126234},
+  publisher = {AIP Publishing},
+}
+
 @Article{O’Connor2021,
   author    = {O’Connor, Joseph and Rogers, Benedict D.},
   journal   = {Journal of Fluids and Structures},

src/schemes/boundary/open_boundary/method_of_characteristics.jl

@@ -1,5 +1,5 @@
 @doc raw"""
-    BoundaryModelLastiwka(; extrapolate_reference_values::Bool=false)
+    BoundaryModelLastiwka(; extrapolate_reference_values=nothing)
 
 Boundary model for [`OpenBoundarySPHSystem`](@ref).
 This model uses the characteristic variables to propagate the appropriate values
@@ -8,15 +8,19 @@ It requires a specific flow direction to be passed to the [`BoundaryZone`](@ref)
 For more information about the method see [description below](@ref method_of_characteristics).
 
 # Keywords
-- `extrapolate_reference_values=false`: If `true`, the reference values are extrapolated
-  from the fluid domain to the boundary particles.
+- `extrapolate_reference_values=nothing`: If one of the follwoing mirror methods is choosen,
+  the reference values are extrapolated from the fluid domain to the boundary particles.
+    - [`ZerothOrderMirroring`](@ref)
+    - [`FirstOrderMirroring`](@ref)
+    - [`SimpleMirroring`](@ref)
+
   **Note:** This feature is experimental and has not been fully validated yet.
   As of now, we are not aware of any published literature supporting its use.
 """
-struct BoundaryModelLastiwka
-    extrapolate_reference_values::Bool
-    function BoundaryModelLastiwka(; extrapolate_reference_values::Bool=false)
-        return new{}(extrapolate_reference_values)
+struct BoundaryModelLastiwka{T}
+    extrapolate_reference_values::T
+    function BoundaryModelLastiwka(; extrapolate_reference_values=nothing)
+        return new{typeof(extrapolate_reference_values)}(extrapolate_reference_values)
     end
 end
 
@@ -31,13 +35,14 @@ end
 
     sound_speed = system_sound_speed(fluid_system)
 
-    if boundary_model.extrapolate_reference_values
+    if !isnothing(boundary_model.extrapolate_reference_values)
         (; prescribed_pressure, prescribed_velocity, prescribed_density) = cache
         v_fluid = wrap_v(v_ode, fluid_system, semi)
         u_fluid = wrap_u(u_ode, fluid_system, semi)
 
         @trixi_timeit timer() "extrapolate and correct values" begin
-            extrapolate_values!(system, v, v_fluid, u, u_fluid, semi, t;
+            extrapolate_values!(system, boundary_model.extrapolate_reference_values,
+                                v, v_fluid, u, u_fluid, semi, t;
                                 prescribed_pressure, prescribed_velocity,
                                 prescribed_density)
         end

src/schemes/boundary/open_boundary/mirroring.jl

@@ -1,30 +1,56 @@
 @doc raw"""
-    BoundaryModelTafuni()
+    BoundaryModelTafuni(; mirror_method=FirstOrderMirroring(; firstorder_tolerance=1e-3))
 
 Boundary model for the `OpenBoundarySPHSystem`.
 This model implements the method of [Tafuni et al. (2018)](@cite Tafuni2018) to extrapolate the properties from the fluid domain
 to the buffer zones (inflow and outflow) using ghost nodes.
 The position of the ghost nodes is obtained by mirroring the boundary particles
 into the fluid along a direction that is normal to the open boundary.
+Fluid properties are then interpolated at these ghost node positions using surrounding fluid particles.
+The values are then mirrored back to the boundary particles.
+We provide three different mirroring methods:
+    - [`ZerothOrderMirroring`](@ref): Uses a Shepard interpolation to interpolate the values.
+    - [`FirstOrderMirroring`](@ref): Uses a first order correction based on the gradient of the interpolated values .
+    - [`SimpleMirroring`](@ref): Similar to the first order mirroring, but does not use the gradient of the interpolated values.
 """
 struct BoundaryModelTafuni{MM}
     mirror_method::MM
 end
 
+"""
+    FirstOrderMirroring
+
+Fluid properties are interpolated onto ghost nodes using the method propsed by [Liu and Liu (2006)](@cite Liu2006),
+to retrieve first oder kernel and particle consistency.
+"""
 struct FirstOrderMirroring{ELTYPE}
     firstorder_tolerance::ELTYPE
     function FirstOrderMirroring(; firstorder_tolerance::ELTYPE=1e-3) where {ELTYPE}
         return new{typeof(firstorder_tolerance)}(firstorder_tolerance)
     end
 end
 
+"""
+    SimpleMirroring
+
+This method is similar to [`FirstOrderMirroring`](@ref), but does not use
+the corrected gradient as proposed by [Negi et al. (2022)](@cite Negi2022).
+"""
 struct SimpleMirroring{ELTYPE}
     firstorder_tolerance::ELTYPE
     function SimpleMirroring(; firstorder_tolerance::Real=1e-3)
         return new{typeof(firstorder_tolerance)}(firstorder_tolerance)
     end
 end
 
+"""
+    ZerothOrderMirroring
+
+Fluid properties are interpolated onto ghost nodes using Shepard interpolation.
+The position of the ghost nodes is obtained by mirroring the boundary particles
+into the fluid along a direction that is normal to the open boundary.
+The interpolated values at the ghost nodes are then assigned to the corresponding boundary particles.
+"""
 struct ZerothOrderMirroring end
 
 function BoundaryModelTafuni(;