<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>compute surf command 
</H3>
<H3>compute surf/kk command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>compute ID surf group-ID mix-ID value1 value2 ... keyword setting ... 
</PRE>
<UL><LI>ID is documented in <A HREF = "compute.html">compute</A> command 

<LI>surf = style name of this compute command 

<LI>group-ID = group ID for which surface elements to perform calculation on 

<LI>mix-ID = mixture ID for particles to perform calculation on 

<LI>one or more values can be appended 

<LI>value = <I>n</I> or <I>nwt</I> or <I>nflux</I> or <I>nflux_incident</I> or <I>mflux</I> or <I>mflux_incident</I> or <I>fx</I> or <I>fy</I> or <I>fz</I> or <I>tx</I> or <I>ty</I> or <I>tz</I> or <I>press</I> or <I>px</I> or <I>py</I> or <I>pz</I> or <I>shx</I> or <I>shy</I> or <I>shz</I> or <I>ke</I> 

<PRE>  n = count of particles hitting surface element
  nwt = weighted count of particles hitting surface element
  nflux = net flux of particles through surface element
  nflux_incident = incident flux of particles on surface element
  mflux = net flux of mass through surface element
  mflux_incident = incident flux of mass on surface element
  fx,fy,fz = components of force on surface element
  tx,ty,tz = components of torque on body center-of-mass
  press = magnitude of normal pressure on surface element
  px,py,pz = components of normal pressure on surface element
  shx,shy,shz = components of shear stress on surface element
  ke = flux of particle kinetic energy on surface element
  erot = flux of particle rotational energy on surface element
  evib = flux of particle vibrational energy on surface element
  echem = flux of particle chemical catalytic energy on surface element
  etot = flux of particle total energy on surface element 
</PRE>
<LI>zero or more keyword/setting pairs can be appended 

<LI>keyword = <I>norm</I> or <I>com</I> 

<PRE>  norm arg = <I>flux</I> or <I>flow</I> for dividing flux quantities by area or not
  com args = Cx Cy Cz = coords of center-of-mass of body for calculating torque 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>compute 1 surf all all n press etot
compute mine surf sphere species press shx shy shz
compute 2 surf all all mflux ke erot norm flow 
</PRE>
<P>These commands will dump time averages for each species and each
surface element to a dump file every 1000 steps:
</P>
<PRE>compute 1 surf all species n press shx shy shz
fix 1 ave/surf all 10 100 1000 c_1[*]
dump 1 surf all 1000 tmp.surf id f_1[*] 
</PRE>
<P>These commands will time-average the force on each surface element
then sum them across element to compute drag (fx) and lift (fy) on the
body:
</P>
<PRE>compute 1 surf all all fx fy
fix 1 ave/surf all 10 100 1000 c_1[*]
compute 2 reduce sum f_1[1] f_1[2]
stats 1000
stats_style step cpu np c_2[1] c_2[2] 
</PRE>
<P><B>Description:</B>
</P>
<P>Define a computation that calculates one or more values for each
explicit surface element in a surface element group, based on the
particles that collide with that element or are emitted from it.  The
values are summed for each group of species in the specified mixture.
See the <A HREF = "mixture.html">mixture</A> command for how a set of species can be
partitioned into groups.  Only surface elements in the surface group
specified by <I>group-ID</I> are included in the calculations.  See the
<A HREF = "group.html">group surf</A> command for info on how surface elements can
be assigned to surface groups.
</P>
<P>This command can only be used for simulations with explicit surface
elements.  See the similar <A HREF = "compute_isurf_grid.html">compute
isurf/grid</A> command for use with simulations
with implicit surface elements.
</P>
<P>Explicit surface elements are triangles for 3d simulations and line
segments for 2d simulations.  Unlike implicit surface elements, each
explicit triangle or line segment may span multiple grid cells.  See
<A HREF = "Section_howto.html#howto_9">Section 4.9</A> of the manual for details.
</P>
<P>Note that when a particle collides with a surface element, it can
bounce off (possibly as a different species), be captured by the
surface (vanish), or a 2nd particle can also be emitted.
Additionally, surface elements can emit particles directly -- see the
<A HREF = "fix_emit_surf.html">fix_emit_surf</A> command doc page.  The formulas
below account for all these possible outcomes.  For example, the
kinetic energy flux <I>ke</I> onto a suface element for a single collision
includes a positive contribution from the incoming particle and
negative contributions from 0, 1, or 2 outgoing particles.  The
exception is the <I>n</I> and <I>nwt</I> values which simply tally counts of
particles colliding with the surface element.
</P>
<P>If the explicit surface element is transparent, the particle will pass
through the surface unaltered.  See the transparent keyword for the
<A HREF = "read_surf.html">read_surf</A> command.  The count of particles going
through the surfacce as well as their mass or energy fluxes can still
be tallied by this compute.  See details on transparent surface
elements below.
</P>
<P>Also note that all values for a collision are tallied based on the
species group of the incident particle.  Quantities associated with
outgoing particles are part of the same tally, even if they are in
different species groups.
</P>
<P>The results of this compute can be used by different commands in
different ways.  The values for a single timestep can be output by the
<A HREF = "dump.html">dump surf</A> command.
</P>
<P>The values over many sampling timesteps can be averaged by the <A HREF = "fix_ave_surf.html">fix
ave/surf</A> command.  It does its averaging as if the
particles striking the surface element at each sampling timestep were
combined together into one large set to compute the formulas below.
The answer is then divided by the number of sampling timesteps if it
is not otherwise normalized by the number of particles.  Note that in
general this is a different normalization than taking the values
produced by the formulas below for a single timestep, summing them
over the sampling timesteps, and then dividing by the number of
sampling steps.  However for the current values listed below, the two
normalization methods are the same.
</P>
<P>NOTE: If particle weighting is enabled via the <A HREF = "global.html">global
weight</A> command, then all of the values below are scaled
by the weight assigned to the grid cell in which the particle
collision with the surface element occurs.  The only exception is the
the <I>n</I> value, which is NOT scaled by the weight; it is a simple count
of particle collisions with the surface element.
</P>
<HR>

<P>The <I>n</I> value counts the number of particles in the group striking the
surface element.
</P>
<P>The <I>nwt</I> value counts the number of particles in the group striking
the surface element and weights the count by the weight assigned to
the grid cell in which the particle collision with the surface element
occurs.  The <I>nwt</I> quantity will only be different than <I>n</I> if
particle weighting is enabled via the <A HREF = "global.html">global weight</A>
command.
</P>
<P>The <I>nflux</I> and <I>nflux_incident</I> values calculate the net and incident
number flux imparted to the surface element by particles in the group
respectively. Incident flux sums over all the impacting particles,
while net flux subtracts out reflected particles and includes effects
from surface chemistry such as particle deletion. These are computed as
</P>
<PRE>Nflux = N / (A * dt / fnum) 
</PRE>
<P>where N is the number of all contributing particles, normalized by
A = the area of the surface element, dt = the timestep, and fnum = the
real/simulated particle ratio set by the <A HREF = "global.html">global fnum</A>
command.
</P>
<P>If the optional <I>norm</I> key is set to <I>flow</I>, then the area A is not
included in the Nflux formula.  The Nflux quantity becomes effectively
a particle flow rate (count per time).  See discussion of the <I>norm</I>
keyword below.
</P>
<P>The <I>mflux</I> and <I>mflux_incident</I> values calculate the net and incident
mass flux imparted to the surface element by particles in the group
respectively.  These are computed as
</P>
<PRE>Mflux = Sum_i (mass_i) / (A * dt / fnum) 
</PRE>
<P>where the sum is over all contributing particle masses, normalized by
the area of the surface element, dt and fnum as defined before.
</P>
<P>If the optional <I>norm</I> key is set to <I>flow</I>, then the area A is not
included in the Nflux formula.  Then Mflux quantity becomes
effectively a mass flow rate (mass per time).  See discussion of the
<I>norm</I> keyword below.
</P>
<P>The <I>fx</I>, <I>fy</I>, <I>fz</I> values calculate the xyz components of force
exerted on the surface element by particles in the group.  These are
computed as
</P>
<PRE>p_delta = mass * (V_post - V_pre)
Fx = - Sum_i (p_delta_x) / (dt / fnum)
Fy = - Sum_i (p_delta_y) / (dt / fnum)
Fz = - Sum_i (p_delta_z) / (dt / fnum) 
</PRE>
<P>where p_delta is the change in momentum of a particle, whose velocity
changes from V_pre to V_post when colliding with the surface element.
The force exerted on the surface element is the sum over all
contributing p_delta, normalized by dt and fnum as defined before.
</P>
<P>The <I>tx</I>, <I>ty</I>, <I>tz</I> values calculate the xyz components of torque Tq
exerted on the entire body by particles in the group colliding with
this surface element.  Use of these values requires the the
center-of-mass (COM) of the body be specified so the torque can be
calculated around the COM.  The COM can be the geometric center of a
triangulated object, or it can reflect an uneven distribution of mass
within the body.  The torque components are computed as
</P>
<PRE>p_delta = mass * (V_post - V_pre)
force = p_delta / (dt / fnum)
R = Xcollide - Xcom
Tq = R x force 
</PRE>
<P>where p_delta is the change in momentum of a particle, whose velocity
changes from V_pre to V_post when colliding with the surface element.
The vector R is from the COM specified by the <I>com</I> keyword Xcollide =
the collision point on the surface.  The force exerted on then the
surface element is the sum over all contributing p_delta, normalized
by dt and fnum as defined before.
</P>
<P>Note that if the surfaces defined in a simulation represent multiple
objects each with their own COM, then you should use this command
multiple times with different surface groups, if you want to
calculate the torque on each object.
</P>
<P>The <I>press</I> value calculates the pressure <I>P</I> exerted on the surface
element in the normal direction by particles in the group, such that
outward pressure is positive.  This is computed as
</P>
<PRE>p_delta = mass * (V_post - V_pre)
P = Sum_i (p_delta_i dot N) / (A * dt / fnum) 
</PRE>
<P>where p_delta, V_pre, V_post, dt, fnum are defined as before.  The
pressure exerted on the surface element is the sum over all
contributing p_delta dotted into the outward normal N of the surface
element, also normalized by A = the area of the surface element.
</P>
<P>The <I>px</I>, <I>py</I>, <I>pz</I> values calculate the normal pressure Px, Py, Pz
extered on the surface element in the direction of its normal by
particles in the group, with respect to the x, y, z coordinate axes.
These are computed as
</P>
<PRE>p_delta = mass * (V_post - V_pre)
p_delta_n = (p_delta dot N) N
Px = - Sum_i (p_delta_n_x) / (A * dt / fnum)
Py = - Sum_i (p_delta_n_y) / (A * dt / fnum)
Pz = - Sum_i (p_delta_n_z) / (A * dt / fnum) 
</PRE>
<P>where p_delta, V_pre, V_post, N, A, and dt are defined as before.
P_delta_n is the normal component of the change in momentum vector
p_delta of a particle.  P_delta_n_x (and y,z) are its x, y, z
components.
</P>
<P>The <I>shx</I>, <I>shy</I>, <I>shz</I> values calculate the shear pressure Sx, Sy, Sz
extered on the surface element in the tangential direction to its
normal by particles in the group, with respect to the x, y, z
coordinate axes.  These are computed as
</P>
<PRE>p_delta = mass * (V_post - V_pre)
p_delta_t = p_delta - (p_delta dot N) N
Sx = - Sum_i (p_delta_t_x) / (A * dt / fnum)
Sy = - Sum_i (p_delta_t_y) / (A * dt / fnum)
Sz = - Sum_i (p_delta_t_z) / (A * dt / fnum) 
</PRE>
<P>where p_delta, V_pre, V_post, N, A, and dt are defined as before.
P_delta_t is the tangential component of the change in momentum vector
p_delta of a particle.  P_delta_t_x (and y,z) are its x, y, z
components.
</P>
<P>The <I>ke</I> value calculates the kinetic energy flux <I>Eflux</I> imparted to
the surface element by particles in the group, such that energy lost
by a particle is a positive flux.  This is computed as
</P>
<PRE>e_delta = 1/2 mass (V_post^2 - V_pre^2)
Eflux = - Sum_i (e_delta) / (A * dt / fnum) 
</PRE>
<P>where e_delta is the kinetic energy change in a particle, whose
velocity changes from V_pre to V_post when colliding with the surface
element.  The energy flux imparted to the surface element is the sum
over all contributing e_delta, normalized by A = the area of the
surface element and dt = the timestep and fnum = the real/simulated
particle ratio set by the <A HREF = "global.html">global fnum</A> command.
</P>
<P>If the optional <I>norm</I> key is set to <I>flow</I>, then the area A is not
included in the Eflux formula.  Then Eflux quantity becomes
effectively an energy flow rate (energy per time).  See discussion of
the <I>norm</I> keyword below.
</P>
<P>The <I>erot</I> value calculates the rotational energy flux <I>Eflux</I>
imparted to the surface element by particles in the group, such that
energy lost by a particle is a positive flux.  This is computed as
</P>
<PRE>e_delta = Erot_post - Erot_pre
Eflux = - Sum_i (e_delta) / (A * dt / fnum) 
</PRE>
<P>where e_delta is the rotational energy change in a particle, whose
internal rotational energy changes from Erot_pre to Erot_post when
colliding with the surface element.  The flux equation is the same as
for the <I>ke</I> value.
</P>
<P>If the optional <I>norm</I> key is set to <I>flow</I>, then the area A is not
included in the Eflux formula.  Then Eflux quantity becomes
effectively an energy flow rate (energy per time).  See discussion of
the <I>norm</I> keyword below.
</P>
<P>The <I>evib</I> value calculates the vibrational energy flux <I>Eflux</I>
imparted to the surface element by particles in the group, such that
energy lost by a particle is a positive flux.  This is computed as
</P>
<PRE>e_delta = Evib_post - Evib_pre
Eflux = - Sum_i (e_delta) / (A * dt / fnum) 
</PRE>
<P>where e_delta is the vibrational energy change in a particle, whose
internal vibrational energy changes from Evib_pre to Evib_post when
colliding with the surface element.  The flux equation is the same as
for the <I>ke</I> value.
</P>
<P>If the optional <I>norm</I> key is set to <I>flow</I>, then the area A is not
included in the Eflux formula.  Then Eflux quantity becomes
effectively an energy flow rate (energy per time).  See discussion of
the <I>norm</I> keyword below.
</P>
<P>The <I>echem</I> value calculates the chemical catalytic energy flux <I>Eflux</I>
imparted to the surface element by particles in the group, such that
energy lost by a particles recombining is a positive flux.  This is computed as
</P>
<P>Eflux = - Sum_i (e_recomb) / (A * dt / fnum)
</P>
<P>where e_recomb is the catalytic chemical energy of a particle pair
(positive for an exothermic recombination reaction). The flux equation
is the same as for the <I>ke</I> value. This option applies only to the
<I>prob</I> style of surface reations. A value of 0.0 will be returned
for other styles of surface reactions, e.g. <I>global</I> and <I>adsorb</I>.
</P>
<P>The <I>etot</I> value calculates the total energy flux imparted to the
surface element by particles in the group, such that energy lost by a
particle is a positive flux.  This is simply the sum of kinetic,
rotational, and vibrational energies.  Thus the total energy flux is
the sum of what is computed by the <I>ke</I>, <I>erot</I>, and <I>evib</I> values.
</P>
<P>If the optional <I>norm</I> key is set to <I>flow</I>, then the area A is not
included in the <I>etot</I> formula.  Then <I>etot</I> quantity becomes
effectively an energy flow rate (energy per time).  See discussion of
the <I>norm</I> keyword below.
</P>
<HR>

<P><B>Transparent surface elements:</B>
</P>
<P>This compute will tally information on particles that pass through
transparent surface elements.  The <A HREF = "Section_howto.html#howto_15">Section
6.15</A> doc page provides an overview of
transparent surfaces and how to create them.
</P>
<P>The <I>n</I> and <I>nwt</I> value are calculated the same for transparent
surfaces as for non-transparent.  I.e. they are the count and weighted
count of particles passing through the surface.
</P>
<P>The <I>nflux</I>, <I>mflux</I>, <I>ke</I>, <I>erot</I>. <I>evib</I>, <I>echem</I>, and <I>etot</I> values are
fluxes.  For transparent surfaces, they are calculated only for the
incident particle as if it had struck the surface.  The outgoing
particle is ignored.  This means the tally quantity is the flux of
particles onto the outward face of the surface.  No tallying is done
for particles hitting the inward face of the transparent surface.  See
<A HREF = "Section_howto.html#howto_15">Section 6.15</A> for how to do tallying in
both directions.
</P>
<P>All the other values are calculated as described above.  This means
they will be zero, since the incident and outgoing particle have the
same mass and velocity.
</P>
<P>IMPORTANT NOTE:
</P>
<P>Transparent surface elements can intersect standard non-transparent
surface elements.  For example, to model flow around a spherical
object, the sphere would be defined by the usual non-transparent
triangles which interact with flow particles.  A plane of transparent
surface elements normal to the flow direction could be defined which
cut through the sphere.  In this case some or all of the transparent
triangles will be partially or wholly inside the sphere.  SPARTA does
not attempt to calculate the portion of a tranparent triangle (or line
segment in 2d) which is inside the flow volume.  The "area" specified
in all the formulas above will be the area of the entire transparent
triangle (or line segment in 2d), which may or may not be what you
want.
</P>
<P>See the optional norm keyword (below) to calculate flux values
un-normalized by the surface element area.  Also see the "sum-area"
and "ave-area" modes of the <A HREF = "compute_reduce.html">compute reduce</A>
command for additional ways to sum or average either normalized or
un-normalized flux values produced by this compute.
</P>
<HR>

<P><B>Optional keywords</B>
</P>
<P>If the <I>norm</I> keyword is used with a setting of <I>flow</I>, then the
formulas above for all flux values will not use the surface element
area A in the denominator.  Specifically these values are nflux,
mflux, ke, erot, evib, etot.
</P>
<P>The formulas thus compute the aggregate mass or energy flow to the
surface (e.g. mass per time), not the flux (e.g. mass per area per
time).
</P>
<P>If the <I>norm</I> keyword setting is <I>flux</I> (the default), then the flux
formulas will be calculated as shown with the area A in the
denominator.
</P>
<P>The <I>com</I> keyword is only used if torque is being computed by any of
the <I>tx</I>, <I>ty</I>, <I>tz</I> values.  The <I>Cx</I>, <I>Cy</I>, <I>Cz</I> settings are the
coordinates of the center-of-mass of the body around which the torque
will be calculated.
</P>
<HR>

<P><B>Output info:</B>
</P>
<P>This compute calculates a per-surf array, with the number of columns
equal to the number of values times the number of groups.  The
ordering of columns is first by values, then by groups.  I.e. if the
<I>n</I> and <I>u</I> values were specified as keywords, then the first two
columns would be <I>n</I> and <I>u</I> for the first group, the 3rd and 4th
columns would be <I>n</I> and <I>u</I> for the second group, etc.
</P>
<P>Surface elements not in the specified <I>group-ID</I> will output zeroes
for all their values.
</P>
<P>The array can be accessed by any command that uses per-surf values
from a compute as input.  See <A HREF = "Section_howto.html#howto_4">Section 6.4</A>
for an overview of SPARTA output options.
</P>
<P>The per-surf array values will be in the <A HREF = "units.html">units</A>
appropriate to the individual values as described above. <I>N</I> is
unitless.  <I>Press</I>, <I>px</I>, <I>py</I>, <I>pz</I>, <I>shx</I>, <I>shy</I>, <I>shz</I> are in in
pressure units.  <I>Ke</I>, <I>erot</I>, <I>evib</I>, <I>echem</I>, and <I>etot</I> are in
energy/area-time units for 3d simulations and energy/length-time units
for 2d simulations.
</P>
<HR>

<P>Styles with a <I>kk</I> 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
<A HREF = "Section_accelerate.html">Accelerating SPARTA</A> 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.
</P>
<P>These accelerated styles are part of the KOKKOS package. They are only
enabled if SPARTA was built with that package.  See the <A HREF = "Section_start.html#start_3">Making
SPARTA</A> section for more info.
</P>
<P>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <A HREF = "Section_start.html#start_7">-suffix command-line
switch</A> when you invoke SPARTA, or you can
use the <A HREF = "suffix.html">suffix</A> command in your input script.
</P>
<P>See the <A HREF = "Section_accelerate.html">Accelerating SPARTA</A> section of the
manual for more instructions on how to use the accelerated styles
effectively.
</P>
<HR>

<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "fix_ave_surf.html">fix ave/surf</A>, <A HREF = "dump.html">dump surf</A>, <A HREF = "compute_isurf_grid.html">compute
isurf/grid</A>
</P>
<P><B>Default:</B>
</P>
<P>The default for the norm keyword is flux.
</P>
</HTML>
