diff --git a/tutorials/postprocessPhasicFlow/segregation/README.md b/tutorials/postprocessPhasicFlow/segregation/README.md new file mode 100644 index 00000000..69ab77e1 --- /dev/null +++ b/tutorials/postprocessPhasicFlow/segregation/README.md @@ -0,0 +1,184 @@ +# Post-processing for Evaluating Segregation of Particles + + - Compatibility: phasicFlow-v-1.0 + - Solvers and tools: sphereGranFlow, postprocessPhasicFlow + +## Background + +In particle-based simulations, it's often necessary to perform operations on particle fields to obtain bulk properties of the powder system (such as sums or averages). For example, we may need to calculate the mass-averaged velocity of particles in a granular flow. For bulk-processing of particle fields, we can use a mesh structure to obtain bulk properties of the powder in each cell. In this tutorial, we use a rectangular mesh in which a cuboid is divided into equal sub-spaces (cells). + +This tutorial demonstrates how to obtain three important bulk properties: + +- Mass-averaged solid velocity (and its fluctuations) +- Solid volume fraction +- Volume fraction of small particles (segregation measurement) + +## Problem Definition + +We will post-process the simulation results from the case [rotating drum with binary particles](../sphereGranFlow/binarySystemOfParticles/). The goal is to create a rectangular mesh with cuboid cells and calculate bulk properties on this mesh to analyze particle segregation patterns. + +*** + +## Case Setup + +This tutorial focuses solely on the post-processing aspect of the simulation. It assumes you have already executed the simulation and the results are available for post-processing. + +**Important Note:** Postprocessing in phasicFlow can be performed in two modes: +1. **In-simulation postprocessing**: Activated during simulation runtime, allowing calculations on live simulation data +2. **Post-simulation postprocessing**: Performed after the simulation has completed + +For more detailed information about different modes of postprocessing, please refer to the [official documentation page](../../../src/PostprocessData/readme.md). + +### Configuration File + +In `settings/postprocessDataDict`, you configure the post-processing parameters: + +```C++ +// file: settings/postprocessDataDict + +// Enable in-simulation postprocessing (set to "no" for post-simulation only) +runTimeActive yes; + +// Shape type used in the simulation +shapeType sphere; + +components +( + on_rectMesh + { + // Use Gaussian distribution for sampling and distributing + // particle properties over cells + processMethod GaussianDistribution; + + processRegion rectMesh; + + // Use time control in settingsDict file + timeControl settingsDict; + + // A rectangular mesh is constructed using corner points of the + // mesh region and number of divisions in each direction + rectMeshInfo + { + min (-0.12 -0.12 0.00); + max (0.12 0.12 0.1); + nx 36; + ny 36; + nz 15; + } + + operations + ( + // Calculate mass-averaged particle velocity + avVelocity + { + function average; + + field velocity; + + fluctuation2 yes; + + threshold 4; + + phi mass; + } + + // Calculate solid volume fraction + solidVolFraction + { + function sum; + + field volume; + + divideByVolume yes; + + threshold 4; + } + + // Calculate volume fraction of small particles + smallSphereVolFraction + { + function average; + + field one; + + phi volume; + + divideByVolume no; + + threshold 4; + + includeMask lessThan; + + lessThanInfo + { + field diameter; + + value 0.0031; + } + } + ); + + } +); +``` + +### Understanding the Configuration + +#### Mesh Configuration +In the `rectMeshInfo` dictionary: +- `min` and `max` define the corner points of the entire domain +- `nx`, `ny`, and `nz` define the number of divisions in each direction + +#### Operations +We define three operations to extract bulk properties: + +1. **avVelocity**: Calculates mass-averaged particle velocity + + The `average` function is defined mathematically as: + + $$\text{average} = \frac{\sum_j w_j \cdot \phi_j \cdot \text{field}_j}{\sum_i w_i \cdot \phi_i}$$ + + When `field` is set to velocity and `phi` is set to mass, we calculate the mass-averaged velocity of particles in each cell. With `fluctuation2` set to yes, we also calculate velocity fluctuations around the mean value. + + Note that: + - Cells with fewer than 4 particles are excluded (via the `threshold` parameter) + - $w_j$ is the weight factor determined by the Gaussian distribution function + +2. **solidVolFraction**: Calculates solid volume fraction in each cell + + The `sum` function is defined as: + + $$\text{sum} = \sum_j w_j \cdot \phi_j \cdot \text{field}_j$$ + + By setting `field` to volume and `divideByVolume` to yes, we sum the volumes of all particles in each cell and divide by the cell volume, giving us the solid volume fraction. + +3. **smallSphereVolFraction**: Calculates volume fraction of small particles in each cell + + This operation measures the volume fraction of small particles relative to total particle volume. The `includeMask` parameter filters particles by diameter, selecting only those smaller than 0.0031 units. + + The numerator of the `average` function calculates the sum of small particle volumes, while the denominator calculates the total volume of all particles. + +### Particle Filtering with includeMask + +The `includeMask` parameter allows filtering particles based on field values. Available options include: + +* `all`: Include all particles (default) +* `lessThan`: Include particles where field < value +* `lessThanEq`: Include particles where field ≤ value +* `greaterThan`: Include particles where field > value +* `greaterThanEq`: Include particles where field ≥ value +* `equal`: Include particles where field = value +* `between`: Include particles where value1 < field < value2 +* `betweenEq`: Include particles where value1 ≤ field ≤ value2 + +## Running the Post-processing Tool + +After completing the simulation, execute the post-processing tool with: + +```bash +postprocessPhasicFlow +``` + +The results will be stored in the `./postprocessData` folder. + +**Tip:** Run `postprocessPhasicFlow -h` to see all available command-line options, including time range selection for post-processing. \ No newline at end of file diff --git a/tutorials/postprocessPhasicFlow/segregation/caseSetup/interaction b/tutorials/postprocessPhasicFlow/segregation/caseSetup/interaction index 43943550..e1379984 100755 --- a/tutorials/postprocessPhasicFlow/segregation/caseSetup/interaction +++ b/tutorials/postprocessPhasicFlow/segregation/caseSetup/interaction @@ -7,47 +7,42 @@ objectType dicrionary; fileFormat ASCII; /*---------------------------------------------------------------------------*/ -materials (prop1); // a list of materials names -densities (1000.0); // density of materials [kg/m3] +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 - - et (1.0); // coefficient of tangential restitution - - mu (0.3); // dynamic friction - - mur (0.1); // rolling friction - -} - contactSearch { - method multiGridNBS; // method for broad search particle-particle - wallMapping multiGridMapping; // method for broad search particle-wall + + method NBS; - multiGridNBSInfo - { - updateFrequency 10; // each 10 timesteps, update neighbor list - sizeRatio 1.1; // bounding box size to particle diameter (max) - } + updateInterval 10; - multiGridMappingInfo - { - updateFrequency 10; // each 10 timesteps, update neighbor list - cellExtent 0.6; // bounding box for particle-wall search (> 0.5) - } + sizeRatio 1.1; + cellExtent 0.55; + + adjustableBox Yes; +} + +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 } + diff --git a/tutorials/postprocessPhasicFlow/segregation/caseSetup/particleInsertion b/tutorials/postprocessPhasicFlow/segregation/caseSetup/particleInsertion deleted file mode 100755 index 76835952..00000000 --- a/tutorials/postprocessPhasicFlow/segregation/caseSetup/particleInsertion +++ /dev/null @@ -1,14 +0,0 @@ -/* -------------------------------*- C++ -*--------------------------------- *\ -| phasicFlow File | -| copyright: www.cemf.ir | -\* ------------------------------------------------------------------------- */ -objectName particleInsertion; -objectType dicrionary; -fileFormat ASCII; -/*---------------------------------------------------------------------------*/ - -active no; // is insertion active? - -collisionCheck No; // not implemented for yes - - diff --git a/tutorials/postprocessPhasicFlow/segregation/caseSetup/sphereShape b/tutorials/postprocessPhasicFlow/segregation/caseSetup/shapes similarity index 91% rename from tutorials/postprocessPhasicFlow/segregation/caseSetup/sphereShape rename to tutorials/postprocessPhasicFlow/segregation/caseSetup/shapes index ffe420d8..166845e6 100755 --- a/tutorials/postprocessPhasicFlow/segregation/caseSetup/sphereShape +++ b/tutorials/postprocessPhasicFlow/segregation/caseSetup/shapes @@ -7,6 +7,8 @@ objectType sphereShape; fileFormat ASCII; /*---------------------------------------------------------------------------*/ -names (smallSphere largeSphere); // names of shapes +names (smallSphere largeSphere); // names of shapes + diameters (0.003 0.005); // diameter of shapes + materials (prop1 prop1); // material names for shapes diff --git a/tutorials/postprocessPhasicFlow/segregation/cleanThisCase b/tutorials/postprocessPhasicFlow/segregation/cleanThisCase index 8a0ab919..c7432438 100755 --- a/tutorials/postprocessPhasicFlow/segregation/cleanThisCase +++ b/tutorials/postprocessPhasicFlow/segregation/cleanThisCase @@ -3,5 +3,5 @@ cd ${0%/*} || exit 1 # Run from this directory ls | grep -P "^(([0-9]+\.?[0-9]*)|(\.[0-9]+))$" | xargs -d"\n" rm -rf rm -rf VTK - +rm -rf postprocessData #------------------------------------------------------------------------------ diff --git a/tutorials/postprocessPhasicFlow/segregation/settings/domainDict b/tutorials/postprocessPhasicFlow/segregation/settings/domainDict new file mode 100755 index 00000000..563cd80d --- /dev/null +++ b/tutorials/postprocessPhasicFlow/segregation/settings/domainDict @@ -0,0 +1,49 @@ +/* -------------------------------*- C++ -*--------------------------------- *\ +| phasicFlow File | +| copyright: www.cemf.ir | +\* ------------------------------------------------------------------------- */ +objectName domainDict; +objectType dictionary; +fileFormat ASCII; +/*---------------------------------------------------------------------------*/ + +// 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 + } +} diff --git a/tutorials/postprocessPhasicFlow/segregation/settings/geometryDict b/tutorials/postprocessPhasicFlow/segregation/settings/geometryDict index 46d4025b..c584a4f6 100644 --- a/tutorials/postprocessPhasicFlow/segregation/settings/geometryDict +++ b/tutorials/postprocessPhasicFlow/segregation/settings/geometryDict @@ -2,70 +2,89 @@ | phasicFlow File | | copyright: www.cemf.ir | \* ------------------------------------------------------------------------- */ -objectName geometryDict; -objectType dictionary; +objectName geometryDict; +objectType dictionary; fileFormat ASCII; /*---------------------------------------------------------------------------*/ -// motion model: rotating object around an axis -motionModel rotatingAxisMotion; +motionModel rotatingAxis; + +rotatingAxisInfo // information for rotatingAxisMotion motion model +{ + 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) + + startTime 0.5; + } +} 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 - } + /* + 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 - /* - 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 - } + p1 (0.0 0.0 0.0); // begin point of cylinder axis - /* - This is a plane wall at the front end of cylinder - */ - wall2 - { - type planeWall; - p1 (-0.12 -0.12 0.1); - p2 ( 0.12 -0.12 0.1); - p3 ( 0.12 0.12 0.1); - p4 (-0.12 0.12 0.1); - material prop1; - motion rotAxis; - } - - + 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 + } } -// information for rotatingAxisMotion motion model -rotatingAxisMotionInfo -{ - 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) - } -} \ No newline at end of file diff --git a/tutorials/postprocessPhasicFlow/segregation/settings/particlesDict b/tutorials/postprocessPhasicFlow/segregation/settings/particlesDict index 88f6aa4c..56fadd18 100644 --- a/tutorials/postprocessPhasicFlow/segregation/settings/particlesDict +++ b/tutorials/postprocessPhasicFlow/segregation/settings/particlesDict @@ -10,21 +10,20 @@ fileFormat ASCII; // positions particles positionParticles { - method positionOrdered; // ordered positioning + method ordered; - maxNumberOfParticles 30001; // maximum number of particles in the simulation - mortonSorting Yes; // perform initial sorting based on morton code? - - cylinder // cylinder region for positioning particles + regionType cylinder; + + cylinderInfo { p1 (0.0 0.0 0.003); // begin point of cylinder axis p2 (0.0 0.0 0.097); // end point of cylinder axis radius 0.117; // radius of cylinder } - positionOrderedInfo + orderedInfo { - distance 0.005; // minimum distance between particles centers + distance 0.005; // minimum space between centers of particles numPoints 30000; // number of particles in the simulation axisOrder (z x y); // axis order for filling the space with particles } @@ -35,8 +34,8 @@ setFields /* Default value for fields defined for particles These fields should always be defined for simulations with - spherical particles.*/ - + spherical particles. + */ defaultValue { velocity realx3 (0 0 0); // linear velocity (m/s) @@ -49,17 +48,17 @@ setFields { shapeAssigne { - selector selectRandom; // type of point selector - selectRandomInfo + selector randomPoints; // type of point selector + + randomPointsInfo { begin 0; // begin index of points - end 29999; // end index of points - number 10000; // number of points to be selected + end 29999; // end index of points + number 10000; } + fieldValue // fields that the selector is applied to { - /* - sets shapeName of the selected points to largeSphere*/ shapeName word largeSphere; } } diff --git a/tutorials/postprocessPhasicFlow/segregation/settings/postprocessDataDict b/tutorials/postprocessPhasicFlow/segregation/settings/postprocessDataDict new file mode 100644 index 00000000..b8786925 --- /dev/null +++ b/tutorials/postprocessPhasicFlow/segregation/settings/postprocessDataDict @@ -0,0 +1,82 @@ +/* -------------------------------*- C++ -*--------------------------------- *\ +| phasicFlow File | +| copyright: www.cemf.ir | +\* ------------------------------------------------------------------------- */ +objectName processDataDict; +objectType dictionary;; +fileFormat ASCII; +/*---------------------------------------------------------------------------*/ + +runTimeActive yes; + +shapeType sphere; + +components +( + on_rectMesh + { + processMethod GaussianDistribution; + processRegion rectMesh; + + timeControl settingsDict; + + rectMeshInfo + { + min (-0.12 -0.12 0.00); + max (0.12 0.12 0.1); + nx 36; + ny 36; + nz 15; + } + + operations + ( + avVelocity + { + function average; + + field velocity; + + fluctuation2 yes; + + threshold 4; + + phi mass; + } + + solidVolFraction + { + function sum; + + field volume; + + divideByVolume yes; + + threshold 4; + } + + smallSphereVolFraction + { + function average; + + field one; + + phi volume; + + divideByVolume no; + + threshold 4; + + includeMask lessThan; + + lessThanInfo + { + field diameter; + + value 0.0031; + } + } + ); + + } +); diff --git a/tutorials/postprocessPhasicFlow/segregation/settings/postprocessDict b/tutorials/postprocessPhasicFlow/segregation/settings/postprocessDict deleted file mode 100644 index d065122a..00000000 --- a/tutorials/postprocessPhasicFlow/segregation/settings/postprocessDict +++ /dev/null @@ -1,54 +0,0 @@ -/* -------------------------------*- C++ -*--------------------------------- *\ -| phasicFlow File | -| copyright: www.cemf.ir | -\* ------------------------------------------------------------------------- */ -objectName postprocessDict; -objectType dictionary;; -fileFormat ASCII; -/*---------------------------------------------------------------------------*/ - -rectMesh -{ - min (-0.12 -0.12 0.0); //minimum corner point - max (0.12 0.12 0.1); //maximum corner point - nx 24; // number of divisions in x direction - ny 24; // number of divisions in y direction - nz 10; // number of divisions in z direction -} - - -numberBased -{ - // num particles in a cell - numParticles - { - field real 1.0; // uniform field with value 1 - operation sum; // sum over all particles in a cell - includeMask all; // select all - } - - // concentration of small particles (number based) - smallConc - { - field real 1.0; // uniform field with value 1 - operation average; // average over all particles in a cell - threshold 1; // exclude cells with number of particles less than 1 - includeMask lessThan; // include mask - lessThanInfo - { - field diameter; // include particles with diameter less than 0.004 - value 0.004; - } - } - - // average velocity of particles - avVelocity - { - field velocity; // read velocity field from time folder - operation average; // average over all particles in the cell - threshold 3; // exclude cells with number of particles less than 3 - includeMask all; // select all - - } - -} diff --git a/tutorials/postprocessPhasicFlow/segregation/settings/settingsDict b/tutorials/postprocessPhasicFlow/segregation/settings/settingsDict index b5d3129b..de477a71 100644 --- a/tutorials/postprocessPhasicFlow/segregation/settings/settingsDict +++ b/tutorials/postprocessPhasicFlow/segregation/settings/settingsDict @@ -2,39 +2,37 @@ | phasicFlow File | | copyright: www.cemf.ir | \* ------------------------------------------------------------------------- */ -objectName settingsDict; -objectType dictionary;; +objectName settingsDict; +objectType dictionary; fileFormat ASCII; /*---------------------------------------------------------------------------*/ -run rotatingDrumSmall; +run rotatingDrumSmall; -dt 0.00001; // time step for integration (s) +libs ("libPostprocessData.so"); -startTime 0; // start time for simulation +auxFunctions postprocessData; -endTime 10; // end time for simulation +dt 0.00001; // time step for integration (s) -saveInterval 0.1; // time interval for saving the simulation +startTime 0; // start time for simulation -timePrecision 6; // maximum number of digits for time folder +endTime 10; // end time for simulation -g (0 -9.8 0); // gravity vector (m/s2) +saveInterval 0.1; // time interval for saving the simulation -/* - Simulation domain - every particles that goes outside this domain is deleted. -*/ -domain -{ - min (-0.12 -0.12 0); - max (0.12 0.12 0.1); -} +timePrecision 6; // maximum number of digits for time folder -integrationMethod AdamsBashforth2; // integration method +g (0 -9.8 0); // gravity vector (m/s2) -writeFormat ascii; +includeObjects (diameter); // save necessary (i.e., required) data on disk -timersReport Yes; // report timers? +integrationMethod AdamsBashforth2; // integration method -timersReportInterval 0.01; // time interval for reporting timers +integrationHistory off; + +writeFormat ascii; // data writting format (ascii or binary) + +timersReport Yes; // report timers (Yes or No) + +timersReportInterval 0.01; // time interval for reporting timers