PARTICLE_SEED

Specifies the initial conditions for a set of particles.

Type

AcuTrace Command

Syntax

PARTICLE_SEED ("name") {parameters...}

Qualifier

User-given name.

Parameters

marker (integer) [=0]
A marker value assigned to all particles in this set.
seed_ids_type or id_type (enumerated) [=user]
Type of seed position specification.
user
Use the seed ids provided by you if available, otherwise, use global seed ids.
global
Use global seed ids.
local
Use local seed ids.
coordinates_type or crd_type (enumerated) [=per_seed]
Type of seed position specification.
per_seed or seeds
Use a list of seed ids and positions (id, x, y, z).
volume_random or vol_random
Seeds randomly distributed in an element set.
volume_uniform or vol_uniform
Seeds randomly distributed in an element set.
surface_random or surf_random
Seeds randomly distributed on a surface.
surface_uniform or surf_uniform
Seeds randomly distributed on a surface.
surface_flux_weighted or surf_flux_weighted
Seeds randomly distributed on a surface in a flux weighted manner.
region_random or reg_random
Seeds randomly distributed in a rectangular region.
region_uniform or reg_uniform
Seeds randomly distributed in a rectangular region.
seed_coordinates or coord (array) [no default]
List of seed ids and positions. Each row contains an integer seed id followed by the three real values, x,y,z, of the seed position. Used only if coordinates_type is per_seed.
number_of_seeds or num_seeds (integer) [=1]
Number of seeds. Ignored if coordinates_type is per_seed.
region_bounding_box or region (array) [={0,0,0;1,1,1}]
Lower and upper corners of the region. Used only if coordinates_type is region_random or region_uniform.
particle_surface or surface (string) [no default]
Name of the particle surface. Used only if coordinates_type is surface_random, surface_uniform, or surface_flux_weighted.
particle_surface_offset or surface_offset (real) [=0]
Offset of seed position from the particle surface as a fraction of the element length. Used only if coordinates_type is surface_random, surface_uniform, or surface_flux_weighted.
element_set or elem_set (string) [no default]
Name of the element set. Used only if coordinates_type is volume_random or volume_uniform.
density_type (enumerated) [=constant]
Type of seed density specification.
constant
All seeds assigned the same density.
per_seed
Use a list of densities, one density per seed.
random
Seed densities are randomly assigned.
seed_densities or densities (array) [no default]
List of seed densities, one per seed. Used only if density_type is per_seed.
constant_density (real) >0.0 [=1.0]
Density assigned to all seeds. Used only if density_type is constant.
density_random_bounds or density_rand_bounds (array) [no default]
Upper and lower bounds used to assign the random density initial conditions. Used only if density_type is random.
radius_type (enumerated) [=constant]
Type of seed radius specification.
constant
All seeds assigned the same radius.
per_seed
Use a list of radii, one density per seed.
random
Seed radii are randomly assigned.
seed_radii or radii (array) (no default)
List of seed radii, one per seed. Used only if radius_type is per_seed.
constant_radius real >0.0 (=1.0)
Radius assigned to all seeds. Used only if radius_type is constant.
radius_random_bounds or radius_rand_bounds (array) (no default)
Upper and lower bounds used to assign the random density initial conditions. Used only if density_type is random.
velocity_type (enumerated) [=use_flow_velocity]
Type of seed velocity specification.
use_flow_velocity or use_flow
Use the flow velocity at the seed location.
constant
All seeds assigned the same velocity.
zero
All seeds assigned a zero velocity.
per_seed
Use a list of velocities, one velocity per seed.
random
Seed velocities are randomly assigned.
particle_velocity_multiplier (real) >=0.0, <=1.0 [=1.0]
When velocity_type equals use_flow_velocity, the particle velocity is set to the flow velocity at the seed location multiplied by particle_velocity_multiplier. Used only if velocity_type is use_flow_velocity.
seed_velocity or seed_vel (array) [no default]
List of seed velocities, one per seed. Used only if velocity_type is per_seed.
constant_velocity or vel (array) [={0,0,0}]
Velocity assigned to all seeds. Used only if velocity_type is constant.
velocity_random_bounds or vel_rand_bounds (array) [no default]
Upper and lower bounds used to assign the random velocity initial conditions. Used only if velocity_type is random.
time_type (enumerated) [=zero]
Type of seed time specification.
zero
All seeds assigned a time of 0.
constant
All seeds assigned an identical time.
per_seed
Use a list of times, one time per seed.
emission_times
Use a list of times. A copy of all the seeds are emitted at each time.
seed_time or time (real) [=0]
Time assigned to all seeds. Used only if time_type is constant.
seed_times or times (array) [no default]
List of seed times, one per seed. Used only if time_type is per_seed.
emission_time_type (enumerated) [=series]
Type of emission seed time specification. The number of particles in the simulation will be the number of seeds times the number of emission times.
time_series or series
Use a list of emission times.
time_interval or interval
Specify times by start and stop times and a time interval.
emission_times (array) [no default]
List of emission times. Used only if emission_time_type is time_series.
emission_start_time or etime_start (real) [=0]
First emission time. Used only if emission_time_type is interval.
emission_stop_time or etime_stop (real) [=0]
Last emission time. Used only if emission_time_type is interval.
emission_time_interval or etime_interval (real) [=0]
Time interval between successive emission times. Used only if emission_time_type is interval. When emission_time_type is interval, the emission times always include emission_start_time and emission_stop_time regardless of the value of emission_time_interval.
stretch_type (enumerated) [=constant]
Type of seed stretch specification.
constant
All seeds assigned the same stretch vector.
random
Stretch vectors are randomly assigned.
per_seed
Use a list of stretch vectors.
constant_stretch (array) [={1,0,0}]
Stretch vector assigned to all seeds. Used only if stretch_type is constant.
seed_stretch (array) [no default}
List of stretch vectors, one per seed. Used only if stretch_type is per_seed.
random_stretch_length (real) [=1]
Value of random stretch length. Used only if stretch_type is random.
component_type (enumerated) [=none]
Type of seed component specification.
none
No components are assigned.
constant
All seeds assigned the same component vector.
random
Component vectors are randomly assigned.
per_seed
Use a list of stretch vectors.
distributed
All components of each seed have value 0 excepting a randomly selected one with a value of 1.
constant_components (array) [no default]
If component_type is constant, the component vector assigned to all seeds. If component_type is distributed, the array is used to construct bins, one for each component. Using these bins, seeds are randomly assigned one component with a value of 1.
seed_components or seed_comp (array) [no default]
List of components vectors, one per seed. Used only if component_type is per_seed.
component_random_bounds or comp_rand_bounds (array) [no default]
Upper and lower bounds used to assign the random component initial conditions. The array should have two rows, one for each bound. The number of columns in each row equal must the number of particle components. Use only if component_type is random.
turbulence_random_seed_type (enumerated) [=constant]
Type of turbulence random seed specification.
constant
All particle seeds assigned the same random seed.
per_seed
Used a list of random seeds.
constant_turbulence_random_seed or turb_seed (integer) [=1]
Turbulence random seed assigned to all particle seeds. The random seed actually used for each particle is this value plus the internal seed id. Used only if turbulence_random_seed_type is constant.
turbulence_random_seeds (array) [no default]
List of turbulence random seeds, one per seed. The random seed actually used for the particles are these values added to the internal seed ids. Used only if turbulence_random_seed_type is per_seed.

Description

The PARTICLE_SEED command defines a set of particles and initial conditions for those particles. The initial conditions that can be set by the PARTICLE_SEED command are

  • particle ids
  • particle set marker
  • position (coordinates)
  • radius
  • density
  • velocity
  • time
  • stretch vector
  • turbulence random seed

User equation initial conditions for a set of particles are defined by the USER_EQUATION_INITIAL_CONDITION command.

There needs to be at least one PARTICLE_SEED command in a trace input file, but as many PARTICLE_SEED commands as necessary are allowed. A unique set of particles is defined for each unique qualifier name used in a PARTICLE_SEED command. For example, two separate sets of particles, four particles in all, are defined if the following two commands appear in the input file:
PARTICLE_SEED( "seed_group_1" ) {
   coordinates_type = per_seed
   seed_coordinates = { 11, -0.05, 0.1, 0.0;
                        12, -0.05, 0.2, 0.0
                      }
}
PARTICLE_SEED( "seed_group_2" ) {
   coordinates_type = per_seed
   seed_coordinates = { 21, -0.05, 0.1, 0.0;
                        22, -0.05, 0.2, 0.0
                      }
}

Particle coordinates are assigned explicitly only if coordinates_type equals per_seed, in which case the number of seeds in the particle set equals the number of particle id and positions provided by the seed_coordinates parameter. In the example above, there are two particles in each particle set. If the coordinates of a seed fall outside the AcuSolve flow domain, the seed is ignored and does not participate in the particle trace. Particle ids are assigned explicitly only if coordinates_type equals per_seed and seed_ids_type equals user.

  • If coordinates_type equals per_seed but seed_ids_type does not equal user, the seed id values in the seed_coordinates parameter are ignored, and the particle ids are automatically assigned based on the value of seed_ids_type.
  • If coordinates_type does not equal per_seed and seed_ids_type does equal user, seed_ids_type is reset to global.
  • If seed_ids_type equals global, the particles are assigned a unique id between 1 and the total number of seeds in all the particle seed sets.
  • If seed_ids_type equals local, the particles are assigned an id between 1 and the number of seeds specified in the current PARTICLE_SEED command.

In the example above, the four seeds are assigned seed ids of 11, 12, 21, and 22. If the parameter seed_ids_type is set to local in both particle seed commands, the four seeds will have ids of 1, 2, 1, and 2. If the parameter seed_ids_type is set to global in both particle seed commands, the four seeds will have ids of 1, 2, 3, and 4. The parameter seed_ids_type does not need to have the same value in all the seed groups. For example, if seed_ids_type is set to user in the first seed group and global in the second, the four seeds will have ids of 11, 12, 3, and 4.

If coordinates_type does not equal per_seed, the number of seeds is specified, and the particle coordinates are automatically assigned based on other command parameters:
  • If fluid_elements is the name of an AcuSolve element set, for example, the command
    ELEMENT_SET( "fluid_elements" ) {
       ...
    }
appears in the AcuSolve input file for the AcuSolve run used by AcuTrace, the following PARTICLE_SEED command initializes a set of particles with initial positions randomly distributed throughout the AcuSolve element set fluid_elements:
PARTICLE_SEED( "seeds" ) {
   ...
   coordinates_type = volume_random
   element_set      = "fluid_elements"
   number_of_seeds  = 20
   ...
}
  • If inflow is the name of an AcuSolve particle surface, for example, if either the command
    PARTICLE_SURFACE( "inflow" ) {
       ...
    }
or the command
SIMPLE_BOUNDARY_CONDITION( "inflow" ) {
   ...
}
appears in the AcuSolve input file for the AcuSolve run used by AcuTrace, the following PARTICLE_SEED command initializes a set of particles with initial positions randomly distributed on the AcuSolve particle surface inflow:
PARTICLE_SEED( "seeds" ) {
   ...
   coordinates_type = surface_random
   particle_surface = "inflow"
   number_of_seeds  = 20
   ...
}
while the following PARTICLE_SEED command initializes a set of particles with initial positions randomly distributed in a mass flux weighted manner on the AcuSolve particle surface inflow:
PARTICLE_SEED( "seeds" ) {
   ...
   coordinates_type = surface_flux_weighted
   particle_surface = "inflow"
   number_of_seeds  = 20
   ...
}
  • A set of particles with positions randomly distributed in a rectangular region is initialized by the command
    PARTICLE_SEED( "seeds" ) {
      ...
       coordinates_type    = region_random
       region_bounding_box = {0,1,2;3,4,5}
       number_of_seeds     = 20
       ...
    }

When coordinates_type equals region_random, particle positions that fall outside the flow domain are discarded. If this happens, the number of particles initialized is less than the value of number_of_seeds.

  • Values of coordinates_type equal to volume_uniform, surface_uniform, and region_uniform currently result in the same seeding as volume_random, surface_uniform, and region_random, respectively.

For coordinates_type of surface_uniform, surface_random, and surface_flux_weighted, the parameter particle_surface_offset defines an offset for the initial particle positions from the surface as a fraction of the representative element length. In other words, when particle_surface_offset is 0, the positions are directly on the surface whereas for a non-zero value they are moved into the element adjacent to the surface. This is particularly useful if the surface is a no-slip wall. In this case, if the particle_surface_offset is 0, the particles will never move since the velocity at the wall is 0 for all time. For a non-zero value, the particles do move because they are put into the fluid next to the wall.

Particle masses are not input directly. Instead, particle densities and radii are specified. The particle masses are then initialized to the particle density times the particle volume. The particle radius and density inputs affect the particle trace only if the finite mass particle equation is used. If the massless particle equation is used, the particle densities and radii are still assigned to the particles but have no effect on the particle trace.

The initial particle densities can be assigned in one of three ways:
  • as a constant over the seed set, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       density_type      = constant
       constant_density  = 1.0
       ...
    }
  • per seed, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       density_type   = per_seed
       seed_densities = { 0.9, 0.7, 1.2, 1.3, 1.05 }
       ...
    }
  • randomly, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       desnity_type          = random
       density_random_bounds = {0.5, 1.5 }
       ...
    }

When density_type equals random, the density of each seed is randomly assigned a value between the values of density_random_bounds, here, between 0.5 and 1.5.

The initial values of the particle radii can also be assigned in one of three ways:
  • as constant over the seed set, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       radius_type      = constant
       constant_radius  = 0.0001
       ...
    }
  • per seed, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       radius_type  = per_seed
       seed_radii   = { 1.1e-4, 9.0e-5, 1.2e-4, 0.85e-4, 1.01e-4 }
       ...
    }
  • randomly, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       density_type         = random
       desity_random_bounds = { 9.0e-5, 1.1e-4 }
       ...
    }

When radius_type equals random, the radius of each seed is randomly assigned a value between the values of radius_random_bounds, here, between 9.0e-5 and 1.1e-4.

Note that the radius and density of a particle is constant in time. The mass of a particle is therefore constant as well.

Particle velocity initialization is relevant only when the finite mass particle equation is used. If the massless particle equation is used, particle velocity inputs are ignored because the particle velocity always equals the flow velocity.

Particle velocities can be initialized in one of six ways:
  • to zero for all seeds in the seed set, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       velocity_type   = zero
       ...
    }
  • to the flow velocity at the seed location, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       velocity_type                = use_flow_velocity
       particle_velocity_multiplier = 1.0
       ...
    }
  • to a constant times the flow velocity, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       velocity_type                = use_flow_velocity
       particle_velocity_multiplier = 0.9
       ...
    }
  • as a constant over the seed set, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       velocity_type             = constant
       constant_velocity         = { 0.7, 0.9, 1.1 }
       ...
    }
  • per seed, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       velocity_type  = per_seed
       seed_velocity  = { 1.0,  1.1,  0.8 ;
                          0.85, 0.95, 1.3 ;
                          1.35, 1.1,  0.65 ;
                          0.7,  0.8,  1.4
                        }
       ...
    }
  • randomly, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       velocity_type           = random
       velocity_random_bounds  = { 0.65,  0.75,  0.6 ;
                                   1.4, 1.2, 1.5
                                 }
       ...
    }

When velocity_type equals random, each component of the velocity of a seed is randomly assigned a value between the values of velocity_random_bounds. In the example above, the x-component is randomly assigned a value between 0.65 and 1.4, the y-component between .75 and 1.2, and the z-component between .6 and 1.5.

Initial particle times can be set in one of four ways:
  • An initial time of 0 is assigned to all the particles in a particle set if time_type is zero.
  • To assign the same non-zero constant time to all the particles, use, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       time_type = constant
       time      = 20.0
       ...
    }
  • To assign a unique time for each particle, use, for example:
    PARTICLE_SEED( "seeds" ) {
       ...
       time_type = per_seed
       times     = Read( "seed_times" )
       ...
    }

The number of values specified by the times must equal the number of seeds in the set.

  • To assign a series of emission times to all the particles in the current set, use, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       time_type          = emission_times
       emission_time_type = time_series
       emission_times     = {
                          0.0 ;
                          1.0;
                          2.0;
                          3.0
                          }
       ...
    }
The total number of particles initialized when time_type equals emission_times equals the number of seeds times the number of emission times. For example, for the command
PARTICLE_SEED( "seeds" ) {
   coordinates_type = per_seed
   seed_coordinates = {
                     1, -0.05, 0.1, 0.0;
                     2, -0.05, 0.2, 0.0
                     }
   ...
   time_type                  = emission_times
   emission_time_type         = time_interval
   emission_start_time        = 0.0
   emission_stop_time         = 3.0
   emission_time_interval     = 1.0
   ...
}

there are eight particles in all. There are four particles at (-0.05, 0.1, 0.0) with initial times of 0.0, 1.0, 2.0, and 3.0, and four particles at (-0.05, 0.2, 0.0) with the same four initial times.

Initial stretch vectors can be assigned in one of three ways:
  • a constant over the seed set, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       stretch_type     = constant
       constant_stretch = { 1.0, 0.0, 1.0 }
       ...
    }
  • per seed, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       stretch_type = per_seed
       seed_stretch = { 1, 0, 0; 0, 1, 0; 1, 1, 1; 0, 0, 1 }
       ...
    }
  • randomly, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       stretch_type          = random
       random_stretch_length = 1.0
       ...
    }

When stretch_type equals per_seed, the number of stretch vectors (four in the example shown) must equal the number of seeds in the seed set. When stretch_type equals random, each component of each stretch vector is randomly assigned a value between 0 and the value of random_stretch_length.

The initial values of the particle component vectors can be assigned in one of four ways. In the following example, it is assumed that number_particle_components is set to five in the EQUATION command.

  • a constant over the seed set, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       component_type      = constant
       constant_components = { 0.0, 0.0, 1.0, 1.0, 0.0 }
       ...
    }
  • per seed, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       component_type  = per_seed
       seed_components = { 1, 0, 0, 0, 0; 0, 1, 0, 0, 0; 0, 0, 1, 0, 0 }
       ...
    }
  • randomly, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       component_type          = random
       component_random_bounds = {0.0, 2.0, 4.0, 3.0, 4.0 ;
                                  1.0, 3.0, 5.0, 4.0, 5.0
                                  }
       ...
    }
  • randomly distributed over the seeds, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       component_type      = distributed
       constant_components = { 1.0, 2.0, 1.0, 0.5, 1.5 }
       ...
    }

When component_type equals constant, all seeds in the seed set are assigned the same component vector, (0.0, 0.0, 1.0, 1.0, 0.0) in the example shown. When component_type equals per_seed, the number of initial component vectors, three in the example shown, must equal the number of seeds in the seed set. When component_type equals random, each component of each seed is randomly assigned a value between the corresponding values of component_random_bounds. Here, the first components all lie between 0.0 and 1.0, the second between 2.0 and 3.0, and so on.

When component_type equals distributed, the values of constant_components represent bin widths. For the example shown, five bins are constructed: 0.0 to 1.0; 1.0 to 3.0; 3.0 to 4.0; 4.0 to 4.5; 4.5 to 6. For each seed, a random number is drawn between the lower bound of the lowest bin and the upper bound of the highest bin. That number is then used to determine a bin number. The component for that bin is set to 1; the components for the other bins are set to 0. For the example show, random numbers are drawn between zero and six. If the random draw for the first seed is 4.1, the first seed is assigned a component vector of (0.0, 0.0, 0.0, 1.0, 0.0) because 4.1 falls in the fourth bin, that is, it is between 4.0 and 4.5. If the draw for the second seed is 2.7, the second seed is assigned a component vector of (0.0, 1.0, 0.0, 0.0, 0.0) because 2.7 falls in the second bin, that is, it is between 1.0 and 3.0. This process is repeated for all the seeds in the seed group.

Note that the particle component vectors retain their initial values throughout the particle trace, that is, they are constant in time.

The initial turbulent seed can be assigned in one of two ways:
  • a constant over the seed set, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       turbulence_random_seed_type = constant
       turbulence_random_seed      = 1.0
       ...
    }
  • per seed, for example,
    PARTICLE_SEED( "seeds" ) {
       ...
       turbulence_random_seed_type = per_seed
       turbulence_random_seeds     = { 1; 3; 99; -3; 17 }
       ...
    }

When turbulence_random_seed_type equals per_seed, the number of turbulent seeds, five in the example shown, must equal the number of seeds in the seed set.