This page contains the following tutorials:

T1: Particle motion in outer space

Particle moving with a constant velocity in outer space.

Problem description:

File Tutorial1.cpp is setup to simulate a particle moving with a constant velocity in the absence of gravity, i.e. $ g= 0 m/s^2$ . Below we describe each bit of the T1.cpp in detail.

Headers:

To setup this problem code, below are the necessary headers (from the kernel) and the standard libraries, we include in Tutorial1.cpp.

#include <Species/Species.h>
#include <Species/LinearViscoelasticSpecies.h>
#include <Mercury3D.h>
#include <Particles/BaseParticle.h>

Details concerning the above included headers (from the kernel) can be found in

Class Tutorial1:

A class named Tutorial1 inherits from Mercury3D and is defined as below

class Tutorial1 : public Mercury3D  
{ 
  public:
  void setupInitialConditions()
  { 
    BaseParticle p0;
    p0.setSpecies(speciesHandler.getObject(0));
    p0.setRadius(0.05); // sets particle radius
    p0.setPosition(Vec3D(0.1*getXMax(),0.1*getYMax(),0.1*getZMax())); // sets particle position
    p0.setVelocity(Vec3D(0.5,0.1,0.1));
    particleHandler.copyAndAddObject(p0);
  }
};

The below function creates and sets up the problems’ initial conditions

void setupInitialConditions()

How to create a particle?

A particle is created and copied in a manner shown below

    BaseParticle p0;
    p0.setSpecies(speciesHandler.getObject(0));
    p0.setRadius(0.05); // sets particle radius
    p0.setPosition(Vec3D(0.1*getXMax(),0.1*getYMax(),0.1*getZMax())); // sets particle position
    p0.setVelocity(Vec3D(0.5,0.1,0.1));
    particleHandler.copyAndAddObject(p0);

p0 is an instance of the class BaseParticle and its properties like radius, initial position and velocity are set as above. The bit

particleHandler.copyAndAddObject(p0)

creates the particle p0 and adds a copy of it needed for the simulation.

Main function:

In the main function, # Problem properties, such as gravity, spatial dimensions (x,y,z), total run time are set as below

  problem.setName("Tutorial1");
  problem.setSystemDimensions(3);
  problem.setGravity(Vec3D(0.0,0.0,0.0));
  problem.setXMax(1.0);
  problem.setYMax(1.0);
  problem.setZMax(1.0);
  problem.setTimeMax(2.0);

# A particle can be of any type. There exist a variety of particle types, e.g. glass, plastic etc. Each of them behave differently when in action. Initially, when a particle is created, it attains the properties of a default species type with ‘0’ as its index. However, one can changes the species properties, as below.

  // The normal spring stiffness and normal dissipation is computed and set as 
  // For collision time tc=0.005 and restitution coefficeint rc=1.0,
  auto species = problem.speciesHandler.copyAndAddObject(LinearViscoelasticSpecies());
  species->setDensity(2500.0); // sets the species type-0 density
  species->setStiffness(258.5);// sets the spring stiffness
  species->setDissipation(0.0);// sets the dissipation

# Data output is vital to analyse simulations, which leads to defining ways to save the simulation data for post processing.
The simulations generate several types of data files. See Understanding the Output Files.
Below we set the flags corresponding to each data file type.

  problem.setSaveCount(10);
  problem.dataFile.setFileType(FileType::ONE_FILE);
  problem.restartFile.setFileType(FileType::ONE_FILE);
  problem.fStatFile.setFileType(FileType::NO_FILE);
  problem.eneFile.setFileType(FileType::NO_FILE);
  std::cout << problem.dataFile.getCounter() << std::endl;

# For XBalls users, additional display options can be set as below

problem.setXBallsAdditionalArguments("-solidf -v0");

# After all the simulation parameters are set, we reach a point where we put all the above bits of code in action by the following statements

problem.setTimeStep(.005/50.0); // (collision time)/50.0

problem.solve(argc, argv);

To see the above snippets as a whole, goto Particle motion in outer space (code)

T2: Particle motion on earth

Particle falling due to gravity.

Problem descritpion:

In Tutorial2.cpp, we simulate a particle when dropped under the influence of gravity, $ g = 9.81 m/s^2$ . Basically this is an extension of T1.cpp with few minor changes. All we need to do is change the following

initial particle position and velocity in Class Tutorial2
p0.setPosition(0.5*getXMax(),0.5*getYMax(),getZMax());

p0.setVelocity(Vec3D(0.0,0.0,0.0));
gravity vector in the main function of Tutorial2.cpp
problem.setGravity(Vec3D(0.0,0.0,-9.81));

To see the whole code with the above snippets included, goto Particle motion on earth (code)

T3: Bouncing ball (elastic)

Particle bouncing off the blue wall.

Problem description:

In Tutorial3.cpp, we simulate a particle bouncing off a wall assuming the collision between the particle and the wall is elastic. By elastic we mean that the particle velocity before and after collision remains the same. Implying that the restitution coefficient is unity. Additionally, we will learn how to add a wall over which the ball bounces.

Headers:

#include <Species/LinearViscoelasticSpecies.h>
#include <Mercury3D.h>
#include <Particles/BaseParticle.h>
#include <Walls/InfiniteWall.h>

In order to add a wall to our problem setup we need to consider including the header

#include “Walls/InfiniteWall.h”

Class Tutorial3:

class Tutorial3 : public Mercury3D
{
  public:
  void setupInitialConditions()
  { 
    BaseParticle p0;
    p0.setSpecies(speciesHandler.getObject(0));
    p0.setRadius(0.005);
    p0.setPosition(Vec3D(0.5*getXMax(),0.5*getYMax(),getZMax()));
    p0.setVelocity(Vec3D(0.0,0.0,0.0));
    particleHandler.copyAndAddObject(p0);
    InfiniteWall w0;
    w0.setSpecies(speciesHandler.getObject(0));
    w0.set(Vec3D(0.0,0.0,-1.0),Vec3D(0, 0, getZMin()));
    wallHandler.copyAndAddObject(w0);
  }
};

The above class is basically an extension when compared to Class Tutorial1 or Class Tutorial2. Only difference being the addition of the wall which is done as shown in the snippet below

    InfiniteWall w0;
    w0.setSpecies(speciesHandler.getObject(0));
    w0.set(Vec3D(0.0,0.0,-1.0),Vec3D(0, 0, getZMin()));
    wallHandler.copyAndAddObject(w0);

The above set of statements, create and place the wall at $Z_{min}$ .
Note: Don’t forget to include the InfiniteWall.h header, as shown in the header section. In some sense, creation and addition of a wall is similar to creation and addition of a particle.

Main function:

As usual, the problem is setup in the main function, see Bouncing ball - elastic (code).

T4: Bouncing ball with dissipation (inelastic)

Problem description:

In Tutorial4.cpp, the difference between an elastic and inelastic collision between a particle and a wall is illustrated. The only difference between T3.cpp and T4.cpp is the value of the restitution coefficient. In T4.cpp, the coefficient of restitution is set to

double rc = 0.88; // restitution coefficient

See Bouncing ball - inelastic (code) for more details.

T5: Elastic collision (2 particles)

Particles moving towards each other.

Problem description:

So far, in the above tutorials, we have seen how a particle and a wall interact during a collision.
In this tutorial, we illustrate how two particles interact using Tutorial5.cpp. For this purpose, we need two particles.
The particles may or may not be of the same species type. But, here we shall assume they are of same species and same size.
As usual, we begin with including the required headers

Headers:

#include <Species/LinearViscoelasticSpecies.h>
#include <Mercury3D.h>
#include <Particles/BaseParticle.h>

Class Tutorial5:

class Tutorial5 : public Mercury3D
{
  public:
  void setupInitialConditions()
  { 
    BaseParticle p0;
    p0.setSpecies(speciesHandler.getObject(0));
 
    p0.setRadius(0.005); //particle-1 radius
    p0.setPosition(Vec3D(0.25*getXMax(),0.5*getYMax(),0.5*getZMax()));
    p0.setVelocity(Vec3D(0.25,0.0,0.0));
    particleHandler.copyAndAddObject(p0); // 1st particle created
    p0.setRadius(0.005); // particle-2 radius
    p0.setPosition(Vec3D(0.75*getXMax(),0.5*getYMax(),0.5*getZMax()));
    p0.setVelocity(Vec3D(-0.25,0.0,0.0));
    particleHandler.copyAndAddObject(p0); // 2nd particle created
  }
};

On comparison between the above class and Class Tutorial1, we see how an additional particle is added. In the above class, in function

void setupParticleInitialConditions(){}

two particles are created, and positioned oppositely apart at a certain distance between them. Both the particles, have a certain velocity directing them towards each other.

Main function:

Similar to Tutorial1.cpp, the problem is setup in Elastic collision - 2 particles (code)

T6: Elastic collisions with periodic boundaries

(a) Illustrates the idea behind periodic boundaries, particle exiting boundary b2 re-enters through boundary b1 (b) Illustrates the problem setup.

Problem description:

In the previous tutorial, we illustrated elastic collision between two particles of same type and size traveling towards each other.
In order to have multiple collisions, in the problem setup as Tutorial 5, we will use periodic boundaries in X.

Headers:

#include <Species/LinearViscoelasticSpecies.h>
#include <Mercury3D.h>
#include <Particles/BaseParticle.h>
#include <Boundaries/PeriodicBoundary.h>

Above are the headers necessary for this problem.

Class Tutorial6:

class Tutorial6 : public Mercury3D
{
  public:
  void setupInitialConditions()
  { 
    BaseParticle p0;
    p0.setSpecies(speciesHandler.getObject(0));
    p0.setRadius(0.5);//particle-1
    p0.setPosition(Vec3D(0.25*getXMax(),0.5*getYMax(),0.75*getZMax()));
    p0.setVelocity(Vec3D(0.5,0.0,-0.3));
    particleHandler.copyAndAddObject(p0);
    p0.setRadius(0.6);// particle-2
    p0.setPosition(Vec3D(0.75*getXMax(),0.5*getYMax(),0.5*getZMax()));
    p0.setVelocity(Vec3D(-0.5,0.0,0.3));
    particleHandler.copyAndAddObject(p0);
    PeriodicBoundary b0;
    b0.set(Vec3D(1.0,0.0,0.0),getXMin(),getXMax());
    boundaryHandler.copyAndAddObject(b0);
  }
};

In the Class Tutorial6
(i) we create two particles of same type and different sizes.
(ii) we setup periodic boundaries in X-direction as

    PeriodicBoundary b0;
    b0.set(Vec3D(1.0,0.0,0.0),getXMin(),getXMax());
    boundaryHandler.copyAndAddObject(b0);

Note:
To create periodic boundaries one has to include the header ‘Boundaries/PeriodicBoundary.h’.
Be aware that the periodic boundary is not the same as an infinite wall.

Main function:

Similar to Tutorial5.cpp, the problem is setup to solve, see Elastic collisions with periodic boundaries (code)

T7: Motion of a particle in a two dimensional (2D) box

Particle motion in a box (blue and black denote the walls).

Problem description:

In previous tutorials, we have seen how a particle interacts with a wall and itself. In this tutorial, we will learn to design boxes of different shapes by using more than one wall. As an example, in absence of gravity, we will simulate a particle moving in a two dimensional square shaped box. We consider two dimensions only for the sake of simplicity.

In Tutorial 3, we have shown you how to setup a wall. This tutorial builds itself on the same idea i.e. setting up walls.

Headers:

#include <Species/LinearViscoelasticSpecies.h>
#include <Mercury3D.h>
#include <Particles/BaseParticle.h>
#include <Walls/InfiniteWall.h> 

We use the same headers as used in Tutorial 3.

Class Tutorial7:

class Tutorial7 : public Mercury3D
{
  public:
  void setupInitialConditions()
  { 
    BaseParticle p0;
    p0.setSpecies(speciesHandler.getObject(0));
    p0.setRadius(0.005);
    p0.setPosition(Vec3D(0.5*getXMax(),0.5*getYMax(),0.0));
    p0.setVelocity(Vec3D(1.2,1.3,0.0));
    particleHandler.copyAndAddObject(p0);
    InfiniteWall w0;
    
    w0.setSpecies(speciesHandler.getObject(0));
    w0.set(Vec3D(1.0,0.0,0.0),Vec3D(getXMax(),0.0,0.0));
    wallHandler.copyAndAddObject(w0);
    w0.set(Vec3D(-1.0,0.0,0.0),Vec3D(getXMin(),0.0,0.0));
    wallHandler.copyAndAddObject(w0);
    w0.set(Vec3D(0.0,1.0,0.0),Vec3D(0.0,getYMax(),0.0));
    wallHandler.copyAndAddObject(w0);
    w0.set(Vec3D(0.0,-1.0,0.0),Vec3D(0.0,getYMin(),0.0));
    wallHandler.copyAndAddObject(w0);
  }
};

In this class, we setup a 2D square shaped box or a polygon by adding more walls as shown above. In total, we have 4 walls forming our box within which the particle will traverse.

Note: As we simulate in 2D, no walls are set in z-direction.

Main function:

As our simulation is two dimensional, we set the system dimensions as 2

problem.setSystemDimensions(2);

Complete code for the above problem description can be found in Motion of a particle in a two dimensional box (code)

T8: Motion of a particle in a box with an obstacle

Problem description:

We extend the problem setup of Tutorial 7, by adding a rectangular block as shown in the above figure. To create this block of wall or obstacle, we will use the Class FiniteWall. Before we go ahead it is advised to know the difference between an infinite wall and finite wall, see Different types of walls. As an example, we create an obstacle using a set of finite walls and place it within the box created using a set of infinite walls. See the above figure.

Headers:

#include <Species/LinearViscoelasticSpecies.h>
#include <Mercury3D.h>
#include <Particles/BaseParticle.h>
#include <Walls/InfiniteWall.h>
#include <Walls/IntersectionOfWalls.h>

Class Tutorial8:

The class Tutorial7 from the previous tutorial is extended by adding the finite wall setup. See the below snippet.

    IntersectionOfWalls w1;
    w1.addObject(Vec3D(-1.0,0.0,0.0),Vec3D(0.75*getXMax(),0.0,0.0));
    w1.addObject(Vec3D(1.0,0.0,0.0),Vec3D(0.25*getXMax(),0.0,0.0));
    w1.addObject(Vec3D(0.0,-1.0,0.0),Vec3D(0.0,0.75*getYMax(),0.0));
    w1.addObject(Vec3D(0.0,1.0,0.0),Vec3D(0.0,0.25*getYMax(),0.0));
    wallHandler.copyAndAddObject(w1);

Main function:

Similar to Tutorial 7, the above described problem is setup in Motion of a particle in a box with an obstacle (code)

T9: Motion of a ball over an inclined plane (Sliding + Rolling)

T1: Particle motion in outer space

Problem description:

Headers:

Class Tutorial1:

How to create a particle?

Main function:

T2: Particle motion on earth

Problem descritpion:

T3: Bouncing ball (elastic)

Problem description:

Headers:

Class Tutorial3:

Main function:

T4: Bouncing ball with dissipation (inelastic)

Problem description:

T5: Elastic collision (2 particles)

Problem description:

Headers:

Class Tutorial5:

Main function:

T6: Elastic collisions with periodic boundaries

Problem description:

Headers:

Class Tutorial6:

Main function:

T7: Motion of a particle in a two dimensional (2D) box

Problem description:

Headers:

Class Tutorial7:

Main function:

T8: Motion of a particle in a box with an obstacle

Problem description:

Headers:

Class Tutorial8:

Main function:

T9: Motion of a ball over an inclined plane (Sliding + Rolling)

Problem description:

Headers:

Class Tutorial9:

Main function: