calculate particle_bond_network command

Purpose

This command calculates the properties of individual pairwise bonds between particles (examples).

Syntax

calculate particle_bond_network keyword/value pairs

Keywords	Description
id	user-assigned name for the command call
particle_group	ID of the group of particles on which the command is applied default: all
properties	list of properties that will be evaluated (options and defaults see below)
bond_type	type of bonds to output, available options: all or cohesive or solid default: all
final_update	Recomputes at the last step of a simulate command. available options: yes or no default: yes
interaction_with_group	ID of the group of particles that interact with the main group i.e. the one defined by particle_group default: all

Examples

calculate particle_bond_network
calculate particle_bond_network bond_type cohesive id cohBonds
calculate particle_bond_network properties {pos,vel,force,torque}
calculate particle_bond_network properties {vel,force,torque} bond_type solid
calculate particle_bond_network id net_1 particle_group all properties {ids, pos} interaction_with_group group_1

Description

This command calculates the properties of individual pairwise bonds between particles. The number of datums generated, aggregated across all processors, equals the number of particle-particle bonds in the system. The bond information is only saved if there exists a bond of the specified bond_type between a pair of particles.

If the optional keyword particle_group is used, the information about the interaction between is only saved if the both particles are in the specified group. If the optional keyword id is used, a custom ID is set for the command. The command can then be referenced by other commands. The optional keyword bond_type can be used to control which bond type should be included in the network. By default all bonds are included, but the user can use cohesive (like liquid bridges) and solid to include specific types only.

The command automatically saves the particle positions (6 values in distance units) for the particle-particle interactions.

The final_update keyword will force a recomputation of the value at the last integration step of a simulate command. This is useful if the value is required in the input script between two simulate commands, e.g. for setting a variable.

If the keyword interaction_with_group with associated value interaction_group_id is set, then the pairwise interaction will only be included if one particle is in the general compute group (set by particle_group) and the other is in the group with id interaction_group_id. Not setting this keyword will result in a default value of interaction_group_id equal to the general compute group.

Information on the properties

Keywords	Description
pos *	position of the two particles (6 values, unit: distance)
vel *	velocity of the particles (6 values, unit: distance/time)
ids *	IDs of the particles and a flag with periodicity information (3 values)
force *	contact force (3 values, unit: force)
force_normal	normal component of contact force (3 values, unit: force)
force_tangential	tangential component of contact force (3 values, unit: force)
torque *	torque between particles (3 values, unit: force*distance)
torque_normal	normal component of torque (3 values, unit: force*distance)
torque_tangential	tangential component of torque (3 values, unit: force*distance)
history *	contact history (# depends on pair style, e.g. 3 shear history values)
contactArea *	area of the contact (1 value, unit: distance*distance)
contactPoint	point at which contact forces between two particles are computed (3 values, pairwise interactions only, unit: distance)
delta	overlap of the contact (sum of radii - distance between particle centers, 1 value, units: distance)
heatFlux	conductive heat flux of the contact (only available if enable_heat_transfer is used, 1 value, unit: energy/time)
ms_id	multisphere IDs of clumps where of particles in contact belong to (in case of wall, second value will be -1) (2 values)
shearrate	shear rate (1 value)
heatConductionArea	heat conduction area of a contact (only available if enable_electrical_conductivity is used, 1 value)
electricCurrent	electric current of a contact (only available if enable_electrical_conductivity is used, 1 value)
electricConductance	electric conductance of a contact (only available if enable_electrical_conductivity is used, 1 value)

* The properties pos, vel, ids, force, torque, history and contactArea are the default output if no properties are selected.

The output force, force_normal, force_tangential and torque are the total contact force, the normal and tangential components of the contact force, and the torque. Note that the normal and tangential components are not necessarily exactly equal to the forces added by the normal and tangential model used , but are geometrically composed, using the connection line between the particle centers as normal direction. Note also that the torque does not contain any rolling friction torque by default. By switching the setting keyword the torsionTorque on in the respective rolling friction model, the full relative rotation contributes to the rolling friction torque.

The output contactArea will output the contact area, in distance-squared units. Note that contactArea is based on an analytic geometric calculation of sphere-sphere intersection rather than a calculation based on mechanics. This is to ensure that contactArea works with all types of contact models.

Output information

This command calculates a local vector or local array depending on the number of keywords. The length of the vector or number of rows in the array is the number of pairs. If a single keyword is specified, a local vector is produced. If two or more keywords are specified, a local array is produced where the number of columns is equal to the number of keywords. The vector or array can be accessed by any command that uses local values from a command as input.

The data can be written to file via the output_settings command, e.g. as shown in the example below

calculate particle_bond_network id net_1 particle_group all properties {ids, pos} interaction_with_group group_1
output_settings write_particle_bond_network yes particle_network_command_ids net_1

Further information

This command is a wrapper for the compute pair/gran/local/bond command.

Warning

The data associated to the different keywords is output in the following order: pos, vel, ids, force, force_normal, force_tangential, torque, history, contactArea, heatFlux, contactPoint. This is independent of the order in which the keywords are specified.

Note that as particles migrate from processor to processor, there will be no consistent ordering of the entries within the local vector or array from one timestep to the next. The only consistency that is guaranteed is that the ordering on a particular time-step will be the same for local vectors or arrays generated by other compute commands.

Warning

This command will, when invoked, issue a call to the pair contact models to calculate what would be the contact forces given the current positions, velocities, etc.

Since this command is typically done when output is created (at the end of the time-step), this is not necessarily exactly equal to (with machine precision) the particle-particle forces which were calculated within one time-step.

Related commands

calculate, enable_heat_transfer, output_settings, calculate wall_bond_network, calculate particle_contact_network, calculate wall_contact_network