Module fd4_iter_mod


Uses:
    module timing_mod
    module fd4_globaldef_mod
    module fd4_vartab_mod
    module fd4_block_mod
    module fd4_domain_mod
    module rbtree_fd4_block_mod
Types:
    public type fd4_iter
Subroutines and functions:
    public subroutine fd4_iter_init (domain, iter)
    public subroutine fd4_iter_next (iter)
    public logical function fd4_iter_valid (iter)
    public subroutine fd4_iter_offset (iter, offset)
    public subroutine fd4_iter_block_extent (iter, idx, ghosts, bext)
    public subroutine fd4_iter_start_clock (iter)
    public subroutine fd4_iter_stop_clock (iter, fact)
    public subroutine fd4_iter_get (iter, idx, st, aext, array, opt_bext)
    public subroutine fd4_iter_put (iter, idx, st, aext, array)
    public subroutine fd4_iter_get_ghost (iter, idx, st, aext, array, opt_bext)
    public subroutine fd4_iter_get_ghost_multi (iter, idx0, idx1, st, aext, array, opt_bext)
    public subroutine fd4_iter_get_facevar (iter, idx, st, aext, array, opt_bext)
    public subroutine fd4_iter_put_ghost (iter, idx, st, aext, array, dyn)
    public subroutine fd4_iter_empty (iter, idx, st)

Module for an iterator over blocks.

Simple usage example without ghost cells:

   call fd4_iter_init(domain, iter)
   do while(associated(iter%cur))
     ! iter%cur%bnd, iter%cur%pos contain bounds and block position
     ! get one field
     call fd4_iter_get(iter,field_idx,array_ext,array,block_ext)
     ! loop over this block's grid cells
     ! integer(i_k) :: block_ext(0:3) contains actual block size
     do k=1,block_ext(3)
       do j=1,block_ext(2)
         do i=1,block_ext(1)
           ! do some computations with the data at this spatial position
           call compute(array(1:block_ext(0),i,j,k))
         end do
       end do
     end do
     ! put data back to the framework
     call fd4_iter_put(iter,field_idx,array_ext,array)
     ! iterate to next block
     call fd4_iter_next(iter)
   end do

TODO:

Author: Matthias Lieber

See also: module fd4_block_mod


Description of Types

fd4_iter

public type fd4_iter
    type (fd4_domain), pointer :: domain => null ()
    type (fd4_block), pointer :: cur => null ()
    type (rbtree_fd4_block_iterator) :: biter
    integer (kind=i8k) :: time_start = 0
end type fd4_iter
Components:
domain the domain which owns the blocks to iterate
cur current block
biter iterator for block data structure
time_start start time of calculation on current block
This is the block iterator type. You can read the components of the type for fast access, but do not modify them!

Description of Subroutines and Functions

fd4_iter_init

public subroutine fd4_iter_init (domain, iter)
    type (fd4_domain), intent(in), target :: domain
    type (fd4_iter), intent(inout) :: iter
end subroutine fd4_iter_init
Parameters:
domain the domain
iter the iterator
Set iterator to first block of a given domain.

See also: module fd4_domain_mod


fd4_iter_next

public subroutine fd4_iter_next (iter)
    type (fd4_iter), intent(inout) :: iter
end subroutine fd4_iter_next
Parameters:
iter the iterator
Iterate to next block.

CAUTION: This routine will intentionally cause a segmentation violation if the iterator is not valid and verbose level < 3!


fd4_iter_valid

public logical function fd4_iter_valid (iter)
    type (fd4_iter), intent(in) :: iter
end function fd4_iter_valid
Parameters:
iter the iterator
Check if iterator points to block.

Currently, this is equal to

  associated(iter%cur)

fd4_iter_offset

public subroutine fd4_iter_offset (iter, offset)
    type (fd4_iter), intent(in) :: iter
    integer (kind=i_k), intent(out), dimension (3) :: offset
end subroutine fd4_iter_offset
Parameters:
iter the iterator
offset local-to-global offset
Get spatial offset from block local coordinates to global coordinates.

Block local coordinates are starting with 1. This subroutine returns the offset which must be added to the local coordinates to retrieve the global domain coordinates. E.g.:

  global_x = block_x + offset(1)

Currently, the value of offset is:

  iter%cur%bnd(:,1) - 1

CAUTION: This routine will intentionally cause a segmentation violation if the iterator is not valid and verbose level < 3!


fd4_iter_block_extent

public subroutine fd4_iter_block_extent (iter, idx, ghosts, bext)
    type (fd4_iter), intent(in) :: iter
    integer (kind=i_k), intent(in) :: idx
    logical, intent(in) :: ghosts
    integer (kind=i_k), intent(out), dimension (0:3) :: bext
end subroutine fd4_iter_block_extent
Parameters:
iter the iterator
idx field index in vartab
ghosts add ghost cells to extent? (cell-centered vars only)
bext actual extents of the block
Get spatial extent of field idx within current block.

Returns the same bext as the fd4_iter_get-Routines do.


fd4_iter_start_clock

public subroutine fd4_iter_start_clock (iter)
    type (fd4_iter), intent(inout) :: iter
end subroutine fd4_iter_start_clock
Parameters:
iter the iterator
Safe the current time as the starting time of calculations for the current block.

fd4_iter_stop_clock

public subroutine fd4_iter_stop_clock (iter, fact)
    type (fd4_iter), intent(inout) :: iter
    real (kind=r4k), intent(in) :: fact
end subroutine fd4_iter_stop_clock
Parameters:
iter the iterator
fact add the time to block weight (1.0) or replace (0.0)
Get the ending time of calculations for the current block.

Sets the block's weight to the time interval between calls to fd4_iter_start_clock and fd4_iter_stop_clock. The argument fact enables to add the time interval to the block weight (fact=1.0) or replacing the value (fact=0.0). More generally, fact is multiplied to the current weight before adding the time interval.


fd4_iter_get

public subroutine fd4_iter_get (iter, idx, st, aext, array, opt_bext)
    type (fd4_iter), intent(in) :: iter
    integer (kind=i_k), intent(in) :: idx
    integer (kind=i_k), intent(in) :: st
    integer (kind=i_k), intent(in), dimension (0:3) :: aext
    real (kind=r_k), intent(inout), dimension (aext(0),aext(1),aext(2),aext(3)) :: array
    integer (kind=i_k), optional, intent(out), dimension (0:3) :: opt_bext
end subroutine fd4_iter_get
Parameters:
iter the iterator
idx field index in vartab
st time step index
aext extents of the buffer array
array buffer array to write data
opt_bext actual extents of the block written to the buffer array
Get data from the current block.

This is the order of the indices in aext, bext, and array: (bins, x, y, z)

CAUTION: Error checking will be enabled only if verbose level >= 3. If not: Absolutely no checking for error conditions will be carried through! This routine will intentionally cause a segmentation violation if the iterator is not valid, the field idx does not exist, or the array is to small!

TODO:


fd4_iter_put

public subroutine fd4_iter_put (iter, idx, st, aext, array)
    type (fd4_iter), intent(inout) :: iter
    integer (kind=i_k), intent(in) :: idx
    integer (kind=i_k), intent(in) :: st
    integer (kind=i_k), intent(in), dimension (0:3) :: aext
    real (kind=r_k), intent(in), dimension (aext(0),aext(1),aext(2),aext(3)) :: array
end subroutine fd4_iter_put
Parameters:
iter the iterator
idx field index in vartab
st time step index
aext extents of the buffer array
array buffer array to read data
Put data to the current block.

This is the order of the indices in aext, bext, and array: (bins, x, y, z)

CAUTION: Error checking will be enabled only if verbose level >= 3. If not: Absolutely no checking for error conditions will be carried through! This routine will intentionally cause a segmentation violation if the iterator is not valid, the field idx does not exist, or the array is to small!

TODO:


fd4_iter_get_ghost

public subroutine fd4_iter_get_ghost (iter, idx, st, aext, array, opt_bext)
    type (fd4_iter), intent(in) :: iter
    integer (kind=i_k), intent(in) :: idx
    integer (kind=i_k), intent(in) :: st
    integer (kind=i_k), intent(in), dimension (0:3) :: aext
    real (kind=r_k), intent(inout), dimension (aext(0),aext(1),aext(2),aext(3)) :: array
    integer (kind=i_k), optional, intent(out), dimension (0:3) :: opt_bext
end subroutine fd4_iter_get_ghost
Parameters:
iter the iterator
idx field index in vartab
st time step index
aext extents of the buffer array
array buffer array to write data
opt_bext actual extents of the block written to the buffer array
Get data from the current block with boundary.

Sets values at boundaries without neighbor block vnull. The order of the indices in aext, opt_bext, and array is: (bins, x, y, z)

CAUTION: Error checking will be enabled only if verbose level >= 3. If not: Absolutely no checking for error conditions will be carried through! This routine will intentionally cause a segmentation violation if the iterator is not valid, the field idx does not exist, or the array is to small!

TODO:


fd4_iter_get_ghost_multi

public subroutine fd4_iter_get_ghost_multi (iter, idx0, idx1, st, aext, array, opt_bext)
    type (fd4_iter), intent(in) :: iter
    integer (kind=i_k), intent(in) :: idx0
    integer (kind=i_k), intent(in) :: idx1
    integer (kind=i_k), intent(in) :: st
    integer (kind=i_k), intent(in), dimension (0:3) :: aext
    real (kind=r_k), intent(inout), dimension (aext(0),aext(1),aext(2),aext(3)) :: array
    integer (kind=i_k), optional, intent(out), dimension (0:3) :: opt_bext
end subroutine fd4_iter_get_ghost_multi
Parameters:
iter the iterator
idx0 first field index in vartab
idx1 last field index in vartab
st time step index
aext extents of the buffer array
array buffer array to write data
opt_bext actual extents of the block written to the buffer array
Get data from the current block with boundary, multiply variables version.

This is a special version of fd4_iter_get_ghost. Get data from variables idx0 to idx1 (according to variable table) on the same time step st.

Caution: Currently, vnull is taken from variable idx0 for all variables.


fd4_iter_get_facevar

public subroutine fd4_iter_get_facevar (iter, idx, st, aext, array, opt_bext)
    type (fd4_iter), intent(in) :: iter
    integer (kind=i_k), intent(in) :: idx
    integer (kind=i_k), intent(in) :: st
    integer (kind=i_k), intent(in), dimension (0:3) :: aext
    real (kind=r_k), intent(inout), dimension (aext(0),aext(1),aext(2),aext(3)) :: array
    integer (kind=i_k), optional, intent(out), dimension (0:3) :: opt_bext
end subroutine fd4_iter_get_facevar
Parameters:
iter the iterator
idx field index in vartab
st time step index
aext extents of the buffer array
array buffer array to write data
opt_bext actual extents of the block written to the buffer array
Get cell-face data from the current block.

Currently, this routine does exactly the same as fd4_iter_get. This is the order of the indices in aext, bext, and array: (bins, x, y, z)

CAUTION: Error checking will be enabled only if verbose level >= 3. If not: Absolutely no checking for error conditions will be carried through! This routine will intentionally cause a segmentation violation if the iterator is not valid, the field idx does not exist, or the array is to small!

TODO:


fd4_iter_put_ghost

public subroutine fd4_iter_put_ghost (iter, idx, st, aext, array, dyn)
    type (fd4_iter), intent(inout) :: iter
    integer (kind=i_k), intent(in) :: idx
    integer (kind=i_k), intent(in) :: st
    integer (kind=i_k), intent(in), dimension (0:3) :: aext
    real (kind=r_k), intent(in), dimension (aext(0),aext(1),aext(2),aext(3)) :: array
    logical, optional, intent(in) :: dyn
end subroutine fd4_iter_put_ghost
Parameters:
iter the iterator
idx field index in vartab
st time step index
aext extents of the buffer array
array buffer array to read data
dyn do costly checks for dynamic block creation and removal?
Put data with boundary to the current block.

This is the order of the indices in aext, bext, and array: (bins, x, y, z)

CAUTION: Error checking will be enabled only if verbose level >= 3. If not: Absolutely no checking for error conditions will be carried through! This routine will intentionally cause a segmentation violation if the iterator is not valid, the field idx does not exist, or the array is to small!

TODO:


fd4_iter_empty

public subroutine fd4_iter_empty (iter, idx, st)
    type (fd4_iter), intent(inout) :: iter
    integer (kind=i_k), intent(in) :: idx
    integer (kind=i_k), intent(in) :: st
end subroutine fd4_iter_empty
Parameters:
iter the iterator
idx field index in vartab
st time step index
Perform empty check on specified variable. Call this routine if you write values directly in the block data structure without using fd4_iter_put_ghost. The variable must be one with a threshold (vartab%vthres).