Add descriptive header to each example

examples/dem/collapsing_sand_pile_3d.jl

@@ -1,13 +1,17 @@
+# ==========================================================================================
+# === 3D Collapsing Sand Pile Simulation
+#
+# This example simulates the collapse of a cylindrical pile of sand under gravity
+# within a confined container using the Discrete Element Method (DEM).
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 
 # Physical parameters
 gravity = -9.81
 acceleration = (0.0, 0.0, gravity)
 
-# ==========================================================================================
-# ==== Collapsing Sand Pile Simulation
-
 # Resolution
 particle_spacing = 0.1
 

examples/dem/rectangular_tank_2d.jl

@@ -1,8 +1,3 @@
-using TrixiParticles
-using OrdinaryDiffEq
-
-gravity = -9.81
-
 # ==========================================================================================
 # ==== Falling Rocks Simulation Setup
 #
@@ -11,6 +6,11 @@ gravity = -9.81
 # a "fluid" region (containing the rock particles) and a "boundary" region (representing walls).
 # ==========================================================================================
 
+using TrixiParticles
+using OrdinaryDiffEq
+
+gravity = -9.81
+
 particle_spacing = 0.1
 
 rock_width = 2.0

examples/fluid/accelerated_tank_2d.jl

@@ -1,6 +1,10 @@
-# This setup is identical to `hydrostatic_water_column_2d.jl`, except that now there is
+# ==========================================================================================
+# 2D Accelerated Tank Example
+#
+# This setup is identical to `hydrostatic_water_column_2d.jl`, except that there is
 # no gravity, and the tank is accelerated upwards instead.
-# Note that the two setups are physically identical, but produce different numerical errors.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/dam_break_2d.jl

@@ -1,9 +1,16 @@
-# 2D dam break simulation based on
+# ==========================================================================================
+# 2D Dam Break Simulation (δ-SPH Model)
+#
+# Based on:
+#   S. Marrone, M. Antuono, A. Colagrossi, G. Colicchio, D. le Touzé, G. Graziani.
+#   "δ-SPH model for simulating violent impact flows".
+#   Computer Methods in Applied Mechanics and Engineering, Volume 200, Issues 13–16 (2011),
+#   pages 1526–1542.
+#   https://doi.org/10.1016/J.CMA.2010.12.016
 #
-# S. Marrone, M. Antuono, A. Colagrossi, G. Colicchio, D. le Touzé, G. Graziani.
-# "δ-SPH model for simulating violent impact flows".
-# In: Computer Methods in Applied Mechanics and Engineering, Volume 200, Issues 13–16 (2011), pages 1526–1542.
-# https://doi.org/10.1016/J.CMA.2010.12.016
+# This example sets up a 2D dam break simulation using a weakly compressible SPH scheme
+# with a δ-SPH formulation for density calculation.
+# ==========================================================================================
 
 using TrixiParticles
 using OrdinaryDiffEq

examples/fluid/dam_break_2d_gpu.jl

@@ -1,8 +1,21 @@
-# This example file demonstrates how to run an existing example file on a GPU.
-# We simply define a GPU-compatible neighborhood search and `trixi_include` the example
-# file with this neighborhood search.
-# To run this example on a GPU, `parallelization_backend` needs to be changed to the
-# backend for the installed GPU. See the docs on GPU support for more information.
+# ==========================================================================================
+# 2D Dam Break Simulation on GPU
+#
+# This example file demonstrates how to adapt an existing CPU-based example
+# for execution on a GPU. It involves:
+# 1. Including the base CPU example to load common parameters and object definitions
+#    (without running the simulation by setting `sol=nothing`).
+# 2. Defining a GPU-compatible neighborhood search.
+# 3. Re-including the base example, overriding the neighborhood search and specifying
+#    a GPU-compatible parallelization backend.
+#
+# Note: To run this example on an actual GPU, the `parallelization_backend`
+# needs to be changed to a GPU-specific backend like `CUDABackend()` (for NVIDIA GPUs)
+# or `AMDGPUBackend()` (for AMD GPUs), and the corresponding GPU packages
+# (e.g., `CUDA.jl`) must be installed.
+# See the TrixiParticles.jl documentation on GPU support for more details.
+# ==========================================================================================
+
 using TrixiParticles
 
 # Load setup from dam break example

examples/fluid/dam_break_2phase_2d.jl

@@ -1,4 +1,9 @@
-# 2D dam break simulation with an air layer on top
+# ==========================================================================================
+# 2D Two-Phase Dam Break Simulation (Water and Air)
+#
+# This example simulates a 2D dam break with an air layer above the water.
+# It demonstrates how to set up a multi-fluid simulation in TrixiParticles.jl.
+# ==========================================================================================
 
 using TrixiParticles
 using OrdinaryDiffEq

examples/fluid/dam_break_3d.jl

@@ -1,3 +1,10 @@
+# ==========================================================================================
+# 3D Dam Break Simulation
+#
+# This example sets up a 3D dam break simulation using a weakly compressible SPH scheme.
+# It is analogous to the 2D dam break (`dam_break_2d.jl`) but extended to three dimensions.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/dam_break_oil_film_2d.jl

@@ -1,4 +1,10 @@
-# 2D dam break simulation with an oil film on top
+# ==========================================================================================
+# 2D Dam Break Simulation with an Oil Film
+#
+# This example simulates a 2D dam break where a layer of oil sits on top of the water.
+# It demonstrates a multi-fluid simulation with two immiscible fluids.
+# The base water setup is loaded from the `dam_break_2d.jl` example.
+# ==========================================================================================
 
 using TrixiParticles
 using OrdinaryDiffEq

examples/fluid/falling_water_column_2d.jl

@@ -1,3 +1,9 @@
+# ==========================================================================================
+# 2D Falling Water Column Simulation
+#
+# This example simulates a column of water falling under gravity within a closed tank.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/falling_water_spheres_2d.jl

@@ -1,5 +1,11 @@
-# In this example two circles of water drop to the floor demonstrating the difference
-# between the behavior with and without surface tension modelling.
+# ==========================================================================================
+# 2D Falling Water Spheres Simulation (With and Without Surface Tension)
+#
+# This example simulates two circular water "spheres" falling under gravity.
+# One sphere includes a surface tension model (Akinci et al.), while the other does not.
+# This demonstrates the effect of surface tension on fluid behavior.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/falling_water_spheres_3d.jl

@@ -1,3 +1,12 @@
+# ==========================================================================================
+# 3D Falling Water Spheres Simulation (With and Without Surface Tension)
+#
+# This example extends `falling_water_spheres_2d.jl` to three dimensions.
+# It simulates two spherical volumes of water falling under gravity.
+# One sphere includes a surface tension model, while the other does not,
+# demonstrating the effect of surface tension in 3D.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/hydrostatic_water_column_2d.jl

@@ -1,3 +1,10 @@
+# ==========================================================================================
+# 2D Hydrostatic Water Column Simulation
+#
+# This example simulates a column of water at rest in a tank under gravity.
+# It is a basic test case to verify hydrostatic pressure distribution and stability.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/hydrostatic_water_column_3d.jl

@@ -1,3 +1,10 @@
+# ==========================================================================================
+# 3D Hydrostatic Water Column Simulation
+#
+# This example sets up a 3D hydrostatic water column by including and modifying
+# the 2D `hydrostatic_water_column_2d.jl` setup.
+# ==========================================================================================
+
 using TrixiParticles
 
 trixi_include(@__MODULE__,

examples/fluid/lid_driven_cavity_2d.jl

@@ -1,9 +1,19 @@
-# Lid-driven cavity
+# ==========================================================================================
+# 2D Lid-Driven Cavity Simulation
+#
+# Based on:
+#   S. Adami, X. Y. Hu, N. A. Adams.
+#   "A transport-velocity formulation for smoothed particle hydrodynamics".
+#   Journal of Computational Physics, Volume 241 (2013), pages 292-307.
+#   https://doi.org/10.1016/j.jcp.2013.01.043
 #
-# S. Adami et al
-# "A transport-velocity formulation for smoothed particle hydrodynamics".
-# In: Journal of Computational Physics, Volume 241 (2013), pages 292-307.
-# https://doi.org/10.1016/j.jcp.2013.01.043
+# This example simulates a 2D lid-driven cavity flow using SPH with a
+# transport velocity formulation. The top lid moves horizontally, driving the
+# fluid motion within a square cavity.
+#
+# The simulation can be run with either a Weakly Compressible SPH (WCSPH)
+# or an Entropically Damped SPH (EDSPH) formulation for the fluid.
+# ==========================================================================================
 
 using TrixiParticles
 using OrdinaryDiffEq

examples/fluid/moving_wall_2d.jl

@@ -1,3 +1,10 @@
+# ==========================================================================================
+# 2D Moving Wall Simulation
+#
+# This example simulates a column of water in a tank where one of the vertical walls
+# moves horizontally, pushing the fluid.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/oscillating_drop_2d.jl

@@ -1,9 +1,15 @@
-# Oscillating drop in a central force field, based on
+# ==========================================================================================
+# 2D Oscillating Drop Simulation
+#
+# Based on:
+#   J. J. Monaghan, Ashkan Rafiee.
+#   "A Simple SPH Algorithm for Multi-Fluid Flow with High Density Ratios."
+#   International Journal for Numerical Methods in Fluids, 71(5) (2013), pp. 537-561.
+#   https://doi.org/10.1002/fld.3671.
 #
-# J. J. Monaghan, Ashkan Rafiee.
-# "A Simple SPH Algorithm for Multi-Fluid Flow with High Density Ratios."
-# In: International Journal for Numerical Methods in Fluids 71, no. 5 (2013), pages 537-61.
-# https://doi.org/10.1002/fld.3671.
+# This example simulates a 2D elliptical drop of fluid oscillating under a central
+# force field.
+# ==========================================================================================
 
 using TrixiParticles
 using OrdinaryDiffEq

examples/fluid/periodic_array_of_cylinders_2d.jl

@@ -1,9 +1,16 @@
-# Channel flow through periodic array of cylinders
+# ==========================================================================================
+# 2D Channel Flow Through a Periodic Array of Cylinders
+#
+# Based on:
+#   S. Adami, X. Y. Hu, N. A. Adams.
+#   "A transport-velocity formulation for smoothed particle hydrodynamics".
+#   Journal of Computational Physics, Volume 241 (2013), pages 292-307.
+#   https://doi.org/10.1016/J.JCP.2013.01.043
 #
-# S. Adami et al.
-# "A transport-velocity formulation for smoothed particle hydrodynamics".
-# In: Journal of Computational Physics, Volume 241 (2013), pages 292-307.
-# https://doi.org/10.1016/j.jcp.2013.01.043
+# This example simulates fluid flow driven by a body force through a channel
+# containing a periodic array of cylinders. Due to periodicity, only one cylinder
+# within a representative channel segment is simulated.
+# ==========================================================================================
 
 using TrixiParticles
 using OrdinaryDiffEq

examples/fluid/periodic_channel_2d.jl

@@ -1,3 +1,12 @@
+# ==========================================================================================
+# 2D Periodic Channel Flow Simulation
+#
+# This example simulates fluid flow in a 2D channel with periodic boundary
+# conditions in the flow direction (x-axis) and solid walls at the top and bottom.
+# The fluid is initialized with a uniform velocity.
+# This setup can be used to study Poiseuille flow or turbulent channel flow characteristics.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/pipe_flow_2d.jl

@@ -1,4 +1,11 @@
-# 2D channel flow simulation with open boundaries.
+# ==========================================================================================
+# 2D Pipe Flow Simulation with Open Boundaries (Inflow/Outflow)
+#
+# This example simulates fluid flow through a 2D pipe (channel) with an inflow
+# boundary condition on one end and an outflow boundary condition on the other.
+# Solid walls form the top and bottom of the pipe.
+# The simulation demonstrates the use of open boundary conditions in TrixiParticles.jl.
+# ==========================================================================================
 
 using TrixiParticles
 using OrdinaryDiffEq

examples/fluid/pipe_flow_3d.jl

@@ -1,4 +1,9 @@
-# 3D channel flow simulation with open boundaries.
+# ==========================================================================================
+# 3D Pipe Flow Simulation with Open Boundaries (Inflow/Outflow)
+#
+# This example extends the 2D pipe flow simulation (`pipe_flow_2d.jl`) to three
+# dimensions.
+# ==========================================================================================
 
 using TrixiParticles
 

examples/fluid/sphere_surface_tension_2d.jl

@@ -1,5 +1,11 @@
-# In this example we can observe that the `SurfaceTensionAkinci` surface tension model correctly leads to a
-# surface minimization of the water square and approaches a sphere.
+# ==========================================================================================
+# 2D Sphere Formation via Surface Tension
+#
+# This example demonstrates how surface tension models in TrixiParticles.jl
+# can cause an initially square patch of fluid to minimize its surface area,
+# ideally forming a circular (2D sphere) shape.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/sphere_surface_tension_3d.jl

@@ -1,5 +1,12 @@
-# In this example we can observe that the `SurfaceTensionAkinci` surface tension model correctly leads to a
-# surface minimization of the water cube and approaches a sphere.
+# ==========================================================================================
+# 3D Sphere Formation via Surface Tension
+#
+# This example extends the 2D sphere formation simulation (`sphere_surface_tension_2d.jl`)
+# to three dimensions. It demonstrates how an initially cubical patch of fluid
+# minimizes its surface area under the influence of a surface tension model,
+# ideally forming a spherical shape.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/sphere_surface_tension_wall_2d.jl

@@ -1,3 +1,12 @@
+# ==========================================================================================
+# 2D Sphere with Surface Tension Interacting with a Wall (Wetting Phenomena)
+#
+# This example simulates a 2D circular drop of fluid (sphere) under gravity,
+# influenced by surface tension, as it interacts with a solid horizontal wall.
+# The setup is designed to observe wetting phenomena (e.g., spreading or beading)
+# by adjusting surface tension and adhesion parameters.
+# ==========================================================================================
+
 using TrixiParticles
 using OrdinaryDiffEq
 

examples/fluid/taylor_green_vortex_2d.jl

@@ -1,9 +1,15 @@
-# Taylor Green vortex
+# ==========================================================================================
+# 2D Taylor-Green Vortex Simulation
+#
+# Based on:
+#   P. Ramachandran, K. Puri.
+#   "Entropically damped artificial compressibility for SPH".
+#   Computers and Fluids, Volume 179 (2019), pages 579-594.
+#   https://doi.org/10.1016/j.compfluid.2018.11.023
 #
-# P. Ramachandran, K. Puri
-# "Entropically damped artificial compressibility for SPH".
-# In: Computers and Fluids, Volume 179 (2019), pages 579-594.
-# https://doi.org/10.1016/j.compfluid.2018.11.023
+# This example simulates the Taylor-Green vortex, a classic benchmark case for
+# incompressible viscous flow, characterized by an array of decaying vortices.
+# ==========================================================================================
 
 using TrixiParticles
 using OrdinaryDiffEq