SWE
Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes
SWE_Block Class Reference

#include <SWE_Block.hh>

Inheritance diagram for SWE_Block:
SWE_BlockCUDA SWE_RusanovBlock SWE_WavePropagationBlock SWE_RusanovBlockCUDA SWE_WavePropagationBlockCuda

List of all members.

Public Member Functions

void initScenario (float _offsetX, float _offsetY, SWE_Scenario &i_scenario, const bool i_multipleBlocks=false)
 initialise unknowns to a specific scenario:
void setWaterHeight (float(*_h)(float, float))
 set the water height according to a given function
void setDischarge (float(*_u)(float, float), float(*_v)(float, float))
 set the momentum/discharge according to the provided functions
void setBathymetry (float _b)
 set the bathymetry to a uniform value
void setBathymetry (float(*_b)(float, float))
 set the bathymetry according to a given function
const Float2DgetWaterHeight ()
 provides read access to the water height array
const Float2DgetDischarge_hu ()
 provides read access to the momentum/discharge array (x-component)
const Float2DgetDischarge_hv ()
 provides read access to the momentum/discharge array (y-component)
const Float2DgetBathymetry ()
 provides read access to the bathymetry data
void setBoundaryType (BoundaryEdge edge, BoundaryType boundtype, const SWE_Block1D *inflow=NULL)
 set type of boundary condition for the specified boundary
virtual SWE_Block1DregisterCopyLayer (BoundaryEdge edge)
 return a pointer to proxy class to access the copy layer
virtual SWE_Block1DgrabGhostLayer (BoundaryEdge edge)
 "grab" the ghost layer in order to set these values externally
void setGhostLayer ()
 set values in ghost layers
float getMaxTimestep ()
 return maximum size of the time step to ensure stability of the method
void computeMaxTimestep (const float i_dryTol=0.1, const float i_cflNumber=0.4)
virtual void simulateTimestep (float dt)=0
 execute a single time step of the simulation
virtual float simulate (float tStart, float tEnd)=0
virtual void computeNumericalFluxes ()=0
 compute the numerical fluxes for each edge of the Cartesian grid
virtual void updateUnknowns (float dt)=0
 compute the new values of the unknowns h, hu, and hv in all grid cells
int getNx ()
 returns nx, i.e. the grid size in x-direction
int getNy ()
 returns ny, i.e. the grid size in y-direction

Static Public Attributes

static const float g = 9.81f
 static variable that holds the gravity constant (g = 9.81 m/s^2):

Protected Member Functions

 SWE_Block (int l_nx, int l_ny, float l_dx, float l_dy)
virtual ~SWE_Block ()
void setBoundaryBathymetry ()
virtual void synchAfterWrite ()
virtual void synchWaterHeightAfterWrite ()
virtual void synchDischargeAfterWrite ()
virtual void synchBathymetryAfterWrite ()
virtual void synchGhostLayerAfterWrite ()
virtual void synchBeforeRead ()
virtual void synchWaterHeightBeforeRead ()
virtual void synchDischargeBeforeRead ()
virtual void synchBathymetryBeforeRead ()
virtual void synchCopyLayerBeforeRead ()
virtual void setBoundaryConditions ()
 set boundary conditions in ghost layers (set boundary conditions)

Protected Attributes

int nx
 size of Cartesian arrays in x-direction
int ny
 size of Cartesian arrays in y-direction
float dx
 mesh size of the Cartesian grid in x-direction
float dy
 mesh size of the Cartesian grid in y-direction
Float2D h
 array that holds the water height for each element
Float2D hu
 array that holds the x-component of the momentum for each element (water height h multiplied by velocity in x-direction)
Float2D hv
 array that holds the y-component of the momentum for each element (water height h multiplied by velocity in y-direction)
Float2D b
 array that holds the bathymetry data (sea floor elevation) for each element
BoundaryType boundary [4]
 type of boundary conditions at LEFT, RIGHT, TOP, and BOTTOM boundary
const SWE_Block1Dneighbour [4]
 for CONNECT boundaries: pointer to connected neighbour block
float maxTimestep
 maximum time step allowed to ensure stability of the method
float offsetX
 x-coordinate of the origin (left-bottom corner) of the Cartesian grid
float offsetY
 y-coordinate of the origin (left-bottom corner) of the Cartesian grid

Detailed Description

SWE_Block is the main data structure to compute our shallow water model on a single Cartesian grid block: SWE_Block is an abstract class (and interface) that should be extended by respective implementation classes.

Cartesian Grid for Discretization:

SWE_Blocks uses a regular Cartesian grid of size nx by ny, where each grid cell carries three unknowns:

Each of the components is stored as a 2D array, implemented as a Float2D object, and are defined on grid indices [0,..,nx+1]*[0,..,ny+1]. The computational domain is indexed with [1,..,nx]*[1,..,ny].

The mesh sizes of the grid in x- and y-direction are stored in static variables dx and dy. The position of the Cartesian grid in space is stored via the coordinates of the left-bottom corner of the grid, in the variables offsetX and offsetY.

Ghost layers:

To implement the behaviour of the fluid at boundaries and for using multiple block in serial and parallel settings, SWE_Block adds an additional layer of so-called ghost cells to the Cartesian grid, as illustrated in the following figure. Cells in the ghost layer have indices 0 or nx+1 / ny+1.

ghost_cells.gif

Memory Model:

The variables h, hu, hv for water height and momentum will typically be updated by classes derived from SWE_Block. However, it is not assumed that such and updated will be performed in every time step. Instead, subclasses are welcome to update h, hu, and hv in a lazy fashion, and keep data in faster memory (incl. local memory of acceleration hardware, such as GPGPUs), instead.

It is assumed that the bathymetry data b is not changed during the algorithm (up to the exceptions mentioned in the following).

To force a synchronization of the respective data structures, the following methods are provided as part of SWE_Block:

Derived Classes

As SWE_Block just provides an abstract base class together with the most important data structures, the implementation of concrete models is the job of respective derived classes (see the class diagram at the top of this page). Similar, parallel implementations that are based on a specific parallel programming model (such as OpenMP) or parallel architecture (such as GPU/CUDA) should form subclasses of their own. Please refer to the documentation of these classes for more details on the model and on the parallelisation approach.


Constructor & Destructor Documentation

SWE_Block::SWE_Block ( int  l_nx,
int  l_ny,
float  l_dx,
float  l_dy 
) [protected]

Constructor: allocate variables for simulation

unknowns h (water height), hu,hv (discharge in x- and y-direction), and b (bathymetry) are defined on grid indices [0,..,nx+1]*[0,..,ny+1] -> computational domain is [1,..,nx]*[1,..,ny] -> plus ghost cell layer

The constructor is protected: no instances of SWE_Block can be generated.

SWE_Block::~SWE_Block ( ) [protected, virtual]

Destructor: de-allocate all variables


Member Function Documentation

void SWE_Block::computeMaxTimestep ( const float  i_dryTol = 0.1,
const float  i_cflNumber = 0.4 
)

Compute the largest allowed time step for the current grid block (reference implementation) depending on the current values of variables h, hu, and hv, and store this time step size in member variable maxTimestep.

Parameters:
i_dryToldry tolerance (dry cells do not affect the time step).
i_cflNumberCFL number of the used method.
virtual void SWE_Block::computeNumericalFluxes ( ) [pure virtual]

compute the numerical fluxes for each edge of the Cartesian grid

The computation of fluxes strongly depends on the chosen numerical method. Hence, this purely virtual function has to be implemented in the respective derived classes.

Implemented in SWE_WavePropagationBlock, SWE_WavePropagationBlockCuda, SWE_RusanovBlock, and SWE_RusanovBlockCUDA.

provides read access to the bathymetry data

return reference to bathymetry unknown b

provides read access to the momentum/discharge array (x-component)

return reference to discharge unknown hu

provides read access to the momentum/discharge array (y-component)

return reference to discharge unknown hv

float SWE_Block::getMaxTimestep ( ) [inline]

return maximum size of the time step to ensure stability of the method

Returns:
current value of the member variable maxTimestep

provides read access to the water height array

Restores values for h, v, and u from file data

Parameters:
_barray holding b-values in sequence return reference to water height unknown h

"grab" the ghost layer in order to set these values externally

"grab" the ghost layer at the specific boundary in order to set boundary values in this ghost layer externally. The boundary conditions at the respective ghost layer is set to PASSIVE, such that the grabbing program component is responsible to provide correct values in the ghost layer, for example by receiving data from a remote copy layer via MPI communication.

Parameters:
specifiededge
Returns:
a SWE_Block1D object that contains row variables h, hu, and hv

Reimplemented in SWE_BlockCUDA.

void SWE_Block::initScenario ( float  _offsetX,
float  _offsetY,
SWE_Scenario i_scenario,
const bool  i_multipleBlocks = false 
)

initialise unknowns to a specific scenario:

Initializes the unknowns and bathymetry in all grid cells according to the given SWE_Scenario.

In the case of multiple SWE_Blocks at this point, it is not clear how the boundary conditions should be set. This is because an isolated SWE_Block doesn't have any in information about the grid. Therefore the calling routine, which has the information about multiple blocks, has to take care about setting the right boundary conditions.

Parameters:
i_scenarioscenario, which is used during the setup.
i_multipleBlocksare the multiple SWE_blocks?

return a pointer to proxy class to access the copy layer

register the row or column layer next to a boundary as a "copy layer", from which values will be copied into the ghost layer or a neighbour;

Returns:
a SWE_Block1D object that contains row variables h, hu, and hv

Reimplemented in SWE_BlockCUDA.

void SWE_Block::setBathymetry ( float  _b)

set the bathymetry to a uniform value

set Bathymetry b in all grid cells (incl. ghost/boundary layers) to a uniform value bathymetry source terms are re-computed

void SWE_Block::setBathymetry ( float(*)(float, float)  _b)

set the bathymetry according to a given function

set Bathymetry b in all grid cells (incl. ghost/boundary layers) using the specified bathymetry function; bathymetry source terms are re-computed

void SWE_Block::setBoundaryBathymetry ( ) [protected]

Sets the bathymetry on OUTFLOW or WALL boundaries. Should be called very time a boundary is changed to a OUTFLOW or WALL boundary or the bathymetry changes.

void SWE_Block::setBoundaryConditions ( ) [protected, virtual]

set boundary conditions in ghost layers (set boundary conditions)

set the values of all ghost cells depending on the specifed boundary conditions

  • set boundary conditions for typs WALL and OUTFLOW
  • derived classes need to transfer ghost layers

Reimplemented in SWE_BlockCUDA.

void SWE_Block::setBoundaryType ( BoundaryEdge  edge,
BoundaryType  boundtype,
const SWE_Block1D i_inflow = NULL 
)

set type of boundary condition for the specified boundary

Set the boundary type for specific block boundary.

Parameters:
i_edgelocation of the edge relative to the SWE_block.
i_boundaryTypetype of the boundary condition.
i_inflowpointer to an SWE_Block1D, which specifies the inflow (should be NULL for WALL or OUTFLOW boundary)
void SWE_Block::setDischarge ( float(*)(float, float)  _u,
float(*)(float, float)  _v 
)

set the momentum/discharge according to the provided functions

set discharge in all interior grid cells (i.e. except ghost layer) to values specified by parameter functions Note: unknowns hu and hv represent momentum, while parameters u and v are velocities!

set values in ghost layers

set the values of all ghost cells depending on the specifed boundary conditions; if the ghost layer replicates the variables of a remote SWE_Block, the values are copied

void SWE_Block::setWaterHeight ( float(*)(float, float)  _h)

set the water height according to a given function

set water height h in all interior grid cells (i.e. except ghost layer) to values specified by parameter function _h

virtual float SWE_Block::simulate ( float  tStart,
float  tEnd 
) [pure virtual]

perform the simulation starting with simulation time tStart, until simulation time tEnd is reached simulate implements the main simulation loop between two checkpoints; note that this function can typically only be used, if you only use a single SWE_Block; in particular, simulate can not trigger calls to exchange values of copy and ghost layers between blocks!

Parameters:
tStarttime where the simulation is started
tEndtime of the next checkpoint
Returns:
actual end time reached

Implemented in SWE_WavePropagationBlock, SWE_WavePropagationBlockCuda, SWE_RusanovBlockCUDA, and SWE_RusanovBlock.

void SWE_Block::synchAfterWrite ( ) [protected, virtual]

Update all temporary and non-local (for heterogeneous computing) variables after an external update of the main variables h, hu, hv, and b.

Reimplemented in SWE_BlockCUDA.

void SWE_Block::synchBathymetryAfterWrite ( ) [protected, virtual]

Update temporary and non-local (for heterogeneous computing) variables after an external update of the bathymetry b

Reimplemented in SWE_BlockCUDA.

void SWE_Block::synchBathymetryBeforeRead ( ) [protected, virtual]

Update temporary and non-local (for heterogeneous computing) variables before an external access to the bathymetry b

Reimplemented in SWE_BlockCUDA.

void SWE_Block::synchBeforeRead ( ) [protected, virtual]

Update all temporary and non-local (for heterogeneous computing) variables before an external access to the main variables h, hu, hv, and b.

Reimplemented in SWE_BlockCUDA.

void SWE_Block::synchCopyLayerBeforeRead ( ) [protected, virtual]

Update (for heterogeneous computing) variables in copy layers before an external access to the unknowns

Reimplemented in SWE_BlockCUDA.

void SWE_Block::synchDischargeAfterWrite ( ) [protected, virtual]

Update temporary and non-local (for heterogeneous computing) variables after an external update of the discharge variables hu and hv

Reimplemented in SWE_BlockCUDA.

void SWE_Block::synchDischargeBeforeRead ( ) [protected, virtual]

Update temporary and non-local (for heterogeneous computing) variables before an external access to the discharge variables hu and hv

Reimplemented in SWE_BlockCUDA.

void SWE_Block::synchGhostLayerAfterWrite ( ) [protected, virtual]

Update the ghost layers (only for CONNECT and PASSIVE boundary conditions) after an external update of the main variables h, hu, hv, and b in the ghost layer.

Reimplemented in SWE_BlockCUDA.

void SWE_Block::synchWaterHeightAfterWrite ( ) [protected, virtual]

Update temporary and non-local (for heterogeneous computing) variables after an external update of the water height h

Reimplemented in SWE_BlockCUDA.

void SWE_Block::synchWaterHeightBeforeRead ( ) [protected, virtual]

Update temporary and non-local (for heterogeneous computing) variables before an external access to the water height h

Reimplemented in SWE_BlockCUDA.

virtual void SWE_Block::updateUnknowns ( float  dt) [pure virtual]

compute the new values of the unknowns h, hu, and hv in all grid cells

based on the numerical fluxes (computed by computeNumericalFluxes) and the specified time step size dt, an Euler time step is executed. As the computational fluxes will depend on the numerical method, this purely virtual function has to be implemented separately for each specific numerical model (and parallelisation approach).

Parameters:
dtsize of the time step

Implemented in SWE_WavePropagationBlock, SWE_WavePropagationBlockCuda, SWE_RusanovBlock, and SWE_RusanovBlockCUDA.


Member Data Documentation

float SWE_Block::maxTimestep [protected]

maximum time step allowed to ensure stability of the method

maxTimestep can be updated as part of the methods computeNumericalFluxes and updateUnknowns (depending on the numerical method)


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends