Michael Thomas Flanagan's Java Scientific LibraryGradient Class:     Gradients in 1- and 2-Dimensional Arrays

Last update: 12 September 2012                                                                                                                              Main Page of Michael Thomas Flanagan's Java Scientific Library

This class contains the constructor and methods for the calculation of the gradients within 1-dimensional and 2-dimensional data arrays.
Two options are offered in the calculation of the gradients:
• Cubic and Bicubic spline interpolation of the first derivatives
• Numerical difference calculation of the first derivatives

### SUMMARY OF CONSTRUCTOR AND METHODS

 Constructors public Gradient(double[] xx, double[] ff) public Gradient(float[] xx, float[] ff) public Gradient(long[] xx, long[] ff) public Gradient(int[] xx, int[] ff) public Gradient(double[] xx, double[] yy, double[][] ff) public Gradient(float[] xx, float[] yy, float[][] ff) public Gradient(long[] xx, long[] yy, long[][] ff) public Gradient(int[] xx, int[] yy, int[][] ff) Return Gradient Spline Interpolation 1D Array At an individual point public double splineDerivAtPoint(double xx) At each or each sampled array element public double[] splineDeriv_1D_array() 2D Array At an individual point public double[] splineDerivAtPoint(double xx, double yy) At each or each sampled array element public double[][] splineDeriv_2D_x_direction() public double[][] splineDeriv_2D_y_direction() public ArrayList

CONSTRUCTORS
Constructors for one-dimensional arrays
Creates an instance of Gradient for a one-dimensional data array, f = f(x), where the x values are entered as the array xx and the f values are entered as the array ff. The two arrays must be of the same data type which maybe double, float, long or int.

Constructors for two-dimensional arrays
public Gradient(double[] xx, double[] yy, double[][] ff)
public Gradient(float[] xx, float[] yy, float[][] ff)
public Gradient(long[] xx, long[] yy, long[][] ff)
public Gradient(int[] xx, int[] yy, int[][] ff)
Creates an instance of Gradient for a two-dimensional data array, f = f(x, y), where the x values are entered as the array xx, the y values are entered as the array yy and the f values are entered as the array ff. The three arrays must be of the same data type which maybe double, float, long or int.
The lengths of all columns in the 2D array, ff, must be equal and equal to the length of the 1D array, xx,
and the lengths of all rows in the 2D array, ff, must be equal and equal to the length of the 1D array, yy,
i.e. the dimensions of the 2D array, ff, are e.g. double[xx.length][yy.length]

### METHODS

The gradients may be calculated as either
spline interpolated values or as numerical difference approximations.

Spline Interpolation Methods
The spline interpolation methods perform either a cubic spline interpolation (1D array) or a bicubic spline interpolation (2D array) on the full entered data arrays and returns the interpolated value/s of df/dx (1D array) or of ∂f/∂x and ∂f/∂y (2D array).
The classes
CubicSpline and BiCubicSplineFirstDerivative are used to calculate the interpolared first dervatives.

1D Array
At a single point in a 1D array
public double splineDerivAtPoint(double xx)
This method returns the cubic spline interpolated value of the first derivative, df/dx, at the point, xx.

At each or each sampled array element in a 1D array
public double[] splineDeriv_1D_array()
This method returns the cubic spline interpolated values of the first derivatives, df/dx, at each element or each sampled element of the entered 1D array. See
Sampling (below) for details of how to restrict the number of gradients returned. If a sampling method is not called the gradients are returned for all entered array elements.

2D Array
At a single point in a 2D array
public double[] splineDerivAtPoint(double xx, double yy)
This method returns the bicubic spline interpolated values of the first derivatives, ∂f/∂x and ∂f/∂y, at the point, xx, yy, as the two element array grads; grads[0] contains the value of ∂f/∂x and grads[1] contains the value of ∂f/∂y.

At each or each sampled array element in a 2D array
public double[][] splineDeriv_2D_x_direction()
This method returns the cubic spline interpolated values of the first derivative, ∂f/∂x, at each element or each sampled element of the entered 2D array. See
Sampling (below) for details of how to restrict the number of gradients returned. If a sampling method is not called the gradients are returned for all entered array elements.

public double[][] splineDeriv_2D_y_direction()
This method returns the cubic spline interpolated values of the first derivative, ∂f/∂y, at each element or each sampled element of the entered 2D array. See Sampling (below) for details of how to restrict the number of gradients returned. If a sampling method is not called the gradients are returned for all entered array elements.

public ArrayList<Object> splineDerivativesArray()
This method returns an ArrayLisy of two elements:
• Element 0: a 2D array of doubles containing the the cubic spline interpolated values of the first derivative, ∂f/∂x, at each element or each sampled element of the entered 2D as described for the method splineDeriv_2D_x_direction() above.
• Element 1: a 2D array of doubles containing the cubic spline interpolated values of the first derivative, ∂f/∂y, at each element or each sampled element of the entered 2D as described for the method splineDeriv_2D_y_direction() above.

Numerical Difference Methods
The numerical difference methods calculate the value of the gradients as numerical difference approximations to the first derivatives.
• For a gradient at an entered point:
• df(xi)/dxi as ((ff[i-1] - ff[i]])/(xx[i-1] - xx[i]) + (ff[i] - ff[i+1])/(xx[i] - xx[i+1]]))/2      [1D array]
• ∂f(xi, yj)/∂xi as ((ff[i-1][j] - ff[i]][j])/(xx[i-1] - xx[i]) + (ff[i][j] - ff[i+1][j])/(xx[i] - xx[i+1]))/2      [2D array]
• ∂f(xi, yj)/∂yj as ((ff[i][j-1] - ff[i]][j])/(yy[j-1] - yy[j]) + (ff[i][j] - ff[i][j+1])/(yy[j] - yy[j+1]))/2      [2D array]
• For a gradient at a point between entered points on and in the direction of an entered grid line:
• df(xbetween i-1 and i)/dx as (ff[i-1] - ff[i]])/(xx[i-1] - xx[i])      [1D array]
• ∂f(xbetween i-1 and i, yj)/∂x as (ff[i-1][j] - ff[i]][j])/(xx[i-1] - xx[i])      [2D array]
• ∂f(xi, ybetween j-1 and j)/∂y as (ff[i][j-1] - ff[i]][j])/(yy[j-1] - yy[j])      [2D array]
• Linear interpolation between the above calculated gradients is used to calculate a gradient at a point between entered points on an entered grid line but at ninety degrees to the grid line or for a gradient at a point not on a grid line.
1D Array
At a single point in a 1D array
public double numDerivAtPoint(double xx)
This method returns the numerical difference approximation of the first derivative, df/dx, at the point, xx.

At each or each sampled array element in a 1D array
public double[] numDeriv_1D_array()
This method returns the numerical difference approximations of the first derivatives, df/dx, at each element or each sampled element of the entered 1D array. See
Sampling (below) for details of how to restrict the number of gradients returned. If a sampling method is not called the gradients are returned for all entered array elements.

2D Array
At a single point in a 2D array
public double[] numDerivAtPoint(double xx, double yy)
This method returns the numerical difference approximations of the first derivatives, ∂f/∂x and ∂f/∂y, at the point, xx, yy, as the two element array grads; grads[0] contains the value of ∂f/∂x and grads[1] contains the value of ∂f/∂y.

At each or each sampled array element in a 2D array
public double[][] numDeriv_2D_x_direction()
This method returns the numerical difference approximation of the first derivative, ∂f/∂x, at each element or each sampled element of the entered 2D array. See
Sampling (below) for details of how to restrict the number of gradients returned. If a sampling method is not called the gradients are returned for all entered array elements.

public double[][] numDeriv_2D_y_direction()
This method returns the numerical difference approximation of the first derivative, ∂f/∂y, at each element or each sampled element of the entered 2D array. See Sampling (below) for details of how to restrict the number of gradients returned. If a sampling method is not called the gradients are returned for all entered array elements.

public ArrayList<Object> numericalDerivativesArray()
This method returns an ArrayLisy of two elements:
• Element 0: a 2D array of doubles containing the numerical difference approximation of the first derivative, ∂f/∂x, at each element or each sampled element of the entered 2D as described for the method numDeriv_2D_x_direction() above.
• Element 1: a 2D array of doubles containing the numerical difference approximation of the first derivative, ∂f/∂y, at each element or each sampled element of the entered 2D as described for the method numDeriv_2D_y_direction() above.

SAMPLING
These methods lay a mask over the entered array determining the elements within the entered array for which a gradient is returned by any of the array gradient methods.

public void sampling(int samplingPeriod)
public void sampling(int xSamplingPeriod, int ySamplingPeriod)
public void sampling(int samplingPeriod, int samplingStart, int samplingEnd)
public void sampling(int xSamplingPeriod, int xSamplingStart, int xSamplingEnd, int ySamplingPeriod, int ySamplingStart, int ySamplingEnd)
Usage:                      gg.sampling(samplingPeriod);
On calling this method gradients will be returned, by any of the array gradient methods, at points determined by the sampling period, msamplingPeriod, as indicated in the following examples.
• For a sampling period, samplingPeriod, of 3 and a 1D array of length 12, gradients will be returned at the points
xx[0], xx[3], xx[6], xx[9].
• For a sampling period, samplingPeriod, of 3 and a 2D array of y length 12 and x length 7, gradients will be returned at the points
xx[0]yy[0], xx[0]yy[3], xx[0]yy[6], xx[0]yy[9]
xx[3]yy[0], xx[3]yy[3], xx[3]yy[6], xx[3]yy[9]
xx[6]yy[0], xx[6]yy[3], xx[6]yy[6], xx[6]yy[9]
NB: indices start at 0.

Usage:                      gg.sampling(xSamplingPeriod, ySamplingPeriod);
On calling this method gradients will be returned, by any of the array gradient methods, at points determined by the sampling periods, xSamplingPeriod and ySamplingPeriod, as indicated in the following example.
• For an x-direction sampling period, xSamplingPeriod, of 2, and a y-direction sampling period, ySamplingPeriod, of 3 and a 2D array of y length 12 and x length 7, gradients will be returned at the points
xx[0]yy[0], xx[0]yy[3], xx[0]yy[6], xx[0]yy[9]
xx[2]yy[0], xx[2]yy[3], xx[2]yy[6], xx[2]yy[9]
xx[4]yy[0], xx[4]yy[3], xx[4]yy[6], xx[4]yy[9]
xx[6]yy[0], xx[6]yy[3], xx[6]yy[6], xx[6]yy[9]
NB: indices start at 0.

Usage:                      gg.sampling(samplingPeriod, samplingStart, samplingEnd);
On calling this method gradients will be returned, by any of the array gradient methods, at points determined by the sampling periods, samplingPeriod, as indicated in the following examples. No gradients are returned for points below the index, samplingStart, and above the index, samplingEnd.
• For a sampling period, samplingPeriod, of 3, a start index, samplingStart, of 1, an end index, samplingEnd, of 8 and a 1D array of length 12, gradients will be returned at the points
xx[1], xx[4], xx[7].
• For an x-direction sampling period, samplingPeriod, of 3, a start index, samplingStart, of 1, an end index, samplingEnd, of 8 and a 2D array of y length 12 and x length 7, gradients will be returned at the points
xx[1]yy[1], xx[1]yy[4], xx[1]yy[7]
xx[4]yy[1], xx[2]yy[4], xx[2]yy[7]
NB: indices start at 0.

Usage:                      gg.sampling(xSamplingPeriod, xSamplingStart, xSamplingEnd, ySamplingPeriod, ySamplingStart, ySamplingEnd);
On calling this method gradients will be returned, by any of the array gradient methods, at points determined by the sampling periods, xSamplingPeriod and ySamplingPeriod, as indicated in the following example. No gradients are returned for points below the indices, xSamplingStart and ySamplingStart, and above the indices, xSamplingEnd and ySamplingEnd.
• For an x-direction sampling period, xSamplingPeriod, of 2, an x-direction start index, xSamplingStart, of 1, an x-direction end index, xSamplingEnd, of 3, a y-direction sampling period, ySamplingPeriod, of 3, an y-direction start index, ySamplingStart, of 2, an y-direction end index, ySamplingEnd, of 7, and a 2D array of y length 12 and x length 7, gradients will be returned at the points
xx[1]yy[2], xx[1]yy[4], xx[1]yy[7]
xx[3]yy[4], xx[3]yy[4], xx[3]yy[7]
NB: indices start at 0.

DEEP COPY