IWAVE Structure and Basic Use Cases

Functions

The implementation of an IWAVE application depends on a half-dozen functions, which the application author must supply. The most obvious of these is the time step, or dynamic field update, function, and it is described here. All six essential functions are documented in

RSFSRC/trip/iwave/core/include/iwinfo.hh

The time step interface accommodates (in principle) the update functions for all orders of derivative, and adjoint (reverse mode) as well as forward time stepping. Its signature is encapsulated in a typedef:

typedef void (*FD_TIMESTEP)(std::vector<RDOM *> dom, 
                            bool fwd, 
                            int iv, 
                            void* fdpars);

The first argument is the RDOM array extracted from an IWaveTree. The order of derivative to be computed is the base 2 log of dom.size(). The implementation should take the form of a case list, one major case for each order of derivative implemented. Each case (except the simulation itself, or order 0) should be divided into two subcases, one each for forward and adjoint modes, switched by the second bool argument fwd. Each subcase is further divided into sub-sub-cases according to the substep index iv. This third refinement permits implementation of multistep methods in this framework. To take a prominent example, staggered grid methods for elastodynamics, in their basic form, use leapfrog time stepping, a two-step methods: velocity fields are updated from stress fields in the first substep, stress fields from velocity fields in the second. This subdivision of time steps in this fashion allows for the simplest coding and reduces the amount of data in ghost cell exchange for domain decomposition, an advantage for low-latency systems. The final void * pointer is the usual dodge for faking private class data members in ``object oriented C'': the opaque object passed by address should be of a type defined for the given application and encapsulating all information needed to compute the time step, such as Courant numbers, auxiliary damping arrays for absorbing layers, and so on. One of the other five functions initializes this object.

IWAVE Structure and Basic Use Cases