Wide-purpose multi-dimensional linear interpolation

This method supports interpolation regarding combinations of 1D and 2D coordinate variables. For instance, suppose self is 4D with coordinates named ["x", "y", "z", "t"] and associated coordinates "sigma"["z"] ("sigma" is 1D and its axis is "z"), "p"["x","y"], "q"["x","y"] ("p" and "q" are 2D having the coordinates "x" and "y"). You can make interpolation by specifying 1D VArrays whose names are among "x", "y", "z", "t", "sigma", "p", "q". You can also use a Hash like {"z" => 1.0} to specify a single point along the "x" coordinate.

If the units of the target coordinate and the current coordinate are different, a converstion was made so that slicing is made correctly, as long as the two units are comvertible; if the units are not convertible, it is just warned.

If you specify only "x", "y", and "t" coordinates for interpolation, the remaining coordinates "z" is simply retained. So the result will be 4 dimensional with coordinates named ["x", "y", "z", "t"], but the lengths of "x", "y", and "t" dimensions are changed according to the specification. Note that the result could be 3-or-smaller dimensional — see below.

Suppose you have two 1D VArrays, xnew and ynew, having names "x" and "y", respectively, and the lengths of xnew and the ynew are the same. Then, you can give an array of the two, [xnew, ynew], for coord0 as

  gp_int = gp_org.interpolate( [xnew, ynew] )

(Here, gp_org represents a GPhys object, and the return value pointed by gp_int is also a GPhys.) In this case, the 1st dimension of the result (gp_int) will be sampled at the points [xnew[0],ynew[0]], [xnew[1],ynew[1]], [xnew[2],ynew[2]], …, while the 2nd and the third dimensions are "z" and "t" (no interpolation). This way, the rank of the result will be reduced from that of self.

If you instead give xnew to coord0 and ynew to coord1 as

  gp_int = gp_org.interpolate( xnew, ynew )

The result will be 4-dimensional with the first coordinate sampled at xnew[0], xnew[1], xnew[2],… and the second coordinate sampled at ynew[0], ynew[1], ynew[2],…

You can also cut regarding 2D coordinate variable as

  gp_int = gp_org.interpolate( pnew, qnew )
  gp_int = gp_org.interpolate( xnew, qnew )
  gp_int = gp_org.interpolate( [pnew, qnew] )
  gp_int = gp_org.interpolate( [xnew, qnew] )

In any case, the desitination VArrays such as xnew ynew pnew qnew must be one-dimensional.

Note that

  gp_int = gp_org.interpolate( qnew )

fails (exception raised), since it is ambiguous. If you tempted to do so, perhaps what you want is covered by the following special form:

As a special form, you can specify a particular dimension like this:

  gp_int = gp_org.interpolate( "x"=>pnew )

Here, interpolation along "x" is made, while other axes are retained. This is useful if pnew corresponds to a multi-D coordinate variable where there are two or more corresponding axes (otherwise, this special form is not needed.)

See the test part at the end of this file for more examples.

LIMITATION

Currently associated coordinates expressed by 3D or greater dimensional arrays are not supported.

Computational efficiency of pure two-dimensional coordinate support should be improved by letting C extensions cover deeper and improving the search algorithm for grid (which is usually ordered quasi-regularly).

COVERAGE

Extrapolation is covered for 1D coordinates, but only interpolation is covered for 2D coordinates (which is limited by gt2dlib in DCL — exception will be raised if you specify a grid point outside the original 2D grid points.).

MATHEMATICAL SPECIFICATION

The multi-dimensional linear interpolation is done by supposing a (hyper-) "rectangular" grid, where each dimension is independently sampled one-dimensionally. In case of interpolation along two dimensional coordinates such as "p" and "q" in the example above, a mapping from a rectangular grid is assumed, and the corresponding points in the rectangular grid is solved inversely (currently by using gt2dlib in DCL).

For 1D and 2D cases, linear interpolations may be expressed as

   1D:  zi = (1-a)*z0 + a*z1
   2D:  zi = (1-a)*(1-b)*z00 + a*(1-b)*z10 + (1-a)*b*z01 + a*b*z11

This method is extended to arbitrary number of dimensions. Thus, if the number of dimensions to interpolate is S, then 2**S grid points are used for each interpolation (8 points for 3D, 16 points for 4D,…). Thus, the linearity of this interpolation is only along each dimension, not over the whole dimensionality.

USAGE

  interpolate(coord0, coord1, ...)

ARGUMENTS

• coord0, coord1,… [ 1D VArray, or Array of 1D VArray, or a 1-element Hash as {coordinate_name(String) => slice_loc_value(Numeric)} ] : locations to which interpolation is made. Names of all the VArray‘s in the arguments must exist among the names of the coordinates of self (including associated coordinates), since the dimension finding is made in terms of coordinate names. If an argument is an Array of VArray‘s, the first VArray will become the main coordinate variable, and the rest will be associated coordinates.
• [SPECIAL CASE] You can specfify a one-element Hash as the only argument such as

       gphys.interpolate("x"=>varray)
  

  where varray is a coordinate onto which interpolation is made. This is espcially useful if varray is multi-D. If varray‘s name "p" (name of a 2D coordnate var), for example, you can interpolate only regarding "x" by retaining other axes. If varray is 1-diemnsional, the same thing can be done simply by

       gphys.interpolate(varray)
  

  since the corresponding 1D coordinate is found aotomatically.

RETURN VALUE

• a GPhys

Makes a subset interactively by specifying a (poly-)line on the DCL viewport

ARGUMENTS

• dimx {String] : name of number (0,1,..) of the dimension corresponding to the X coordinate in the current window of DCL
• dimy {String] : name of number (0,1,..) of the dimension corresponding to the Y coordinate in the current window of DCL
• num {Integer] : the number of points along the (poly-)line (2 or greater — if 2, a single line segment; if 3 or more, a poly-line)

RETURN VALUE

• a GPhys

Interpolation onto grid points specified by the previous call of GPhys#mouse_cut

Interpolate to conform the grid to a target GPhys object

ARGUMENTS

• to [GPhys] : the target gphys

RETURN VALUE

• a GPhys