Add "get started" page (#318)

* implement * Revert "implement" This reverts commit 171505a. * some improvements to the documentation * some more fixes * add install documentation * add more info * update * Update get_started.md * add tutorial * fix * update * update * review comments * forgot one predefined * rename rect_tank * review
trixi-framework · Feb 15, 2024 · 881ebc7 · 881ebc7
1 parent 4893303
commit 881ebc7
Show file tree

Hide file tree

Showing 7 changed files with 96 additions and 2 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -49,6 +49,9 @@ makedocs(sitename="TrixiParticles.jl",
              "News" => "news.md",
              "Installation" => "install.md",
              "Getting started" => "getting_started.md",
+             "Tutorial" => "tutorial.md",
+             "Examples" => "examples.md",
+             "Visualization" => "visualization.md",
              "Components" => [
                  "General" => [
                      "Semidiscretization" => joinpath("general", "semidiscretization.md"),

diff --git a/docs/src/examples.md b/docs/src/examples.md
@@ -0,0 +1,7 @@
+# Examples
+
+
+## WCSPH
+
+
+## TLSPH
diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md
@@ -1 +1,52 @@
-# Getting started
+# Getting started  
+If you have not installed TrixiParticles.jl, please follow the instructions given [here](install.md).
+
+In the following sections, we will give a short introduction. For a more thorough discussion, 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.
+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.
+
+```julia
+julia> using TrixiParticles
+```
+
+Then start the simulation by executing
+```julia
+julia> trixi_include(joinpath(examples_dir(), "fluid", "hydrostatic_water_column_2d.jl"))
+```
+
+This will result in the following:
+![image](https://github.com/svchb/TrixiParticles.jl/assets/10238714/f8d2c249-fd52-4958-bc8b-265bbadc49f2)
+
+
+To visualize the results, 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`
+```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.
+```julia
+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)``.
+
+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.
+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
+See [Set up your first simulation](tutorials/tut_setup.md). 
+
+Find an overview over the available tutorials under [Tutorials](tutorial.md).
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -21,4 +21,4 @@ TrixiParticles.jl is a numerical simulation framework designed for particle-base
 
 ## Start with development
 1. [Installation](@ref)
-2. [Contributing](@ref)
+2. [Contributing](@ref)
diff --git a/docs/src/tutorial.md b/docs/src/tutorial.md
@@ -0,0 +1,10 @@
+# Tutorial
+
+
+## Fluid
+
+
+## Mechanics
+
+
+## Fluid-Structure Interaction
diff --git a/docs/src/tutorials/tut_setup.md b/docs/src/tutorials/tut_setup.md
diff --git a/docs/src/visualization.md b/docs/src/visualization.md
@@ -0,0 +1,23 @@
+# Visualization
+
+## 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/).
+
+### ParaView
+
+Follow these steps to view the exported VTK files in ParaView:
+
+1. Click `File -> Open`.
+2. Navigate to the `out` directory (relative to the directory that you are running Julia from).
+3. Open both `boundary_1.pvd` and `fluid_1.pvd`.
+4. Click "Apply", which by default is on the left pane below the "Pipeline Browser".
+5. Hold the left mouse button to move the solution around.
+
+You will now see the following:
+![image](https://github.com/svchb/TrixiParticles.jl/assets/10238714/45c90fd2-984b-4eee-b130-e691cefb33ab)
+
+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).
+![image](https://github.com/svchb/TrixiParticles.jl/assets/10238714/7565a13f-9532-4a69-9f81-e79505400b1c)