Particles on an inclined chute

Problem description

File ChuteDemo.cpp treats particles cascading down an inclined chute. The entire code of this problem can be viewed here: Particles on an inclined chute (code).

Headers

The following headers are included:

#include <iostream>
#include <Species/LinearViscoelasticSpecies.h>
#include "Chute.h"

The particle species is manually set here, and therefore needs to be included. We're treating a chute problem here, and the Chute class needs to be included therefore as well. The particles, walls and boundaries classes are already implemented by the chute class and don't need inclusion here.

<tt> int %main()</tt>

Since the whole structure of the problem is already implemented in the Chute class, no separate class needs to be set up. The setup of initial conditions of the Chute class is shortly treated at the end of this section.
The main driver program starts by initialising a Chute object. Next, the most basic problem properties are set, namely its name (which determines the naming of the data output files), save count (which is the number of time steps skipped between every saved one), particle collision time (which is a species property, but also used in setting the time step), time step and maximum time. Note, that the total number of time steps saved to the output files is not directly set, but is equal to the maximum time divided by time step size and save count.

    // Problem parameters
    Chute problem;
    
    problem.setName("ChuteDemo");   // data output file name
    problem.setGravity({0,-1,0});
    problem.setSaveCount(102);      // number of time steps skipped between saves
    Mdouble tc = 2.5e-3;            // collision time
    problem.setTimeStep(0.02 * tc); // actual time step
    problem.setTimeMax(0.5);        // maximum time
                                    // NB: number of time steps saved to output files
                                    // is timeMax/(timeStep*saveCount)

Next, the particle properties are set. setFixedParticleRadius() sets the radius of the fixed chute bottom particles, while setInflowParticleRadius() sets the inflow particles to be mono-disperse with the given particle radius. If inflow particles with random radii are desired, setMinInflowParticleRadius() and setMaxInflowParticleRadius() can be used instead to set the minimum and maximum particle radius, respectively.
The particle species (i.e. its intrinsic material properties) are set next, by specifying the density (species.setDensity()) and the characteristic collision time and coefficient of restitution (with a typical particle mass given; species.setCollisionTimeAndRestitutionCoefficient( \( t_c, r_c, m\))).

    // Particle radii
    problem.setFixedParticleRadius(0.001);  // radius of fixed chute bottom particles
    problem.setInflowParticleRadius(0.001); // radius of (monodisperse) inflow particles
 
    // Particle species
    LinearViscoelasticSpecies species;              // initialise species
    species.setHandler(&problem.speciesHandler);    // assign problem species handler to species
    species.setDensity(2000);                       // particle density
    species.setCollisionTimeAndRestitutionCoefficient( tc, 
            0.8, species.getMassFromRadius(problem.getInflowParticleRadius())); // material properties
    problem.speciesHandler.copyAndAddObject(species);   // assign species to problem species handler
    

The chute properties are subsequently set by specifying the chute's length, width and angle relative to the horizontal.

    // Chute properties
    problem.setChuteAngle(30.0);                    // set angle of chute relative to horizontal
    problem.setXMax(0.1);                           // chute length = 0.1
    problem.setYMax(2.0 * problem.getInflowParticleRadius()); // chute width = 1 particle diameter

The chute inflow parameters (besides the previously set inflow particle properties) are set by specifying the inflow height (in Z-direction), the mean iflow particle velocity (in X-direction), and the particle velocity variance (in ratio of the mean velocity).

    // Inflow properties
    problem.setInflowHeight(0.1);                   // particle inflow between 0 <= Z <= 0.1
    problem.setInflowVelocity(0.1);                 // particle inflow mean velocity
    problem.setInflowVelocityVariance(0.02);        // particle inflow velocity variance (in ratio of the mean velocity)
    //Write paraview data
    problem.setParticlesWriteVTK(true);
    problem.wallHandler.setWriteVTK(true);

After all the problem parameters are specified, the simulation is run by calling the solve() method.

problem.solve(); 

Chute::setupInitialConditions()

void Chute::setupInitialConditions()
{
    if (speciesHandler.getNumberOfObjects() == 0)
    {
        logger(FATAL, "[Chute::setupInitialConditions()] Chute % cannot "
                      "complete because no species have been defined.", getName());
    }

The setup of initial conditions of the Chute class starts by checking for the presence of a species, and returns an error if there is none. Make sure therefore that you assign a species to the Chute object's speciesHandler before you call the solve() method.
After that, the side walls (in the Y-direction) are set up by calling Chute::setSideWalls(). These are set to be solid, infinite walls by default, but can be set to be periodic instead by setting Chute::isChutePeriodic_ to be true.
A particle is then created (on the heap) which is assigned the first (and only) species in the speciesHandler which we earlier specified in the driver (ChuteDemo.cpp).
A ChuteInsertionBoundary is created, and its parameters subsequently set by its set() method. The set() method arguments are, respectively:

• p: the previously specified particle
• maxFailed_: internally used parameter
• Vec3D(getXMin(), getYMin(), getZMin()): the first defining corner of the cuboidal insertion boundary
• Vec3D(getXMax(), getYMax(), getZMax()): the second defining corner of the cuboidal insertion boundary
• min- / maxInflowParticleRadius_: the minimum and maximum radii of inflow particles
• fixedParticleRadius_: the particle radius making up the chute bottom
• inflowVelocity(Variance)_: the mean velocity of inflow particles and the allowed variance about the mean

After setting the insertion boundary characteristics, it is added to the problem's boundaryHandler.
Lastly, the chute's bottom is created. The type of bottom created may be set by calling the Chute::setRoughBottomType() method in the driver, giving either of the following four arguments (which are of type enum RoughBottomType):

• FLAT: just a flat wall (of the species given in the driver)
• MONOLAYER_ORDERED: (a single layer of) fixed particles in a rectangular grid pattern
• MONOLAYER_DISORDERED: (default) a single layer of randomly placed particles
• MULTILAYER: a few layers of randomly placed particles, with a random variation in vertical position as well

Reference:

Thornton, A. R., Weinhart, T., Luding, S., & Bokhove, O. (2012). Frictional dependence of shallow-granular flows from discrete particle simulations. The European Physical Journal E, 35(12), 127.
Weinhart, T., Thornton, A. R., Luding, S., & Bokhove, O. (2012). Closure relations for shallow granular flows from particle simulations. Granular matter, 14(4), 531-552.

(Return to Overview of advanced tutorials)