@@ -5,239 +5,4 @@ MigFlow is a free and open source software dedicated to the simulations, in comp

If you use MigFlow, please cite the following reference in your work:

Constant, M., Dubois, F., Lambrechts, J. and Legat, V. (2018). Implementation of an unresolved stabilised FEM-DEM model to solve immersed granular flows. _Computational Particle Mechanics_. [doi:10.1007/s40571-018-0209-4](https://doi.org/10.1007/s40571-018-0209-4).

#### Contents

* Installation

* Main Features

* Frequantly Asked Questions

## Installation

MigFlow requires a linear solver to solve the Navier-Stokes equations. Before starting the installation of MigFlow, make sure you have a recent version of [PETSc](https://www.mcs.anl.gov/petsc/download/index.html) with proper configuration.

Meshes representing the computational domain on which Navier-Stokes equations are discretised are created from .geo files using [GMSH](http://gmsh.info/)

+ Installation of the mesh generator :

The continuous equations of the model used in the MigFlow project are solved on unstructured meshes. The msh file format is the only one supported by MigFlow and require the installation of a specific mesh generator.

1. Go on [GMSH](http://gmsh.info/) webpage and follow the instruction given in the _Download_ section

2. Create a path in your .bashrc to launch gmsh with command system

3. State the location of the python modules by writing the following line in your .bashrc

export PYTHONPATH=$HOME/MigFlow/build:$PYTHONPATH

→ For MacOS you possibly need to create this hidden file in your HOME directory

4. (Optional) Linear Solver:

MigFlow solves the nonlinear Navier-Stokes equations using a Newton's method equations solver that requires the use of a linear solver. MigFlow has its own linear solver based on LU decomposition but it supports the use of PETSc to fasten time consuming computations.

a. For Ubuntu and other Unix system it is more convenient to use the PETSc project supported by the officiel distribution repository:

- Ubuntu:

sudo apt install petsc_dev

b. For other OS, go on [PETSc](https://www.mcs.anl.gov/petsc/download/index.html) webpage and clone the repository on your computer:

Many test cases are given to help users to understand how to use the different features offered by the MigFlow Software. Test cases are in the TheGoodPath/MigFlow/testcases directory. They are given to provide users basic tools in order to build computation script for their own applications.

### Test Cases Structure

Let us illustrate the structure of the executable python files with a two dimensional deposit of grains in fluid. This test case is provided in the [testcases/depo-2d/dep.py](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/depot-2d/dep.py) file.

Some steps have to be followed in order to define properly the application you want to solve with the MigFlow Software.

1. Set the problem parametres

In application you have to define a lot of variables that are used to define:

*[fluid and grains properties](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/depot-2d/depot.py#L69)

2. Define the positions of the grains matrix and create grains at these positions

* Setting the initial situation require 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/oneFluid/testcases/depot-2d/depot.py#L37) in which centre positions 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 innitial condition of the grains are written in an output file.

```python

defgenInitialPosition(filename,r,H,ly,lx,rhop):

"""Set all the particles centre positions and create the particles objects to add in the computing structure

#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

foriinrange(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/oneFluid/testcases/depot-2d/depot.py#L86) the global particle structure with the information written in the initial file

```python

genInitialPosition(outputdir,r,H,ly,lx,rhop)

p=scontact.ParticleProblem(2)

p.read_vtk(outputdir,0)

```

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

```python

fluid=fluid.FluidProblem(2,g,[nu*rho],[rho])

# Set the mesh geometry for the fluid computation

fluid.load_msh("mesh.msh")

```

4. Once the fluid variables and properties are created, it is mandatory to set the boundary conditions of the fluid problem. Boundary conditions are of two types:

*[Strong boundaries](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/depot-2d/depot.py#L107) constrain a field variable to a specified value. This is done by suppressing an equation of the linear system to replace it by this constraint :

```pyhton

fluid.set_strong_boundary(Physical boundary tag, field variable item, field value)

```

*[Weak boundaries](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/depot-2d/depot.py#L111) specify the flux at each boundary. The flux terms added by these conditions come from the integration by part arising from the finite element methods and can be suppressed for some weak boundary type. For example, if you consider a wall, it is quite obvious that the velocity flux across the boundary is zero.

5. Coupling between fluid and solid is mainly based on the detection of the mesh cells in which grains are. Computing fluid fraction in a cell or evaluating the fluid velocity at the grain position imply to know where the grains are in the fluid. The tree structure based on mesh cells is used to locate the grains in the fluid.

6. At this step, the initial state is completely defined and all the variables and parametres have been created. Then the computation can start. The [computational loop](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/depot-2d/depot.py#L121) is composed of three main steps:

* Fluid equations solving

```python

whilet<tEnd:

fluid.implicit_euler(dt)

```

* Computation of the new grain free velocities

```python

forces=fluid.compute_node_force(dt)

vn=p.velocity()+forces*dt/p.mass()

```

* Contacts solving using a sub-timestep and grains displacement

```python

foriinrange(nsub):

tol=1e-6

p.iterate(dt/nsub,forces,tol)

```

The loop also contained instruction to write output files. It is important to note that after moving the grains in computational loop you have to use the _set_particles()_ function to search the new location og the grains in the mesh.

## Main Features

It is important to note that within the granular flows field there are many different types of applications, which can be computed in a variety of way. The model you used may be dependant of the observed quantity. In this section, we will briefly outline the possibilities offered by the MigFlow Software.

### Friction, Cohesion and so on...

One of the greatest advantage of the MigFlow Software is its compatibility with the [LMGC90](https://git-xen.lmgc.univ-montp2.fr/lmgc90/lmgc90_user/wikis/home) Software (for installation we recommand to follow instructions on their website). A contact solver, named _scontact_ is provided with MigFlow to compute velocities and trajectories of grains, forbiding interpenatration, in a lagrangian way. It uses a time-stepping method that corrects iteratively the free velocities of the grains, obtained by applying external forces, to compute a set of velocities giving after displacement of the grains a stationnary state without intersection. But _scontact_ module can be disconnected from the fluid part and replaced by LMGC90 to take advantage of the huge variety of contact law implemented in it. Some test cases are given to present how to call LMGC90 from the Users Interface:

-[betonlmgc.py](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/couette-2d/betonlmgc.py) presents the mixing of grains with different radii in a rotating drum using LMGC90 to take into account the impact of the friction on the mixing efficiency.

### Adaptive Mesh

MigFlow is based on an unresolved Computational Fluid Dynamics-Discrete Element Method model. The discretisation method we choose for the CFD part is the Finite Element Method. On one hand, unstructured grids offer a great flexibility to represent complex geometries with which grains interact. On the other hand, it is easy to adapt the mesh in order to refine it around the area of interest to capture accurately flow fields during the grains motion.

-[drop.py](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/drop-2d/SimpleDrop/drop.py) presents the fall of a cloud made of grains in a viscous fluid and make use of this feature to refine the the cloud area during the fall. In this way, it is possible to highly fasten the computation because the area of interest (i.e. the cloud) is small compared with the entire computational domain.

The arguments a and b in the _adapt_mesh_ function are optional. These parametres are used to weigh the maximum and minimum gradient used to compute the new mesh size at each node of the old mesh. For more information on the refinment formula see: Constant, M., Dubois, F., Lambrechts, J. and Legat, V. (2018). Implementation of an unresolved stabilised FEM-DEM model to solve immersed granular flows. _Computational Particle Mechanics_. [doi:10.1007/s40571-018-0209-4](https://doi.org/10.1007/s40571-018-0209-4).

### Two Fluids + Grains

To consider two continuous phases, an advective equation for the concentration is added to the standard Navier-Stokes equations. See the following example to run test cases with two different continuous phases.

-[avalanch2fluids.py](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/avalanch/avalanch2fluids/avalanch2fluids.py) presents the fall of a granular column immersed in sea water in a 2D domain filled with soft water.

## Frequent Asked Questions

See the [wiki](https://git.immc.ucl.ac.be/fluidparticles/migflow/wikis/home) for documented examples and installation instructions.