data_grid< DATA_TYPE, NUM_DIMS > Class Template Reference

Collaboration diagram for data_grid< DATA_TYPE, NUM_DIMS >:
Collaboration graph
[legend]

Detailed Description

template<class DATA_TYPE, size_t NUM_DIMS>
class usml::types::data_grid< DATA_TYPE, NUM_DIMS >

N-dimensional data set and its associated axes.

Supports interpolation in any number of dimensions.

Parameters:
DATA_TYPE Type of data to be interpolated. Must support +,-,*,/ with itself and double precision scalars.
NUM_DIMS Number of dimensions in this grid. Specifying this at compile time allows for some loop un-wrapping.

Member Typedef Documentation

typedef data_grid<DATA_TYPE,NUM_DIMS> self_type [private]
typedef size_t size_type [private]

Constructor & Destructor Documentation

data_grid ( seq_vector axis[]  )  [inline]

Create data grid from its associated axes.

Allocates new memory for the data at each grid point. Initialize all of the interpolation types to GRID_INTERP_LINEAR.

Parameters:
axis Axes to use for each dimension of the grid. The seq_vector::clone() routine is used to make a local copy of each axis within the data grid.
data_grid ( const data_grid< DATA_TYPE, NUM_DIMS > &  other,
bool  copy_data 
) [inline]

Create data grid from an existing grid.

Allocates new memory for the data at each grid point. Copies interpolation types from the original grid.

Parameters:
other Grid to be copied.
copy_data Copy both axes and data if true. Copy just axes and structure if false.
virtual ~data_grid (  )  [inline, virtual]

Destroys memory area for field data.

data_grid (  )  [inline, protected]

Default constructor for sub-classes.


Member Function Documentation

seq_vector* axis ( size_t  dim  )  [inline]

Extract a reference to one of the axes.

const seq_vector* axis ( size_t  dim  )  const [inline]

Extract a constant reference to one of the axes.

void copy ( const self_type rhs  )  [inline]

Copy operator The data and axes are copied from rhs to this.

void data ( const size_t *  index,
DATA_TYPE  value 
) [inline]

Define a new data value at a specific combination of indices.

Parameters:
index Index number in each dimension.
value Value to insert at this location.
DATA_TYPE data ( const size_t *  index  )  const [inline]

Extract a data value at a specific combination of indices.

Parameters:
index Index number in each dimension.
void edge_limit ( size_t  dimension,
bool  flag 
) [inline]

Set the edge_limit flag for the requested dimension.

Note: Default is true

Parameters:
dimension Dimension number to be modified.
flag Limits locations when true.
bool edge_limit ( size_t  dimension  )  const [inline]

Returns the edge_limit flag for the requested dimension.

DATA_TYPE interp ( int  dim,
const size_t *  index,
const double *  location,
DATA_TYPE &  deriv,
DATA_TYPE *  deriv_vec 
) const [inline, private]

Private recursion engine for multi-dimensional interpolation.

Recursion engine for multi-dimensional interpolation.

The type of interpolation for each dimension is determined using the _interp_type[] field. Interpolation coefficients are computed on the fly to make arbitrary combinations of interpolation types viable.

Parameters:
dim Index of the dimension currently being processed. Recursion starts at dim=NUM_DIMS-1 and reduces to element retrieval when dim=-1.
index Position of the corner before the desired field point. Must have the same rank as the data grid.
location Location at which field value is desired. Must have the same NUM_DIM as the data grid or higher.
deriv Derivative for this iteration.
deriv_vec Results vector for derivative. Derivative not computed if NULL.
Returns:
Estimate of the field after interpolation.
void interp_type ( size_t  dimension,
enum GRID_INTERP_TYPE  type 
) [inline]

Define the type of interpolation for one of the axes.

Modifies the axis buffer size as a side effect. Note that linear interpolation requires a minimum of 2 points; pchip requires a minimum of 4 points.

Parameters:
dimension Dimension number to be modified.
type Type of interpolation for this dimension.
enum GRID_INTERP_TYPE interp_type ( size_t  dimension  )  const [inline]

Retrieve the type of interpolation for one of the axes.

void interpolate ( const matrix< double > &  x,
const matrix< double > &  y,
const matrix< double > &  z,
matrix< double > *  result,
matrix< double > *  dx = NULL,
matrix< double > *  dy = NULL,
matrix< double > *  dz = NULL 
) [inline]

Interpolation 3-D specialization where the arguments, and results, are matrix<double>.

This is used frequently in the WaveQ3D model to interpolate environmental parameters.

Parameters:
x First dimension of location.
y Second dimension of location.
z Third dimension of location.
result Interpolated values at each location (output).
dx First dimension of derivative (output).
dy Second dimension of derivative (output).
dz Third dimension of derivative (output).

Reimplemented in data_grid_svp.

void interpolate ( const matrix< double > &  x,
const matrix< double > &  y,
matrix< double > *  result,
matrix< double > *  dx = NULL,
matrix< double > *  dy = NULL 
) [inline]

Interpolation 2-D specialization where the arguments, and results, are matrix<double>.

This is used frequently in the WaveQ3D model to interpolate environmental parameters.

Parameters:
x First dimension of location.
y Second dimension of location.
result Interpolated values at each location (output).
dx First dimension of derivative (output).
dy Second dimension of derivative (output).

Reimplemented in data_grid_bathy.

void interpolate ( const matrix< double > &  x,
matrix< double > *  result,
matrix< double > *  dx = NULL 
) [inline]

Interpolation 1-D specialization where the arguments, and results, are matrix<double>.

This is used frequently in the WaveQ3D model to interpolate environmental parameters.

Parameters:
x First dimension of location.
result Interpolated values at each location (output).
dx First dimension of derivative (output).
DATA_TYPE interpolate ( double *  location,
DATA_TYPE *  derivative = NULL 
) [inline]

Multi-dimensional interpolation with the derivative calculation.

So many calculations are shared between the determination of an interpolate value and its derivative, that it is computationally efficient to compute them both at the same time.

Limit interpolation to axis domain if _edge_limit turned on for that dimension. Allow extrapolation if _edge_limit turned off.

Parameters:
location Location at which field value is desired. Must have the same rank as the data grid or higher. WARNING: The contents of the location vector may be modified if edge_limit() is true for any dimension.
derivative If this is not null, the first derivative of the field at this point will also be computed.
Returns:
Value of the field at this point.

Reimplemented in data_grid_bathy, and data_grid_svp.

DATA_TYPE linear ( int  dim,
const size_t *  index,
const double *  location,
DATA_TYPE &  deriv,
DATA_TYPE *  deriv_vec 
) const [inline, private]

Perform a linear interpolation on this dimension.

Parameters:
dim Index of the dimension currently being processed.
index Position of the corner before the desired field point. Must have the same rank as the data grid.
location Location at which field value is desired. Must have the same rank as the data grid or higher.
deriv Derivative for this iteration. Constant across the interval for linear interpolation.
deriv_vec Results vector for derivative. Derivative not computed if NULL.
Returns:
Estimate of the field after interpolation.
DATA_TYPE nearest ( int  dim,
const size_t *  index,
const double *  location,
DATA_TYPE &  deriv,
DATA_TYPE *  deriv_vec 
) const [inline, private]

Perform a nearest neighbor interpolation on this dimension.

Parameters:
dim Index of the dimension currently being processed.
index Position of the corner before the desired field point. Must have the same NUM_DIM as the data grid.
location Location at which field value is desired. Must have the same NUM_DIM as the data grid or higher.
deriv Derivative for this iteration. Always zero for nearest neighbor interpolation.
deriv_vec Results vector for derivative. Derivative not computed if NULL.
Returns:
Estimate of the field after interpolation.
DATA_TYPE pchip ( int  dim,
const size_t *  index,
const double *  location,
DATA_TYPE &  deriv,
DATA_TYPE *  deriv_vec 
) const [inline, private]

Interpolate this dimension using the Piecewise Cubic Hermite Interpolation Polynomial (PCHIP) algorithm from Matlab.

Matlab uses shape preserving, "visually pleasing" version of the cubic interpolant that does not suffer from the overshooting issues prevalent in the cubic spline. Although the the first derivative of the PCHIP result is guaranteed to be continuous, the second derivative has no such guarantee.

This algorithm differs from the Matlab implementation in that is simultaneously interpolates the function value for the current dimension, and interpolates the derivative for the previous dimension.

When using a gridded data set, it is recommended that edge_limit be set to TRUE for any dimensional axis that uses the PCHIP interpolation. This is because of PCHIP allowing for extreme values when extrapolating data.

References:

Cleve Moler, Numerical Computing in Matlab, Chapter 3 Interpolation, http://www.mathworks.com/moler/chapters.html accessed 5/15/2012.

F. N. Fritsch and R. E. Carlson, Monotone Piecewise Cubic Interpolation, SIAM Journal on Numerical Analysis, 17 (1980), pp. 238-246.

D. Kahaner, C. Moler, and S. Nash, Numerical Methods and Software, Prentice{Hall, Englewood Cli®s, NJ, 1989.

The basic algorithm assumes that the interpolation location is in the interval [ x[k], x[k+1] ), where "k" is known as the "interval index". The result is then calculated from four unevenly spaced points, and their forward (one-sided) derivatives.

 		y0 = y[k-1]		h0 = x[k]-x[k-1]	deriv0 = (y1-y0)/h0
 		y1 = y[k]		h1 = x[k+1]-x[k]	deriv1 = (y2-y1)/h1
 		y2 = y[k+1]		h2 = x[k+2]-x[k+1]	deriv2 = (y3-y2)/h2
 		y3 = y[k+2]		s = x - x[k]
 such that
      p(x) = y[k+1]  * ( 3 h1 s^2 - 2 s^3 ) / h1^3
             y[k]    * ( h1^3 - 3 h1 s^2 - 2 s^3 ) / h1^3
             slope[k+1] * ( s1^2 (s-h) ) / h1^2
             slope[k]   * ( s (s-h[k])^2 ) / h1^2
 where:
		slope[k] = weighted harmonic average of deriv0, deriv1, deriv2 terms
 

At the end-points, y'[0] and y'[N-1] must be estimated. This implementation uses Matlab's non-centered, shape-preserving, three-point formula for the end-point slope.

Parameters:
dim Index of the dimension currently being processed.
index Position of the corner before the desired field point. Must have the same rank as the data grid.
location Location at which field value is desired. Must have the same rank as the data grid or higher.
deriv Derivative for this iteration. Constant across the interval for linear interpolation.
deriv_vec Results vector for derivative. Derivative not computed if NULL.
Returns:
Estimate of the field after interpolation.
void write_netcdf ( const char *  filename  )  [inline]

Output data_grid to netcdf file.

Parameters:
filename name of the netcdf file to output to

Member Data Documentation

seq_vector* _axis[NUM_DIMS] [protected]

Axis associated with each dimension of the data grid.

DATA_TYPE* _data [protected]

Multi-dimensional data stored as a linear array in column major order.

This format is used to support an N-dimensional data set with any number of dimensions. This memory is created in the constructor and deleted in the destructor.

bool _edge_limit[NUM_DIMS] [protected]

Limits locations to values inside axis when true.

enum GRID_INTERP_TYPE _interp_type[NUM_DIMS] [protected]

Defines the type of interpolation for each axis.

size_t _offset[NUM_DIMS] [protected]

Used during interpolation to hold the axis offsets.


Generated on 4 May 2015 for USML by  doxygen 1.6.1