particle_distribution command

Purpose

Command for creating a particle distributions from particle templates.

Note

This command is supported by Aspherix GPU.

Syntax

particle_distribution keyword value

Keywords:

Keyword

Description

id

user-assigned name for the command call

templates

list of particle_template IDs that form the distribution

fractions ¹
list of fractions belonging to the corresponding template ID
sum of all fractions should be 1, values are normalized otherwise

percentages ¹
list of percentages belonging to the corresponding template ID
sum of all percentages should be 100, values are normalized otherwise

normal_distribution ¹
normal_distribution requires some additional kewords:
standard_deviation ²: standard deviation, for sphere
particles only; units: [length]
standard_deviation_scale ²: scaled standard
deviation, for all particles shapes (=standard_deviation/particle_size, dimensionless)
cutoff: cutoff value for the normal distribution, divided by the standard deviation
number_of_bins: number of bins to create between -cutoff and +cutoff
default: cutoff 2; number_of_bins: 5;

mode
available options: massbased or numberbased
default: massbased

template_scales

list of scale factors belonging to the corresponding template ID

scale_axis

available options: x, y or z

seed

a positive integer used to seed the random number generator

¹ The keywords fractions, percentages and normal_distribution are mutually exclusive.

² The keywords standard_deviation or standard_deviation_scale are mutually exclusive, the usage of one of them is mandatory.

Examples

particle_distribution id pd1 seed 545387 templates {smallerParticles, biggerParticles} fractions {0.3, 0.7}
particle_distribution id pd1 seed 545387 mode numberbased templates {smallerParticles,biggerParticles} &
  percentages {70%,30%}
particle_distribution id pd1 seed 545387 templates {baseParticle, baseParticle} fractions {0.3, 0.7} &
  template_scales {0.2, 0.8}
particle_distribution id pd1 seed 545387 mode numberbased templates {convexParticle,convexParticle} &
  percentages {70%,30%} template_scales {0.3, 0.7} scale_axis y
particle_distribution id pd1 seed 545387 mode numberbased templates {meanSphericalParticle} &
  normal_distribution standard_deviation 0.0005 number_of_bins 7
particle_distribution id pd1 seed 545387 templates {meanGeneralParticle} &
  normal_distribution standard_deviation_scale 0.1 cutoff 2.8 number_of_bins 7

Description

This command defines a discrete particle distribution to be inserted by an insertion command. It takes as input one or more templates defined by the particle_template command, which sets the properties of the single particles that are part of the distribution. The IDs from the list in templates define the distribution together with the values from percentages or fractions or template_scales or normal_distribution.

Note that not all optional keywords can be used in a single command. Only one keyword from percentages, fractions and normal_distribution must be chosen. Furthermore, template_scales can only be combined with percentages and fractions. The number of percentages/fractions/template_scales in the list following the keyword must be equal to the number of templates IDs that have been specified. The values in percentages need to sum up to 100, while the values in fractions are normalized if they do not sum up to one. If normal_distribution is used, templates must contain exactly 1 template ID (which defines the mean particle size) and exactly one of standard_deviation or standard_deviation_scale must be specified as well. Note that standard_deviation can only be used for spherical particles, while standard_deviation_scale can be used for any particle shape. The difference is that standard_deviation has length units, while the standard_deviation_scale is dimensionless (it is equivalent to standard_deviation / particle_size).

The scale_axis can only be used if template_scales or normal_distribution is used. For the normal_distribution the particle sizes are scaled with the average value of the bin lower and upper limits. The fractions used for each bin are computed from the area under the normal distribution, and scaled with the sum of all these fractions. The fractions outside the cutoff range are neglected and not used in any way. The use of the mode keyword is not restricted, it can be combined with any other keyword. For mode massbased, the weight of each template within the distribution is interpreted as mass-%, for mode numberbased the weight is interpreted as number-%.

Note

Note that the inserted particle size depends on all scales specified. Any scale specified in the particle template will be multiplied (in all directions, or just the direction specified by scale_axis) by the provided template_scales or normal_distribution scale (determined from the standard_deviation or standard_deviation_scale).

Note

Note that large particles are inserted first, so that a higher volume fraction can be achieved. If not all desired insertions could be performed, it is likely that the distribution is not accurately reproduced.

The optional seed keyword can be used to define the seed value for the random number generator used internally. Valid values are positive integers. If seed is not set, a hardcoded value will be used.

Restart, fix_modify, output, run start/stop

Information about the random state in this command is written to binary restart files so you can restart a simulation with the same particles being chosen for insertion. None of the fix_modify options are relevant to this command. No global scalar or vector or per-atom quantities are stored by this command for access by various output commands. No parameter of this command can be used with the start/stop keywords of the run command.

Restrictions

none