create_particles command

Purpose

Command for creating single particles or particles on a pre-defined lattice.

Note

This command is supported by Aspherix GPU.

Syntax

create_particles keyword value

Keywords:

Keyword	Description
template	obligatory, ID of a particle_template
mode	obligatory, available options: `single position` position_vector or `on_lattice` region_id position_vector = coordinates of a single particle (units: [length]) region_id = particles will only be created if contained in the region
units	available options: `lattice` or `box` `lattice`: geometry is defined in lattice units default: `box`
velocity	vector with x-, y- and z-component of velocity default: (0,0,0); units: [length/time]
omega	vector with x-, y- and z-component of angular velocity default: (0,0,0); units: [1/time]
orientation	can be given by a quaternion or an axis / angle pair; either a quaternion (w, x, y, z) with the values for desired orientation or `axis` axis_vector `angle` angle_value, with axis_vector for rotation and angle in degrees default: (1,0,0,0)
save_template_information	`yes` or `no` default: `yes`

Examples

create_particles template pts mode on_lattice my_region_id
create_particles template pts mode single position (0,0,5) velocity (0,0,-1)
create_particles template pts mode on_lattice my_region_id omega (-1,0,0) orientation (1,0,0,0)
create_particles template pts mode on_lattice my_region_id orientation axis (1,0,0) angle 60

Description

This command creates a single particle as an alternative to reading in their coordinates explicitly via a read_data or read_restart command. A simulation box must already exist, which is typically created via the simulation_domain or the create_box command. In case of units = lattice or mode on_lattice, a lattice must also be defined using the define_lattice command.

The kind of particles is defined by the particle_template command and used here through its ID. Unless otherwise specified per-particle properties are initialized with their default settings.

For mode single position a single particle is added to the system at the specified coordinates. This can be useful for debugging purposes or to create a tiny system with a handful of particles at specified positions.

For mode on_lattice the geometric volume is filled that is inside the simulation box and is also consistent with the region volume. See the region command for details. To be able to use this command a lattice needs to be defined as the particles will be placed on this lattice inside the region. Note that a region can be specified so that its “volume” is either inside or outside a geometric boundary. Also note that if your region is the same size as a periodic simulation box (in some dimension), Aspherix® does not ensure exactly one particle at the boundary. If this is what you desire, you should tweak the region size to get precisely the particles you want.

The units keyword determines the meaning of the distance units used to specify the coordinates of the one particle created by mode single position. A box value selects standard distance units as defined by the units command, e.g. Angstroms for units = real or metal. A lattice value means the distance units are in lattice spacings.

The velocity keyword allows to set the initial velocity of the particle. Similarly, the omega keyword sets the initial angular velocity of the inserted particles.

The orientation keyword is used to set the particles orientation in space. Obviously, this keyword makes only sense for particle templates that track the particles orientation like superquadric. For everybody not familiar with quaternions, the particle orientation can also be defined by an axis and an angle (in degrees). Further it is possible to do several rotations consecutively.

The save_template_information is required when DEM-based drag models are applied. This will save the information from which template a specific particle was generated from.

Note that this command adds particles to those that already exist. By using the create_particles command multiple times, multiple sets of particles can be added to the simulation. For example, interleaving create_particles with lattice commands specifying different orientations, grain boundaries can be created. By using the create_particles command in conjunction with the delete_particles command, reasonably complex geometries can be created. The create_particles command can also be used to add particles to a system previously read in from a data or restart file. In all these cases care should be taken to ensure that new particles do not overlap existing particles inappropriately. The delete_particles command can be used to handle overlaps. If any newly created particle overlaps a primitive wall or a surface mesh at insertion (in such a case the particle will already experience a force during the first time step) a warning or error will be shown.

Particle IDs are assigned to created particles in the following way. The collection of created particles are assigned consecutive IDs that start immediately following the largest particle ID existing before the create_particles command was invoked. When a simulation is performed on different numbers of processors, there is no guarantee a particular created particle will be assigned the same ID.

The update_particle command can be used to override many of the default settings.

Restrictions

An particle_template must be previously defined to use this command. If the per-particle surfaceLiquidContent property was not found (a warning will be shown), the surfaceLiquidContentInitial will be used for initialization. This can be resolved by a dummy simulate time_steps 0 command just before the create_particles command.