FLASH4.5 API

Generated from /asc/asci2/site/flashcode/secure/release_4p5/source/Grid/Grid_fillGuardCells.F90 with ROBODoc v4.99.8 on Tue Mar 05 16:16:16 2019

TABLE OF CONTENTS


[Functions] source/Grid/Grid_fillGuardCells

[top][index]

NAME

  Grid_fillGuardCells

SYNOPSIS

  call Grid_fillGuardCells(integer(IN) :: gridDataStruct,
                           integer(IN) :: idir,
                  optional,integer(IN) :: minLayers,
                  optional,integer(IN) :: eosMode,
                  optional,logical(IN) :: doEos,
                  optional,integer(IN) :: maskSize,
                  optional,logical(IN) :: mask(maskSize),
                  optional,logical(IN) :: makeMaskConsistent,
                  optional,logical(IN) :: doLogMask,
                  optional,integer(IN) :: selectBlockType,
                  optional,logical(IN) :: unitReadsMeshDataOnly)

DESCRIPTION

  This routine fills the guardcells of the specified data structure of 
  each block present in the mesh. If the adjacent blocks are at the same
  level of refinement, then the values are copied from the appropriate
  internal cells of the neighboring block. If the blocks are at different
  levels of refinement, then in addition to copying, there will be 
  restriction or prolongation. 

  The optional arguments related to the Eos calls are provided because if
  a solver relies on a call to Eos to establish thermodynamic equilibrium
  in various variables, then either the solver can call Eos explicitly itself,
  or more conveniently, it can instruct the gcfill process to do it. This 
  feature is especially useful when mesh quantities are used to derive 
  for example tracer particle attributes. 
  
  For performance reason, users may choose to use masking in filling the 
  guardcells, which is feature supported only with Paramesh 4. They can 
  do so by using the optional arguments mask, maskSize and makeMaskConsistent. However, 
  users should exercise extreme caution in using masking. Please see the 
  NOTES section for potential side effects. If masking is present, and 
  both makeMaskConsistent, and doEos are true, the Eos calculation is done only
  if one of the variables selected in the mask is affected by Eos calculation.
  A local routine gr_makeMaskConsistent handles this processing.

  The argument "gridDataStruct" can take on one of many valid 
  values to determine a specific grid data structure on which to apply
  the guardcell fill operation. The currently available options are listed with
  the arguments. Most users will use CENTER as the option,
  since applications typically use the cell centered grid data, and they want
  guardcells to be filled for all the variables. When using AMR with paramesh,
  the function Grid_markRefineDerefine may use the single variable data
  structure provided by paramesh represented by the option "WORK".
  More specialized applications, such as the unsplit methods, may want to use
  other options. 
  The user can also choose to fill guard cells either in a single direction,
  or all of them. For most of the Flash solvers supplied with the release,
  guard cell are filled in all directions.

ARGUMENTS

  gridDataStruct - integer constant, defined in "constants.h", 
                   indicating which grid data structure 
                   variable's guardcells to fill.
                   Paramesh has 5 data structures for grid variables, the first
                   four include all physical variables defined on the mesh. The 
                   fifth one includes a single variable.

                   unk                cell centered, 
                   facex,facey,facez  face centered along i,j,k 
                                      direction respectively
                   work               cell centered, single variable.
                   
                   valid values of gridDataStruct are  
                   CENTER             unk only
                   WORK               work 
                   FACEX              facex
                   FACEY              facey
                   FACEZ              facez
                   FACES              facex,facey, and facez
                   CENTER_FACES     unk,facex,facey,facez

  idir - direction of guardcell fill.  User can specify ALLDIR for all (x,y,z)
         directions, or if for example the algorithm only does one directional
         sweep at a time then time can be saved by filling only the guardcell
         direction that is needed.  A user would pass in the constants defined
         in constants.h IAXIS, JAXIS or KAXIS to fill guardcells in only one 
         direction.        
         All layers of guardcells in the given direction(s) are filled if one
         of IAXIS, JAXIS, or KAXIS is specified, or if ALLDIR is specified
         and minLayers (see below) is not present.

  minLayers - minimum number of guardcell layers requested for all directions.
              The caller requests at least this many layers of
              guardcells to be filled.  If idir is given as one of IAXIS,
              JAXIS, or KAXIS, this applies to any directions NOT selected by
              idir. On the other hand, if idir is given as ALLDIR, then
              minLayers appliers to all directions equally.
              If not specified, the default is 0 if idir is given as IAXIS,
              JAXIS, or KAXIS, meaning no guardcells need to be filled in for
              the directions perpendicular to what idir selects; the default
              is NGUARD, the full number of available guardcells, if idir
              is ALLDIR.
              Note that the caller can specify, using minLayers, how many
              layers it needs filled, but the implementation may do
              more and actually fill all or some additional layers.
              The caller must therefore not rely on some guardcells
              remaining unchanged.
              
              This argument is meaningful with PARAMESH4 only.

   eosMode -  the EOS mode being used by the solver that is calling the 
              routine. The valid values are :
              MODE_DEFAULT     the default eos mode being used by the grid unit
              MODE_DENS_EI     density and energy input, pressure and temp output
              MODE_DENS_PRES   density/pressure input, temperature/energy output
              MODE_DENS_TEMP   density/temperature input, pressure/energy output

  doEos    - a logical variable indicating if the calling routine wants the
             gcfill process to also make sure that Eos is applied to achieve
             thermodynamically consistent values of all variables.
 
             The mask related arguments are useful only with PARAMESH4. They have 
             no meaning in PARAMESH2 and UG.
  maskSize - the size of the mask array. 
 
  mask -  It is a one-dimensional logical array 
          with indices corresponding to variables in the grid data
          structures. If a variable should have its guardcells filled,
          the corresponding element in "mask" is true, otherwise it is
          false.
          The mask is always ignored if the runtime parameter
          enableMaskedGCFill is set .FALSE.
  
 makeMaskConsistent - If true when mask is applied, it is made sure that for
          all the selected variables in the mask, the ones they are dependent
          on are true too. It is also determined whether there is a need to 
          apply Eos if doEos argument is true.

 doLogMask - If present and true when mask is applied, stamp some information
          about masking (and whether Eos is or would be called) to the Logfile.
          Ignored in implementations that do not support variable masking.

  selectBlockType - selects the blocks whose guard cells must be filled
            by block type.

              This argument is ignored in UG Implementations.

              For PARAMESH Grid implementations, recognized values are :

              ALL_BLKS    all local blocks on a processor.
                          This is not valid in all PARAMESH versions.

              ACTIVE_BLKS all currently active blocks, in paramesh
              context that means parent and leaf blocks
              
              LEAF        only LEAF blocks, i.e., bocks whose paramesh
                          node type is 1
            
              These constants are defined in constants.h

       Note that if advance_all_levels is set (in a PARAMESH version
       that implements this global flag), guard cells in all levels of
       blocks are filled anyway.

       Note that the caller can specify, using selectBlockType, which
       blocks it needs filled, but the implementation may do
       more and actually fill guard cells in additional blocks.
       The caller must therefore not rely on guardcells
       in other blocks remaining unchanged.

 unitReadsMeshDataOnly - specifies that the unit calling Grid_fillGuardCells
                         does not update any internal grid data.  This
                         allows us to skip the next guard cell fill because
                         the guard cells already contain up to date data.

EXAMPLE

   #include "Flash.h"
   #include "constants.h"

      call Grid_fillGuardCells( CENTER, IAXIS)

     This call will fill all guardcells for all cell-centered 
     variables in the x direction.
     
 EXAMPLE 2

   #include "Flash.h"
   #include "constants.h"

      call Grid_fillGuardCells( WORK, ALLDIR)
     
     This call fills guardcells along all directions. The operation is applied
     to the WORK data structure available in paramesh only.

SIDE EFFECTS

  After this function returns, all parents of leaf blocks will have current and 
  valid solution data (at least for the variables determined by the gridDataStruct
  and mask dummy arguments). This is because amr_guardcell calls amr_restrict
  internally.  If selectBlockType is used, even more parents of blocks of interest
  may get updated by restriction.

NOTES

  In the default mode, this routine fills guardcells of all the variables
  in the specified data structure. However, if masking is used
  it is possible to fill guardcells of only 
  selected variables. The users must exercise a great deal of caution in 
  using masking in the guardcell filling, since masking out some variables may
  have unintended consequences.  For example if any conserved variable
  is set to true in the mask, density must be true, otherwise the interpolated
  values of the the conserved variable at fine-coarse boundaries will be 
  wrong. It is highly recommended that the argument makeMaskConsistent be set to 
  true when using masking, since that provides error checking for
  the variable sets included in the released solvers. However,  
  these checks may not be enough for new solvers introduced by the users.

  This function, or one of the lower-level functions invoked by it, MUST
  be called (with updated solution data) before child blocks may be removed
  in the course of derefinement! See side effects, above, for the reason.