# LF_DEM

 A code simulating simple shear flow of dense, overdamped suspensions of spherical particles. It includes hydrodynamics, contacts (with several contact models), potential interactions, and Brownian motion.

## Requirements

LF_DEM needs a C++11 compatible compiler.

LF_DEM requires the sparse linear algebra software SuiteSparse to be installed. SuiteSparse is easy to compile from sources. For Ubuntu users, there is a SuiteSparse package libsuitesparse-dev which is not the latest SuiteSparse version, but is the simplest possible installation.

## Getting the code

### By using git

We strongly encourage to use the version control system Git (for Mac OS X, for Linux). This will allow you to get updates of the code in a very easy and clean way and to contribute to the code by sending bug fixes or new features with a minimal effort.

You can get the code by typing in a terminal:

$make install  The second command is only needed if you want to install LF_DEM in the given install_dir. ## Usage ### Running a simulation LF_DEM takes two kinds of inputs, command-line arguments and parameter files. The general syntax is: $ LF_DEM [-r shear_rate ] [-s shear_stress ] [-k kn_kt_File] Configuration_File Parameter_File


where Configuration_File contains the initial positions and Parameter_File the (many) simulation parameters. Either the shear rate or the shear stress must be given in input (but not both). You must enter them with their units as a suffix (see below). The kn_kt_File is an optional file which specifies the contact stiffnesses as a function of the volume fraction and shear rate.

#### Input of units

LF_DEM is designed to work with several unit scales, each based on a force scale. As a consequence the user must specify the units in input, by appending a literal suffix to the numeral value. The list of suffixes corresponding to the forces currently implemented in LF_DEM is the following:

Set of unit Suffix
Repulsive force "r"
Brownian force "b"
Cohesion "c"
Normal contact stiffness "kn"
Tangential contact stiffness "kt"
Rolling contact stiffness "kr"

For example, if using repulsive force and a Brownian force, one can specify in the Parameter_File:

 repulsion_amplitude = 3.2b; 

which will tell LF_DEM to work with an repulsive force with amplitude $$3.2kT/a$$ at contact (with $$kT$$ the temperature and $$a$$ the typical radius of a particle).

There is always one "special" force scale which gives a meaning (a unit) to the shear rate or the shear stress. Hence, to work with Peclet 5 you must input LF_DEM -r 5b, to work with a stress of $$4F_R^{\ast}/a^2$$, you must input LF_DEM -s 4r.

Note that the suffix notation is not limited to forces. For example, the simulation length can be set with

time_end = 100b;

in which case the simulation will run for $$100\times 6\pi\eta_0 a^3/kT$$, or with

time = 100h;

in which case it will run for $$100 \dot\gamma^{-1}$$, ie $$100$$ strain units.

#### Configuration file

The initial configuration can be generated by LF_DEM, see Initial configurations.

#### Parameter file

The list of all possible parameters and their description is available in html format in LF_DEM/html/struct_parameter_set.html. This file can also be viewed online here. (If none of this works for you, the complete list of parameters is kept in LF_DEM/ParameterSet.h.)

Although none of these parameters is compulsory (the simulation can run with default hard-coded values), as much as possible they should be provided by the user. One example of input parameter file is given in the file nobrownian_2D.txt.

#### Rate-controlled mode

It is selected by -r followed by the value of the shear rate (with suffix for units!):

#### Stress-controlled mode

It is selected by -s followed by the value of the stress (with a unit too). It does not work in the Brownian case.

#### Other options

No documentation for this yet. Many options are temporary.

### Initial configurations

Initial configurations can be generated through:

\$ LF_DEM -g Random_Seed


LF_DEM will ask to input a series of parameters (number of particles, dimension, etc). The generated configuration is written in a file with a parameter dependant filename D*N*VF*.dat. An extra D*N*VF*.dat.yap is also generated to visualize the generated configuration with yaplot or homer.

Alternatively, you can generate initial configurations with the LFDEM_confgen.py utility built upon pyLF_DEM (see below).

### Python wrapper

There is a Python wrapper for LF_DEM that can be used to control the protocol (e.g. to impose a complex strain rate protocol) with the flexibility of a Python script.

## Complementary documentation

A source code documentation is maintained here.