trixi-framework · svchb · Jun 13, 2025 · May 22, 2025 · May 22, 2025 · May 22, 2025
diff --git a/examples/dem/collapsing_sand_pile_3d.jl b/examples/dem/collapsing_sand_pile_3d.jl
@@ -51,7 +51,8 @@ min_coords_floor = (min_boundary[1] - boundary_thickness,
 floor_particles = RectangularShape(particle_spacing,
                                    (n_particles_floor_x, n_particles_floor_y,
                                     n_particles_floor_z),
-                                   min_coords_floor; density=boundary_density, tlsph=true)
+                                   min_coords_floor; density=boundary_density,
+                                   place_on_shell=true)
 boundary_particles = floor_particles
 
 # ==========================================================================================

diff --git a/examples/fsi/dam_break_gate_2d.jl b/examples/fsi/dam_break_gate_2d.jl
@@ -75,18 +75,18 @@ solid_particle_spacing = thickness / (n_particles_x - 1)
 n_particles_y = round(Int, length_beam / solid_particle_spacing) + 1
 
 # The bottom layer is sampled separately below. Note that the `RectangularShape` puts the
-# first particle half a particle spacing away from the boundary, which is correct for fluids,
-# but not for solids. We therefore need to pass `tlsph=true`.
+# first particle half a particle spacing away from the shell of the shape, which is
+# correct for fluids, but not for solids. We therefore need to pass `place_on_shell=true`.
 #
 # The right end of the plate is 0.2 from the right end of the tank.
 plate_position = 0.6 - n_particles_x * solid_particle_spacing
 plate = RectangularShape(solid_particle_spacing,
                          (n_particles_x, n_particles_y - 1),
                          (plate_position, solid_particle_spacing),
-                         density=solid_density, tlsph=true)
+                         density=solid_density, place_on_shell=true)
 fixed_particles = RectangularShape(solid_particle_spacing,
                                    (n_particles_x, 1), (plate_position, 0.0),
-                                   density=solid_density, tlsph=true)
+                                   density=solid_density, place_on_shell=true)
 
 solid = union(plate, fixed_particles)
 

diff --git a/examples/fsi/dam_break_plate_2d.jl b/examples/fsi/dam_break_plate_2d.jl
@@ -51,15 +51,15 @@ solid_particle_spacing = thickness / (n_particles_x - 1)
 n_particles_y = round(Int, length_beam / solid_particle_spacing) + 1
 
 # The bottom layer is sampled separately below. Note that the `RectangularShape` puts the
-# first particle half a particle spacing away from the boundary, which is correct for fluids,
-# but not for solids. We therefore need to pass `tlsph=true`.
+# first particle half a particle spacing away from the shell of the shape, which is
+# correct for fluids, but not for solids. We therefore need to pass `place_on_shell=true`.
 plate = RectangularShape(solid_particle_spacing,
                          (n_particles_x, n_particles_y - 1),
                          (2initial_fluid_size[1], solid_particle_spacing),
-                         density=solid_density, tlsph=true)
+                         density=solid_density, place_on_shell=true)
 fixed_particles = RectangularShape(solid_particle_spacing,
                                    (n_particles_x, 1), (2initial_fluid_size[1], 0.0),
-                                   density=solid_density, tlsph=true)
+                                   density=solid_density, place_on_shell=true)
 
 solid = union(plate, fixed_particles)
 

diff --git a/examples/preprocessing/packing_2d.jl b/examples/preprocessing/packing_2d.jl
@@ -6,7 +6,7 @@ file = pkgdir(TrixiParticles, "examples", "preprocessing", "data", filename * ".
 
 # ==========================================================================================
 # ==== Packing parameters
-tlsph = false
+place_on_shell = false
 
 # ==========================================================================================
 # ==== Resolution
@@ -36,7 +36,7 @@ shape_sampled = ComplexShape(geometry; particle_spacing, density,
 
 # Returns `InitialCondition`
 boundary_sampled = sample_boundary(signed_distance_field; boundary_density=density,
-                                   boundary_thickness, tlsph=tlsph)
+                                   boundary_thickness, place_on_shell=place_on_shell)
 
 trixi2vtk(shape_sampled)
 trixi2vtk(boundary_sampled, filename="boundary")
@@ -52,12 +52,13 @@ background_pressure = 1.0
 
 smoothing_length = 0.8 * particle_spacing
 packing_system = ParticlePackingSystem(shape_sampled; smoothing_length=smoothing_length,
-                                       signed_distance_field, tlsph=tlsph,
+                                       signed_distance_field, place_on_shell=place_on_shell,
                                        background_pressure)
 
 boundary_system = ParticlePackingSystem(boundary_sampled; smoothing_length=smoothing_length,
                                         is_boundary=true, signed_distance_field,
-                                        tlsph=tlsph, boundary_compress_factor=0.8,
+                                        place_on_shell=place_on_shell,
+                                        boundary_compress_factor=0.8,
                                         background_pressure)
 
 # ==========================================================================================

diff --git a/examples/preprocessing/packing_3d.jl b/examples/preprocessing/packing_3d.jl
@@ -15,5 +15,5 @@ boundary_thickness = 8 * particle_spacing
 
 trixi_include(joinpath(examples_dir(), "preprocessing", "packing_2d.jl"),
               density=1000.0, particle_spacing=particle_spacing, file=file,
-              boundary_thickness=boundary_thickness, tlsph=true,
+              boundary_thickness=boundary_thickness, place_on_shell=true,
               save_intervals=false)
diff --git a/examples/solid/oscillating_beam_2d.jl b/examples/solid/oscillating_beam_2d.jl
@@ -23,7 +23,7 @@ fixed_particles = SphereShape(particle_spacing, clamp_radius + particle_spacing
                               (0.0, elastic_beam.thickness / 2), material.density,
                               cutout_min=(0.0, 0.0),
                               cutout_max=(clamp_radius, elastic_beam.thickness),
-                              tlsph=true)
+                              place_on_shell=true)
 
 n_particles_clamp_x = round(Int, clamp_radius / particle_spacing)
 
@@ -33,9 +33,9 @@ n_particles_per_dimension = (round(Int, elastic_beam.length / particle_spacing)
 
 # Note that the `RectangularShape` puts the first particle half a particle spacing away
 # from the boundary, which is correct for fluids, but not for solids.
-# We therefore need to pass `tlsph=true`.
+# We therefore need to pass `place_on_shell=true`.
 beam = RectangularShape(particle_spacing, n_particles_per_dimension,
-                        (0.0, 0.0), density=material.density, tlsph=true)
+                        (0.0, 0.0), density=material.density, place_on_shell=true)
 
 solid = union(beam, fixed_particles)
 

diff --git a/src/general/interpolation.jl b/src/general/interpolation.jl
@@ -191,9 +191,10 @@ function interpolate_plane_2d(min_corner, max_corner, resolution, semi, ref_syst
     x_range = range(min_corner[1], max_corner[1], length=n_points_per_dimension[1])
     y_range = range(min_corner[2], max_corner[2], length=n_points_per_dimension[2])
 
-    # Generate points within the plane. Use `tlsph=true` to generate points on the boundary
+    # Generate points within the plane. Use `place_on_shell=true` to generate points
+    # on the shell of the geometry.
     point_coords = rectangular_shape_coords(resolution, n_points_per_dimension, min_corner,
-                                            tlsph=true)
+                                            place_on_shell=true)
 
     results = interpolate_points(point_coords, semi, ref_system, v_ode, u_ode,
                                  smoothing_length=smoothing_length,

diff --git a/src/preprocessing/particle_packing/signed_distance.jl b/src/preprocessing/particle_packing/signed_distance.jl
@@ -59,7 +59,7 @@ function SignedDistanceField(geometry, particle_spacing;
                                                 particle_spacing))
 
         grid = rectangular_shape_coords(particle_spacing, n_particles_per_dimension,
-                                        min_corner; tlsph=true)
+                                        min_corner; place_on_shell=true)
 
         points = reinterpret(reshape, SVector{NDIMS, ELTYPE}, grid)
     end

diff --git a/src/preprocessing/particle_packing/system.jl b/src/preprocessing/particle_packing/system.jl
@@ -6,7 +6,7 @@
                           smoothing_length_interpolation=smoothing_length,
                           is_boundary=false, boundary_compress_factor=1,
                           neighborhood_search=GridNeighborhoodSearch{ndims(shape)}(),
-                          background_pressure, tlsph=false, fixed_system=false)
+                          background_pressure, place_on_shell=false, fixed_system=false)
 
 System to generate body-fitted particles for complex shapes.
 For more information on the methods, see [particle packing](@ref particle_packing).
@@ -18,10 +18,11 @@ For more information on the methods, see [particle packing](@ref particle_packin
 - `background_pressure`:   Constant background pressure to physically pack the particles.
                            A large `background_pressure` can cause high accelerations
                            which requires a properly adjusted time step.
-- `tlsph`:                 With the [`TotalLagrangianSPHSystem`](@ref), particles need to be placed
-                           on the boundary of the shape and not half a particle spacing away,
-                           as for fluids. When `tlsph=true`, particles will be placed
-                           on the boundary of the shape.
+- `place_on_shell`:        If `place_on_shell=true`, particles will be placed
+                           on the shell of the geometry. For example,
+                           the [`TotalLagrangianSPHSystem`](@ref) requires particles to be placed
+                           on the shell of the geometry and not half a particle spacing away,
+                           as for fluids.
 - `is_boundary`:           When `shape` is inside the geometry that was used to create
                            `signed_distance_field`, set `is_boundary=false`.
                            Otherwise (`shape` is the sampled boundary), set `is_boundary=true`.
@@ -64,7 +65,7 @@ struct ParticlePackingSystem{S, F, NDIMS, ELTYPE <: Real, PR, C, AV,
     smoothing_kernel               :: K
     smoothing_length_interpolation :: ELTYPE
     background_pressure            :: ELTYPE
-    tlsph                          :: Bool
+    place_on_shell                 :: Bool
     signed_distance_field          :: S
     is_boundary                    :: Bool
     shift_length                   :: ELTYPE
@@ -79,7 +80,8 @@ struct ParticlePackingSystem{S, F, NDIMS, ELTYPE <: Real, PR, C, AV,
     # See the comments in general/gpu.jl for more details.
     function ParticlePackingSystem(initial_condition, mass, density, particle_spacing,
                                    smoothing_kernel, smoothing_length_interpolation,
-                                   background_pressure, tlsph, signed_distance_field,
+                                   background_pressure, place_on_shell,
+                                   signed_distance_field,
                                    is_boundary, shift_length, neighborhood_search,
                                    signed_distances, particle_refinement, buffer,
                                    update_callback_used, fixed_system, cache,
@@ -93,7 +95,7 @@ struct ParticlePackingSystem{S, F, NDIMS, ELTYPE <: Real, PR, C, AV,
                                                  mass, density, particle_spacing,
                                                  smoothing_kernel,
                                                  smoothing_length_interpolation,
-                                                 background_pressure, tlsph,
+                                                 background_pressure, place_on_shell,
                                                  signed_distance_field, is_boundary,
                                                  shift_length, neighborhood_search,
                                                  signed_distances, particle_refinement,
@@ -108,7 +110,8 @@ function ParticlePackingSystem(shape::InitialCondition;
                                smoothing_length_interpolation=smoothing_length,
                                is_boundary=false, boundary_compress_factor=1,
                                neighborhood_search=GridNeighborhoodSearch{ndims(shape)}(),
-                               background_pressure, tlsph=false, fixed_system=false)
+                               background_pressure, place_on_shell=false,
+                               fixed_system=false)
     NDIMS = ndims(shape)
     ELTYPE = eltype(shape)
     mass = copy(shape.mass)
@@ -147,12 +150,12 @@ function ParticlePackingSystem(shape::InitialCondition;
     # Its value is negative if the particle is inside the geometry.
     # Otherwise (if outside), the value is positive.
     if is_boundary
-        offset = tlsph ? shape.particle_spacing : shape.particle_spacing / 2
+        offset = place_on_shell ? shape.particle_spacing : shape.particle_spacing / 2
 
         shift_length = -boundary_compress_factor *
                        signed_distance_field.max_signed_distance - offset
     else
-        shift_length = tlsph ? zero(ELTYPE) : shape.particle_spacing / 2
+        shift_length = place_on_shell ? zero(ELTYPE) : shape.particle_spacing / 2
     end
 
     cache = (; create_cache_refinement(shape, particle_refinement, smoothing_length)...)
@@ -161,7 +164,7 @@ function ParticlePackingSystem(shape::InitialCondition;
 
     return ParticlePackingSystem(shape, mass, density, shape.particle_spacing,
                                  smoothing_kernel, smoothing_length_interpolation,
-                                 background_pressure, tlsph, signed_distance_field,
+                                 background_pressure, place_on_shell, signed_distance_field,
                                  is_boundary, shift_length, nhs,
                                  fill(zero(ELTYPE), nparticles(shape)), particle_refinement,
                                  nothing, Ref(false), fixed_system, cache,
@@ -187,7 +190,7 @@ function Base.show(io::IO, ::MIME"text/plain", system::ParticlePackingSystem)
                      system.neighborhood_search |> typeof |> nameof)
         summary_line(io, "#particles", nparticles(system))
         summary_line(io, "smoothing kernel", system.smoothing_kernel |> typeof |> nameof)
-        summary_line(io, "tlsph", system.tlsph ? "yes" : "no")
+        summary_line(io, "place_on_shell", system.place_on_shell ? "yes" : "no")
         summary_line(io, "boundary", system.is_boundary ? "yes" : "no")
         summary_footer(io)
     end
@@ -349,8 +352,8 @@ function constrain_particle!(u, system, particle, distance_signed, normal_vector
     (; shift_length) = system
 
     # For fluid particles:
-    # - `tlsph = true`: `shift_length = 0`
-    # - `tlsph = false`: `shift_length = particle_spacing / 2`
+    # - `place_on_shell = true`: `shift_length = 0`
+    # - `place_on_shell = false`: `shift_length = particle_spacing / 2`
     # For boundary particles:
     # `shift_length` is the thickness of the boundary.
     if distance_signed >= -shift_length
@@ -365,7 +368,7 @@ function constrain_particle!(u, system, particle, distance_signed, normal_vector
     system.is_boundary || return u
 
     particle_spacing = system.initial_condition.particle_spacing
-    shift_length_inner = system.tlsph ? particle_spacing : particle_spacing / 2
+    shift_length_inner = system.place_on_shell ? particle_spacing : particle_spacing / 2
 
     if distance_signed < shift_length_inner
         shift = (distance_signed - shift_length_inner) * normal_vector

diff --git a/src/setups/complex_shape.jl b/src/setups/complex_shape.jl
@@ -79,7 +79,7 @@ end
 
 """
     sample_boundary(signed_distance_field::SignedDistanceField;
-                    boundary_thickness::Real, tlsph=true)
+                    boundary_thickness::Real, place_on_shell=true)
 
 Sample boundary particles of a complex geometry by using the [`SignedDistanceField`](@ref)
 of the geometry.
@@ -89,9 +89,9 @@ of the geometry.
 
 # Keywords
 - `boundary_thickness`: Thickness of the boundary
-- `tlsph`             : When `tlsph=true`, boundary particles will be placed
+- `place_on_shell`:     When `place_on_shell=true`, boundary particles will be placed
                         one particle spacing from the surface of the geometry.
-                        Otherwise when `tlsph=true` (simulating fluid particles),
+                        Otherwise when `place_on_shell=true` (simulating fluid particles),
                         boundary particles will be placed half particle spacing away from the surface.
 
 
@@ -117,7 +117,7 @@ boundary_sampled = sample_boundary(signed_distance_field; boundary_density=1.0,
 ```
 """
 function sample_boundary(signed_distance_field;
-                         boundary_density, boundary_thickness, tlsph=true)
+                         boundary_density, boundary_thickness, place_on_shell=true)
     (; max_signed_distance, boundary_packing,
      positions, distances, particle_spacing) = signed_distance_field
 
@@ -157,6 +157,6 @@ function particle_grid(geometry, particle_spacing;
     end
 
     grid = rectangular_shape_coords(particle_spacing, n_particles_per_dimension,
-                                    min_corner; tlsph=true)
+                                    min_corner; place_on_shell=true)
     return reinterpret(reshape, SVector{ndims(geometry), eltype(geometry)}, grid)
 end