• Antelope Release 5.5 Linux 2.6.32-220.el6.x86_64 2015-04-21

 

#

NAME

pathintegral - integrate a 3D field variable along a predefined path

SYNOPSIS

#include "gclgrid.h"
vector <double> pathintegral(GCLscalarfield3d& field,dmatrix& path)
				throw(GCLgrid_error);
dmatrix& remap_path(GCLgrid3d& pathgrid, dmatrix& path, GCLgrid3d& othergrid)
				throw(GCLgrid_error);

SUPPORT


Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.

FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.

DESCRIPTION

A path integral of a field variable is a common mathematical construct in physics. This function assumes the field to be integrated is defined by the GCLscalarfield3d object which is derived by inheritance from a GCLgrid3d object (see gclgrid(3)). The integration path is defined in the Cartesian coordinate system of the GCLgrid3d parent object using a matrix passed as the simple matrix object path (see dmatrix(3)). The path matrix is assumed to be a 3xN matrix where the rows define the coordinates and each column defines and ordered sequence that define the path through space.

The path is integrated using a trapezoidal rule with no endpoint corrections. That is, each piece of the sum is formed as the average of the current and previous values of the field variable. This means the first point is always 0.0 and each successive point should be thought of as an approximation of the integral to that point. As a practical matter it tacitly assumes that path is more finely sampled than the field variable. The result is returned as an STL vector object with the ith component of the result approximating the integral from the first to the ith point in path. If the path wanders outside the domain of the GCLscalarfield3d object the path output vector will be truncated at the point where this happens. An exception is no thrown in this case but a valid vector is returned. This was done by design because this should not normally be considered an exception. The caller is expected to handle this problem cleanly by testing size.path() against return_vector.size() (see dmatrix(3) and vector(3)).

The function remap_path should be considered a helper function that will sometimes be necessary. That is, there are cases where a path might be defined in one grid, but needs to be applied in a different one. (For example, a ray path built in one grid that needs to be integrated to produce travel times in another grid that may not be congruent with the geometry of the former.) Note congruency of grids can be tested with the == or != operators of the base class GCLgrid(3) object.

Both functions will throw an exception only in one condition. If the path object does not have exactly 3 rows both functions will throw a GCLgrid_error exception announcing this. This would always be a coding error and most applications can probably choose to not arrange to catch this exception and simply let the program crash during initial debugging.

RETURN VALUES

See above and vector(3) if you are unfamiliar with the standard template library.

LIBRARY

-lgclgrid

SEE ALSO

gclgrid(3), dmatrix(3), vector(3), and C++ books discussing the Standard
Template Library

AUTHOR

Gary L. Pavlis
Indiana University
pavlis@indiana.edu

Antelope User Group Contributed Software
Printer icon