Michael Thomas Flanagan's Java Library: Gradient

Michael Thomas Flanagan's Java Scientific Library

Gradient 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

import directive: import flanagan.math.Gradient;

Summary table of constructors and methods
Details of constructor and methods
Java source file last update: 12 September 2012
Home Page of Michael Thomas Flanagan's Java Scientific Library
Other classes, from this library, used by this class.

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)
		1D Array	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<Object> splineDerivativesArray()
	Numerical Differences	1D Array	At an individual point	public double numDerivAtPoint(double xx)
		1D Array	At each or each sampled array element	public double[] numDeriv_1D_array()
		2D Array	At an individual point	public double[] numDerivAtPoint(double xx, double yy)
			At each or each sampled array element	public double[][] numDeriv_2D_x_direction()
				public double[][] numDeriv_2D_y_direction()
				public ArrayList<Object> numericalDerivativesArray()
Sampling				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)
Deep copy				public Gradient copy()

CONSTRUCTORS
Constructors for one-dimensional arrays
public Gradient(double[] xx, double[] ff)
public Gradient(float[] xx, float[] ff)
public Gradient(long[] xx, long[] ff)
public Gradient(int[] xx, int[] ff)
Usage: Gradient gg = new Gradient(xx, ff);
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)
Usage: Gradient gg = new Gradient(xx, yy, 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

RETURN A GRADIENT OR ARRAY OF GRADIENTS
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)
Usage:                      grad = gg.splineDerivAtPoint(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()
Usage:                      grads = gg.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)
Usage:                      grads = gg.splineDerivAtPoint(xx, 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()
Usage:                      grads = gg.splineDeriv_2D_array_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()
Usage:                      grads = gg.splineDeriv_2D_array_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()
Usage:                      gradsArray = gg.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(x_i)/dx_i 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(x_i, y_j)/∂x_i 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(x_i, y_j)/∂y_j 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(x_{between i-1 and i})/dx as (ff[i-1] - ff[i]])/(xx[i-1] - xx[i]) [1D array]
- ∂f(x_{between i-1 and i}, y_j)/∂x as (ff[i-1][j] - ff[i]][j])/(xx[i-1] - xx[i]) [2D array]
- ∂f(x_i, y_{between 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)
Usage:                      grad = gg.numDerivAtPoint(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()
Usage:                      grads = gg.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)
Usage:                      grads = gg.numDerivAtPoint(xx, 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()
Usage:                      grads = gg.numDeriv_2D_array_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()
Usage:                      grads = gg.numDeriv_2D_array_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()
Usage:                      gradsArray = gg.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
public Gradient copy()
Usage: copy = gg.copy();
This method returns a deep copy of gg.

OTHER CLASSES USED BY THIS CLASS

This class uses the following classes in this library:

This page was prepared by Dr Michael Thomas Flanagan