Go through the maths for consistency

README.md

@@ -15,30 +15,29 @@
   <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 simulation framework for particle-based methods for complex multiphysics applications, written in [Julia](https://julialang.org).
 
 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)
+- Structural mechanics
+  - Methods: Total Lagrangian SPH (TLSPH), Discrete Element Method (DEM)
 - Fluid-Structure Interaction
-- Particle sampling of complex geometries from `.stl` and `.asc` files.
+- 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 +67,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.
 
@@ -115,7 +114,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).
@@ -160,7 +164,7 @@ and
 
 ## Authors
 Erik Faulhaber (University of Cologne) and Niklas Neher (HLRS) implemented the foundations
-for TrixiParticles.jl and are principal developers along with Sven Berger (hereon).
+for TrixiParticles.jl and are principal developers along with Sven Berger (Hereon).
 The project was started by Michael Schlottke-Lakemper (University of Augsburg)
 and Gregor Gassner (University of Cologne), who provide scientific direction and technical advice.
 The full list of contributors can be found in [AUTHORS.md](AUTHORS.md).
@@ -183,4 +187,3 @@ or [create an issue](https://github.com/trixi-framework/TrixiParticles.jl/issues
 </p>
 
 The project has benefited from funding from [hereon](https://www.hereon.de/), [HiRSE](https://www.helmholtz-hirse.de/), and through [ScienceServe](https://www.helmholtz.de/en/research/current-calls-for-applications/article/scienceserve-boosting-research-software-at-helmholtz/) for the MATRIX project.
-

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
@@ -65,4 +66,3 @@ To create a new release for TrixiParticles.jl, perform the following steps:
    `-dev` suffix added. For example, if you just released `v0.3.0`, the new development
    version should be `v0.3.1-dev`. If you just released `v0.2.4`, the new development
    version should be `v0.2.5-dev`.
-

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
 ```

docs/src/index.md

@@ -1,24 +1,26 @@
 # TrixiParticles.jl
 
-**TrixiParticles.jl** is a high-performance particle simulation framework designed to overcome challenges of particle-based numerical methods in multiphysics applications. Existing frameworks often lack user-friendliness, involve complex configuration, and are not easily extensible for development of new methods. In the future we also want to provide seamless scalability from CPU to Exascale-level computing with GPU support. **TrixiParticles.jl** addresses these limitations with an intuitive interface, straightforward configuration, and an extensible design, facilitating efficient simulation setup and execution.
+**TrixiParticles.jl** is a high-performance simulation framework for particle-based methods in complex multiphysics applications. It combines an accessible user interface with an extensible architecture for developing new methods, while also providing GPU-accelerated execution.
 
 TrixiParticles.jl focuses on the following use cases:
 
-- Development of new particle-based methods and models. By providing an extensible architecture to incorporate additional particle methods easily and not focusing on a single model or numerical method.
-- Accurate, reliable and efficient physics-based modelling of complex multiphysics problems by providing a flexible configuration system, tools, high performance and a wide range of validation and test cases.
-- Easy setup of accessible simulations for educational purposes, including student projects, coursework, and thesis work through extensive documentation, community engagement and readable configuration files.
+- Development of new particle-based methods and models through an extensible architecture that is not tied to a single numerical method.
+- Accurate, reliable, and efficient physics-based modeling of complex multiphysics problems through a flexible configuration system, high performance, and a broad set of validation and test cases.
+- Accessible simulation setup for educational purposes, including student projects, coursework, and thesis work, supported by extensive documentation and readable configuration files.
 
-Its features include:
+Its main features include:
 
 ## Features
-- Incompressible Navier-Stokes
-  - Methods: Weakly Compressible Smoothed Particle Hydrodynamics (WCSPH), Entropically Damped Artificial Compressibility (EDAC)
-  - Models: Surface Tension
-- Solid-body mechanics
-  - Methods: Total Lagrangian SPH (TLSPH)
+- 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
+- Structural mechanics
+  - Methods: Total Lagrangian SPH (TLSPH), Discrete Element Method (DEM)
 - Fluid-Structure Interaction
+- Particle sampling of complex geometries from `.stl`, `.asc`, and `.dxf` files
 - Output formats:
   - VTK
+- Experimental GPU support for NVIDIA, AMD, and Apple devices
 
 ## Examples
 ```@raw html
@@ -42,14 +44,14 @@ Its features include:
 </table>
 ```
 
-## Quickstart
+## Quick Start
 1. [Installation](@ref installation)
 2. [Getting started](@ref getting_started)
 
-If you have any questions concerning **TrixiParticles.jl** you can join our community [on Slack](https://join.slack.com/t/trixi-framework/shared_invite/zt-sgkc6ppw-6OXJqZAD5SPjBYqLd8MU~g) or open an issue with your question.
+If you have questions about **TrixiParticles.jl**, join our community [on Slack](https://join.slack.com/t/trixi-framework/shared_invite/zt-sgkc6ppw-6OXJqZAD5SPjBYqLd8MU~g) or open an issue.
 
-## Start with development
-To get started with development have a look at these pages:
+## Getting Started with Development
+If you want to contribute or extend the code, start with:
 
 1. [Installation](@ref installation)
 2. [Development](@ref development)