Merge remote-tracking branch 'upstream/main' into fix_obs_for_free_su…

…rface

.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.23.6
+        uses: crate-ci/typos@v1.25.0

README.md

@@ -12,7 +12,8 @@
 
 **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.
-Its features include:
+
+[![YouTube](https://github.com/user-attachments/assets/dc2be627-a799-4bfd-9226-2077f737c4b0)](https://www.youtube.com/watch?v=V7FWl4YumcA&t=4667s)
 
 ## Features
 - Incompressible Navier-Stokes

docs/Project.toml

@@ -1,11 +1,13 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 PointNeighbors = "1c4d5385-0a27-49de-8e2c-43b175c8985c"
 TrixiBase = "9a0f1c46-06d5-4909-a5a3-ce25d3fa3284"
 
 [compat]
 Documenter = "1"
+DocumenterCitations = "1"
 OrdinaryDiffEq = "6"
 PointNeighbors = "0.4"
 TrixiBase = "0.1"

docs/make.jl

@@ -1,4 +1,4 @@
-using Documenter
+using Documenter, DocumenterCitations
 using TrixiParticles
 using TrixiBase
 using PointNeighbors
@@ -90,7 +90,10 @@ copy_file("NEWS.md")
 # Define module-wide setups such that the respective modules are available in doctests
 DocMeta.setdocmeta!(TrixiParticles, :DocTestSetup, :(using TrixiParticles); recursive=true)
 
+bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"))
+
 makedocs(sitename="TrixiParticles.jl",
+         plugins=[bib],
          # Run doctests and check docs for the following modules
          modules=[TrixiParticles],
          format=Documenter.HTML(),
@@ -139,6 +142,7 @@ makedocs(sitename="TrixiParticles.jl",
              "Contributing" => "contributing.md",
              "Code of Conduct" => "code_of_conduct.md",
              "License" => "license.md",
+             "References" => "references.md",
          ])
 
 deploydocs(repo="github.com/trixi-framework/TrixiParticles.jl",

docs/src/install.md

@@ -1,8 +1,8 @@
 # [Installation](@id 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
+If you have not yet installed Julia, please [follow the instructions on the
+official website](https://julialang.org/downloads/). TrixiParticles.jl works
 with Julia v1.9 and newer. We recommend using the latest stable release of Julia.
 
 ## For users

docs/src/preprocessing/preprocessing.md

@@ -15,12 +15,12 @@ Here, ``\Theta_i`` is the *signed* angle between ``\mathbf{c}_i - \mathbf{p}`` a
 In 3D, we refer to the solid angle of an *oriented* triangle with respect to ``\mathbf{p}``.
 
 We provide the following methods to calculate ``w(\mathbf{p})``:
-- Horman et al. (2001) evaluate the winding number combined with an even-odd rule, but only for 2D polygons (see [WindingNumberHorman](@ref)).
-- Naive winding: Jacobson et al. (2013) generalized the winding number so that the algorithm can be applied for both 2D and 3D geometries (see [WindingNumberJacobson](@ref)).
-- Hierarchical winding: Jacobson et al. (2013) also introduced a fast hierarchical evaluation of the winding number. For further information see the description below.
+- [Hormann et al. (2001)](@cite Hormann2001) evaluate the winding number combined with an even-odd rule, but only for 2D polygons (see [WindingNumberHormann](@ref)).
+- Naive winding: [Jacobson et al. (2013)](@cite Jacobson2013) generalized the winding number so that the algorithm can be applied for both 2D and 3D geometries (see [WindingNumberJacobson](@ref)).
+- Hierarchical winding: [Jacobson et al. (2013)](@cite Jacobson2013) also introduced a fast hierarchical evaluation of the winding number. For further information see the description below.
 
 ## [Hierarchical Winding](@id hierarchical_winding)
-According to Jacobson et al. (2013) the winding number with respect to a polygon (2D) or triangle mesh (3D) is the sum of the winding numbers with respect to each edge (2D) or face (3D).
+According to [Jacobson et al. (2013)](@cite Jacobson2013) the winding number with respect to a polygon (2D) or triangle mesh (3D) is the sum of the winding numbers with respect to each edge (2D) or face (3D).
 We can show this with the following example in which we determine the winding number for each edge of a triangle separately and sum them up:
 
 ```julia
@@ -164,7 +164,7 @@ Splitting stops when the number of a box's edges slips below a
 threshold (usually ``\approx 100`` faces in 3D, here: 6 edges).
 
 (3):
-For the closure, Jacobson et al. (2013) define *exterior vertices* (*exterior edges* in 3D)
+For the closure, [Jacobson et al. (2013)](@cite Jacobson2013) define *exterior vertices* (*exterior edges* in 3D)
 as boundary vertices of such a segmentation (red dots in (3)).
 To find them, we traverse around each edge (face in 3D) in order, and
 increment or decrement for each vertex (edge) a specific counter.
@@ -210,7 +210,7 @@ This is because the property ``w_{\mathcal{S}}(\mathbf{p}) = - w_{\bar{\mathcal{
 only holds when ``\mathbf{p}`` is outside of ``\mathcal{B}``, which is not the case here.
 
 #### Correct evaluation
-Jacobson et al. (2013) don't mention this problem or provide a solution to it.
+[Jacobson et al. (2013)](@cite Jacobson2013) don't mention this problem or provide a solution to it.
 We contacted the authors and found that they know about this problem and solve it
 by resizing the bounding box to fully include the closing surface
 of the neighboring box, since it doesn't matter if the boxes overlap.
@@ -243,7 +243,7 @@ The evaluation then looks as follows.
 
 ```@autodocs
 Modules = [TrixiParticles]
-Pages = [joinpath("preprocessing", "point_in_poly", "winding_number_horman.jl")]
+Pages = [joinpath("preprocessing", "point_in_poly", "winding_number_hormann.jl")]
 ```
 
 ```@autodocs
@@ -255,11 +255,3 @@ Pages = [joinpath("preprocessing", "point_in_poly", "winding_number_jacobson.jl"
 Modules = [TrixiParticles]
 Pages = [joinpath("preprocessing", "geometries", "io.jl")]
 ```
-
-### [References](@id references_complex_shape)
-- Alec Jacobson, Ladislav Kavan, and Olga Sorkine-Hornung "Robust inside-outside segmentation using generalized winding numbers".
-  In: ACM Transactions on Graphics, 32.4 (2013), pages 1--12.
-  [doi: 10.1145/2461912.2461916](https://igl.ethz.ch/projects/winding-number/robust-inside-outside-segmentation-using-generalized-winding-numbers-siggraph-2013-jacobson-et-al.pdf)
-- Kai Horman, Alexander Agathos "The point in polygon problem for arbitrary polygons".
-  In: Computational Geometry, 20.3 (2001), pages 131--144.
-  [doi: 10.1016/s0925-7721(01)00012-8](https://doi.org/10.1016/S0925-7721(01)00012-8)

docs/src/references.md

@@ -0,0 +1,2 @@
+```@bibliography
+```