Commit 18c9bfa2 authored by Matthieu Constant's avatar Matthieu Constant
Browse files

Merge branch 'oneFluid' of git.immc.ucl.ac.be:fluidparticles/migflow into oneFluid

parents 4fbc5d20 6ed8789a
Pipeline #4560 passed with stage
in 2 minutes and 5 seconds
......@@ -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
- Linux
export PATH="TheGoodPath/gmsh/build:$PATH"
- MacOs
export PATH="/Applications/Gmsh.app/Contents/MacOS:$PATH"
+ Installation of MigFlow
1. Go on the [gitlab](https://git.immc.ucl.ac.be/fluidparticles/migflow) page dedicated to the project to upload your ssh or https link
2. Open your terminal and type the following commands
cd ~
git clone https://username@git.immc.ucl.ac.be/fluidparticles/MigFlow.git
cd MigFlow
mkdir build
cmake ..
make
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:
git clone -b maint https://bitbucket.org/petsc/petsc petsc
c. Compiling options for PETSc:
cd petsc
./configure --with-mpi=0 -with-mpi=0 COPTFLAGS="-O3" --with-fc=0 --with-cxx=0 --with-debugging=0
d. Compile PETSc:
cd ../
make -j4
e. Compile MigFlow specifying PETSc paths:
- Ubuntu:
cd ~/MigFlow/build
cmake .. -DENABLE_PETSC=1 -DPETSC_DIR=/usr/lib/petscdir/petsc3.9/ -DPETSC_ARCH=x86_64-linux-gnu-real
make
- Other OS:
cd ~/MigFlow/build
cmake .. -DENABLE_PETSC=1 -DPETSC_DIR=$HOME/petsc -DPETSC_ARCH==seq-real-opt
make
## Test Cases Ready to Use
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)
```python
g = -9.81 # gravity
r = 1e-3 # grains radius
rhop = 1500 # grains density
rho = 1000 # fluid density
nu = 1e-6 # kinematic viscosity
```
* [numerical parametres](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/depot-2d/depot.py#L76)
```python
outf = 5 # number of iterations between output files
dt = 1e-2 # time step
tEnd = 100 # final time
```
* [domain geometry](https://git.immc.ucl.ac.be/fluidparticles/migflow/blob/oneFluid/testcases/depot-2d/depot.py#L81)
```python
#geometrical parameters
ly = 5e-2 # grains area height
lx = 4e-1 # grains area widht
H = 1.2 # domain height
```
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
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/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.
```python
fluid.set_weak_boundary(Physical boundary tag, Weak boundary type)
```
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.
```python
fluid.set_particles(p.mass(), p.volume(), p.position(), p.velocity())
```
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
while t < 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
for i in range(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.
```python
fluid.adapt_mesh(Max. element size, Min. element size, Total number of elements, a, b)
```
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.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment