diff --git a/README.md b/README.md index e9e9eb2957..f210755cc1 100644 --- a/README.md +++ b/README.md @@ -15,30 +15,29 @@ TrixiP_logo

-**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 +- Structural 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. +- 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. @@ -116,7 +115,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: Further details can be found in the [documentation](https://trixi-framework.github.io/TrixiParticles.jl/stable). @@ -168,7 +172,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). diff --git a/docs/src/development.md b/docs/src/development.md index 85a099c7c4..314f0824ee 100644 --- a/docs/src/development.md +++ b/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 diff --git a/docs/src/examples.md b/docs/src/examples.md index f19e623e9e..59e2bda55c 100644 --- a/docs/src/examples.md +++ b/docs/src/examples.md @@ -42,7 +42,7 @@ ``` -## Fluid Structure Interaction +## Fluid-Structure Interaction ### Dam Break with Elastic Plate (`fsi/dam_break_plate_2d.jl`) ```@raw html @@ -59,7 +59,7 @@ ``` -## Structure Mechanics +## Structural Mechanics ### Oscillating Beam (`solid/oscillating_beam_2d.jl`) ```@raw html diff --git a/docs/src/general/neighborhood_search.md b/docs/src/general/neighborhood_search.md index b639e4a05f..93019eaffc 100644 --- a/docs/src/general/neighborhood_search.md +++ b/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) diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md index a68bb620c0..08ebfeb066 100644 --- a/docs/src/getting_started.md +++ b/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,8 +29,8 @@ 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")) ``` @@ -38,18 +38,18 @@ 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). diff --git a/docs/src/gpu.md b/docs/src/gpu.md index 1037908548..a7bdd6c3af 100644 --- a/docs/src/gpu.md +++ b/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 ``` diff --git a/docs/src/index.md b/docs/src/index.md index 27c1e9d474..0a06ed3175 100644 --- a/docs/src/index.md +++ b/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 +- GPU support for NVIDIA, AMD, and Apple devices ## Examples ```@raw html @@ -42,14 +44,14 @@ Its features include: ``` -## 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) diff --git a/docs/src/install.md b/docs/src/install.md index 821efe9e48..533fd4fc5f 100644 --- a/docs/src/install.md +++ b/docs/src/install.md @@ -1,7 +1,7 @@ # [Installation](@id installation) ## Setting up Julia -If you have not yet installed Julia, please [follow the instructions on the +If you have not installed Julia yet, please [follow the instructions on the official website](https://julialang.org/downloads/). TrixiParticles.jl works with Julia v1.10 and newer. We recommend using the latest stable release of Julia. @@ -45,18 +45,17 @@ and always have a reproducible environment at hand to share with others. - [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) -- A Julia package of ordinary differential equation solvers; examples in TrixiParticles.jl use sub-packages such as `OrdinaryDiffEqLowStorageRK` and `OrdinaryDiffEqSymplecticRK` - [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 +- [ParaView](https://www.paraview.org/) -- Visualization software for simulation results ## [Common issues](@id installation-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, +If you followed the [installation instructions for developers](@ref for-developers) and run +into package issues after 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: +then update packages, resolve dependency conflicts, and install new dependencies: ```julia julia> using Pkg diff --git a/docs/src/overview.md b/docs/src/overview.md index a1b6a70d5a..fc500ab85d 100644 --- a/docs/src/overview.md +++ b/docs/src/overview.md @@ -1,18 +1,18 @@ # Overview -The actual API reference is not listed on a single page, like in most Julia packages, -but instead is split into multiple sections that follow a similar structure -as the code files themselves. -In these sections, API docs are combined with explanations of the theoretical background -of these methods. +The API reference is not collected on a single page. +Instead, it is split into sections that largely mirror the source tree. +These sections combine API documentation with short explanations of the +underlying methods. The following page gives a rough overview of important parts of the code. ## Program flow -To initiate a simulation, the goal is to solve an ordinary differential equation, for example, -by employing the time integration schemes provided by OrdinaryDiffEq.jl. These schemes are then -utilized to integrate ``\mathrm{d}u/\mathrm{d}t`` and ``\mathrm{d}v/\mathrm{d}t``, where ``u`` -represents the particles' positions and ``v`` their properties such as velocity and density. +To run a simulation, TrixiParticles.jl solves an ordinary differential equation, +typically with a time integration scheme from OrdinaryDiffEq.jl. These schemes are +used to integrate ``\mathrm{d}u/\mathrm{d}t`` and ``\mathrm{d}v/\mathrm{d}t``, +where ``u`` represents particle positions and ``v`` particle properties such as +velocity and density. During a single time step or an intermediate step of the time integration scheme, the functions `drift!` and `kick!` are invoked, followed by the functions depicted in this diagram (with key parts highlighted in orange/yellow). @@ -78,9 +78,10 @@ flowchart TD ``` ## Structure -What we refer to as schemes are various models such as Weakly Compressible Smoothed Particle Hydrodynamics (WCSPH) -or Total Lagrangian Smoothed Particle Hydrodynamics (TLSPH). These schemes are categorized based on the applicable -physical regimes, namely fluid, solid, gas, and others. Each scheme comprises at least two files: a `system.jl` file -and an `rhs.jl` file. The `system.jl` file provides the data structure holding the particles of this scheme and some -routines, particularly those for allocation and the main update routines, excluding system interactions. -The interactions between particles of this scheme (and with particles of other schemes) are handled in the `rhs.jl` file. +In the codebase, a scheme denotes a particle method or model such as Weakly Compressible +SPH (WCSPH) or Total Lagrangian SPH (TLSPH). Schemes are organized by application area, +for example fluid, structure, and boundary systems. A scheme typically comprises at least +two files: a `system.jl` file and an `rhs.jl` file. The `system.jl` file defines the data +structure that stores the particles of the scheme together with routines for allocation and +main updates that do not involve particle interactions. The `rhs.jl` file contains the +interaction terms between particles of the same scheme and between different schemes. diff --git a/docs/src/visualization.md b/docs/src/visualization.md index 1f74108b4f..9dda94bfba 100644 --- a/docs/src/visualization.md +++ b/docs/src/visualization.md @@ -2,8 +2,10 @@ ## Export VTK files You can export particle data as VTK files by using the [`SolutionSavingCallback`](@ref). -All our [predefined examples](examples.md) are already using this callback to export VTK files to the `out` directory (relative to the directory that you are running Julia from). -VTK files can be read by visualization tools like [ParaView](https://www.paraview.org/) and [VisIt](https://visit.llnl.gov/). +All [predefined examples](examples.md) already use this callback to export VTK files to the `out` +directory relative to the current working directory. +VTK files can be opened in visualization tools such as [ParaView](https://www.paraview.org/) +and [VisIt](https://visit.llnl.gov/). ### ParaView @@ -29,8 +31,8 @@ Then, in the Properties panel (bottom left), adjust the following settings: ![image](https://github.com/user-attachments/assets/194d9a09-5937-4ee4-b229-07078afe3ff0) #### Visualization with Macro -To simplify the visualization of your particle data in ParaView, you can use a macro. -This macro automates the manual steps in the previous section to a single click of a button. +To simplify visualization of particle data in ParaView, you can use a macro. +It reduces the manual steps from the previous section to a single click. Install the macro as follows. 1. **Save the macro code** (see below) as a `.py` file, e.g. `PointGaussianMacro.py`. @@ -77,8 +79,10 @@ sourceDisplay.GaussianRadius = 0.5 ``` #### Show results -To now view the result variables **first** make sure you have "fluid_1.pvd" highlighted in the "Pipeline Browser" then select them in the variable selection combo box (see picture below). -Let's, for example, pick "density". To now view the time progression of the result hit the "play button" (see picture below). +To view the result variables, first make sure that "fluid_1.pvd" is highlighted in the +"Pipeline Browser", then select a variable in the variable-selection combo box +(see the image below). For example, choose "density". To view the time evolution, +press the play button (also shown below). ![image](https://github.com/user-attachments/assets/10dcf7eb-5808-4d4d-9db8-4beb25b5e51a) ## API