Merge branch 'main' into switch-integration

.github/workflows/Documenter.yml

@@ -0,0 +1,44 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - 'main'
+    tags: '*'
+    paths-ignore:
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/CompatHelper.yml'
+  pull_request:
+    paths-ignore:
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/CompatHelper.yml'
+  workflow_dispatch:
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+jobs:
+  build-docs:
+    name: Build and Deploy Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out project
+        uses: actions/checkout@v4
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+          show-versioninfo: true
+      - uses: julia-actions/cache@v1
+      - name: Build package
+        uses: julia-actions/julia-buildpkg@v1
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        # env:
+        #   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        #   DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs --color=yes docs/make.jl

.github/workflows/FormatCheck.yml

@@ -0,0 +1,40 @@
+name: Format Check
+
+on:
+  push:
+    branches:
+      - 'main'
+    tags: '*'
+  pull_request:
+
+jobs:
+  check-format:
+    name: Check format with JuliaFormatter.jl
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out project
+        uses: actions/checkout@v4
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - run: julia -e 'using InteractiveUtils; versioninfo(verbose=true)'
+      - uses: julia-actions/cache@v1
+      - name: Install JuliaFormatter and format
+        # This will use the latest version by default but you can set the version like so:
+        #
+        # julia  -e 'using Pkg; Pkg.add(PackageSpec(name = "JuliaFormatter", version = "0.13.0"))'
+        run: |
+          julia  -e 'using Pkg; Pkg.add(PackageSpec(name = "JuliaFormatter"))'
+          julia  -e 'using JuliaFormatter; format(".")'
+      - name: Format check
+        run: |
+          julia -e '
+          out = Cmd(`git diff --name-only`) |> read |> String
+          if out == ""
+              exit(0)
+          else
+              @error "Some files have not been formatted !!!"
+              write(stdout, out)
+              exit(1)
+          end'

.github/workflows/SpellCheck.yml

@@ -10,4 +10,4 @@ jobs:
       - name: Checkout Actions Repository
         uses: actions/checkout@v4
       - name: Check spelling
-        uses: crate-ci/typos@v1.16.26
+        uses: crate-ci/typos@v1.17.2

.github/workflows/ci.yml

@@ -33,6 +33,7 @@ concurrency:
 
 jobs:
   build:
+    name: Run Tests
     runs-on: ubuntu-latest
 
     steps:
@@ -43,11 +44,6 @@ jobs:
         with:
           version: '1'
       - uses: julia-actions/cache@v1
-      - name: Apply JuliaFormatter and check format
-        run: |
-          julia -e 'using Pkg; Pkg.add("JuliaFormatter")'
-          julia -e 'using JuliaFormatter; !format(".", verbose=true) &&
-            error("Code not properly formatted")'
       - name: Build package
         uses: julia-actions/julia-buildpkg@v1
       - name: Run unit tests
@@ -62,16 +58,13 @@ jobs:
         with:
           directories: src,test
       - name: Upload coverage report to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
-          token: ${{ secrets.CODECOV_TOKEN }}
           files: lcov.info
           fail_ci_if_error: true
           flags: unit
-      - name: Compile docs
-        run: |
-          julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
-          julia --project=docs --color=yes docs/make.jl
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
       - name: Run example tests
         uses: julia-actions/julia-runtest@v1
         with:

.gitignore

@@ -12,8 +12,10 @@ docs/src/news.md
 run
 *.json
 *.png
+*.jpg
 *.gif
 *.svg
 *.vtu
 *.pvd
 *.mp4
+*.csv

LICENSE.md

@@ -1,7 +1,8 @@
 MIT License
 
-Copyright (c) 2023-present The TrixiParticles.jl Authors (see [AUTHORS.md](AUTHORS.md))
-
+Copyright (c) 2023-present The TrixiParticles.jl Authors (see [AUTHORS.md](AUTHORS.md)) \
+Copyright (c) 2023-present Helmholtz-Zentrum hereon GmbH, Institute of Surface Science \
+ \
 Permission is hereby granted, free of charge, to any person obtaining a copy  
 of this software and associated documentation files (the "Software"), to deal  
 in the Software without restriction, including without limitation the rights  

README.md

@@ -10,7 +10,7 @@
 
 **TrixiParticles.jl** is a numerical simulation framework designed for particle-based numerical methods, with an emphasis on multiphysics applications, written in [Julia](https://julialang.org).
 A primary goal of the framework is to be user-friendly for engineering, science, and educational purposes. In addition to its extensible design and optimized implementation, we prioritize the user experience, including installation, pre- and postprocessing.
-It features include:
+Its features include:
 
 ## Features
 - Incompressible Navier-Stokes

docs/make.jl

@@ -5,7 +5,14 @@ trixiparticles_root_dir = dirname(@__DIR__)
 
 # Copy files to not need to synchronize them manually
 function copy_file(filename, replaces...)
-    content = read(joinpath(trixiparticles_root_dir, filename), String)
+    source_path = joinpath(trixiparticles_root_dir, filename)
+
+    if !isfile(source_path)
+        error("File $filename not found. Ensure that you provide a path relative to the TrixiParticles.jl root directory.")
+        return
+    end
+
+    content = read(source_path, String)
     content = replace(content, replaces...)
 
     header = """
@@ -38,6 +45,8 @@ makedocs(sitename="TrixiParticles.jl",
          pages=[
              "Home" => "index.md",
              "News" => "news.md",
+             "Installation" => "install.md",
+             "Getting started" => "getting_started.md",
              "Components" => [
                  "General" => [
                      "Semidiscretization" => joinpath("general", "semidiscretization.md"),

docs/src/getting_started.md

@@ -0,0 +1 @@
+# Getting started

docs/src/index.md

@@ -1 +1,24 @@
 # TrixiParticles.jl
+
+TrixiParticles.jl is a numerical simulation framework designed for particle-based numerical methods, with an emphasis on multiphysics applications, written in Julia. A primary goal of the framework is to be user-friendly for engineering, science, and educational purposes. In addition to its extensible design and optimized implementation, we prioritize the user experience, including installation, pre- and postprocessing. Its features include:
+
+## Features
+- Incompressible Navier-Stokes
+  - Methods: Weakly Compressible Smoothed Particle Hydrodynamics (WCSPH), Entropically Damped Artificial Compressibility (EDAC)
+- Solid-body mechanics
+  - Methods: Total Lagrangian SPH (TLSPH)
+- Fluid-Structure Interaction
+- Output formats:
+  - VTK
+
+## Examples
+
+
+## Quickstart
+1. [Installation](@ref)
+2. [Getting started](@ref)
+
+
+## Start with development
+1. [Installation](@ref)
+2. [Contributing](@ref)

docs/src/install.md

@@ -0,0 +1,57 @@
+# Installation
+
+## Setting up Julia
+If you have not yet installed Julia, please [follow the instructions for your
+operating system](https://julialang.org/downloads/platform/). TrixiParticles.jl works
+with Julia v1.9 and newer. We recommend using the latest stable release of Julia.
+
+## Installation for users
+
+
+## [Installation for developers](@id for-developers)
+If you plan on editing TrixiParticles.jl itself, you can download TrixiParticles.jl to a local folder and use the
+code from the cloned directory:
+```bash
+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.add("OrdinaryDiffEq")' # Add TrixiParticles.jl to `run` project
+```
+
+If you installed TrixiParticles.jl this way, you always have to start Julia with the `--project`
+flag set to your `run` directory, e.g.,
+```bash
+julia --project=run
+```
+from the TrixiParticles.jl root directory.
+
+The advantage of using a separate `run` directory is that you can also add other
+related packages (e.g., OrdinaryDiffEq.jl, see above) to the project in the `run` folder
+and always have a reproducible environment at hand to share with others.
+
+## Optional software/packages
+- [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) -- A Julia package of ordinary differential equation solvers that is used in the examples
+- [Plots.jl](https://github.com/JuliaPlots/Plots.jl) -- Julia Plotting library that is used in some examples
+- [PythonPlot.jl](https://github.com/JuliaPy/PythonPlot.jl) -- Plotting library that can be used instead of Plots.jl
+- [ParaView](https://www.paraview.org/) -- Software that can be used for visualization of results
+
+## Common issues
+
+If you followed the [installation instructions for developers](@ref for-developers) and you
+run into any problems with packages when pulling the latest version of TrixiParticles.jl,
+start Julia with the project in the `run` folder,
+```bash
+   julia --project=run
+```
+update all packages in that project, resolve all conflicts in the project, and install all
+new dependencies:
+```julia
+julia> using Pkg
+
+julia> Pkg.update()
+
+julia> Pkg.resolve()
+
+julia> Pkg.instantiate()
+```

examples/fluid/oscillating_drop_2d.jl

@@ -0,0 +1,93 @@
+# Oscillating drop in a central force field, based on
+#
+# 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.
+
+using TrixiParticles
+using OrdinaryDiffEq
+
+# ==========================================================================================
+# ==== Resolution
+fluid_particle_spacing = 0.05
+
+# ==========================================================================================
+# ==== Experiment Setup
+radius = 1.0
+sigma = 0.5
+# Make this a constant because global variables in the source terms are slow
+const OMEGA = 1.0
+
+source_terms = (coords, velocity, density, pressure) -> -OMEGA^2 * coords
+
+# 1 period in the exact solution as computed below (but integrated with a small timestep)
+period = 4.567375
+tspan = (0.0, 1period)
+
+fluid_density = 1000.0
+sound_speed = 10.0
+state_equation = StateEquationCole(; sound_speed, exponent=7,
+                                   reference_density=fluid_density)
+
+# Equation A.19 in the paper rearranged.
+# sigma^2 = Q / rho * (a^2 + b^2) / (a^2 b^2) - OMEGA^2.
+Q = (sigma^2 + OMEGA^2) * fluid_density / 2
+pressure = coords -> Q * (1 - coords[1]^2 - coords[2]^2)
+density = coords -> TrixiParticles.inverse_state_equation(state_equation, pressure(coords))
+
+fluid = SphereShape(fluid_particle_spacing, radius, (0.0, 0.0),
+                    density, pressure=pressure,
+                    sphere_type=RoundSphere(),
+                    velocity=coords -> sigma .* (coords[1], -coords[2]))
+
+# ==========================================================================================
+# ==== Fluid
+smoothing_length = 3.0 * fluid_particle_spacing
+smoothing_kernel = WendlandC2Kernel{2}()
+
+fluid_density_calculator = ContinuityDensity()
+viscosity = ArtificialViscosityMonaghan(alpha=0.01, beta=0.0)
+
+density_diffusion = DensityDiffusionAntuono(fluid, delta=0.1)
+fluid_system = WeaklyCompressibleSPHSystem(fluid, fluid_density_calculator,
+                                           state_equation, smoothing_kernel,
+                                           smoothing_length, viscosity=viscosity,
+                                           density_diffusion=density_diffusion,
+                                           source_terms=source_terms)
+
+# ==========================================================================================
+# ==== Simulation
+semi = Semidiscretization(fluid_system)
+ode = semidiscretize(semi, tspan)
+
+info_callback = InfoCallback(interval=50)
+saving_callback = SolutionSavingCallback(dt=0.04, prefix="")
+
+callbacks = CallbackSet(info_callback, saving_callback)
+
+# Use a Runge-Kutta method with automatic (error based) time step size control.
+sol = solve(ode, RDPK3SpFSAL49(),
+            abstol=1e-7, # Default abstol is 1e-6 (may need to be tuned to prevent intabilities)
+            reltol=1e-4, # Default reltol is 1e-3 (may need to be tuned to prevent intabilities)
+            save_everystep=false, callback=callbacks);
+
+@inline function exact_solution_rhs(u, p, t)
+    sigma, A, B = u
+
+    dsigma = (sigma^2 + OMEGA^2) * ((B^2 - A^2) / (B^2 + A^2))
+    dA = sigma * A
+    dB = -sigma * B
+
+    return SVector(dsigma, dA, dB)
+end
+
+exact_u0 = SVector(sigma, radius, radius)
+exact_solution_ode = ODEProblem(exact_solution_rhs, exact_u0, tspan)
+
+# Use the same time integrator to avoid compilation of another integrator in CI
+sol_exact = solve(exact_solution_ode, RDPK3SpFSAL49(), save_everystep=false)
+
+# Error in the semi-major axis of the elliptical drop
+error_A = maximum(sol.u[end].x[2]) + 0.5fluid_particle_spacing -
+          maximum(sol_exact.u[end][2:3])

examples/fsi/dam_break_2d.jl

@@ -88,8 +88,8 @@ boundary_system = BoundarySPHSystem(tank.boundary, boundary_model)
 
 # ==========================================================================================
 # ==== Solid
-solid_smoothing_length = sqrt(2) * solid_particle_spacing
-solid_smoothing_kernel = SchoenbergCubicSplineKernel{2}()
+solid_smoothing_length = 2 * sqrt(2) * solid_particle_spacing
+solid_smoothing_kernel = WendlandC2Kernel{2}()
 
 # For the FSI we need the hydrodynamic masses and densities in the solid boundary model
 hydrodynamic_densites = fluid_density * ones(size(solid.density))

examples/fsi/dam_break_gate_2d.jl

@@ -117,8 +117,8 @@ boundary_system_gate = BoundarySPHSystem(gate, boundary_model_gate, movement=gat
 
 # ==========================================================================================
 # ==== Solid
-solid_smoothing_length = sqrt(2) * solid_particle_spacing
-solid_smoothing_kernel = SchoenbergCubicSplineKernel{2}()
+solid_smoothing_length = 2 * sqrt(2) * solid_particle_spacing
+solid_smoothing_kernel = WendlandC2Kernel{2}()
 
 # For the FSI we need the hydrodynamic masses and densities in the solid boundary model
 hydrodynamic_densites = fluid_density * ones(size(solid.density))