Syntax:
fix ID emit/surf mix-ID group-ID keyword value ...
n value = Np = number of particles to create
Np can be a variable (see below)
normal value = yes or no = emit normal to surface elements or with streaming velocity
nevery value = Nstep = add particles every this many timesteps
perspecies value = yes or no
region value = region-ID
subsonic values = Psub Tsub keyword/value
Psub = pressure setting at inflow boundary (pressure units)
Tsub = temperature setting at inflow boundary, can be NULL (temperature units)
zero or one additional keyword/value pair may be appended:
window value = Nwin = moving-average window for the cell streaming velocity
mflow values = Mdot Tin keyword/value
Mdot = target mass flow rate through the surface group (mass/time units)
Tin = thermal temperature of inflow particles (temperature units)
zero or one additional keyword/value pair may be appended:
window value = Nwin = moving-average window for the cell streaming velocity
custom values = attribute s_name
attribute = density or temperature or vstream or speed or fractions
s_name = custom per-surf vector or array with name
twopass values = none
Examples:
fix in emit/surf air all fix in emit/face mymix myPatch region circle normal yes fix in emit/surf air all subsonic 0.1 300 fix in emit/surf air all subsonic 0.05 NULL
fix in emit/surf air inlet mflow 1.0e-6 300 fix in emit/surf air inlet normal no mflow 1.0e-6 300 window 1000
read_surf sdata.circle custom myrho float 0 custom mystream float 3 fix in emit/surf air all custom nrho s_myrho custom vstream s_mystream
Description:
Emit particles from a group of surface elements, continuously during a simulation. If invoked every timestep, this fix creates a continuous outflux of particles from the surface elements in the group. This command can only be used with explicit surfaces, not implicit. See Section Howto 6.13 for a discussion of explicit and implicit surface elements.
The properties of the added particles are determined by the mixture with ID mix-ID. This sets the number and species of added particles, as well as their streaming velocity, thermal temperature, and internal energy modes. The details are explained below.
Which surface elements emit particles is specified by the group-ID for a surface group, which defines a set of surface elements. The group surf is used to define surface groups.
On each insertion timestep, each grid cell that overlaps with one or more emitting surface elements performs the following computations to add particles for each grid cell/surface element pairing. The particles are added at the beginning of the SPARTA timestep.
The molecular flux emitted from a surface element per unit time is given by equation 4.22 of (Bird94). The number of particles M to insert on the portion of a surface element that is contained within a grid cell is based on this flux and additional global, flow, and surface element properties:
The flow properties are defined for the specified mixture via the mixture command.
If M has a fractional value, e.g. 12.5, then 12 particles are added, and a 13th depending on the value of a random number. Each particle is added at a random location within the portion of the surface element that overlaps with 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.
IMPORTANT NOTE: The preceeding calculation is actually done using surface element areas associated with weighted cell volumes. Grid cells can be weighted using the global weight command.
The velocity of the particle is set to the sum of the streaming velocity and a thermal velocity sampled from the thermal temperature. The internal energy modes of the particle are determined by the trot and tvib settings of the mixture and the rotate and vibrate options of the collide_modify command. Note that if the collide command has not been specified (free molecular flow), then no rotational or vibrational energy will be assigned to created particles. See the discussion of the normal keyword below for a way to change the velocity assignment to be oriented in the direction normal to the surface element, rather than in the direction of the streaming velocity.
If the final particle velocity is not directed "out of" the surface element, then the velocity sampling procedure is repeated until it is. This insures that all added particles emit from the surface element, as desired.
The first timestep that added particles are advected, they move for a random fraction of the timestep. This insures a continuous flow field of particles emitting from each surface element.
The n keyword can alter how many particles are added, which can be useful for debugging purposes. If Np is set to 0, then the number of added particles is a function of fnum, nrho, and other mixture settings, as described above.
If Np is set to a value > 0, then the fnum and nrho settings are ignored, and roughly Np particles are added on each insertion timestep. For each grid cell/surface element pair, its target number of emitted particles is set to its fraction of the total emission area (for all grid cell/surface element pairs), multiplied by Np. If that results in a fractional value, then an extra particle is emitted depending on the value of a random number, as explained above.
Np may be set to a non-integer value, e.g. 12.5 or 0.5. Since the per-surface-element target is rounded stochastically, this allows for an emission rate of less than one particle per timestep, which is useful when a low inflow rate is desired through a specific group of surface elements without changing the global fnum setting.
The Np value can be also be specified as an equal-style variable. If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the variable will be evaluated on each emission timestep, and its value used as Np on that step to determine the target number of emitted particles for each grid cell/surface element pair, the same as described in the preceeding paragraph.
Equal-style variables can specify formulas with various mathematical functions, and include stats_style command keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent value of Np.
The normal keyword can be used to alter how velocities are set for added particles. If normal is set to no, then a particle's velocity is set as described above, using the mixture's streaming velocity superposed with a thermal velocity sampled from the temperature of the mixture. Note that the same streaming velocity is used for all emitting surface elements, regardless of their orientation with respect to the streaming velocity. If normal is set to yes, then each surface element is assigned its own "streaming" velocity in the following manner. The streaming velocity points in the direction of the outward normal of the surface element, and its magnitude is set to the magnitude of the mixture's streaming velocity. A velocity is then assigned to the particle in the same manner as before. It is assigned the outward streaming velocity superposed with a thermal velocity sampled from the temperature of the mixture. The effect is that particles effectively stream outward from each emitting surface element.
The nevery keyword determines how often particles are added. If Nstep > 1, this may give a non-continuous, clumpy distribution in the inlet flow field.
The perspecies keyword determines how the species of each added particle is randomly determined. This has an effect on the statistical properties of added particles.
If perspecies is set to yes, then a target insertion number M for a grid cell/surface element pair is calculated for each species, which is a function of the relative number fraction of the species, as set by the mixture nfrac command. If M has a fractional value, e.g. 12.5, then 12 particles of that species will always be added, and a 13th depending on the value of a random number.
If perspecies is set to no, then a single target insertion number M for a grid cell/surface element pair is calculated for all the species. Each time a particle is added, a random number is used to choose the species of the particle, based on the relative number fractions of all the species in the mixture. As before, if M has a fractional value, e.g. 12.5, then 12 particles will always be added, and a 13th depending on the value of a random number.
Here is a simple example that illustrates the difference between the two options. Assume a mixture with 2 species, each with a relative number fraction of 0.5. Assume a particular grid cell/surface element pair adds 10 particles from that mixture. If perspecies is set to yes, then exactly 5 particles of each species will be added on every timestep insertions take place. If perspecies is set to no, then exactly 10 particles will be added every time and on average there will be 5 particles of each of the two species. But on one timestep it might be 6 of the first and 4 of the second. On another timestep it might be 3 of the first and 7 of the second.
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 on a subset of the collective area of the specified group of surface elements. 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 on an insertion timestep. This is because grid cell/suface element pairs will be candidates for particle insertion, unless the grid cell is entirely outside the bounding box that encloses the region. Particles those grid cell/surface element pairs will 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 subsonic keyword uses the method of Fang and Liou (Fang02) to determine the number of particles to insert in each grid cell on the emitting face(s). They used the method of characteristics to calculate the mean properties of the incoming molecular flux, so that the prescribed pressure condition is achieved. These properties are then applied to calculate the molecular flux across a grid cell face per unit time, as given by equation 4.22 of (Bird94).
This keyword allows specification of both the pressure and temperature at the surface or just the pressure (by specifying the temperature as NULL). If specified, the temperature must be > 0.0. Currently, instantaneous values for the density, temperature, and stream velocity of particles in the cells containing the surface elements are computed and used to determine the properties of inserted particles on each timestep.
The optional window keyword applies a moving average to the cell streaming velocity used by the subsonic boundary condition, to reduce the statistical fluctuations inherent in the instantaneous cell values (see (Sun05)). On each timestep the averaged velocity is vcom = a*vnew + (1-a)*vold with a = 1/(Nwin+1), where vnew is the current center-of-mass velocity of the cell and vold is the average from the previous step; larger Nwin gives heavier smoothing. The default Nwin = 0 disables smoothing and reproduces the instantaneous behavior. Only the cell velocity is averaged; for a pressure-only boundary (Tsub = NULL) the characteristic pressure correction is applied to the averaged velocity once per step, not accumulated.
IMPORTANT NOTE: The moving average is stored per grid cell/surface element pair, and those pairs are rebuilt whenever the grid changes. So the average restarts after fix balance or fix adapt alters the grid. Avoid dynamic load balancing, or use a window much shorter than the rebalance interval, if a converged average matters.
IMPORTANT NOTE: Caution must be exercised when using the subsonic boundary condition without specifying an inlet temperature. In this case the code tries to estimate the temperature of the flow from the properties of the particles in the domain. If the domain contains few particles per cell it may lead to spurious results. This boundary condition is meant more for an outlet than an inlet boundary condition, and performs well in cases where the cells are adequately populated.
IMPORTANT NOTE: When using this keyword, you should also use an appropriate surface collision or chemistry model via the surf_collide or surf_react commands, so that particles hitting the surface disappear as if they were exiting the simulation domain. That is necessary to produce the correct subsonic conditions that the particle insertions due to this command are trying to achieve.
The mflow keyword imposes a target mass flow rate Mdot (in mass/time units) through the entire emitting surface group, rather than a prescribed pressure. This is useful for internal-flow problems where the inflow rate, not the inlet pressure, is the known quantity.
On each timestep the code computes a single number density that makes the expected total inserted mass rate, summed over all emitting grid cell/surface element pairs (and over all processors), equal to Mdot. It does this from the actual molecular inflow flux (equation 4.22 of (Bird94), the same flux used for insertion) evaluated over the true overlap area of each surface element with its grid cell. The inlet area is therefore computed internally from the surface geometry; it is not a user input, so the imposed mass flow rate is independent of the surface mesh resolution and is correct for arbitrary geometries.
Cell weighting (see the weight keyword of the global command) does not change the imposed rate: fewer particles are inserted in a more heavily weighted cell, but each one represents proportionally more molecules.
The inflow particles are given the thermal temperature Tin, which must be > 0.0. By default the streaming direction in each cell is taken from the center-of-mass velocity of the particles currently in that cell (or, with normal set to yes, along the inward surface normal). Because that velocity is a noisy instantaneous quantity, the optional window keyword applies a moving average to it, exactly as described above for the subsonic keyword (including the caveat that the average restarts when the grid changes).
The calculation accounts for how the species of each inserted particle is chosen. With perspecies = yes each species is inserted in proportion to its own inflow flux, so masses are flux-weighted; with perspecies = no a single species is drawn from the mixture number fractions, so the mean inserted mass is the fraction-weighted mean mass of the mixture. Either setting delivers the requested Mdot.
IMPORTANT NOTE: The imposed mass flow rate is achieved in an expected (statistical) sense. The number of particles inserted on any single timestep fluctuates, so the realized rate should be measured as a time-average over many steps. A clean way to verify it is from the fix's cumulative insertion count (see output below): realized mass rate = (ntotal * fnum * mean-inserted-mass) / (Nsteps * dt), where the per-particle mass must be multiplied by the cell weight if cell weighting is enabled.
IMPORTANT NOTE: As with subsonic, you should use an appropriate surf_collide or surf_react model on the emitting surfaces so particles hitting them disappear as if exiting the domain. The mflow keyword cannot be combined with the subsonic, n, custom, or region keywords. Both mflow and subsonic are supported by the kk suffix version of this fix. The region restriction exists because insertions rejected by a region are not resampled, which would silently reduce the realized mass flow rate below Mdot.
The custom keyword can be used to tailor the emission of particles from individual surface elements. This is done by using custom per-surf vectors or arrays defined by other commands.
For example, the read_surf command can read per-surf attributes included in a surface data file. The custom and fix custom commands allow for definition of custom per-surf vectors or arrays and their initialization by use of surf-style variables or by reading the values from a file. Note that the use of "fix custom" allows for the resetting of custom attributes once every N timesteps, which allows for time-dependence in per-surface emission properties. The fix surf/temp command resets per-surf temperatures based on gas collisions with each surface element.
See Section Howto 6.17 for a discussion of custom per-surf attributes.
IMPORTANT NOTE: The custom keyword cannot be used together with either the n or subsonic keywords.
The attribute value of the custom keyword can be any of the following:
The s_name value of the custom keyword is the name of the custom per-surf vector or array. It must store floating-point values and be a vector or array, as indicated in the list above.
When the fix emit/surf command calculates the number of particles (and their attributes) to be emitted from each surface element, by default it uses the mixture properties of the specified mix-ID for number density, streaming velocity, temperature, and relative species fractions. The same values are used for all surface elements. If the custom keyword is used for one or more of these properties, the values of the associated custom per-surf vector or array override the default mixture properties.
The custom attribute nrho sets a number density used to calculate the count of particles emitted from each surface element. The nrho values should be in per-volume units = per-length^3 for 3d models or axisymmetric models. The values should be in per-area units = per-length^2 for 2d models.
The custom attribute vstream can only be used if the normal keyword is set to no, which is the default. In this case it must refer to a 3-column per-surf custom array which stores the 3 streaming velocity components for each surface element. If the normal keyword is set to yes, then the custom atrribute speed should be used instead. It must refer to a custom per-surf vector which stores the "speed" of the emission in the direction normal to each surface element. I.e. it is the scalar length of the streaming velocity vector, as described above for the normal keyword.
The custom attribute temp sets a temperature for each surface element. This temperature is used as the thermal, rotational, vibrational temeperature for each inserted particle which means it affects their thermal velocity components as well as their rotational and vibrational energies.
The custom attribute fractions must refer to a per-surf custom array with N columns, where N is the number of species in the mixture. For each surface element, the N values will be used to set the relative fractions of emitted particles for that element, using the logic for the perspecies yes/no keyword described above.
For each surface element, the N per-species fractional values must sum to 1.0. However, one or more of the numeric values can be < zero, say M of them. In this case, each of the M values will be reset to (1 - sum)/M, where sum is the sum of the N-M values which are >= zero.
Note that the ordering of species within the N columns of the custom per-surf array, is the same as the order of species within the mix-ID mixture. This is determined by the mixture command. It is the order the gas species names were listed when the mixture command was specified (one or more times).
The twopass keyword does not require a value. If used, the insertion procedure will loop over the insertion surface elements twice, the same as the KOKKOS package version of this fix does, so that it can reallocate memory efficiently, e.g. on a GPU. If this keyword is used the non-KOKKOS and KOKKOS version will generate exactly the same set of particles, which makes debugging easier. If the keyword is not used, the non-KOKKOS and KOKKOS runs will use random numbers differently and thus generate different particles, though they will be statistically similar.
Restart, output info:
No information about this fix is written to binary restart files.
This fix computes a global vector of length 2 which can be accessed by various output commands. The first element of the vector is the total number of particles added on the most recent insertion step. The second element is the cummulative total number added since the beginning of the run. The 2nd value is initialized to zero each time a run is performed.
Styles with a kk suffix are functionally the same as the corresponding style without the suffix. They have been optimized to run faster, depending on your available hardware, as discussed in the Accelerating SPARTA section of the manual. The accelerated styles take the same arguments and should produce the same results, except for different random number, round-off and precision issues.
These accelerated styles are part of the KOKKOS package. They are only enabled if SPARTA was built with that package. See the Making SPARTA section for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix command-line switch when you invoke SPARTA, or you can use the suffix command in your input script.
See the Accelerating SPARTA section of the manual for more instructions on how to use the accelerated styles effectively.
Restrictions:
A n setting of Np > 0 or Np as a variable can only be used with a perspecies setting of no.
If normal is set to no, which is the default, then unlike the fix emit/face command, no warning is issued if a surface element has an inward normal in a direction opposing the streaming velocity, as defined by the mixture.
For that surface element, particles will still be emitted, so long as a small fraction have a thermal velocity large enough to overcome the outward streaming velocity, so that their net velocity is inward. The threshold for this is the thermal velocity for particles 3*sigma from the mean thermal velocity.
Related commands:
mixture, create_particles, fix emit/face
Default:
The keyword defaults are n = 0, normal = no, nevery = 1, perspecies = yes, region = none, no subsonic settings, no mflow settings, no twopass setting. For the subsonic and mflow keywords, the moving-average window defaults to 0 (no smoothing).
(Bird94) G. A. Bird, Molecular Gas Dynamics and the Direct Simulation of Gas Flows, Clarendon Press, Oxford (1994).
(Fang02) Y. Fang and W. W. Liou, Microfluid Flow Computations Using a Parallel DSMC Code, AIAA 2002-1057. (2002).
(Sun05) Q. Sun and I. D. Boyd, Evaluation of Macroscopic Properties in the Direct Simulation Monte Carlo Method, Journal of Thermophysics and Heat Transfer, 19(3), 329-335 (2005).