From 9599ffa30dd50cd3514479dfd33a1918afd2f02f Mon Sep 17 00:00:00 2001
From: aelligp <pascal.aellig@hotmail.com>
Date: Fri, 5 Jul 2024 15:34:28 +0200
Subject: [PATCH] update docs

---
 docs/src/man/boundary_conditions.md | 54 +++++++++++++++++++++++++----
 1 file changed, 48 insertions(+), 6 deletions(-)

diff --git a/docs/src/man/boundary_conditions.md b/docs/src/man/boundary_conditions.md
index 98665708..4d414aaa 100644
--- a/docs/src/man/boundary_conditions.md
+++ b/docs/src/man/boundary_conditions.md
@@ -14,12 +14,21 @@ Supported boundary conditions:
 
     $\sigma_z = 0 \rightarrow \tau_z = P$ at the top boundary
 
-## Defining the boundary contions
-Information regarding flow boundary conditions is defined in the `FlowBoundaryConditions` object. They can be switched on and off by setting them as `true` or `false` at the appropriate boundaries. Valid boundary names are `left` and `right`, `top` and `bot`, and for the 3D case, `front` and `back`. 
+## Defining the boundary conditions
+We have two ways of defining the boundary condition formulations:
+    - `VelocityBoundaryConditions`, and
+    - `DisplacementBoundaryConditions`.
+The first one is used for the velocity-pressure formulation, and the second one is used for the displacement-pressure formulation. The flow boundary conditions can be switched on and off by setting them as `true` or `false` at the appropriate boundaries. Valid boundary names are `left` and `right`, `top` and `bot`, and for the 3D case, `front` and `back`.
 
-For example, if we want to have free free-slip in every single boundary in a 2D simulation, we need to instantiate `FlowBoundaryConditions` as:
+
+For example, if we want to have free free-slip in every single boundary in a 2D simulation, we need to instantiate `VelocityBoundaryConditions` or `DisplacementBoundaryConditions` as:
 ```julia
-bcs = FlowBoundaryConditions(;
+bcs = VelocityBoundaryConditions(;
+    no_slip      = (left=false, right=false, top=false, bot=false),
+    free_slip    = (left=true, right=true, top=true, bot=true),
+    free_surface = false
+)
+bcs = DisplacementBoundaryConditions(;
     no_slip      = (left=false, right=false, top=false, bot=false),
     free_slip    = (left=true, right=true, top=true, bot=true),
     free_surface = false
@@ -28,9 +37,42 @@ bcs = FlowBoundaryConditions(;
 
 The equivalent for the 3D case would be:
 ```julia
-bcs = FlowBoundaryConditions(;
+bcs = VelocityBoundaryConditions(;
     no_slip      = (left=false, right=false, top=false, bot=false, front=false, back=false),
     free_slip    = (left=true, right=true, top=true, bot=true, front=true, back=true),
     free_surface = false
 )
-```
\ No newline at end of file
+bcs = DisplacementBoundaryConditions(;
+    no_slip      = (left=false, right=false, top=false, bot=false, front=false, back=false),
+    free_slip    = (left=true, right=true, top=true, bot=true, front=true, back=true),
+    free_surface = false
+)
+```
+## Prescribing the velocity/displacement boundary conditions
+Normally, one would prescribe the velocity/displacement boundary conditions by setting the velocity/displacement field at the boundary through the application of a background strain rate `εbg`.
+Depending on the formulation, the velocity/displacement field is set as follows for the 2D case:
+### Velocity formulation
+```julia
+stokes.V.Vx .= PTArray(backend)([ x*εbg for x in xvi[1], _ in 1:ny+2]) # Velocity in x direction
+stokes.V.Vy .= PTArray(backend)([-y*εbg for _ in 1:nx+2, y in xvi[2]]) # Velocity in y direction
+```
+Make sure to apply the set velocity to the boundary conditions. You do this by calling the `flow_bcs!` function,
+```julia
+flow_bcs!(stokes, flow_bcs)
+```
+and then applying the velocities to the halo
+```julia
+update_halo!(@velocity(stokes)...)
+```
+### Displacement formulation
+```julia
+stokes.U.Ux .= PTArray(backend)([ x*εbg*lx*dt for x in xvi[1], _ in 1:ny+2]) # Displacement in x direction
+stokes.U.Uy .= PTArray(backend)([-y*εbg*ly*dt for _ in 1:nx+2, y in xvi[2]]) # Displacement in y direction
+flow_bcs!(stokes, flow_bcs)
+```
+Make sure to initialize the displacement according to the extent of your domain. Here, lx and ly are the domain lengths in the x and y directions, respectively.
+Also for the displacement formulation it is important that the displacement is converted to velocity before updating the halo. This can be done by calling the `displacement2velocity!` function.
+```julia
+displacement2velocity!(stokes, dt) # convert displacement to velocity
+update_halo!(@velocity(stokes)...)
+```