From a545acb3741c9bd360db8e329b683df3e6c6d791 Mon Sep 17 00:00:00 2001 From: Hamidreza Date: Fri, 25 Apr 2025 11:36:46 +0330 Subject: [PATCH] readme.md for particlesPhasicFlow and change diameter to distance in dict files --- utilities/particlesPhasicFlow/README.md | 369 ++++++++++++++++++ utilities/particlesPhasicFlow/empty/empty.hpp | 2 +- .../positionFile/positionFile.hpp | 4 +- .../positionOrdered/positionOrdered.cpp | 6 +- .../positionOrdered/positionOrdered.hpp | 8 +- .../positionParticles/positionParticles.hpp | 3 +- .../positionRandom/positionRandom.cpp | 10 +- .../positionRandom/positionRandom.hpp | 22 +- 8 files changed, 399 insertions(+), 25 deletions(-) create mode 100644 utilities/particlesPhasicFlow/README.md diff --git a/utilities/particlesPhasicFlow/README.md b/utilities/particlesPhasicFlow/README.md new file mode 100644 index 00000000..439377bc --- /dev/null +++ b/utilities/particlesPhasicFlow/README.md @@ -0,0 +1,369 @@ +# particlesPhasicFlow Utility + +## 1. Overview + +`particlesPhasicFlow` is a pre-processing utility for Discrete Element Method (DEM) simulations in phasicFlow. It is used to: + +1. Position particles in the simulation domain using different methods +2. Set initial field values (such as velocity, acceleration, shape) for particles +3. Apply field values to selected subsets of particles + +The utility reads its configuration from `settings/particlesDict` in your simulation case directory. + +## Table of Contents + +- [1. Overview](#1-overview) +- [2. Command Line Options](#2-command-line-options) +- [3. The particlesDict File Structure](#3-the-particlesdict-file-structure) + - [3.1. positionParticles Sub-dictionary](#31-positionparticles-sub-dictionary) + - [3.1.1. Positioning Methods](#311-positioning-methods) + - [3.1.2. Region Types](#312-region-types) + - [3.2. setFields Dictionary](#32-setfields-dictionary) + - [3.2.1. Selector Types](#321-selector-types) +- [4. Usage Examples](#4-usage-examples) + - [4.1. Example 1: Positioning Particles in an Ordered Pattern](#41-example-1-positioning-particles-in-an-ordered-pattern) + - [4.2. Example 2: Setting Field Values for a Binary Mixture of Particles](#42-example-2-setting-field-values-for-a-binary-mixture-of-particles) + - [4.3. Example 3: Empty Initial Particle System (for Insertion Later)](#43-example-3-empty-initial-particle-system-for-insertion-later) +- [5. Workflow Tips](#5-workflow-tips) +- [6. Common Field Types](#6-common-field-types) +- [7. Shape Handling](#7-shape-handling) +- [8. See Also](#8-see-also) + +## 2. Command Line Options + +The utility can be run with the following command line options: + +``` +particlesPhasicFlow [OPTIONS] +``` + +Where `[OPTIONS]` can include: + +- `--positionParticles-only`: Execute only the positioning part and store the created pointStructure. +- `--setFields-only`: Execute only the field setting part, reading an existing pointStructure file from the time folder. +- `-c, --coupling`: Specify if this is a fluid-particle coupling simulation. + +## 3. The particlesDict File Structure + +The `particlesDict` file consists of two main sections: + +1. `positionParticles`: Defines how particles are positioned in the domain. +2. `setFields`: Defines initial field values for particles and selective field assignments. + +### 3.1. positionParticles Sub-dictionary + +This section defines how particles are positioned in the simulation domain: + +```C++ +positionParticles +{ + method ; // Options: ordered, random, file, empty + + regionType ; // Options: box, cylinder, sphere, domain + + // Method-specific settings + Info + { + // Parameters for the selected method + } + + // Region-specific settings + Info + { + // Parameters for the selected region + } +} +``` + +#### 3.1.1. Positioning Methods + +1. **ordered**: Positions particles in an ordered pattern along specified axes + + ```C++ + orderedInfo + { + distance ; // Minimum space between centers of particles + numPoints ; // Number of particles to position + axisOrder ( ); // Order of axes for filling (x, y, z) + } + ``` + +2. **random**: Positions particles randomly in the specified region + + ```C++ + randomInfo + { + distance ; // Minimum distance between particle centers + numPoints ; // Number of particles to position + maxIterations ; // Maximum iterations for random positioning (default: 10) + } + ``` + +3. **file**: Reads particle positions from a file + + ```C++ + fileInfo + { + fileName ; // Path to file containing positions + commaSeparated Yes/No; // Whether file is comma-separated + } + ``` + +4. **empty**: Creates an empty pointStructure with no particles. No additional sub-dictionary is required. + +#### 3.1.2. Region Types + +1. **box**: Rectangular region + + ```C++ + boxInfo + { + min ( ); // Lower corner point coordinates + max ( ); // Upper corner point coordinates + } + ``` + +2. **cylinder**: Cylindrical region + + ```C++ + cylinderInfo + { + p1 ( ); // Begin point of cylinder axis + p2 ( ); // End point of cylinder axis + radius ; // Radius of cylinder + } + ``` + +3. **sphere**: Spherical region + + ```C++ + sphereInfo + { + center ( ); // Center of sphere + radius ; // Radius of sphere + } + ``` + +4. **domain**: Uses the global domain defined in the simulation (in file `settings/domainDict`) + + ```C++ + // No additional information needed when using domain + ``` + +### 3.2. setFields Dictionary + +This section defines the initial field values for particles and allows selective field assignments: + +```C++ +setFields +{ + defaultValue + { + // Default field values for all particles + velocity realx3 ( ); // Initial linear velocity (m/s) + acceleration realx3 ( ); // Initial linear acceleration (m/s²) + rVelocity realx3 ( ); // Initial rotational velocity (rad/s) + shapeName word ; // Particle shape name + // Additional fields as required + } + + selectors + { + + { + selector ; // Type of selector + + Info + { + // Parameters specific to the selector type + } + + fieldValue + { + // Field values to set for selected particles + ; + // Additional fields as required + } + } + // Additional selectors as required + } +} +``` + +#### 3.2.1. Selector Types + +1. **stridedRange**: Selects particles based on index ranges + + ```C++ + stridedRangeInfo + { + begin ; // Beginning index + end ; // Ending index + stride ; // Step size (default: 1) + } + ``` + +2. **box**: Selects particles within a box region + + ```C++ + boxInfo + { + min ( ); // Lower corner point coordinates + max ( ); // Upper corner point coordinates + } + ``` + +3. **cylinder**: Selects particles within a cylindrical region + + ```C++ + cylinderInfo + { + p1 ( ); // Begin point of cylinder axis + p2 ( ); // End point of cylinder axis + radius ; // Radius of cylinder + } + ``` + +4. **sphere**: Selects particles within a spherical region + + ```C++ + sphereInfo + { + center ( ); // Center of sphere + radius ; // Radius of sphere + } + ``` + +5. **randomPoints**: Selects a random subset of particles + + ```C++ + randomPointsInfo + { + begin ; // Beginning index + end ; // Ending index + number ; // Number of random points to select + } + ``` + +## 4. Usage Examples + +### 4.1. Example 1: Positioning Particles in an Ordered Pattern + +```C++ +positionParticles +{ + method ordered; + mortonSorting Yes; + + orderedInfo + { + distance 0.005; + numPoints 30000; + axisOrder (z x y); + } + + regionType cylinder; + + cylinderInfo + { + p1 (0.0 0.0 0.003); + p2 (0.0 0.0 0.097); + radius 0.117; + } +} +``` + +### 4.2. Example 2: Setting Field Values for a Binary Mixture of Particles + +```C++ +setFields +{ + defaultValue + { + velocity realx3 (0 0 0); + acceleration realx3 (0 0 0); + rVelocity realx3 (0 0 0); + shapeName word smallSphere; + } + + selectors + { + shapeAssigne + { + selector stridedRange; + + stridedRangeInfo + { + begin 0; + end 30000; + stride 3; + } + + fieldValue + { + shapeName word largeSphere; + } + } + } +} +``` + +### 4.3. Example 3: Empty Initial Particle System (for Insertion Later) + +```C++ +positionParticles +{ + method empty; +} +``` + +## 5. Workflow Tips + +1. To create particles at the beginning of a simulation: + + ``` + particlesPhasicFlow + ``` + +2. To only position particles without setting fields: + + ``` + particlesPhasicFlow --positionParticles-only + ``` + +3. To modify fields on existing particles (e.g., at a later time step): + + ``` + particlesPhasicFlow --setFields-only + ``` + +4. For fluid-particle coupling simulations: + + ``` + particlesPhasicFlow -c + ``` + +5. To change particle properties at a later time step in a simulation: + - Change `startTime` in the settings dictionary to the desired time + - Run `particlesPhasicFlow --setFields-only` + - Restart the simulation from that time step + +## 6. Common Field Types + +- `realx3`: 3D vector of real values, e.g., `(0 0 0)` +- `real`: Single real value +- `word`: Text string +- `uint32`: Unsigned 32-bit integer + +## 7. Shape Handling + +When using the `shapeName` field, ensure that the shapes are defined in the `shape` file in the `caseSetup` directory. The utility will automatically convert shape names to shape indices and hashes for the simulation. + +For any further assistance, please refer to the tutorial examples in the phasicFlow distribution. + +## 8. See Also + +- [Tutorials](../../tutorials) - Example cases demonstrating phasicFlow capabilities and more about particlesPhasicFlow +- [geometryPhasicFlow](../geometryPhasicFlow) - Utility for geometry creation and manipulation in phasicFlow +- [pFlowToVTK](../pFlowToVTK) - Utility for converting phasicFlow data to VTK format for visualization +- [postprocessPhasicFlow](../postprocessPhasicFlow) - Utility for post-processing simulation results \ No newline at end of file diff --git a/utilities/particlesPhasicFlow/empty/empty.hpp b/utilities/particlesPhasicFlow/empty/empty.hpp index 9b296893..4b8bdeac 100755 --- a/utilities/particlesPhasicFlow/empty/empty.hpp +++ b/utilities/particlesPhasicFlow/empty/empty.hpp @@ -64,7 +64,7 @@ public: return 0; } - real maxDiameter() const final + real distance() const final { return 1.0; } diff --git a/utilities/particlesPhasicFlow/positionFile/positionFile.hpp b/utilities/particlesPhasicFlow/positionFile/positionFile.hpp index e2df0841..aa46a456 100755 --- a/utilities/particlesPhasicFlow/positionFile/positionFile.hpp +++ b/utilities/particlesPhasicFlow/positionFile/positionFile.hpp @@ -74,9 +74,9 @@ public: return static_cast(position_.size()); } - real maxDiameter() const final + real distance() const final { - return 0; + return 1.0; } // bool commaSeparated()const diff --git a/utilities/particlesPhasicFlow/positionOrdered/positionOrdered.cpp b/utilities/particlesPhasicFlow/positionOrdered/positionOrdered.cpp index eb1c94d4..b655a8c5 100755 --- a/utilities/particlesPhasicFlow/positionOrdered/positionOrdered.cpp +++ b/utilities/particlesPhasicFlow/positionOrdered/positionOrdered.cpp @@ -79,7 +79,7 @@ bool pFlow::positionOrdered::positionPointsOrdered() { position_.clear(); - realx3 dl(diameter_); + realx3 dl(distance_); const auto& region = pRegion(); auto minP = region.minPoint(); auto maxP = region.maxPoint(); @@ -131,9 +131,9 @@ pFlow::positionOrdered::positionOrdered ( dict.subDict("orderedInfo") ), - diameter_ + distance_ ( - poDict_.getVal("diameter") + poDict_.getVal("distance") ), numPoints_ ( diff --git a/utilities/particlesPhasicFlow/positionOrdered/positionOrdered.hpp b/utilities/particlesPhasicFlow/positionOrdered/positionOrdered.hpp index caf711dd..744554c8 100755 --- a/utilities/particlesPhasicFlow/positionOrdered/positionOrdered.hpp +++ b/utilities/particlesPhasicFlow/positionOrdered/positionOrdered.hpp @@ -35,7 +35,8 @@ private: dictionary poDict_; - real diameter_; + /// Minimum distance between centers of particles + real distance_; uint32 numPoints_; @@ -86,9 +87,10 @@ public: return static_cast(position_.size()); } - real maxDiameter() const final + /// Minimum distance between centers of particles + real distance() const final { - return diameter_; + return distance_; } // - const access to position diff --git a/utilities/particlesPhasicFlow/positionParticles/positionParticles.hpp b/utilities/particlesPhasicFlow/positionParticles/positionParticles.hpp index 749ba7c3..e62ef575 100755 --- a/utilities/particlesPhasicFlow/positionParticles/positionParticles.hpp +++ b/utilities/particlesPhasicFlow/positionParticles/positionParticles.hpp @@ -83,7 +83,8 @@ public: virtual uint32 size()const = 0; - virtual real maxDiameter() const = 0; + /// Minimum distance between centers of particles + virtual real distance() const = 0; // - const access to position virtual const realx3Vector& position()const = 0; diff --git a/utilities/particlesPhasicFlow/positionRandom/positionRandom.cpp b/utilities/particlesPhasicFlow/positionRandom/positionRandom.cpp index d67f9df4..9717cf66 100755 --- a/utilities/particlesPhasicFlow/positionRandom/positionRandom.cpp +++ b/utilities/particlesPhasicFlow/positionRandom/positionRandom.cpp @@ -35,10 +35,10 @@ bool pFlow::positionRandom::positionOnePass(collisionCheck& collCheck) { realx3 p = region.peek(); - if( collCheck.checkPoint(p, diameter_) ) + if( collCheck.checkPoint(p, distance_) ) { position_.push_back(p); - diameters_.push_back(diameter_); + diameters_.push_back(distance_); if(!collCheck.mapLastAddedParticle()) { @@ -64,7 +64,7 @@ bool pFlow::positionRandom::positionPointsRandom() uint32 pass = 0; collisionCheck collCheck( box(pRegion().minPoint(), pRegion().maxPoint()), - diameter_, + distance_, position_, diameters_); @@ -107,9 +107,9 @@ pFlow::positionRandom::positionRandom ( dict.subDict("randomInfo") ), - diameter_ + distance_ ( - prDict_.getVal("diameter") + prDict_.getVal("distance") ), numPoints_ ( diff --git a/utilities/particlesPhasicFlow/positionRandom/positionRandom.hpp b/utilities/particlesPhasicFlow/positionRandom/positionRandom.hpp index 6faa81d9..e676c476 100755 --- a/utilities/particlesPhasicFlow/positionRandom/positionRandom.hpp +++ b/utilities/particlesPhasicFlow/positionRandom/positionRandom.hpp @@ -32,23 +32,25 @@ class positionRandom : public positionParticles { private: - dictionary prDict_; + dictionary prDict_; - real diameter_; + real distance_; - uint32 numPoints_; + uint32 numPoints_; - uint32 maxIterations_; + uint32 maxIterations_; + + uint32 reportInterval_ = 100; realx3Vector position_; + // still keeping this variable name as diameters_ since it stores + // the collection of distance values realVector diameters_; - uint32 reportInterval_; + bool positionOnePass(collisionCheck& collCheck); - bool positionOnePass(collisionCheck& collCheck); - - bool positionPointsRandom(); + bool positionPointsRandom(); public: @@ -79,9 +81,9 @@ public: return position_.size(); } - real maxDiameter() const override + real distance() const override { - return diameter_; + return distance_; } // - const access to position