calculate collision_statistics command
Purpose
This command calculates the collision statistics (both particle-particle as particle-wall) in the entire simulation domain or for a group of particles.
Syntax
calculate collision_statistics keyword values
With the following keyword argument pairs:
Keywords |
Description |
|---|---|
id |
user-assigned name for the command call
|
particle_group |
group of particles for which collision statistics are evaluated
(default: all)
|
region |
region in which collision statistics is evaluated
(default: simulation domain)
|
wall |
|
output_per_type |
output global statistics for per-type collisions.
valid values:
yes or no(default:
no) |
histogram_velocity |
normal or tangential or magnitude |
range |
vector with range for histogram binning (velocity units)
|
number_of_bins |
number of histogram bins (dimensionless integer)
|
collision_properties |
a list of the values to track upon collision.
Values are reported at the beginning of a collision. Supported propterties are:
|
write_every_time |
output interval (each processor will write its local data).
While all collisions are tracked, this setting defines how often the internal buffer
is written to file.
|
file |
filename to write the collision properties to (mutually exclusive with
append) |
append |
filename to append the collision properties to (mutually exclusive with
file) |
Examples
calculate collision_statistics id stats
calculate collision_statistics region bc output_per_type no histogram_velocity normal range (0.,5.) number_of_bins 5 id stats1
calculate collision_statistics region bc output_per_type yes collision_properties {time,pos,vn,ids} file my_collisions.txt id stats2
calculate collision_statistics wall zwalls id stats_primitive_wall file wall_stats.txt
calculate collision_statistics wall cad collision_properties {time,pos,angle, mass} id stats_surface_mesh
calculate collision_statistics wall cad histogram_velocity normal range (0.,5.) number_of_bins 5 id stats_surface_mesh_vn
calculate collision_statistics wall cad histogram_velocity tangential range (0.,10.) number_of_bins 5 id stats_surface_mesh_vt
Description
This command can calculate the particle-particle (p-p) or particle-wall (p-w) collision statistics since the simulation start. Depending on the settings, the calculated collision statistics can reflect the total number of p-p / p-w collisions, the total number of p-p / p-w collisions for each particle, the total number of contacts per particle type (p-p only), the total number of collisions per particle type for each particle (p-p only) and/or a (single) velocity histogram with p-p / p-w collision statistics.
If no wall is defined, the statistics will reflect p-p collisions only. If a wall is defined, the statistics will reflect p-w collisions only. In this context, the wall can either be a primitive wall or a surface mesh. It is not possible to calculate both p-p and p-w collision statistics with a single command.
The histogram with p-p / p-w collision statistics can be generated by using keyword histogram_velocity. Valid histogram types are normal, tangential, magnitude, which set the recorded relative particle velocity upon collision to the normal velocity, tangential velocity or velocity magnitude, respectively. The range is a vector containing the minimum and maximum velocity values of the histogram. The number_of_bins determines into how many bins the range is (uniformly) divided.
Warning
The output_per_type keyword can not be used for p-w collision statistics, and not for p-p collision statistics if the histogram_velocity keyword is used. For both cases it has to be turned off (or not set at all, as the default is ‘no’)
A p-p contact is defined for finite-size spherical particles as a neighboring particle overlaps the central particle, meaning that their distance of separation is less than or equal to the sum of the radii of the two particles. A p-w contact is defined as an overlap between a particle and a wall (or wall element in case of mesh walls). A value of 0.0 will be assigned for particles not in the specified particle_group.
Warning
This command will work as intended for all particle shapes, but will significantly overestimate the number of contacts for compound particles (multispheres, multiplespheres and concave) since the contacts themselves are counted per primary particle and not per compound.
Note that the total number of p-p contacts for each pair of particle types since the simulation start is symmetric, i.e. the number of i-j collisions is equal to the number of j-i collisions.
The region keyword can be used to only count contacts that happen in the specified region.
The keyword collision_properties can be used to buffer collision data for local (per processor) output. The list with properties can contain one (or more) of the following collision options:
Collision property |
Description |
Number of values |
time |
time of collision |
1 float |
step |
time step number of collision |
1 integer |
pos / position |
position of particle(s) |
6 (p1-p2), 3 (p-w) float |
v / vel / velocity |
velocity of particle(s) / wall |
6 (p1-p2, p-w) float |
vn / veln / normal_velocity |
normal velocity |
3 (p1-p2, p-w) float |
ids |
particle(s) / mesh element IDs |
2 (p1-p2, p-w) integer |
angle |
collision angle in radians |
1 float |
mass |
mass in kg |
2 (p1-p2), 1 (p-w) float |
type |
particle type |
2 (p1-p2), 1 (p-w) integer |
Note that the ID of primitive walls will be set to -1. These collision properties can be written to a (new) file via the file keywords (use append to append data to a file). If no collision_properties and file / append are defined, nothing will be computed / written, so only the total number of collisions will be available (see output info below). If only file / append is defined, all available collision properties (see the table above) will be written to the file. If the collision_properties are defined by the user, but file / append is not, the collision properties will be written to the default output file (this is by default set to “collision_statistics_CMDID”, where CMDID is the user-assigned name for the command). The output frequency of the buffer data to the file can be set via write_every_time, which by default is equal to the output frequency set via write_output_timestep.
Output info:
This command computes a global scalar, which corresponds to the total number of p-p / p-w collisions since the simulation start (accessible via id_CMDID). Furthermore, in case output_type yes is used, it also computes a global array, where the value for indices i-j corresponds to total number of p-p / p-w contacts between particle/wall of material type i and j since simulation start. These values can be accessed by any command that uses global scalars and array values from a command as input. See Section_howto 15 for an overview of Aspherix® output options.
The total number of contacts since simulation start for each particle is stored in a separate command as a part of a per-particle array, and can be accessed via id_collision_counter_CMDID[1] in several by output commands which take per-particle arrays as input, see Section_howto 8. CMDID here is the id of the command whose data should be accessed.
The total number of contacts since simulation start with each particle type for each particle is stored in a separate command as part of a per-particle array, and can be accessed via id_collision_counter_CMDID[1+itype] in several by output commands which take per-particle arrays as input, see Section_howto 8.
In case the histogram_velocity keyword is used, the total number of contacts for each bin since simulation start is stored in a separate per-particle array. This data can be accessed via id_collision_counter_histogram_CMDID_TYPE[ibin], where CMDID, TYPE and ibin are the user-assigned name for the command, the chosen histogram type (in abbreviated form: normal: vn, tangential: vt, magnitude: vmag) and the bin index, respectively. Access is possible by several output commands which take per-particle arrays as input, see Section_howto 15.
Restrictions
This command requires that particles store a radius as defined by the atom_style sphere command, and use a granular pair style with history, see pair gran.
As a command can have only one global array output, either the histogram or per-type global statistics can be output at a time.