SPARTA WWW Site - SPARTA Documentation - SPARTA Commands

create_particles command

Syntax:

create_particles mix-ID style args keyword value ... 

Examples:

create_particles background n 0
create_particles air n 100000 region sphere
create_particles air n 100000 global yes
create_particles air single 3 5.0 6.0 5.4 10.0 -1.0 0.0
create_particles air n 0 species mySpecies xpos NULL zpos
create_particles air n 0 density myDens xgrid ygrid NULL
create_particles air n 0 temperature myTemp xgrid ygrid zgrid
create_particles air n 0 velocity myVx NULL myVz xpos ypos NULL 

Description:

Create particles and add them to the simulation domain. The attributes of individual particles, such as species and velocity, are determined by the mixture attributes, as specied by the mix-ID. In particular the temp, trot, tvib, and vstream attributes of the mixture affect create particle velocities and internal energy modes. See the mixture command for more details. Note that this command can be used multiple times to add more and more particles.

Particles are only created in grid cells which are entirely external to surfaces. Particles are not created in grid cells cut by surfaces.

IMPORTANT NOTE: When a particle is created at a specified temperature (as set by the mixture command), it's rotational and vibrational energy will also be initialized, consistent with the mixture temperatures. The rotate and vibrate options of the collide_modify command determine how internal energy modes are initialized. If the collide command has not yet been specified, then no rotational or vibrational energy will be assigned to created particles. Thus if you wish to create particles with non-zero internal energy, the collide and (optionally) collide_modify commands must be used before this command.

If the n style is used with Np = 0, then the number of created particles is calculated by SPARTA as a function of the global fnum value, the mixture number density, and the flow volume of the simulation domain.

The fnum value is set by the global fnum command. The mixture nrho is set by the mixture command. The flow volume of the simulation is the total volume of the simulation domain as specified by the create_box command, minus any volume that is interior to surfaces defined by the read_surf command. Note that the flow volume includes volume contributions from grid cells cut by surfaces. However particles are only created in grid cells entirely external to surfaces. This means that particles may be created in external cells at a (slightly) higher density to compensate for no particles being created in cut cells that still contribute to the overall flow volume.

If the n style is used with a non-zero Np, then exactly Np particles are created, which can be useful for debugging or benchmarking purposes.

Based on the value of Np, each grid cell will have a target number of particles M to insert, which is a function of the cell's volume as compared to the total system flow volume. If M has a fractional value, e.g. 12.5, then 12 particles will be inserted, and a 13th depending on the outcome of a random number generation. As grid cells are looped over, the remainder fraction is accumulated, so that exactly Np particles are created across all the processors.

IMPORTANT NOTE: The preceeding calculation is actually done using weighted cell volumes. Grid cells can be weighted using the global weight command.

Each particle is inserted at a random location within the grid cell. The particle species is chosen randomly in accord with the frac settings of the collection of species in the mixture, as set by the mixture command. The velocity of the particle is set to the sum of the streaming velocity of the mixture and a thermal velocity sampled from the thermal temperature of the mixture. Both the streaming velocity and thermal temperature are also set by the mixture command. The internal rotational and vibrational energies of the particle are also set based on the trot and tvib settings for the mixture, as explained above.

The single style creates a single particle. This can be useful for debugging purposes, e.g. to advect a single particle towards a surface. A single particle of the specified species is inserted at the specified position and with the specified velocity. In this case the mix-ID is ignored.


This is the meaning of the other allowed keywords.

The global keyword only applies when the n style is used, and controls how particles are generated in parallel.

If the value is yes, then every processor loops over all Np particles. As the coordinates of each is generated, each processor checks what grid cell it is in, and only stores the particle if it owns that grid cell. Thus an identical set of particles are created, no matter how many processors are running the simulation

IMPORTANT NOTE: The global yes option is not yet implemented.

If the value is no, then each of the P processors generates a N/P subset of particles, using its own random number generation. It only adds particles to grid cells that it owns, as described above. This is a faster way to generate a large number of particles, but means that the individual attributes of particles will depend on the number of processors and the mapping of grid cells to procesors. The overall set of created particles should have the same statistical properties as with the yes setting.

If the region keyword is used, then a particle will only added if its position is within the specified region-ID. This can be used to only allow particle insertion within a subset of the simulation domain. Note that the side option for the region command can be used to define whether the inside or outside of the geometric region is considered to be "in" the region.

IMPORTANT NOTE: If the region and n keywords are used together, less than N particles may be added. This is because grid cells will be candidates for particle insertion, unless they are entirely outside the bounding box that encloses the region. Particles those grid cells attempt to add are included in the count for N, even if some or all of the particle insertions are rejected due to not being inside the region.

The species keyword can be used to create particles with a spatially-dependent separation of species. The specified svar is the name of an equal-style variable whose formula should evaluate to a species number, i.e. an integer from 1 to Nsp, where Nsp is the number of species in the mixture with mix-ID. Since equal-style variables evaluate to floating-point values, this value is truncated to an integer value. The formula for the species variable can use one or two or three variables which will store the x, y, or z coordinates of the particle that is being created. If used, these variables must be internal-style variables defined in the input script; their initial numeric values can be anything. They must be internal-style variables, because this command resets their values directly. Their names are specified as xvar, yvar, and zvar. If any of them is not used in the svar formula, it can be specified as NULL.

When a particle is added, its coordinates are stored in the xvar, yvar, zvar variables if they are specified. The svar variable is then evaluated. The returned value is used to set the species of that particle, based on the list of species defined for the mixture. If the returned value is <= 0 or greater than Nsp = the number of species in the mixture, then no particle is created.

As an example, these commands can be used in a 2d simulation, to create a particle distribution with species 1 on top of species 2 with a sinudoidal interface between the two species, as illustrated in the snapshot of the initial particle distribution. Click on the image for a larger version. Note that when using this option less than the requested N particles can be created if the species variable returns values <= 0 or greater than Nsp = the number of species in the mixture.

variable x internal 0
variable y internal 0
variable n equal 3
variable s equal "(v_y < 0.5*(ylo+yhi) + 0.15*yhi*sin(2*PI*v_n*v_x/xhi)) + 1"
create_particles species n 10000 species s x y NULL 

The density keyword can be used to create particles with a spatially-dependent density variation. The specified dvar is the name of an equal-style variable whose formula should evaluate to a positive value. The formula for dvar can use one or two or three variables which will store the x, y, or z coordinates of the geometric center point of a grid cell. If used, these other variables must be internal-style variables defined in the input script; their initial numeric values can by anything. Their names are specified as xvar, yvar, and zvar. If any of them is not used in the dvar formula, it can be specified as NULL.

When particles are added to a grid cell, its center point coordinates are stored in xvar, yvar, zvar if they are defined. The dvar variable is then evaluated. The returned value is used as a scale factor on the number of particles to create in that grid cell. Thus a value of 0.5 would create half as many particles in that grid cell as would otherwise be the case, due to the global fnum and mixture nrho settings that define the density, as explained above. A value of 1.2 would create 20% more particles in that grid cell.

As an example, these commands can be used in a 2d simulation, to create more particles towards the upper right corner of the domain and less towards the lower left corner, as illustrated in the snapshot of the initial particle distribution. Click on the image for a larger version. Note that less than requested N particles will be created in this case because all the scale factors generated by the variable d are less than 1.0.

variable x internal 0
variable y internal 0
variable d equal "v_x/xhi * v_y/yhi"
create_particles air n 10000 density d x y NULL 

The temperature keyword can be used to create particles with a spatially-dependent thermal temperature variation. The specified tvar is the name of an equal-style variable whose formula should evaluate to a positive value. The formula for the tvar variable can use one or two or three variables which will store the x, y, or z coordinates of the geometric center point of a grid cell. If used, these other variables must be internal-style variables defined in the input script; their initial numeric values can by anything. Their names are specified as xvar, yvar, and zvar. If any of them is not used in the tvar formula, it can be specified as NULL.

When particles are added to a grid cell, its center point coordinates are stored in xvar, yvar, zvar if they are defined. The tvar variable is then evaluated. The returned value is used as a scale factor on the thermal temperature number for particles created in that grid cell. Thus a value of 0.5 would create particles with a thermal temperature half of what would otherwise be the case, due to the mixture temp setting which defines the thermal temperature, as explained above. A value of 1.2 would create particles with a 20% higher thermal temperature.

As an example, these commands can be used in a 2d simulation, to create a thermal temperature gradient in x, where the temperature on the left side of the box is the default value, and the temperature on the right side is 3x larger.

variable x internal 0
variable t equal "1.0 + 2.0*(v_x-xlo)/(xhi-xlo)"
create_particles air n 10000 temperature t x NULL NULL 

The velocity keyword can be used to create particles with a spatially-dependent streaming velocity. The specified vxvar, vyvar, vzvar are the names of equal-style variables whose formulas should evaluate to the corresponding component of the streaming velocity. If any of them are specified as NULL, then that streaming velocity component is set by the corresponding global or mixture streaming velocity component, the same as if the velocity keyword were not used.

The formulas for the vxvar, vyvar, vzvar variables can use one or two or three variables which will store the x, y, or z coordinates of the particle that is being created. If used, these other variables must be internal-style variables defined in the input script; their initial numerica values can by anything. Their names are specified as xvar, yvar, and zvar. If any of them is not used in the vxvar, vyvar, vzvar formulas, it can be specified as NULL.

When a particle is added, its coordinates are stored in xvar, yvar, zvar if they are defined. The vxvar, vyvar, vzvar variables are then evaluated. The returned values are used to set the streaming velocity of that particle. A thermal velocity is also added to the particle, using the the global or mixture temperature, as described above.

As an example, these commands can be used in a 2d simulation, to give particles an initial velocity pointing towards the upper right corner of the domain with a magnitude that makes them all reach that point at the same time (assuming their thermal velocity is small and it is not a collisional flow). Click on the image to play an animation of the effect.

variable x internal 0
variable y internal 0
variable vx equal (xhi-v_x)/(1000*7.0e-9)  # timesteps and timestep-size
variable vy equal (yhi-v_y)/(1000*7.0e-9)
create_particles air n 10000 velocity vx vy NULL x y NULL 

Restrictions: none

Related commands:

mixture, fix emit/face

Default:

The option default is global = no.