readme.md for particlesPhasicFlow and change diameter to distance in dict files

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        <method>;        // Options: ordered, random, file, empty
+    
+    regionType    <region>;        // Options: box, cylinder, sphere, domain
+    
+    // Method-specific settings
+    <method>Info
+    {
+        // Parameters for the selected method
+    }
+    
+    // Region-specific settings
+    <region>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    <value>;        // Minimum space between centers of particles
+       numPoints   <value>;        // Number of particles to position
+       axisOrder   (<axis1> <axis2> <axis3>);  // Order of axes for filling (x, y, z)
+   }
+   ```
+
+2. **random**: Positions particles randomly in the specified region
+
+   ```C++
+   randomInfo
+   {
+       distance       <value>;     // Minimum distance between particle centers
+       numPoints      <value>;     // Number of particles to position
+       maxIterations  <value>;     // Maximum iterations for random positioning (default: 10)
+   }
+   ```
+
+3. **file**: Reads particle positions from a file
+
+   ```C++
+   fileInfo
+   {
+       fileName       <path>;      // 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 (<x> <y> <z>);          // Lower corner point coordinates
+       max (<x> <y> <z>);          // Upper corner point coordinates
+   }
+   ```
+
+2. **cylinder**: Cylindrical region
+
+   ```C++
+   cylinderInfo
+   {
+       p1     (<x> <y> <z>);       // Begin point of cylinder axis
+       p2     (<x> <y> <z>);       // End point of cylinder axis
+       radius <value>;             // Radius of cylinder
+   }
+   ```
+
+3. **sphere**: Spherical region
+
+   ```C++
+   sphereInfo
+   {
+       center (<x> <y> <z>);       // Center of sphere
+       radius <value>;             // 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 (<x> <y> <z>);    // Initial linear velocity (m/s)
+        acceleration  realx3 (<x> <y> <z>);    // Initial linear acceleration (m/s²)
+        rVelocity     realx3 (<x> <y> <z>);    // Initial rotational velocity (rad/s)
+        shapeName     word   <shape>;          // Particle shape name
+        // Additional fields as required
+    }
+    
+    selectors
+    {
+        <selectorName>
+        {
+            selector <selectorType>;           // Type of selector
+            
+            <selectorType>Info
+            {
+                // Parameters specific to the selector type
+            }
+            
+            fieldValue
+            {
+                // Field values to set for selected particles
+                <fieldName> <fieldType> <value>;
+                // Additional fields as required
+            }
+        }
+        // Additional selectors as required
+    }
+}
+```
+
+#### 3.2.1. Selector Types
+
+1. **stridedRange**: Selects particles based on index ranges
+
+   ```C++
+   stridedRangeInfo
+   {
+       begin  <value>;             // Beginning index
+       end    <value>;             // Ending index
+       stride <value>;             // Step size (default: 1)
+   }
+   ```
+
+2. **box**: Selects particles within a box region
+
+   ```C++
+   boxInfo
+   {
+       min (<x> <y> <z>);          // Lower corner point coordinates
+       max (<x> <y> <z>);          // Upper corner point coordinates
+   }
+   ```
+
+3. **cylinder**: Selects particles within a cylindrical region
+
+   ```C++
+   cylinderInfo
+   {
+       p1     (<x> <y> <z>);       // Begin point of cylinder axis
+       p2     (<x> <y> <z>);       // End point of cylinder axis
+       radius <value>;             // Radius of cylinder
+   }
+   ```
+
+4. **sphere**: Selects particles within a spherical region
+
+   ```C++
+   sphereInfo
+   {
+       center (<x> <y> <z>);       // Center of sphere
+       radius <value>;             // Radius of sphere
+   }
+   ```
+
+5. **randomPoints**: Selects a random subset of particles
+
+   ```C++
+   randomPointsInfo
+   {
+       begin   <value>;      // Beginning index
+       end     <value>;      // Ending index
+       number  <value>;      // 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

utilities/particlesPhasicFlow/empty/empty.hpp

@@ -64,7 +64,7 @@ public:
 		return 0;
 	}
 
-	real maxDiameter() const final
+	real distance() const final
 	{
 		return 1.0;
 	}

utilities/particlesPhasicFlow/positionFile/positionFile.hpp

@@ -74,9 +74,9 @@ public:
 		return static_cast<uint32>(position_.size());
 	}
 
-	real maxDiameter() const final
+	real distance() const final
 	{
-		return 0;
+		return 1.0;
 	}
 
 	// bool commaSeparated()const

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<real>("diameter")
+		poDict_.getVal<real>("distance")
 	),
 	numPoints_
 	(

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<uint32>(position_.size());
 	}
 
-	real maxDiameter() const final
+	/// Minimum distance between centers of particles
+	real distance() const final
 	{
-		return diameter_;
+		return distance_;
 	}
 	
 	// - const access to position

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;

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<real>("diameter")
+		prDict_.getVal<real>("distance")
 	),
 	numPoints_
 	(

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