Handy-test-cases.md

@@ -6,7 +6,7 @@ Let us illustrate the structure of the executable python files with a two dimens
 
 Several steps are required to properly define the problem you want to solve with the MigFlow Software.
 
-1. Set the problem parametres.
+1. Define the problem parameters.
 
   * [fluid and grains properties](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/master/testcases/depot-2d/depot.py#L69)
 ```python
@@ -16,7 +16,7 @@ rhop = 1500                                    # grains density
 rho = 1000                                     # fluid density
 nu = 1e-6                                      # kinematic viscosity
 ```
-  * [numerical parametres](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/master/testcases/depot-2d/depot.py#L76)
+  * [numerical parameters](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/master/testcases/depot-2d/depot.py#L76)
 ```python
 outf = 5                                       # number of iterations between output files
 dt = 1e-2                                      # time step
@@ -24,46 +24,40 @@ tEnd = 100                                     # final time
 ```
   
 
-2. Define the matrix of the grains positions and actually create the grains at these positions
+2. Set the initial conditions for the granular phase.
 
-  * Setting the initial situation requires to define the initial positions of the grains. In test cases, this is often achieved by defining a [function](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/master/testcases/depot-2d/depot.py#L37) in which the positions of the centres are defined. The arguments of the function are related to the grains properties and the grains area geometry defined previously. The physical surfaces defined in your mesh.geo file are used to specify the solid boundaries for the grains. Grain objects are created locally and all the information about the initial conditions of the grains are written in an output file. The argument of the particles structure builder is the dimension of the problem.
+  * [Build](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/master/testcases/depot-2d/depot.py#L72) the particle structure and load the boundaries from the mesh file. The dimension of the particle problem is given as an argument to the initializer. 
 ```python
-def genInitialPosition(filename, r, H, ly, lx, rhop) :
-    """Set all the particles centre positions and create the particles objects to add in the computing structure
-    
-    Keyword arguments:    
-    filename -- name of the output file
-    r -- max radius of the particles
-    H -- domain height
-    ly - particles area height
-    lx -- particles area width
-    rhop -- particles density        
-    """
-    # Particles structure builder
 p = scontact.ParticleProblem(2)
-    # Load mesh.msh file specifying physical boundaries names
 p.load_msh_boundaries("mesh.msh", ["Top", "Lateral","Bottom"])
 
-    #Definition of the points where the particles are located
-    x = np.arange(-lx/2+r, lx/2-r, 2*r)
-    y = np.arange(H/2-r, H/2-ly+r, -2*r)
-    x, y = np.meshgrid(x, y)
-    x = x.flat
-    y = y.flat
-    # Add a grain at each centre position
-    for i in range(len(x)) :
-        p.add_particle((x[i], y[i]), r, r**2 * np.pi * rhop)
-    p.write_vtk(filename,0,0)
-
 ```
 
-  * Use the previous function to set the initial condition and write it in the outputdir directory. Then, build the particle structure and [fill](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/master/testcases/depot-2d/depot.py#L86) the global particle structure with the information written in the initial file
+  * Add the grains at their initial positions. In most test cases, this is achieved by defining a [function](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/master/testcases/depot-2d/depot.py#L37) in which the positions of the centres are defined. The [arguments](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/master/testcases/depot-2d/depot.py#L67) of the function correspond to the dimension of the regular grid on which the grains will be placed.
 ```python
-genInitialPosition(outputdir, r, H, ly, lx, rhop)
-p = scontact.ParticleProblem(2)
-p.read_vtk(outputdir,0)
+def gen_rect(origin, w, h, step):
+    """ Generate coordinates on a rectangular grid
+    Keyword arguments:
+        origin -- origin of top left corner
+        w : width
+        h : height
+        step : maximal radius
+    """
+    eps = 1e-8
+    x = np.arange(-w/2+step-eps, w/2-step+eps, 2*step) + origin[0]
+    y = np.arange(-step, -h+step, -2*step) + origin[1]
+    x, y = np.meshgrid(x,y)
+    return x.reshape(-1), y.reshape(-1)
 
 ```
+The grains are then added to the particle problem as follows:
+```python
+x, y = gen_rect([0, H/2], w, h, r)
+for xi,yi in zip(x,y):
+    p.add_particle((xi, yi), r, r**2*np.pi*rhop)
+```
+
+  
 
 3. Create the fluid structure and specify the computational domain (i.e. give the mesh to the fluid class). At this step, all the variables (velocity, pressure...) of the fluid problem and the properties of the fluid are stored in the fluid structure. The arguments for the fluid structure builder are the dimension of the problem, the gravity, the dynamic viscosity and the density of the fluid.
 ```python