Update Docs (#1085)

* correct language and general update pass

* Clarify GPU support for devices

Removed 'Experimental' from GPU support description.

* implement suggestions

* update with rigid body feature

* small h

* break line

---------

Co-authored-by: Erik Faulhaber <44124897+efaulhaber@users.noreply.github.com>

Author: svchb

README.md

@@ -15,30 +15,31 @@
   <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/479ff0c6-3c65-44fe-b3e0-2ed653e7e3a5" alt="TrixiP_logo" width="40%"/>
 </p>
 
-**TrixiParticles.jl** is a high-performance numerical simulation framework for particle-based methods, focused on the simulation of complex multiphysics problems, and written in [Julia](https://julialang.org).
+**TrixiParticles.jl** is a high-performance numerical simulation framework for particle-based methods in complex multiphysics applications, written in [Julia](https://julialang.org).
+It combines an accessible user interface with an extensible architecture for developing new methods, while offering high performance on both CPU and GPU.
 
 TrixiParticles.jl focuses on the following use cases:
-- Accurate and efficient physics-based modelling of complex multiphysics problems.
+
+- Accurate and efficient physics-based modeling of complex multiphysics problems.
 - Development of new particle-based methods and models.
-- Easy setup of accessible simulations for educational purposes, including student projects, coursework, and thesis work.
+- Accessible simulation setup for educational purposes, including student projects, coursework, and thesis work.
 
-It offers intuitive configuration, robust pre- and post-processing, and vendor-agnostic GPU-support based on the Julia package [KernelAbstractions.jl](https://github.com/JuliaGPU/KernelAbstractions.jl).
+It offers intuitive configuration, robust pre- and post-processing, and vendor-agnostic GPU support based on the Julia package [KernelAbstractions.jl](https://github.com/JuliaGPU/KernelAbstractions.jl).
 
 [![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
-  - Methods: Weakly Compressible Smoothed Particle Hydrodynamics (WCSPH),
-    Entropically Damped Artificial Compressibility (EDAC),
-    Implicit Incompressible SPH (IISPH)
+- Incompressible Navier-Stokes flows
+  - Methods: Weakly Compressible Smoothed Particle Hydrodynamics (WCSPH), Entropically Damped Artificial Compressibility (EDAC),
+    Implicit Incompressible Smoothed Particle Hydrodynamics (IISPH)
   - Models: Surface Tension, Open Boundaries
-- Solid-body mechanics
-  - Methods:  Total Lagrangian SPH (TLSPH), Discrete Element Method (DEM), Rigid Body Dynamics (RBD)
-- Fluid-Structure Interaction
-- Particle sampling of complex geometries from `.stl` and `.asc` files.
+- Structural mechanics
+  - Methods: Total Lagrangian SPH (TLSPH), Discrete Element Method (DEM), Rigid Body Dynamics (RBD)
+- Fluid-Structure Interaction with elastic structures and rigid bodies
+- Particle sampling of complex geometries from `.stl`, `.asc`, and `.dxf` files.
 - Output formats:
   - VTK
-- Support for GPUs by Nvidia, AMD and Apple (experimental)
+- GPU support for NVIDIA, AMD, and Apple devices
 
 ## Examples
 We provide several example simulation setups in the `examples` folder (which can be accessed from Julia via `examples_dir()`).
@@ -68,7 +69,7 @@ We provide several example simulation setups in the `examples` folder (which can
 
 
 ## Installation
-If you have not yet installed Julia, please [follow the instructions for your
+If you have not installed Julia yet, please [follow the instructions for your
 operating system](https://julialang.org/downloads/platform/). TrixiParticles.jl works
 with Julia v1.10 and newer. We recommend using the latest stable release of Julia.
 
@@ -116,7 +117,12 @@ Then start the simulation by executing
 julia> trixi_include(joinpath(examples_dir(), "fluid", "hydrostatic_water_column_2d.jl"))
 ```
 
-This will open a new window with a 2D visualization of the final solution:
+To visualize the result quickly, use Plots.jl:
+```julia
+julia> using Plots; plot(sol)
+```
+
+This opens a new window with a 2D visualization of the final solution:
 <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/44124897/95821154-577d-4323-ba57-16ef02ea24e0" width="400">
 
 Further details can be found in the [documentation](https://trixi-framework.github.io/TrixiParticles.jl/stable).

docs/literate/src/tut_rigid_body_fsi.jl

@@ -381,12 +381,12 @@ nothing # hide
 # ### Loading Geometries from Files
 #
 # Instead of using predefined shapes like `RectangularShape` or `SphereShape`, you can load
-# custom geometries from external files. For 2D, `TrixiParticles.jl` supports a simple
+# custom geometries from external files. For 2D, TrixiParticles.jl supports a simple
 # ASCII format with the extension `.asc`.
 #
 # An `.asc` file should contain a list of 2D coordinates, with x and y values separated by a space,
 # and one point per line. The points should form a closed polygon.
-# `TrixiParticles.jl` includes some example files in the `examples/preprocessing/data` directory.
+# TrixiParticles.jl includes some example files in the `examples/preprocessing/data` directory.
 #
 # Here is how you can load the `hexagon.asc` file from this directory, create a `ComplexShape` from it,
 # and then use it in a simulation.
@@ -432,7 +432,7 @@ nothing # hide
 #
 # You can find the `.asc` files used in this tutorial and other examples in the
 # [`examples/preprocessing/data`](https://github.com/trixi-framework/TrixiParticles.jl/blob/main/examples/preprocessing/data/)
-# directory of the `TrixiParticles.jl` repository.
+# directory of the TrixiParticles.jl repository.
 #
 # Some files can be found in examples/preprocessing/data.
 # To use them, you can use `pkgdir` as shown above, for example:

docs/make.jl

@@ -127,8 +127,8 @@ makedocs(sitename="TrixiParticles.jl",
                                                                            "implicit_incompressible_sph.md")
                      ],
                      "Discrete Element Method (Solid)" => joinpath("systems", "dem.md"),
-                     "Rigid Body SPH (Rigid Structure)" => joinpath("systems",
-                                                                    "rigid_body.md"),
+                     "Rigid Body Dynamics (Rigid Structure)" => joinpath("systems",
+                                                                         "rigid_body.md"),
                      "Total Lagrangian SPH (Elastic Structure)" => joinpath("systems",
                                                                             "total_lagrangian_sph.md"),
                      "Boundary" => joinpath("systems", "boundary.md")

docs/src/development.md

@@ -3,24 +3,25 @@
 
 ## Preview of the documentation
 
-To generate the Documentation, first instantiate the `docs` environment
-by executing the following command from the TrixiParticles.jl root directory:
+To build the documentation, first instantiate the `docs` environment by running the
+following command from the TrixiParticles.jl root directory:
 ```bash
 julia --project=docs -e "using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()"
 ```
-This command only has to be run once. After that, maintain the `docs` environment
+You only need to run this command once. After that, maintain the `docs` environment
 as described under [Installation](@ref installation-issues).
 
-With an instantiated `docs` environment, generate the docs with the following command (again from the TrixiParticles.jl root directory):
+Once the `docs` environment is instantiated, build the documentation with the following
+command (again from the TrixiParticles.jl root directory):
 ```bash
 julia --project=docs --color=yes docs/make.jl
 ```
-You can then open the generated files in `docs/build` with your webbrowser.
+You can then open the generated files in `docs/build` in your web browser.
 Alternatively, run
 ```bash
 python3 -m http.server -d docs/build
 ```
-and open `localhost:8000` in your webbrowser.
+and open `localhost:8000` in your web browser.
 
 
 ## Release management

docs/src/examples.md

@@ -42,7 +42,7 @@
 <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/f9a542bf-956b-4647-843b-94cbb085a4fa" width="60%"/>
 ```
 
-## Fluid Structure Interaction
+## Fluid-Structure Interaction
 
 ### Dam Break with Elastic Plate (`fsi/dam_break_plate_2d.jl`)
 ```@raw html
@@ -59,7 +59,7 @@
 <img src="https://github.com/trixi-framework/TrixiParticles.jl/assets/10238714/b3964f68-2782-43e6-b6ff-be96f9f224ae" width="60%"/>
 ```
 
-## Structure Mechanics
+## Structural Mechanics
 
 ### Oscillating Beam (`solid/oscillating_beam_2d.jl`)
 ```@raw html

docs/src/general/neighborhood_search.md

@@ -1,13 +1,14 @@
 # Neighborhood Search
 
-The neighborhood search is the most essential component for performance.
+The neighborhood search is one of the most performance-critical components.
 We provide several implementations in the package
 [PointNeighbors.jl](https://github.com/trixi-framework/PointNeighbors.jl).
-See the docs of this package for an overview and a comparison of different implementations.
+See the PointNeighbors.jl documentation for an overview and a comparison of the
+different implementations.
 
 !!! note "Usage"
-    To run a simulation with a neighborhood search implementation, pass a template of the
-    neighborhood search to the constructor of the [`Semidiscretization`](@ref).
+    To run a simulation with a neighborhood search implementation, pass a neighborhood
+    search template to the constructor of the [`Semidiscretization`](@ref).
     A template is just an empty neighborhood search with search radius `0.0`.
     See [`copy_neighborhood_search`](@ref) and the examples below for more details.
     ```jldoctest semi_example; output=false, setup = :(using TrixiParticles; trixi_include(@__MODULE__, joinpath(examples_dir(), "fluid", "hydrostatic_water_column_2d.jl"), sol=nothing); system1 = fluid_system; system2 = boundary_system)

docs/src/getting_started.md

@@ -1,14 +1,14 @@
 # [Getting started](@id getting_started)
-If you have not installed TrixiParticles.jl, please follow the instructions given [here](install.md).
+If you have not installed TrixiParticles.jl yet, please follow the instructions in [Installation](@ref installation).
 
-In the following sections, we will give a short introduction. For a more thorough discussion, take a look at our [Tutorials](tutorial.md).
+This page provides a short introduction. For a broader introduction, take a look at our [Tutorials](tutorial.md).
 
 ## Running an Example
-The easiest way to run a simulation is to run one of our predefined example files.
+The easiest way to start is to run one of the predefined example files.
 We will run the file `examples/fluid/hydrostatic_water_column_2d.jl`, which simulates a fluid resting in a rectangular tank.
 Since TrixiParticles.jl uses multithreading, you should start Julia with the flag `--threads auto` (or, e.g. `--threads 4` for 4 threads).
 
-In the Julia REPL, first load the package TrixiParticles.jl.
+In the Julia REPL, first load TrixiParticles.jl.
 ```jldoctest getting_started
 julia> using TrixiParticles
 ```
@@ -29,27 +29,27 @@ This will open a new window with a 2D visualization of the final solution:
 For more information about visualization, see [Visualization](visualization.md).
 
 ## Running other Examples
-You can find a list of our other predefined examples under [Examples](examples.md).
-Execute them as follows from the Julia REPL by replacing `subfolder` and `example_name`
+You can find more predefined examples under [Examples](examples.md).
+Run them from the Julia REPL by replacing `subfolder` and `example_name`:
 ```julia
 julia> trixi_include(joinpath(examples_dir(), "subfolder", "example_name.jl"))
 ```
 
 ## Modifying an example
 You can pass keyword arguments to the function `trixi_include` to overwrite assignments in the file.
 
-With `trixi_include`, we can overwrite variables defined in the example file to run a different simulation without modifying the example file.
+With `trixi_include`, we can overwrite variables defined in the example file to run a different simulation without modifying the file itself.
 ```jldoctest getting_started; filter = r".*"s
 julia> trixi_include(joinpath(examples_dir(), "fluid", "hydrostatic_water_column_2d.jl"), initial_fluid_size=(1.0, 0.5))
 ```
-This for example, will change the fluid size from ``(0.9, 1.0)`` to ``(1.0, 0.5)``.
+This, for example, changes the fluid size from ``(0.9, 1.0)`` to ``(1.0, 0.5)``.
 
-To understand why, take a look into the file `hydrostatic_water_column_2d.jl` in the subfolder `fluid` inside the examples directory, which is the file that we executed earlier.
+To understand why, take a look at the file `hydrostatic_water_column_2d.jl` in the `fluid` subdirectory of the examples directory, which is the file we executed earlier.
 You can see that the initial size of the fluid is defined in the variable `initial_fluid_size`, which we could overwrite with the `trixi_include` call above.
 Another variable that is worth experimenting with is `fluid_particle_spacing`, which controls the resolution of the simulation in this case.
 A lower value will increase the resolution and the runtime.
 
-## Set up you first simulation from scratch
+## Set Up Your First Simulation from Scratch
 See [Set up your first simulation](tutorials/tut_setup.md).
 
-Find an overview over the available tutorials under [Tutorials](tutorial.md).
+An overview of the available tutorials is available under [Tutorials](tutorial.md).

docs/src/gpu.md

@@ -1,9 +1,8 @@
 # [GPU Support](@id gpu_support)
 
-GPU support is still an experimental feature that is actively being worked on.
 Currently, the [`WeaklyCompressibleSPHSystem`](@ref), [`TotalLagrangianSPHSystem`](@ref)
 and [`WallBoundarySystem`](@ref) support GPU execution.
-We have tested GPU support on Nvidia, AMD and Apple GPUs.
+We have tested GPU support on NVIDIA, AMD, and Apple GPUs.
 Note that most Apple GPUs do not support `Float64`.
 See [below on how to run single precision simulations](@ref single_precision).
 
@@ -42,14 +41,14 @@ semi = Semidiscretization(fluid_system, boundary_system,
 └──────────────────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
-At this point, we should run the simulation and make sure that it still works and that
-the bounding box is large enough.
+At this point, run the simulation and make sure that it still works and that the
+bounding box is large enough.
 For some simulations where particles move outside the initial tank coordinates,
 for example when the tank is not closed or when the tank is moving, an appropriate
 bounding box has to be specified.
 
-Then, we only need to specify the parallelization backend that is used for the simulation.
-On an Nvidia GPU, we specify:
+Then, we only need to specify the parallelization backend used for the simulation.
+On an NVIDIA GPU, we specify:
 ```julia
 using CUDA
 semi = Semidiscretization(fluid_system, boundary_system,
@@ -65,7 +64,7 @@ semi = Semidiscretization(fluid_system, boundary_system,
 ```
 Now, we can run the simulation as usual.
 All data is transferred to the GPU during initialization and all loops over particles
-and their neighbors will be executed on the GPU as kernels generated by KernelAbstractions.jl.
+and their neighbors are executed on the GPU as kernels generated by KernelAbstractions.jl.
 Data is only copied to the CPU for saving VTK files via the [`SolutionSavingCallback`](@ref).
 
 ## Run an existing example file on the GPU
@@ -84,7 +83,7 @@ Note that in `examples/fluid/dam_break_2d.jl`, we explicitly set
 so that we can use `trixi_include` to replace this value.
 
 To run this simulation on a GPU, simply update `parallelization_backend` to the backend
-of the installed GPU. We can run this simulation on an Nvidia GPU as follows.
+of the installed GPU. We can run this simulation on an NVIDIA GPU as follows.
 ```julia
 using CUDA
 trixi_include(joinpath(examples_dir(), "fluid", "dam_break_2d_gpu.jl"), parallelization_backend=CUDABackend())
@@ -94,7 +93,7 @@ For AMD GPUs, use
 using AMDGPU
 trixi_include(joinpath(examples_dir(), "fluid", "dam_break_2d_gpu.jl"), parallelization_backend=ROCBackend())
 ```
-For Apple GPUs (which don't support double precision, see below), use
+For Apple GPUs (which do not support double precision, see below), use
 ```julia
 using Metal
 trixi_include_changeprecision(Float32,
@@ -110,7 +109,7 @@ which is significantly faster on most GPUs and required for many Apple GPUs.
 
 To run a simulation with single precision, all `Float64` literals in an example file
 must be converted to `Float32` (e.g. `0.0` to `0.0f0`).
-TrixiParticles provides a function to automate this conversion:
+TrixiParticles.jl provides a function to automate this conversion:
 ```@docs
 trixi_include_changeprecision
 ```