<HTML>
<CENTER><A HREF = "https://sparta.github.io">SPARTA WWW Site</A> - <A HREF = "Manual.html">SPARTA Documentation</A> - <A HREF = "Section_commands.html#comm">SPARTA Commands</A> 
</CENTER>






<HR>

<H3>fix emit/surf command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>fix ID emit/surf mix-ID group-ID keyword value ... 
</PRE>
<UL><LI>ID is documented in <A HREF = "fix.html">fix</A> command 

<LI>emit/surf = style name of this fix command 

<LI>mix-ID = ID of mixture to use when creating particles 

<LI>group-ID = ID of surface group that emits particles 

<LI>zero or more keyword/value pairs may be appended 

<LI>keyword = <I>n</I> or <I>normal</I> or <I>nevery</I> or <I>perspecies</I> or <I>region</I> or <I>subsonic</I> or <I>custom</I> 

<PRE>  <I>n</I> value = Np = number of particles to create
                   Np can be a variable (see below)
  <I>normal</I> value = yes or no = emit normal to surface elements or with streaming velocity
  <I>nevery</I> value = Nstep = add particles every this many timesteps
  <I>perspecies</I> value = <I>yes</I> or <I>no</I>
  <I>region</I> value = region-ID
  <I>subsonic</I> values = Psub Tsub
    Psub = pressure setting at inflow boundary (pressure units)
    Tsub = temperature setting at inflow boundary, can be NULL (temperature units)
  <I>custom</I> values = attribute s_name
    attribute = <I>nrho</I> or <I>vstream</I> or <I>speed</I> or <I>temp</I> or <I>fractions</I>
    s_name = custom per-surf vector or array with name 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>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 
</PRE>
<PRE>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 
</PRE>
<P><B>Description:</B>
</P>
<P>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
<A HREF = "Section_howto.html#howto_13">Section Howto 6.13</A> for a discussion of
explicit and implicit surface elements.
</P>
<P>The properties of the added particles are determined by the mixture
with ID <I>mix-ID</I>.  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.
</P>
<P>Which surface elements emit particles is specified by the <I>group-ID</I>
for a surface group, which defines a set of surface elements.  The
<A HREF = "group.html">group surf</A> is used to define surface groups.
</P>
<P>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.
</P>
<P>The molecular flux emitted from a surface element per unit time is
given by equation 4.22 of <A HREF = "#Bird94">(Bird94)</A>.  The number of particles
<I>M</I> 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:
</P>
<UL><LI>global property: <I>fnum</I> ratio as specified by the <A HREF = "global.html"">global</A> command
<LI>flow properties: number density, streaming velocity, and thermal temperature
<LI>surface element properties: portion of surface element area that overlaps with the grid cell and its orientation relative to the streaming velocity 
</UL>
<P>The flow properties are defined for the specified mixture via the
<A HREF = "mixture.html">mixture</A> command.
</P>
<P>If <I>M</I> 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 <I>frac</I> settings of the collection
of species in the mixture, as set by the <A HREF = "mixture.html">mixture</A>
command.
</P>
<P>IMPORTANT NOTE: The preceeding calculation is actually done using
surface element areas associated with <I>weighted</I> cell volumes.  Grid
cells can be weighted using the <A HREF = "global.html">global weight</A> command.
</P>
<P>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 <I>trot</I>
and <I>tvib</I> settings of the mixture and the <I>rotate</I> and <I>vibrate</I>
options of the <A HREF = "collide_modify.html">collide_modify</A> command.  Note
that if the <A HREF = "collide.html">collide</A> 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 <I>normal</I>
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.
</P>
<P>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.
</P>
<P>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.
</P>
<HR>

<P>The <I>n</I> keyword can alter how many particles are added, which can be
useful for debugging purposes.  If <I>Np</I> is set to 0, then the number
of added particles is a function of <I>fnum</I>, <I>nrho</I>, and other mixture
settings, as described above.
</P>
<P>If <I>Np</I> is set to a value > 0, then the <I>fnum</I> and <I>nrho</I> settings are
ignored, and roughly <I>Np</I> 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 <I>Np</I>.  If
that results in a fractional value, then an extra particle is emitted
depending on the value of a random number, as explained above.
</P>
<P>The <I>Np</I> value can be also be specified as an equal-style
<A HREF = "variable.html">variable</A>.  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 <I>Np</I> 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.
</P>
<P>Equal-style variables can specify formulas with various mathematical
functions, and include <A HREF = "status_style.html">stats_style</A> command
keywords for the simulation box parameters and timestep and elapsed
time.  Thus it is easy to specify a time-dependent value of <I>Np</I>.
</P>
<P>The <I>normal</I> keyword can be used to alter how velocities are set for
added particles.  If <I>normal</I> is set to <I>no</I>, 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 <I>normal</I> is
set to <I>yes</I>, 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.
</P>
<P>The <I>nevery</I> keyword determines how often particles are added.  If
<I>Nstep</I> > 1, this may give a non-continuous, clumpy distribution in
the inlet flow field.
</P>
<P>The <I>perspecies</I> keyword determines how the species of each added
particle is randomly determined.  This has an effect on the
statistical properties of added particles.
</P>
<P>If <I>perspecies</I> is set to <I>yes</I>, then a target insertion number <I>M</I>
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 <A HREF = "mixture.html">mixture nfrac</A> command.  If <I>M</I> 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.
</P>
<P>If <I>perspecies</I> is set to <I>no</I>, then a single target insertion number
<I>M</I> 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 <I>M</I> 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.
</P>
<P>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 <I>perspecies</I> is set to
<I>yes</I>, then exactly 5 particles of each species will be added on every
timestep insertions take place.  If <I>perspecies</I> is set to <I>no</I>, 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.
</P>
<P>If the <I>region</I> keyword is used, then a particle will only added if
its position is within the specified <I>region-ID</I>.  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 <I>side</I> option
for the <A HREF = "region.html">region</A> command can be used to define whether the
inside or outside of the geometric region is considered to be "in" the
region.
</P>
<P>IMPORTANT NOTE: If the <I>region</I> and <I>n</I> 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.
</P>
<P>The <I>subsonic</I> keyword uses the method of Fang and Liou
<A HREF = "#Fang02">(Fang02)</A> 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
<A HREF = "#Bird94">(Bird94)</A>.
</P>
<P>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.
</P>
<P>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.
</P>
<P>IMPORTANT NOTE: When using this keyword, you should also use an
appropriate surface collision or chemistry model via the
<A HREF = "surf_collide.html">surf_collide</A> or <A HREF = "surf_react.html">surf_react</A>
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.
</P>
<HR>

<P>The <I>custom</I> 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.  E.g. the
<A HREF = "read_surf.html">read_surf</A> command which can read per-surf attributes
included in the surface data file.  Or the custom command which allows
for definition of custom per-surf vectors or arrays and their
initialization by use of <A HREF = "variable.html">surf-style variables</A>.  See
<A HREF = "Section_howto.html#howto_17">Section Howto 6.17</A> for a discussion of
custom per-surf attributes.
</P>
<P>IMPORTANT NOTE: The <I>custom</I> keyword cannot be used together with
either the <I>n</I> or <I>subsonic</I> keywords.
</P>
<P>The <I>attribute</I> value of the <I>custom</I> keyword can be any of the
following:
</P>
<UL><LI>nrho = number density (# per length^3 units) = per-surf vector
<LI>vstream = 3-component streaming velocity (velocity units) = per-surf array with 3 columns
<LI>speed = length of streaming velocity vector in normal direction (velocity units) = per-surf vector
<LI>temp = temperature (temperature units) = per-surf vector
<LI>fractions = species fractions (unitless) = per-surf array 
</UL>
<P>The <I>s_name</I> value of the <I>custom</I> 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.
</P>
<P>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 <I>mix-ID</I> for number
density, streaming velocity, temperature, and relative species
fractions.  The same values are used for all surface elements.  If the
<I>custom</I> keyword is used for one or more of these properties, the
values of the associated custom per-surf vector(s) or array(s)
override the default mixture properties.
</P>
<P>The <I>custom</I> attribute <I>vstream</I> can only be used if the <I>normal</I>
keyword is set to <I>no</I>, 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 <I>normal</I> keyword
is set to <I>yes</I>, then the <I>custom</I> atrribute <I>speed</I> 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 <I>normal</I> keyword.
</P>
<P>The <I>custom</I> attribute <I>temp</I> sets a temperature for each surface
element.  This temperature is used as the thermal temeperature for
each inserted particle which means it affects its thermal velocity
components as well as its rotational and vibrational energies.
</P>
<P>The <I>custom</I> attribute <I>fractions</I> 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 <I>perspecies yes/no</I> keyword described above.
</P>
<P>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.
</P>
<P>Note that the order of species within the N columns of the custom
per-surf array, if the same as the order of species within the mix-ID
mixture.  This is determined by the <A HREF = "mixture.html">mixture</A> command.
It is the order the gas species names were listed when the mixture
command was specified (one or more times).
</P>
<HR>

<P><B>Restart, output info:</B>
</P>
<P>No information about this fix is written to <A HREF = "restart.html">binary restart
files</A>.
</P>
<P>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.
</P>
<P><B>Restrictions:</B>
</P>
<P>A <I>n</I> setting of <I>Np</I> > 0 or <I>Np</I> as a variable can only be used with
a <I>perspecies</I> setting of <I>no</I>.
</P>
<P>If <I>normal</I> is set to <I>no</I>, which is the default, then unlike the <A HREF = "fix_emit/face.html">fix
emit/face</A> 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.
</P>
<P>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.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "mixture.html">mixture</A>, <A HREF = "create_particles.html">create_particles</A>, <A HREF = "fix_emit_face.html">fix
emit/face</A>
</P>
<P><B>Default:</B>
</P>
<P>The keyword defaults are n = 0, normal = no, nevery = 1, perspecies =
yes, region = none, no subsonic settings.
</P>
<HR>

<A NAME = "Bird94"></A>

<P><B>(Bird94)</B> G. A. Bird, Molecular Gas Dynamics and the Direct
Simulation of Gas Flows, Clarendon Press, Oxford (1994).
</P>
<A NAME = "Fang02"></A>

<P><B>(Fang02)</B> Y. Fang and W. W. Liou, Microfluid Flow Computations
Using a Parallel DSMC Code, AIAA 2002-1057. (2002).
</P>
</HTML>
