369 lines
9.9 KiB
Markdown
369 lines
9.9 KiB
Markdown
# 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 |