phasicFlow/tutorials/sphereGranFlow/rotatingDrumSmall/README.md

# Simulating a Rotating Drum (v-1.0)

## Problem Definition

The problem is to simulate a rotating drum with a diameter of 0.24 m and a length of 0.1 m, rotating at 11.6 rpm. It is filled with 30,000 spherical particles, each with a diameter of 4 mm. The timestep for integration is 0.00001 s. This tutorial demonstrates the basic setup for creating a rotation-based simulation using built-in geometry in PhasicFlow.

<div align="center">
<b>
A view of the rotating drum
</b>
<div>
<img src="https://github.com/PhasicFlow/phasicFlow/blob/media/media/rotating-drum-s.png" width="600px">
</div>
</div>

***

## Setting up the Case 

PhasicFlow simulation case setup is based on text-based scripts provided in two folders located in the simulation case folder: `settings` and `caseSetup`. All commands should be entered in the terminal while the current working directory is the simulation case folder (at the top level of `caseSetup` and `settings`).

### Creating Particles

In the file `settings/particlesDict`, two dictionaries, `positionParticles` and `setFields`, position particles and set the field values for the particles.

The `positionParticles` dictionary uses the `ordered` method to position particles in a space defined by `box`. The box space is defined by two corner points: `min` and `max`. In the `orderedInfo` sub-dictionary, `numPoints` defines the number of particles (30,000), `distance` defines the spacing between adjacent particles (4 mm), and `axisOrder` defines the axis order for filling the space with particles.

<div align="center"> 
in <b>settings/particlesDict</b> file
</div>

```C++
positionParticles           
{ 
    method         ordered; // other options: random and empty

    mortonSorting  Yes;     // perform initial sorting based on morton code?   

    orderedInfo
    {
        distance  0.004;    // minimum space between centers of particles

        numPoints 30000;    // number of particles in the simulation 

        axisOrder (z y x);  // axis order for filling the space with particles
    }

    regionType    box;      // other options: cylinder and sphere  

    boxInfo                 // box information for positioning particles 
    {
        min (-0.08 -0.08 0.015);  // lower corner point of the box 

        max ( 0.08  0.08 0.098);   // upper corner point of the box 
    }
}
```

In the `setFields` dictionary, the `defaultValue` sub-dictionary defines the initial values for particle fields (velocity, acceleration, rotational velocity, and shape name). The shape name field should be consistent with the name defined in the shapes file (here, "sphere1").

<div align="center"> 
in <b>settings/particlesDict</b> file
</div>

```C++
setFields
{
    defaultValue 
    {
        velocity        realx3  (0 0 0);         // linear velocity (m/s)

        acceleration    realx3  (0 0 0);         // linear acceleration (m/s2)

        rVelocity       realx3  (0 0 0);         // rotational velocity (rad/s)

        shapeName       word    sphere1;         // name of the particle shape 
    }

    selectors
    {
        // Selectors can be used to modify properties for specific particle groups
    }
}
```

To create the particles and store them in the `0` folder, enter the following command:

```
particlesPhasicFlow
```

### Creating Geometry

In the file `settings/geometryDict`, you define the motion model and geometry for the simulation. The `rotatingAxis` motion model defines a fixed axis which rotates around itself. The `rotAxis` dictionary specifies the axis endpoints and rotation speed.

<div align="center"> 
in <b>settings/geometryDict</b> file
</div>

```C++
motionModel rotatingAxis; 

rotatingAxisInfo 
{
    rotAxis 
    {
        p1 (0.0 0.0 0.0);     // first point for the axis of rotation 

        p2 (0.0 0.0 1.0);     // second point for the axis of rotation

        omega      1.214;     // rotation speed (rad/s)
    }
}
```

The `surfaces` dictionary defines all the walls in the simulation. This tutorial uses built-in geometries provided by PhasicFlow. The geometry consists of:

1. A `cylinder` dictionary defining a cylindrical shell with end radii (`radius1` and `radius2`), axis endpoints (`p1` and `p2`), material name (`prop1`), and motion component (`rotAxis`).
2. Two plane walls (`wall1` and `wall2`) at the ends of the cylindrical shell, each defined with four coplanar corner points, the same material name, and the same motion component.

<div align="center"> 
in <b>settings/geometryDict</b> file
</div>

```C++
surfaces
{
    /*
        A cylinder with begin and end radii 0.12 m and axis points at (0 0 0) and (0 0 0.1)
    */
    cylinder
    {
        type cylinderWall;      // type of the wall

        p1  (0.0 0.0 0.0);     // begin point of cylinder axis

        p2  (0.0 0.0 0.1);     // end point of cylinder axis

        radius1      0.12;     // radius at p1

        radius2      0.12;     // radius at p2

        resolution     24;      // number of divisions

        material    prop1;      // material name of this wall

        motion    rotAxis;      // motion component name 
    }

    /*
        This is a plane wall at the rear end of cylinder
    */
    wall1
    {
        type       planeWall;      // type of the wall

        p1 (-0.12 -0.12 0.0);      // first point of the wall

        p2 ( 0.12 -0.12 0.0);      // second point

        p3 ( 0.12  0.12 0.0);      // third point

        p4 (-0.12  0.12 0.0);      // fourth point 

        material       prop1;      // material name of the wall

        motion       rotAxis;      // motion component name 
    }

    /*
        This is a plane wall at the front end of cylinder
    */
    wall2
    {
        type       planeWall;      // type of the wall

        p1 (-0.12 -0.12 0.1);      // first point of the wall

        p2 ( 0.12 -0.12 0.1);      // second point

        p3 ( 0.12  0.12 0.1);      // third point

        p4 (-0.12  0.12 0.1);      // fourth point 

        material       prop1;      // material name of the wall

        motion       rotAxis;      // motion component name 
    }
}
```

To create the geometry and store it in the `0/geometry` folder, enter:

```
geometryPhasicFlow
```

### Defining Properties and Interactions 

In the file `caseSetup/interaction`, you define properties of materials and their interactions. The `materials` entry lists material names, and `densities` sets the corresponding densities. The `model` dictionary defines the contact force and rolling friction models, along with other required properties.

<div align="center"> 
in <b>caseSetup/interaction</b> file
</div>

```C++
materials                   (prop1);   // a list of materials names

densities                  (1000.0);   // density of materials [kg/m3]

contactListType   sortedContactList; 

model
{
    contactForceModel    nonLinearNonLimited;

    rollingFrictionModel              normal;

    Yeff  (1.0e6);     // Young modulus [Pa]

    Geff  (0.8e6);     // Shear modulus [Pa]

    nu    (0.25);      // Poisson's ratio [-]

    en    (0.7);       // coefficient of normal restitution

    mu    (0.3);       // dynamic friction 

    mur   (0.1);       // rolling friction      
}
```

The `contactSearch` dictionary specifies the algorithm and parameters for finding particle-particle contacts. The `method` determines the broad search algorithm, `updateInterval` sets how often to update the neighbor list, and `sizeRatio` controls the enlarged cell size for finding neighbors.

<div align="center"> 
in <b>caseSetup/interaction</b> file
</div>

```C++
contactSearch
{
    method          NBS;  

    updateInterval   10;

    sizeRatio       1.1;

    cellExtent     0.55;

    adjustableBox   Yes;
} 
```

In the file `caseSetup/shapes`, you define particle shapes, including their names, diameters, and material properties:

<div align="center"> 
in <b>caseSetup/shapes</b> file
</div>

```C++
names       (sphere1);    // names of shapes 

diameters     (0.004);    // diameter of shapes 

materials     (prop1);    // material names for shapes
```

### Simulation Domain and Boundaries

The file `settings/domainDict` defines a rectangular bounding box with boundaries. Particles that exit this box are automatically deleted.

<div align="center"> 
in <b>settings/domainDict</b> file
</div>

```C++
// Simulation domain: every particles that goes outside this domain will be deleted
globalBox                                        
{
    min (-0.12 -0.12 0.00);   // lower corner point of the box 

    max (0.12   0.12 0.11);   // upper corner point of the box 
}

boundaries
{
    left
    {
        type     exit;      // other options: periodic, reflective 
    }

    right
    {
        type     exit;      // other options: periodic, reflective 
    }

    bottom
    {
        type     exit;      // other options: periodic, reflective 
    }

    top
    {
        type     exit;      // other options: periodic, reflective 
    }

    rear
    {
        type     exit;      // other options: periodic, reflective 
    }

    front
    {
        type     exit;      // other options: periodic, reflective 
    }
}
```

### Other Settings

Additional parameters for the simulation are set in `settings/settingsDict`, including timestep, start and end times, saving intervals, and gravity:

<div align="center"> 
in <b>settings/settingsDict</b> file
</div>

```C++
dt              0.00001;     // time step for integration (s)

startTime             0;     // start time for simulation 

endTime              10;     // end time for simulation 

saveInterval        0.1;     // time interval for saving the simulation

timePrecision         6;     // maximum number of digits for time folder 

g            (0 -9.8 0);     // gravity vector (m/s2) 

includeObjects (diameter);   // save necessary (i.e., required) data on disk

// exclude unnecessary data from saving on disk
excludeObjects ();

integrationMethod       AdamsBashforth2;  // integration method

integrationHistory                  off;  // to save space on disk

writeFormat                       ascii;  // data writing format (ascii or binary)

timersReport                        Yes;  // report timers (Yes or No)
```

## Running the Case 

To execute the simulation, follow these steps in order:

1. Create the geometry:

```
geometryPhasicFlow
```

2. Create the initial particle fields:

```
particlesPhasicFlow
```

3. Run the simulation:

```
sphereGranFlow
```

Depending on your computational resources, the simulation may take from a few minutes to several hours to complete.

## Post Processing 

After the simulation completes, you can visualize the results in ParaView by converting them to VTK format:

```
pFlowToVTK --binary
```

This command converts all simulation results (particles and geometry) to VTK format and stores them in a `VTK/` folder. You can then open these files in ParaView for detailed analysis and visualization.

For more specific field output, you can specify fields:

```
pFlowToVTK --binary --fields diameter velocity id
```