compute coordination_number command

Purpose

coordination_number can be used to compute the coordination number between different particles (e.g. for mixing quality control)

Warning

GPU support for this command has not been tested and may not work as expected.

Syntax

compute ID group-ID coordination_number general_keyword general_values keywords values

ID, group-ID are documented in compute command
coordination_number = style name of this compute command
general_keywords general_values are documented in compute
zero or more keyword/value pairs must be appended to args
keyword = mode (mandatory) or distance_threshold or surface_distance or count_same_type or count_with

mode value = sphere_overlap or contact or distance or bonded
    sphere_overlap = interaction detection based on overlap of (bounding) sphere
    contact = interaction detected if particle pair exchanges forces
    distance = interaction detection based on minimum surface distance
    bonded = interaction detected if a bond exists between particles
distance_threshold value = delta (for mode = sphere_overlap or distance only)
    delta = interaction detected if distance between particles is less than delta
surface_distance value = yes or no (for mode = sphere_overlap only)
    yes = distance computed from (bounding) sphere surface
    no = distance computed from particle center
count_same_type value = yes or no
    yes = particle interaction counted between all particle types
    no = particle interaction only counted between particles of different types
count_with value = same_group or other_groups or all or group_list
    same_group = particle interaction only counted with particles in same group (default)
    other_groups = particle interaction only counted with particles not in same group
    all = particle interaction counted with all particles
    group_list {...} = particle interaction counted with particles in groups provided
         in bracketed list

Examples

compute coord all coordination_number mode sphere_overlap distance 1e-4 surface_distance yes
compute coord all coordination_number mode contact
compute coord all coordination_number mode distance count_same_type no
compute coord all coordination_number mode contact count_with other_groups
compute coord all coordination_number mode contact count_with group_list {myGroup1,myGroup2}

Description

Define a compute that calculates the coordination number for each particle.

The coordination number is defined as the number of neighbor particles that satisfy a certain interaction detection criterion. This compute implements three different types of such direction criterion which can be selected by specifying the model keyword. The table below summarizes the different modes.

mode	interaction detection condition	formula
sphere_overlap	(bounding) spheres are close to each other	$r - (r_i + r_j) < \delta$
contact	particles exchange forces	$f_{ij} > 0$
distance	minimum surface distance is less than threshold	$d_{ij} < \delta$
bonded	bond by a bond model exists between particles

where $r$ is the distance between the center of two particles, $r_i$ and $r_j$ are the radii of the (bounding) spheres of particles $i$ and $j$ , respectively. $f_{ij}$ is the force acting between two particles, $d_{ij}$ is the minimum distance between the surfaces of two particles. Finally, $\delta$ is the distance threshold which can be set by the user using the distance_threshold keyword and whose default is 0.

The sphere_overlap mode ignores the actual shape of a particle and only considers its bounding radius. For spherical particles this is identical to the distance mode as the particle shape and the bounding sphere are identical. This mode also allows to set the surface_distance keyword, which by default is yes. If it is set to no then the formula is altered to read $r < \delta$ , i.e. instead of considering the distance between the surfaces of the (bounding) spheres the distance between the particle centers is taken and compared to the distance_threshold.

The contact mode identifies interaction if a particle pair exchanges forces. In general this happens only if particles are in contact with each other but several contact models also result in forces across distances (e.g. bond or lubrication models) in this case also non-touching pairs will be counted.

The distance mode computes the minimum distance between the surfaces of two particles and this value is compared to the distance_threshold.

Warning

The distance mode only works for particles of shape sphere or superquadric.

The bonded mode checks if two particles are connected by a bond created by the gran cohesion bond model. No further contact or distance checks are performed in this mode, however the other keywords (count_same_type, count_with etc) still apply.

The keyword count_same_type allows to specify whether particle pairs are counted regardless of the particles types (yes) or whether only particle pairs of differing types (no) are counted. The latter can be useful to quantify the mixture of different species.

Interactions are only counted for the compute group, the coordination number is 0 for particles not in said group. The count_with keyword allows to specify the group(s) with which interactions are counted. The default setting is same_group, meaning that only interactions with particles in the compute group are counted. other_groups means that interactions are counted for particles that are not in the compute group. all counts interactions with all particles, and group_list allows the user to provide a list of groups IDs in round brackets to count interactions with.

Output info:

The compute calculates a per-particle vector which contains the number of detected interactions based on the specified compute settings. These values can be accessed by any command that uses per-particle values from a compute as input. See Section_howto 15 for an overview of Aspherix® output options. If this command is used, it will automatically be added to the particle properties of the output_settings command.

Restrictions

The mode distance only works for spheres and superquadric particles.