Docs tutorials

.gitignore

@@ -9,6 +9,7 @@ docs/src/contributing.md
 docs/src/license.md
 docs/src/code_of_conduct.md
 docs/src/news.md
+*_replaced.md
 run
 *.json
 *.png

docs/make.jl

@@ -6,7 +6,8 @@ using TrixiBase
 trixiparticles_root_dir = dirname(@__DIR__)
 
 # Copy files to not need to synchronize them manually
-function copy_file(filename, replaces...)
+function copy_file(filename, replaces...;
+                   new_file=joinpath(@__DIR__, "src", lowercase(filename)))
     source_path = joinpath(trixiparticles_root_dir, filename)
 
     if !isfile(source_path)
@@ -24,9 +25,52 @@ function copy_file(filename, replaces...)
     """
     content = header * content
 
-    write(joinpath(@__DIR__, "src", lowercase(filename)), content)
+    write(new_file, content)
 end
 
+function replace_with_code(filename)
+    if !isfile(filename)
+        cwd = pwd()
+        error("Markdown file not found: $filename in directory: $cwd")
+        return
+    end
+
+    # Define a regex pattern to match the include markers
+    pattern = r"!!include:([^\s!]+\.jl)!!"
+
+    function replace_include(match_::SubString{String})
+        # Extract the filename using regex
+        m = match(pattern, match_)
+        if m === nothing
+            error("Invalid include format in: $match")
+        end
+        file_to_include = joinpath(trixiparticles_root_dir, m.captures[1])
+
+        try
+            # Check if the Julia file exists
+            if !isfile(file_to_include)
+                error("File to include not found: $(file_to_include)")
+            end
+
+            # Read the content of the file to include
+            return read(file_to_include, String)
+        catch e
+            # In case of any error
+            error("Unable to include file $(file_to_include): $(e)")
+        end
+    end
+
+    # Replace all occurrences in the markdown content
+    filename_noext, extension = splitext(filename)
+    copy_file(filename, new_file="$(filename_noext)_replaced$extension",
+              pattern => replace_include)
+end
+
+replace_with_code("docs/src/tutorials/tut_setup.md")
+replace_with_code("docs/src/tutorials/tut_dam_break.md")
+replace_with_code("docs/src/tutorials/tut_beam.md")
+replace_with_code("docs/src/tutorials/tut_falling.md")
+
 copy_file("AUTHORS.md",
           "in the [LICENSE.md](LICENSE.md) file" => "under [License](@ref)")
 copy_file("CONTRIBUTING.md",

docs/src/examples.md

@@ -1,7 +1,14 @@
 # Examples
 
 
-## WCSPH
+## Fluid
 
 
-## TLSPH
+## Structure Mechanics
+
+
+## Fluid Structure Interaction
+
+
+## Postprocessing
+

docs/src/install.md

@@ -15,7 +15,7 @@ code from the cloned directory:
 git clone [email protected]:trixi-framework/TrixiParticles.jl.git
 cd TrixiParticles.jl
 mkdir run
-julia --project=run -e 'using Pkg; Pkg.develop(PackageSpec(path=".."))' # Install locally
+julia --project=run -e 'using Pkg; Pkg.develop(PackageSpec(path="."))' # Install locally
 julia --project=run -e 'using Pkg; Pkg.add("OrdinaryDiffEq")' # Add TrixiParticles.jl to `run` project
 ```
 

docs/src/tutorial.md

@@ -2,9 +2,12 @@
 
 
 ## Fluid
-
+- [Setting up your simulation from scratch](tutorials/tut_setup_replaced.md)
+- [Setting up a dam break simulation](tutorials/tut_dam_break_replaced.md)
 
 ## Mechanics
+- [Deforming a beam](tutorials/tut_beam_replaced.md)
 
 
-## Fluid-Structure Interaction
+## Fluid-Structure Interaction
+- [Setting up a falling structure](tutorials/tut_falling_replaced.md)

docs/src/tutorials/tut_beam.md

@@ -0,0 +1,5 @@
+# Example file
+```julia
+!!include:examples/solid/oscillating_beam_2d.jl!!
+
+```

docs/src/tutorials/tut_dam_break.md

@@ -0,0 +1,5 @@
+# Example file
+```julia
+!!include:examples/fluid/dam_break_2d.jl!!
+
+```

docs/src/tutorials/tut_falling.md

@@ -0,0 +1,5 @@
+# Example file
+```julia
+!!include:examples/fsi/falling_spheres_2d.jl!!
+
+```

docs/src/tutorials/tut_setup.md

@@ -0,0 +1,13 @@
+# Setting up your simulation from scratch
+
+## Hydrostatic tank
+
+
+
+
+# Example file
+```julia
+!!include:examples/fluid/hydrostatic_water_column_2d.jl!!
+
+```
+

examples/fluid/hydrostatic_water_column_edac_2d.jl

@@ -32,5 +32,4 @@ saving_callback = SolutionSavingCallback(dt=0.02, prefix="")
 callbacks = CallbackSet(info_callback, saving_callback)
 
 # Use a Runge-Kutta method with automatic (error based) time step size control
-sol = solve(ode, RDPK3SpFSAL35(),
-            save_everystep=false, callback=callbacks);
+sol = solve(ode, RDPK3SpFSAL35(), save_everystep=false, callback=callbacks);

src/general/semidiscretization.jl

@@ -195,9 +195,33 @@ end
 @inline foreach_system(f, systems) = foreach_noalloc(f, systems)
 
 """
-    semidiscretize(semi, tspan)
+    semidiscretize(semi, tspan; reset_threads=true)
 
 Create an `ODEProblem` from the semidiscretization with the specified `tspan`.
+
+# Arguments
+- `semi`: A [`Semidiscretization`](@ref) holding the systems involved in the simulation.
+- `tspan`: The time span over which the simulation will be run.
+
+# Keywords
+- `reset_threads`: A boolean flag to reset Polyester.jl threads before the simulation (default: `true`).
+  After an error within a threaded loop, threading might be disabled. Resetting the threads before the simulation
+  ensures that threading is enabled again for the simulation.
+  See also [trixi-framework/Trixi.jl#1583](https://github.com/trixi-framework/Trixi.jl/issues/1583).
+
+# Returns
+A `DynamicalODEProblem` (see [the OrdinaryDiffEq.jl docs](https://docs.sciml.ai/DiffEqDocs/stable/types/dynamical_types/))
+to be integrated with [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl).
+Note that this is not a true `DynamicalODEProblem` where the acceleration does not depend on the velocity.
+Therefore, not all integrators designed for `DynamicalODEProblems` will work properly.
+However, all integrators designed for `ODEProblems` can be used.
+
+# Examples
+```julia
+semi = Semidiscretization(fluid_system, boundary_system)
+tspan = (0.0, 1.0)
+ode_problem = semidiscretize(semi, tspan)
+```
 """
 function semidiscretize(semi, tspan; reset_threads=true)
     (; systems) = semi