readme.md for particlesPhasicFlow and change diameter to distance in dict files
This commit is contained in:
Hamidreza
parent
6cc4b3954a
commit
a545acb374
|
|
@ -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
|
||||
|
|
@ -64,7 +64,7 @@ public:
|
|||
return 0;
|
||||
}
|
||||
|
||||
real maxDiameter() const final
|
||||
real distance() const final
|
||||
{
|
||||
return 1.0;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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_
|
||||
(
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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_
|
||||
(
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue