Flash Variable Database

Subroutines and Functions:
dBaseGetData
dBasePutData
dBaseGetCoords
dBasePutCoords
dBaseGetBoundaryFluxes
dBasePutBoundaryFluxes
dBaseKeyNumber
dBaseSpecies
dBaseVarName
dBasePropertyInteger
dBasePropertyReal
dBaseSetProperty
dBaseVarIndex
Various Pointer Returning Functions
The Tree Interface Functions

Subroutines:
dBaseGetData
dBasePutData
dBaseGetData([variable, [direction, [q1, [q2, [q3,]]]]] block, storage)
dBasePutData([variable, [direction, [q1, [q2, [q3,]]]]] block, storage)
Files:
source/database/common-interfaces.f90
source/database/common-databyname.f90
source/database/common-databypointer.f90
Description:
Data exchange with grid variables. All variables registered with the framework
via the VARIABLE keywords within a Module Config file can be read/written with
this pair of functions. The data is assumed to be composed of one or more structured
blocks each with an integer block id = [1,num_blocks], where num_blocks is the total
number of blocks on a given processor.
Example:
Given a config file with the following variable registration specification:
VARIABLE dens
the variable dens can be accessed from within FLASH as, for example:
real, dimension(nxb,nyb,nzb) :: density
do this_block = 1, total_blocks
call dBaseGetData("dens", this_block, density)
call foo(density)
end do
Arguments:

character
integer variable variable name;
if given as string it should match Config description;
if not present all variables will be exchanged

character
integer direction specifies the shape of the data
and how q1, q2, q3 should be interpreted;
if not present whole variable will be exchanged

integer q1, q2, q3 coordinated of data exchanged in order i-j-k ;
for vectors (q1,q2) = (i,j), (j,k), or (i,k)

integer block integer block id on a given processor specifying the patch of data to access.

real storage
storage(:)
storage(:,:)
storage(:,:,:) allocated storage to recieve result.
rank and shape of the storage array should match the rank and shape of data taken or put

Strings:

direction = "xyPlane"
"xzPlane"
"yzPlane"
"yxPlane"
"zxPlane"
"zyPlane"
"xVector"
"yVector"
"zVector"
"Point"

Integers:
Integers for variables and directions are not publicly available, but can be accessed through dBaseKeyNumber .
Note:
The "xyzCube" keyword is obsolete. When direction keyword is not specified, whole variable will be exchanged. When, in addition, variable keyword is omitted all variables for the block will be exchanged.

Subroutines:
dBaseGetCoords
dBasePutCoords
dBaseGetCoords(variable, direction, [q,] block, storage)
dBasePutCoords(variable, direction, [q,] block, storage)
Files:
source/database/common-interfaces.f90
source/database/common-coordsbyname.f90
source/database/common-ccordsbypointer.f90
Description:
Access global coordinate information for a given block, including ghost points.
Example:
real, DIMENSION(block_size) :: xCoords, data
do i = 1, lnblocks
   call dBaseGetCoords("zn", "xCoord", i, xCoords)
   call dBaseGetData("dens", "xVector", 0, 0, i, data)
   call foo(data,xCoords)
enddo

Arguments:

character
integer variable specifies position of coord relative to block: left,
right, or center (see below).

character
integer direction specifies x-, y-, or z-coordinate

integer q allows to get/put a single point

integer block integer block id on a given processor specifying the patch of data to access.

real storage
storage(:) allocated storage to receive result

Strings:

direction = "xCoord"
"yCoord"
"zCoord" coord position = "znl" : left block boundary
"zn" : block center
"znr" : right block boundary
"znl0": ??
"znr0": ??
"ugrid": ??

Integers:
Integers for variables and directions are not publicly available, but can be accessed through dBaseKeyNumber .

Subroutines:
dBaseGetBoundaryFluxes
dBasePutBoundaryFluxes
dBaseGetBoundaryFluxes(time_context, position, direction, block, storage)
dBasePutBoundaryFluxes(time_context, position, direction, block, storage)
File:
source/database/common-boundaryData.f90
Description:
Access boundary fluxes for all flux variables on a specified block associated with a given time-level. Currently,
only the current and previous time-step are supported.
Example:
       real, dimension(nfluxes,ny,nz): xl_bound_fluxes, xr_bound_fluxes
        do this_block = 1, num_blocks
           call dBaseGetBoundaryFluxes(0,0,"xCoord", this_block, xl_bound_fluxes)
           call dBaseGetBoundaryFluxes(0,1,"xCoord", this_block, xr_bound_fluxes)
           call foo(xl_bound_fluxes, xr_bound_fluxes)
           call dBasePutBondaryFluxes(0,0,"xCoord",this_block,xl_bound_fluxes)
           call dBasePutBondaryFluxes(0,1,"xCoord",this_block,xl_bound_fluxes)
        end do

Arguments:

integer time_context specifies fluxes stored at current or previous time-step

integer position specifies left or right boundary in a given direction

character direction specifies x-, y-, or z-coordinate

integer block integer block id on a given processor specifying the patch of data to access.

real storage(:,:,:) return buffer of size nFluxes * dim1 * dim2

Strings:

direction = "xCoord"
"yCoord"
"zCoord"

Integers:
   time_context =    -1 (previous time-step)
                                   0 (current time-step)

position = 0 (left)
1 (right)

Function:
dBaseKeyNumber
dBaseKeyNumber(keyname)
Files:
source/database/common-keynumber.f90
Description:
For faster performance, dBase Get/Put Data/Coords can be called with integer arguments instead
of strings. Each of the string arugments accepted by the Get/Put functions can be replaced by a
corresponding integer. However, these integers are not publicly available. To obtain them, one must
call dBaseKeyNumber.

Example:
   integer :: idens, ixCoord
   idens = dBaseKeyNumber("dens"
   ixCoord = dBaseKeyNumber("xCoord")
   call dBasePutData(idens, ixCoord, block_no, data)

Arguments and return type:

character keyname string with "variable" or "direction" name, as in get/put data/coords;
names of variables must match Config description

integer dBaseKeyNumber integer assinged for the string key name

Strings:

keyname = "xyzCube"
"xyPlane"
"xzPlane"
"yzPlane"
"yxPlane"
"zxPlane"
"zyPlane"
"xVector"
"yVector"
"zVector"
"Point" "RefineVariable1"
"RefineVariable2"
"RefineVariable3"
"RefineVariable4"
"xCoord"
"yCoord"
"zCoord" "OldTemp"
"Shock"
"znl"
"zn"
"znr"
"znl0"
"znr0"
"ugrid" "rhoflx"
"uflx"
"pflx"
"utflx"
"uttflx"
"eflx"
"eintflx"
"nucflx_begin"

Function:
dBaseSpecies
dBaseSpecies(index)
File:
source/database/common-keynumber.f90
Description:
Maps species number (from one to maximum number of species) to variable number (actual index in "unk" array).
Arguments and return type :

integer index species number from one to maximum number of species

integer dBaseSpecies actual index in "unk" array

Function:
dBaseVarName
dBaseVarName(keynumber)
File:
source/database/common-keynumber.f90
Description:
given a keyNumber, return the associated variable name.
Example:
   integer :: idens
   char(len = 4) :: name
   idens = dBaseKeyNumber("dens")
   name = dBaseVarName(idens)     ! name now = "dens"
Arguments and return type :

integer keynumber variable keynumber obtained with
call to dBaseKeyNumber

character(len = 4) dBaseVarName string name of variable as defined in Config;
if variable does not exist returns "null"

Function:
dBasePropertyInteger
dBasePropertyInteger(property)
File:
source/database/common-properties.f90
Description:
Accessor methods for integer-valued scalars variables.

Arguments and return type:

character property string with variable name, see below

integer dBasePropertyInteger property value

Strings:

property = "Dimensionality"
   dimension of problem defined at setup
"NumberOfVariables"
   total number of solution variables for a given problem
"NumberOfSpecies"
   number of nuclear species defined for a a given problem.
"NumberOfGuardCells"
   width of ghost-cell region on each boundary of a block.
"NumberOfFluxes"
   total number of fluxes defined for a given problem.
"NumberOfNamedVariables"
   total number of solution variables for a given problem
   excluding nuclear abunducances.
"NumberOfAdvectVariables"
   total number of variables with the ADVECT attribute for a given problem
"NumberOfRenormVariables"
   total number of variables with the RENORM attribute for a given problem
"NumberOfConserveVariables"
   total number of variables with the CONSERVE attribute for a given problem.
"MaxNumberOfBlocks"
   total number of allocated blocks on a given processor. May be > number
   of blocks currently defined in the AMR hierarchy, since block memory
   is allocated statically.
"LocalNumberOfBlocks"
   total number of blocks on a given processor.
"MaxBlocks_tr"
   statically allocated buffer size for work arrays
"NumberOfGuards_work"
   guardcells for scratch array.
"xDimensionExists"
   value of 1 if x-Dimension is defined for given problem, 0 otherwise.
"yDimensionExists"
   value of 1 if y-Dimension is defined for given problem, 0 otherwise.
"zDimensionExists"
   value of 1 if z-Dimension is defined for given problem, 0 otherwise.
"xBlockSize"
    number of points in x-direction for AMR blocks, excluding ghost points.
"yBlockSize"
    number of points in x-direction for AMR blocks, excluding ghost points.
"zBlocksize"
    number of points in x-direction for AMR blocks, excluding ghost points.
"xLowerBound"
    begin x-index of a block (including ghost points)
"yLowerBound"
    begin y-index of a block (including ghost points)
"zLowerBound"
    begin z-index of a block (including ghost points)
"xUpperBound"
    end x-index of a block (including ghost points)
"yUpperBound"
    end y-index of a block (including ghost points)
"zUpperBound"
    end z-index of a block (including ghost points)
"CurrentStepNumber"
    current time-step
"BeginStepNumber"
    initial time-step
"MyProcessor"
    local processor id
"MasterProcessor"
    master processor id
"NumberOfProsessors"
    total number of processors

Function:
dBasePropertyReal
dBasePropertyReal(property)
File:
source/database/common-properties.f90
Description:
Accessor methods for real-valued scalar variables.
Arguments and return type:

character property string with variable name, see below

integer dBasePropertyReal property value

Strings:

property = "Time"
   current value of the simulation time
"TimeStep"
   Curent value of the simulation timestep

Subroutine:
dBaseSetProperty
dBaseSetProperty(property, value)
File:
source/database/common-properties.f90
Description:
Mutator methods for writeable scalar variables. See dBasePropertyInteger/Real for documentation
on property names.
Arguments:

character property string with variable name

integer
real value new property value

Strings:

property = "CurrentStepNumber"
"BeginStepNumber"
"MyProcessor"
"MasterProcessor"
"NumberOfProsessors"
"Time"
"TimeStep"

Function:
dBaseVarIndex
dBaseVarIndex(property)
File:
source/database/common-properties.f90
Description:
Returns pointer to array of integer keys of variables with specified property.
Arguments and return type:

character property string with property name, see below

integer, POINTER, DIMENSION(:) dBaseVarIndex pointer to array of unk indexes of variables with given property

Strings:

property = "advect"
"renorm"
"conserve"

Various Pointer Returning Functions
dBaseGetDataPtrAllBlocks()
return an f90 pointer to the left-hand-side solution vector for all blocks on a given processor, arranged in
row-major order as: (var,nx,ny,nz,block). dBaseKeyNumber must still be called to access the proper elements of
the array.
dBaseGetDataPtrSingleBlock(block_no)
    return an f90 pointer to the left-hand-side solution vector on a specified block, arranged as (var,nx,ny,nz).
dBaseGetPtrToXCoords()
    return an f90 pointer to an array containing information on the x-coords of the AMR blocks. the array returned is arranged as
    (block_position, i, block_number), where block_position values denote center, left, or right coordinates, and are obtained by calling
    dBaseKeyNumber with "zn", "znl", "znr" and using the corresponding index to access the approriate row in the array.
    example:
        real, pointer, dimension(:,:,:) :: xCoords
        real :: x, xl, xr
        integer :: izn, iznl, iznr
        izn = dBaseKeyNumber("izn")
        iznl = dBaseKeyNumber("iznl")
        iznr = dBaseKeyNumber("iznr")
        xCoord => dBaseGetPtrToXCoords()
        do this_block = 1, num_blocks
           do i = 1, blocksize
             x = xCoord(izn, i, block_no)     ! get first center coord
             xl = xCoord(iznl, i, block_no)   ! get first left coord
             xr = xCoord(iznr, i, block_no)   ! get first right coord
              ...
dBaseGetPtrToYCoords()
      see above.
dBaseGetPtrToZCoords()
      see above.
dBaseGetScratchPtrAllBlocks()
       Return an f90 pointer to a scratch array of size (2, nxb, nyb, nzb, maxblocks).
dBaseGetScratchPtrSingleBlock(block_no)
       Return an f90 pointer to a scratch array of size(2, nxb, nyb, nzb).
General Comments:
Each of these functions allows FLASH developers to hook directly into an internal data structure in the database. In general these functions will offer better performance then their corresponding dBaseGet/Put counterparts, and will require less memory overhead. However, the interfaces are more complicated and the functions are less flexible, and less safe, so it is suggested that developers strongly consider using dBaseGet/PutData when performance differences are small.
Each function above returns an f90 pointer to the solution vector on specified block. If no block is specified, a pointer is returned to all blocks on the calling processor. Currently layout is assumed to be (var,nx,ny,nz,block) in row-major ordering. Scratch (unksm) array stores variables with no guardcells this name should probably be changed in the future.
Argument and return type:

integer block

real, DIMENSION( :,:,:,:,: ), POINTER dBaseGetDataPtrAllBlocks

real, DIMENSION( :,:,:,: ),    POINTER dBaseGetDataPtrSingleBlock

real, DIMENSION( :,:,: ),        POINTER dBaseGetPtrToXCoords

real, DIMENSION( :,:,: ),        POINTER dBaseGetPtrToYCoords

real, DIMENSION( :,:,: ),        POINTER dBaseGetPtrToZCoords

real, DIMENSION( :,:,:,:,: ), POINTER dBaseGetScratchPtrAllBlocks

real, DIMENSION( :,:,:,: ),     POINTER dBaseGetScratchPtrSingleBlock

The Tree Interface Functions
dBaseNeighborBlockList (block)
given a block id, return an array of block id's which are the neighbors of the specified block.
The returned array is of size max_faces = 6, but not all of the six elements will have meaningful
values if the problem is run in fewer than three dimensions. Assuming the function is called as
NEIGH = dBaseNeighborBlockList, the ordering is as follows:
The neighbor on the lower x face of block L is at NEIGH(1,L), the neighbor on the upper x
face at NEIGH(2,L), the lower y face at NEIGH(3,L), the upper y face at NEIGH(4,L),
the lower z face at NEIGH(5,L) and the upper z face at NEIGH(6,L). If any of these values
are set to -1 or lower, there is no to this block at this refinement level. However there may be a
neighbor to this blocks parent. If the value is -20 or lower then this face represents an external
boundary, and the user is required to apply some boundary condition on this face. The exact value
below -20 can be used to distinguish between the different boundary conditions which the user may
wish to implement.

dbaseNeighborBlockProcList (block)
    given a block id, return an array of size max_faces = 6 elements containing processor id's identifying the processor that a
    given neighbor resides on. Ordering is identical to dBaseNeighborBlockList..
dBaseChildBlockList (block)
given a block id, return an array of size max_child = 2^max_dim elements containing the block id's of
the children blocks of the specified block. The children of a parent are numbered according to the
fortran array ordering convention, ie child 1 is at the lower x, y and z corner of the parent, child 2
at the higher x coordinate but lower y and z, child 3 at lower x, higher y and lower z, child 4 at higher x
and y and lower z, and so on.
dBaseChildBlockProcList (block)
given a block id, return an array of size max_child elements containing processor id's of the children
of the pecified block. Ordering is identical to dBaseChildBlockList.
dBaseParentBlockList (block)
given a block id, return the id of the block's parent block.
dBaseParentBlockProcList (block)
given a block id, return the processor id upon which the block's parent resides.
dBaseRefinementLevel (block)
   given a block id, return that block id's integer level of refinement.
dBaseNodeType (block)
   given a block id, return the id's node type.
   if 1 then the node is a leaf node, if 2 then the node is a parent but
   with at least 1 leaf child, otherwise it is set to 3 and it does not
   have any up-to-date data.

dbaseNeighborType (block)
   given a block id, return an array of size (mfaces, maxblocks_tr), containing
   the type id's of the neighbors of the specified block. mfaces = maxblocks_tr * 3,
   where maxblocks_tr is a statically defined public variable in dBase.
dBaseBlockCoord (block)
   given a block id, return an array of size ndim containing the x,y,z coordinates
   of the center of the block.
dBaseBlockSize (block)
   given a block id, return an array of size ndim containing the block size in the
   x, y, and z directions.

dBaseRefine (block)
   given a block id, return .true. if that block is set for refinement in the next
   call to amr_refine_derefine, and .false. otherwise.
dBaseDeRefine (block)
   given a block id, return .true. if that block is set for refinement in the next
   call to amr_refine_derefine, and .false. otherwise.
dBaseNotRefine (block)
    ??
File:
source/database/common-tree.fh
Description:
Interface for the tree data structures and box geometries, currently defined in "tree.fh".
Arguunent and return type:

integer block

integer, DIMENSION (mfaces) dBaseNeighborBlockList

integer, DIMENSION (mfaces) dbaseNeighborBlockProcList

integer, DIMENSION (mchild) dBaseChildBlockList

integer, DIMENSION (mchild) dBaseChildBlockProcList

integer dBaseParentBlockList

integer dBaseParentBlockProcList

integer dBaseRefinementLevel

integer, DIMENSION (nfaces) dbaseNeighborType

real, DIMENSION (mdim) dBaseBlockCoord

real, DIMENSION (mdim) dBaseBlockSize

integer dBaseNodeType

logical dBaseRefine

logical dBaseDeRefine

logical dBaseNotRefine

Last modified: 16 October 2001

Flash Variable Database

dBaseGetData
dBasePutData

dBaseGetCoords
dBasePutCoords

dBaseGetBoundaryFluxes
dBasePutBoundaryFluxes

dBaseKeyNumber

dBaseSpecies

dBaseVarName

dBasePropertyInteger

dBasePropertyReal

dBaseSetProperty

dBaseVarIndex

Various Pointer Returning Functions

The Tree Interface Functions

character integer	`variable`	variable name; if given as string it should match Config description; if not present all variables will be exchanged
character integer	`direction`	specifies the shape of the data and how `q1, q2, q3` should be interpreted; if not present whole variable will be exchanged
integer	`q1, q2, q3`	coordinated of data exchanged in order `i-j-k` ; for vectors `(q1,q2) = (i,j), (j,k),` or `(i,k)`
integer	`block`	integer block id on a given processor specifying the patch of data to access.
real	`storage` `storage(:)` `storage(:,:)` `storage(:,:,:)`	allocated storage to recieve result. rank and shape of the storage array should match the rank and shape of data taken or put

character integer	`variable`	specifies position of coord relative to block: left, right, or center (see below).
character integer	`direction`	specifies x-, y-, or z-coordinate
integer	`q`	allows to get/put a single point
integer	`block`	integer block id on a given processor specifying the patch of data to access.
real	`storage` `storage(:)`	allocated storage to receive result

integer	`time_context`	specifies fluxes stored at current or previous time-step
integer	position	specifies left or right boundary in a given direction
character	`direction`	specifies x-, y-, or z-coordinate
integer	`block`	integer block id on a given processor specifying the patch of data to access.
real	`storage(:,:,:)`	return buffer of size nFluxes * dim1 * dim2

character	`keyname`	string with "variable" or "direction" name, as in get/put data/coords; names of variables must match Config description
integer	`dBaseKeyNumber`	integer assinged for the string key name

integer	`index`	species number from one to maximum number of species
integer	`dBaseSpecies`	actual index in "unk" array

integer	`keynumber`	variable keynumber obtained with call to dBaseKeyNumber
character(len = 4)	`dBaseVarName`	string name of variable as defined in Config; if variable does not exist returns `"null"`

character	`property`	string with variable name, see below
integer	`dBasePropertyInteger`	property value

character	`property`	string with variable name
integer real	`value`	new property value

character	`property`	string with property name, see below
integer, POINTER, DIMENSION(:)	`dBaseVarIndex`	pointer to array of unk indexes of variables with given property

integer	`block`
real, DIMENSION( `:,:,:,:,:` ), POINTER	`dBaseGetDataPtrAllBlocks`
real, DIMENSION( `:,:,:,:` ), POINTER	`dBaseGetDataPtrSingleBlock`
real, DIMENSION( `:,:,:` ), POINTER	`dBaseGetPtrToXCoords`
real, DIMENSION( `:,:,:` ), POINTER	`dBaseGetPtrToYCoords`
real, DIMENSION( `:,:,:` ), POINTER	`dBaseGetPtrToZCoords`
real, DIMENSION( `:,:,:,:,:` ), POINTER	`dBaseGetScratchPtrAllBlocks`
real, DIMENSION( `:,:,:,:` ), POINTER	`dBaseGetScratchPtrSingleBlock`

integer	`block`
integer, DIMENSION (`mfaces`)	`dBaseNeighborBlockList`
integer, DIMENSION (`mfaces`)	`dbaseNeighborBlockProcList`
integer, DIMENSION (`mchild`)	`dBaseChildBlockList`
integer, DIMENSION (`mchild`)	`dBaseChildBlockProcList`
integer	`dBaseParentBlockList`
integer	`dBaseParentBlockProcList`
integer	`dBaseRefinementLevel`
integer, DIMENSION (`nfaces`)	`dbaseNeighborType`
real, DIMENSION (`mdim`)	`dBaseBlockCoord`
real, DIMENSION (`mdim`)	`dBaseBlockSize`
integer	`dBaseNodeType`
logical	`dBaseRefine`
logical	`dBaseDeRefine`
logical	`dBaseNotRefine`

Flash Variable Database

dBaseGetData dBasePutData

dBaseGetCoords dBasePutCoords

dBaseGetBoundaryFluxes dBasePutBoundaryFluxes

dBaseKeyNumber

dBaseSpecies

dBaseVarName

dBasePropertyInteger

dBasePropertyReal

dBaseSetProperty

dBaseVarIndex

Various Pointer Returning Functions

The Tree Interface Functions

dBaseGetData
dBasePutData

dBaseGetCoords
dBasePutCoords

dBaseGetBoundaryFluxes
dBasePutBoundaryFluxes