<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>adapt_grid command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>adapt_grid group-ID action1 action2 style args ... keyword args ... 
</PRE>
<LI>group-ID = group ID for which grid cells adaptation will be attempted on 

<LI>action1 = <I>refine</I> or <I>coarsen</I> 

<LI>action2 = <I>coarsen</I> or <I>refine</I>, optional 

<LI>style = <I>particle</I> or <I>surf</I> or <I>value</I> or <I>random</I> 

<PRE>  <I>particle</I> args = rthresh cthresh
    rcount = threshold in particle count for refinment
    ccount = threshold in particle count for coarsening
  <I>surf</I> arg = surfID ssize
    surfID = group ID for which surface elements to consider
    ssize = do not refine to create cells smaller than ssize (dist units)
            coarsen only if child cells are smaller than ssize (dist units)
  <I>value</I> args = c_ID/c_ID[N]/f_ID/f_ID[N] rthresh cthresh
    c_ID = ID of a compute that calculates a per grid vector, use values from vector
    c_ID[N] = ID of a compute that calculates a per grid array, use values from Nth column of array
    f_ID = ID of a fix that calculates a per grid vector, use vector
    f_ID[N] = ID of a fix that calculates a per grid array, use Nth column of array
    rvalue = threshold in value for refinement
    cvalue = threshold in value for coarsening
  <I>random</I> args = rfrac cfrac
    rfrac = fraction of child cells to refine
    cfrac = fraction of parent cells to coarsen 
</PRE>
<LI>zero or more keyword/args pairs may be appended 

<LI>keyword = <I>iterate</I> or <I>maxlevel</I> or <I>minlevel</I> or <I>thresh</I> or <I>combine</I> or <I>cells</I> or <I>region</I> or <I>dir</I> 

<PRE>  <I>iterate</I> arg = niterate
    niterate = number of iterations of action loop
  <I>maxlevel</I> arg = Nmax
    Nmax = do not refine to create child cells at a level > Nmax
  <I>minlevel</I> arg = Nmin
    Nmin = do not coarsen to create child cells at a level < Nmin
  <I>thresh</I> args = rdecide cdecide
    rdecide = <I>less</I> or <I>more</I> = refine when value is less or more than rvalue
    cdecide = <I>less</I> or <I>more</I> = coarsen when value is less or more than cvalue
  <I>combine</I> arg = <I>sum</I> or <I>min</I> or <I>max</I> = how to combine child values into parent value
  <I>cells</I> args = Nx Ny Nz
    Nx,Ny,Nz = refine a cell into Nx by Ny by Nz child cells
  <I>region</I> args = regID rflag
    regID = ID of region that cells must be inside to be eligible for adaptation
    rflag = <I>all</I> or <I>one</I> or <I>center</I> = what portion of grid cell must be inside
  <I>dir</I> args = Sx Sy Sz
    Sx,Sy,Sz = vector components used with style <I>surf</I> to test surf elements
  <I>file</I> arg = filename
    filename = name of file to write out with new parent grid info 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>adapt_grid all refine particle 50 10
adapt_grid all coarsen particle 50 10
adapt_grid all refine coarsen particle 50 10
adapt_grid all refine surf all 0.15 iterate 1 dir 1 0 0 
adapt_grid all refine coarsen value c_1[1] 5.0 10.0 iterate 2 
</PRE>
<P><B>Description:</B>
</P>
<P>This command perform a one-time adaptation of grid cells within a grid
cell group, either by refinement or coarsening or both.  This command
can be invoked as many times as desired, before or between simulation
runs.  Grid adaptation can also be performed on-the-fly during a
simulation by using the <A HREF = "fix_adapt.html">fix adapt</A> command.
</P>
<P>Refinement means splitting one child cell into multiple new child
cells.  The original child cell disappears, conceptually it becomes a
parent cell.  Coarsening means combining all the child cells of a
parent cell, so that the child cells are deleted and the parent cell
becomes a single new child cell.  See <A HREF = "Section_howto.html#howto_8">Section howto
4.8</A> for a description of the hierarchical
grid used by SPARTA and definitions of child and parent cells.
</P>
<P>Grid adaptation can be useful for adjusting the grid cell sizes to the
current density distribution, or mean-free-path of particles, or to
other simulation attributes such as the presence of surface elements.
A well-adapted grid can improve accuracy of the simulation and/or
reduce a simulation's computational cost.
</P>
<P>Only grid cells in the grid group specified by <I>group-ID</I> are eligible
for refinement.  A parent grid cell is only eligible for coarsening if
all its child cells are in the specified grid group.  See the <A HREF = "group.html">group
grid</A> command for info on how grid cells can be assigned to
grid groups.  Note that the grid group assignment is transferred to
new refined or coarsened cells, so that new cells remain eligible for
adaptation if the adapt_grid command is invoked again or successive
adaptations are performed via the <A HREF = "fix_adapt.html">fix adapt</A> command.
</P>
<P>The <I>action1</I> and <I>action2</I> parameters determine whether refinement or
coarsening is performed and in what order.  <I>Action2</I> is optional.  If
not specified, only <I>action1</I> is performed.  Note that cells which are
refined by <I>action1</I> are not eligible for subsequent coarsening by
<I>action2</I>, during a single invocation of this command.  Likewise cells
that are coarsened by <I>action1</I> are not eligible for subsequent
refinement by <I>action2</I>.  This is also true if the <I>iterate</I> keyword
is used to loop over the two actions multiple times.  Cells can be
successivly refined on each iteration, but will never be coarsened.
Likewise cells can be successivly coarsensed, but will never be
refined.  Of course any cell may be refined or coarsened later if the
adapt_grid command is used again, including on later timesteps via the
<A HREF = "fix_adapt.html">fix adapt</A> command.
</P>
<P>Examples of 2d and 3d refined grids are shown here.  The 3d simulation
shows 2d planar cuts through the 3d grid.  Click on either image for a
larger version.
</P>
<CENTER><A HREF = "JPG/adapt_2d.jpg"><IMG SRC = "JPG/adapt_2d_small.jpg"></A><A HREF = "JPG/adapt_3d.jpg"><IMG SRC = "JPG/adapt_3d_small.jpg"></A>
</CENTER>
<HR>

<P>The first step in a refinement action is to determine what child cells
are eligible for refinement.  Child cells that are wholly inside a
closed surface are not eligible.  The <I>maxlevel</I> and <I>region</I> keywords
also affect eligibility.  They are described below.
</P>
<P>The first step in a coarsening action is to determine what parent
cells are eligible for coarsening.  Only parent cells whose children
are all child cells are eligible.  If one or more of their children
are also parent cells, then the parent cell is a "grandparent" and is
not eligible for coarsening.  The <I>minlevel</I> and <I>region</I> keywords
also affect eligibility.  They are described below.
</P>
<P>The <I>style</I> parameter is then used to decide whether to refine or
coarsen each eligible grid cell.  The operation of the different
styles is described in the next section.  Note that for refinement,
the number of new child cells created withing a single cell is set by
the <I>cells</I> keyword which defaults to 2x2x2 for 3d models and 2x2x1
for 2d models.
</P>
<P>Note that many of the style take an argument for both refinement and
coarsening, e.g. <I>rcount</I> and <I>ccount</I> for style <I>particle</I>.  Both
arguments must be specified, though one or the other will be ignored
if the specified actions do not include refinement or coarsening.
</P>
<HR>

<P>The <I>particle</I> style adapts based on the number of particles in a grid
cell.  For refinement, if the current number (on this timestep) is
more than <I>rcount</I>, the cell is refined.  For coarsening, if the sum
of the current number of particles in all child cells of the parent
cell is less than <I>ccount</I>, the parent cell is coarsened.  Note that
if you wish to use time-averaged counts of particles in each cell you
should use the <I>value</I> style with the ID of a <A HREF = "fix_ave_grid.html">fix
ave/grid</A> command that time-averages particle counts
from the <A HREF = "compute_grid.html">compute grid</A> command.
</P>
<P>The <I>surf</I> style adapts only if a grid cell contains one or more
surface elements in the specified <I>surfID</I> group.  The <I>dir</I> keyword
can be used to exclude additional surface elements.  For refinement,
the cell is refined unless the refinement will create child cells with
any of their dimensions smaller than the specified <I>ssize</I>.  For
coarsening, the parent cell is coarsened only if any of the child cell
dimensions is smaller than the specified <I>ssize</I>.
</P>
<P>The <I>value</I> style uses values calculated by a <A HREF = "compute.html">compute</A>
or <A HREF = "fix.html">fix</A> to decide whether to adapt each cell.  The fix or
compute must calculate per-grid values as described in <A HREF = "Section_howto.html#howto_4">Section howto
4.4</A>.  If the compute or fix calculates a
vector of such values, it is specified as c_ID or f_ID.  If it
calculates an array of such values, it is specified as c_ID[N] or
f_ID[N] when N is the column of values to use, from 1 to Ncolumns.
</P>
<P>For refinement, if the compute or fix value for the grid cell is
"more" than <I>rvalue</I>, the cell is refined.  For coarsening, if the
"sum" of the compute or fix values in all child cells of the parent
cell is "less" than <I>cvalue</I>, the parent cell is coarsened.  The
<I>thresh</I> keyword can be used to change the refinment or coarsening
criteria to "less" versus "more".  Likewise the <I>combine</I> keyword can
be used to change the "sum" of child cell values to be a "min" or
"max" operation.
</P>
<P>Here is an example using particle count as calculated by the <A HREF = "compute_grid.html">compute
grid</A> command as an adaptation criterion.  A cell
will be refined if its count > 25, and a parent cell coarsened if
the sum of its children cell counts < 10.
</P>
<PRE>compute 1 grid all n nrho
adapt_grid refine coarsen value c_1[1] 25 10 
</PRE>
<P>The same thing could be accomplished with this command:
</P>
<PRE>adapt_grid refine coarsen particle 25 10 
</PRE>
<P>These commands use a time-averaged particle count as an adaptation
criterion in the same manner:
</P>
<PRE>compute 1 grid all n nrho
fix 1 ave/grid 10 100 1000 c_1[1]
run 1000    # run to accumulate time averages
adapt_grid refine coarsen value f_1[1] 25 10 
</PRE>
<P>Here is an example using mean-free path (MFP) as calculated by the
<A HREF = "compute_lambda_grid.html">compute lambda/grid</A> command as an
adaptation criterion.  Note the use of "thresh less more" to refine
when MFP is less than the specified threshold (0.05).
</P>
<PRE>compute 1 lambda/grid f_1[2] NULL N2 kall
adapt_grid refine coarsen value c_1[2] 0.05 0.1 &
           combine min thresh less more 
</PRE>
<P>The <I>random</I> style is provided for test and debugging purposes.  For
each cell eligible for adaptation, a uniform random number RN bewteen
0.0 and 1.0 is generated.  For refinement, the cell is refined if RN <
<I>rfrac</I>, so that approximately an <I>rfrac</I> fraction of the child cells
are refined.  Similarly, for coarsening, the parent cell is coarsened
if RN < <I>cfrac</I>, so that approximately a <I>cfrac</I> fraction of the
parent cells are coarsened.
</P>
<HR>

<P>Various optional keywords can also be specified.
</P>
<P>The <I>iterate</I> keyword determines how many times the <I>action1</I> and
<I>action2</I> operations are looped over.  The default is once.  If
multiple iterations are used, cells can be recursively refined or
coarsened.  If no further refinement or coarsening occurs on an
iteration, the loop ends.  Note that the compute used with style
<I>value</I> will be recalculated at each iteration to accurately reflect
per grid values for the current grid.
</P>
<P>The <I>maxlevel</I> keyword limits how far a grid cell can be refined.  See
<A HREF = "Section_howto.html#howto_8">Section howto 4.8</A> for a definition of the
level assigned to each parent and child cell.  Child cells with a
level >= <I>Nmax</I> are not eligible for refinement.  The default setting
of <I>Nmax</I> = 0 means there is no limit on refinement.
</P>
<P>The <I>minlevel</I> keyword limits how far a grid cell can be coarsened.
See <A HREF = "Section_howto.html#howto_8">Section howto 4.8</A> for a definition of
the level assigned to each parent and child cell.  Parent cells with a
level < <I>Nmin</I> are not eligible for coarsening.  The default setting
of <I>Nmin</I> = 1 means the only limit on coarsening is that the first
level grid is preserved (never coarsened to a single root cell).  The
specified <I>Nmin</I> must be >= 1.
</P>
<P>The <I>thresh</I> keyword is only used by style <I>value</I>.  It sets the
comparison criterion for refinement as <I>rdecide</I> = <I>less</I> or <I>more</I>.
This means a child cell is refined if its compute or fix value is
<I>less</I> or <I>more</I> than <I>rvalue</I>.  Similarly, it sets the comparison
criterion for coarsening as <I>cdecide</I> = <I>less</I> or <I>more</I>.  This means
a parent cell is coarsened if the compute or fix value accumulated
from the compute or fix values of its children is <I>less</I> or <I>more</I>
than <I>cvalue</I>.
</P>
<P>The <I>combine</I> keyword is only used by style <I>value</I>.  It determines
how the compute or fix value for a parent cell is accumulated from the
compute or fix values of all its children.  If the setting is <I>sum</I>,
the child values are summed.  If it is <I>min</I> or <I>max</I>, the parent
value is the minimum or maximum of all the child values.
</P>
<P>The <I>cells</I> keyword determines how many new child cells are created
when a single grid cell is refined.  Nx by Ny by Nz new child cells
are created.  <I>Nz</I> must be one for 2d.  Any of Nx, Ny, Nz may have a
value of 1, but they cannot all be 1.
</P>
<P>The <I>region</I> keyword can be used to limit which grid cells are
eligible for adapation.  It applies to both child cells for refinment
and parent cells for coarsening.  The ID of the geometric region is
speficied as <I>regID</I>.  See the <A HREF = "region.html">region</A> command for
details on what kind of geometric regions can be defined.  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>The grid cell must be in the region to be eligible for adaptation.
The <I>rflag</I> setting determines how a grid cell is judged to be in the
region or not.  For <I>rflag</I> = <I>one</I>, it is in the region if any of its
corner points (4 for 2d, 8 for 3d) is in the region.  For <I>rflag</I> =
<I>all</I>, all its corner points must be in the region.  For <I>rflag</I> =
<I>center</I>, the center point of the grid cell must be in the region.
</P>
<P>The <I>dir</I> keyword is only used by the style <I>surf</I>.  The Sx,Sy,Sz
settings are components of a vector.  It's length does not matter,
just its direction.  Only surface elements whose normal is opposed to
the vector direction (in a dot product sense) are eligible surfaces
for the adapation procedure described above for the <I>surf</I> style.
This can be useful to exclude refinement around surface elements that
are not facing "upwind" with respect to the flow direction of the
particles.  This is accomplished by setting Sx,Sy,Sz to the flow
direction.  If Sy,Sy,Sz = (0,0,0), which is the default, then no
surface elements are excluded.
</P>
<P>The <I>file</I> keyword triggers output of the adapted grid to the
specified <I>filename</I>.  The format of the file is the same as that
created by the <A HREF = "write_grid.html">write_grid</A> command, which is a list
of parent cells.  The file can be read in by a subsequent simulation
to define a grid, or used by visualization or other post-procesing
tools.  Note that no file is written if no grid cells are refined or
coarsened.
</P>
<P>If the filename contains a "*" wildcard character, then the "*" is
replaced by the current timestep.  This is useful for the <A HREF = "fix_adapt.html">fix
adapt</A> command, if you wish to write out multiple grid
files, each time the grid iadapts.
</P>
<HR>

<P>If the grid is partitioned across processors in a "clumped" manner
before this command is invoked, it will still be clumped by processor
after the adaptation.  Likewise if it is not clumped before, it will
remain un-clumped after adaptation.  See <A HREF = "Section_howto.html#howto_8">Section howto
4.8</A> for a description clumped and
unclumped grids.
</P>
<P>If you want the grid partitioning (and their particles) to be
rebalanced across processors after grid adaptation, you can use the
<A HREF = "balance_grid.html">balance_grid</A> command after this command.
</P>
<P><B>Restrictions:</B>
</P>
<P>This command can only be used after the grid has been created by the
<A HREF = "create_grid.html">create_grid</A>, <A HREF = "read_grid">read_grid</A>, or
<A HREF = "read_restart.html">read_restart</A> commands.
</P>
<P>Currently a fix cannot be used with style <I>value</I> for <I>iterate</I> > 1.
This is because the per-grid cell values accumulated by the fix are
not interpolated to new grid cells so that the fix can be re-evaluated
multiple times.  In the future we may revove this restriction.
</P>
<P>Currently, if there are custom attributes defined for grid cells, grid
adaptation does not set new values for new grid cells created when
either refinement or coarsening takes place.  The new cells will have
zero values for their attributes.  This is because there is no simple
way to determine how new attribute values should be computed.  This
may be changed in the future.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "fix_adapt.html">fix adapt</A>, <A HREF = "balance_grid.html">balance_grid</A>
</P>
<P><B>Default:</B>
</P>
<P>The keyword defaults are iterate = 1, minlevel = 1, maxlevel = 0,
thresh = more for rdecide and less for cdecide, combine = sum, cells =
2 2 2 for 3d and 2 2 1 for 2d, no region, dir = 0 0 0, and no file.
</P>
</HTML>
