org.javaseis.array
Interface IMultiArray

All Known Implementing Classes:

DistributedArray, MultiArray

public interface IMultiArray

Yet Another Container (YAC) for multidimensional arrays used in seismic analysis and processing. This interface attempts to re-use concepts in existing array packages, such as JBLAS (http://math.nist.gov/javanumerics/blas.html) and the NCAR/UCAR NetCDF packages (http://www.unidata.ucar.edu/software/netcdf-java). This interface is initially designed for simplicity of usage with both Java and native methods, especially Fortran. The Java Array utilities and CSM Array utilities can be used with the underlying arrays.

The main design targets are:

• 1D Java arrays of primitive elements or Objects
• A superimposed "shape" that follows Fortran conventions
• Access via "range" triplets (start,end,increment)
• Ranges for Java zero based indexing or Fortran 1 to N based indexing
• Access to the "native" storage array for more arbitrary access
• MultiArray "elements" can have multiple values (i.e. complex, multi-component)
• Designed to be upward compatible with JavaSeis Distributed arrays
• Possible extensions could include Collections interface methods

Simple usage: Call a Fortran native method on a 2D slice of a 3D array:

 // Allocate a 3D array
 int n1=512; n2=256; n3=128;
 IMultiArray a = MultiArray.float3d( n1, n2, n3 );
 // Get the 1D underlying storage for this array
 float [] xa = a.floats();
 int[] position = new int[3];
 // Loop over the 3rd dimension
 for (int k=0; k<n3; k++) {
   // Set the position to the start of this 2D plane
   position[0] = 0;
   position[1] = 0; 
   position[2] = k;
   // Get the index of this 2D plane and call a native method
   int index = a.index(position)
   callNativeMethod2D( n1, n2, a[index] );
 }
 

More complex usage in Java:

  // Allocate 1D array that will be shaped to 3D
 int lengths[] = {512,256,128};
 float x[512*256*128];
  // Allocate an empty MultiArray
 IMultiArray a = new MultiArray();
  // Use methods to set the type and shape
 a.setDataType( float.class );
 a.setDimensions( 3 );
 a.setShape( lengths );
  // Assign our 1D array to this MultiArray and then zero
 a.setArray( x );
 a.clear();
  // Get the 1D vector for this MultiArray
 x = getFloats();
  // Get the index of the first value and set to 1.0
 int position[] = {0,0,0};
 int ix = a.index( position );
 x[ix] = 1.0;
  //
  // get a range triplet for the traversing the first "trace"
 int[] range = a.range( position, 1, 1, a.getLength(1), 1 );
  // Loop and set values for the first trace
 for (int ix=range[0],i=1; ix<range[1]; ix+=range[2],i++)
     x[ix] = (float)i;
  //
  // Loop over all values in the 3D array
 for (int k=1; k<=a.getLength(3); k++ ) {
     position[2] = k;
     for (int j=1; j<=a.getLength(2); j++) {
         position[1] = j;
         position[0] = 1;
         // Get a range triplet for the current trace
         int[] range = a.range(position,1,1,a.getLength(1),1);
         int i = 0;
         // Loop and set values for this trace
         for (ix=range[0]; ix<range[1]; ix+=range[2]) {
             i++;
             x[ix] = (float)(i*j*k); 
         }
     }
 }
 

Author:

Chuck Mosher for JavaSeis.org

Method Summary

byte[]	bytes()
IMultiArray	clone()
double[]	doubles()
float[]	floats()
int	getDimensions() Return the number of dimensions in this MultiArray
void	getFrame(byte[][] buf, int[] position)
void	getFrame(double[][] buf, int[] position)
void	getFrame(float[][] buf, int[] position)
void	getFrame(int[][] buf, int[] position)
void	getFrame(long[][] buf, int[] position)
void	getFrame(short[][] buf, int[] position)
<T> void	getFrame(T[][] buf, int[] position) Place a 2-dimensional array of values into the multiarray
int	getLength(int index) Return the length of a particular dimension
int	getOffset() Return the zero-based offset within the underlying storage for this array
int[]	getShape() Return the length of each dimension in this MultiArray
void	getTrace(byte[] buf, int[] position)
void	getTrace(double[] buf, int[] position)
void	getTrace(float[] buf, int[] position)
void	getTrace(int[] buf, int[] position)
void	getTrace(long[] buf, int[] position)
void	getTrace(short[] buf, int[] position)
<T> void	getTrace(T[] buf, int[] position) Return a 1-dimensional array of values from the multiarray
int	index(int[] position) Return the index in the underlying storage of the data at a particular position in the MultiArray
int	index(int[] position, int element) Return the index in the underlying storage of an element at a particular position in the MultiArray.
int	indexFortran(int[] position) Return the index in the underlying storage of the data at a particular position in the MultiArray.
int	indexFortran(int[] position, int element) Return the index in the underlying storage of an element at a particular position in the MultiArray.
int[]	ints()
long[]	longs()
<T> T[]	objects() Return the underlying storage for this MultiArray as a 1D array
void	putFrame(byte[][] buf, int[] position)
void	putFrame(double[][] buf, int[] position)
void	putFrame(float[][] buf, int[] position)
void	putFrame(int[][] buf, int[] position)
void	putFrame(long[][] buf, int[] position)
void	putFrame(short[][] buf, int[] position)
<T> void	putFrame(T[][] buf, int[] position) Place a 2-dimensional array of values into the multiarray
void	putTrace(byte[] buf, int[] position)
void	putTrace(double[] buf, int[] position)
void	putTrace(float[] buf, int[] position)
void	putTrace(int[] buf, int[] position)
void	putTrace(long[] buf, int[] position)
void	putTrace(short[] buf, int[] position)
<T> void	putTrace(T[] buf, int[] position) Place a 1-dimensional array of values into the multiarray
int[]	range(int[] position, int dimension) Return a zero-based index triplet defining start,end,increment that will traverse a specified dimension for this MultiArray.
int[]	range(int[] position, int dimension, int start, int end, int increment) Return a zero-based index triplet defining start,end,increment that can be used to access the elements of the underlying 1D array storage for this MultiArray.
int[]	range(int[] position, int dimension, int start, int end, int increment, int element) Return a zero-based index triplet defining start,end,increment that can be used to access individual elements of the underlying 1D array storage for this MultiArray.
int[]	rangeFortran(int[] position, int dimension) Return a zero-based index triplet defining start,end,increment that will traverse a specified dimension for this MultiArray.
int[]	rangeFortran(int[] position, int dimension, int start, int end, int increment) Return a Fortran index triplet defining start,end,increment that can be used to access the elements of the underlying 1D array storage for this MultiArray.
int[]	rangeFortran(int[] position, int dimension, int start, int end, int increment, int element) Return a Fortran style index triplet defining start,end,increment that can be used to access individual elements of the underlying 1D array storage for this MultiArray.
void	setArray(byte[] buf)
void	setArray(double[] buf)
void	setArray(float[] buf)
void	setArray(int[] buf)
void	setArray(long[] buf)
void	setArray(short[] buf)
<T> void	setArray(T[] buf) Provide the array that is used for underlying storage The "object" version is a generic method that handles arbitrary objects The rest of the methods are for primitive types
void	setClassType(java.lang.Class classType) Set the class type of this MultiArray
void	setDimensions(int ndim) Set the number of dimensions for this MultiArray
void	setElementCount(int elementCount) Set the element count for this MultiArray
void	setOffset(int offset) Set the zero-based offset within the underlying storage for this array
void	setShape(int[] lengths) Set the shape of this MultiArray, in Fortran style with the "fast" dimension first
short[]	shorts()
void	transpose(TransposeType type) Transpose the array

Method Detail

bytes

byte[] bytes()

Returns:

byte array for this MultiArray, null if undefined

clone

IMultiArray clone()

doubles

double[] doubles()

Returns:

double array for this MultiArray, null if undefined

floats

float[] floats()

Returns:

float array for this MultiArray, null if undefined

getDimensions

int getDimensions()

Return the number of dimensions in this MultiArray

Returns:

number of dimensions

getFrame

void getFrame(byte[][] buf,
              int[] position)

getFrame

void getFrame(double[][] buf,
              int[] position)

getFrame

void getFrame(float[][] buf,
              int[] position)

getFrame

void getFrame(int[][] buf,
              int[] position)

getFrame

void getFrame(long[][] buf,
              int[] position)

getFrame

void getFrame(short[][] buf,
              int[] position)

getFrame

<T> void getFrame(T[][] buf,
                  int[] position)

Place a 2-dimensional array of values into the multiarray

Parameters:

buf - array to be placed into the multiarray

position - zero-based index location in fortran order

getLength

int getLength(int index)

Return the length of a particular dimension

Parameters:

index - the index of the dimension whose length will be returned

Returns:

length of the dimension

getOffset

int getOffset()

Return the zero-based offset within the underlying storage for this array

Returns:

zero based offset of the start of this array

getShape

int[] getShape()

Return the length of each dimension in this MultiArray

Returns:

length of each dimension

getTrace

void getTrace(byte[] buf,
              int[] position)

getTrace

void getTrace(double[] buf,
              int[] position)

getTrace

void getTrace(float[] buf,
              int[] position)

getTrace

void getTrace(int[] buf,
              int[] position)

getTrace

void getTrace(long[] buf,
              int[] position)

getTrace

void getTrace(short[] buf,
              int[] position)

getTrace

<T> void getTrace(T[] buf,
                  int[] position)

Return a 1-dimensional array of values from the multiarray

Parameters:

buf - array to receive data from the multiarray

position - zero-based index location in fortran order

index

int index(int[] position)

Return the index in the underlying storage of the data at a particular position in the MultiArray

Parameters:

position - position of the sample to be accessed using zero-based indices

Returns:

zero-based index in the underlying storage of this sample

index

int index(int[] position,
          int element)

Return the index in the underlying storage of an element at a particular position in the MultiArray. This method is used for Arrays where the SeisDataType defines multiple "elements" for each "sample" (i.e. complex or multicomponent data)

Parameters:

position - position of the sample to be accessed using zero-based indices

element - index of the "sample" "element" that will be accessed

Returns:

zero-based index in the underlying storage of the element

indexFortran

int indexFortran(int[] position)

Return the index in the underlying storage of the data at a particular position in the MultiArray. This method uses Fortran style 1 to N based indexing.

Parameters:

position - position of the sample to be accessed using Fortran indices

Returns:

Fortran index in the underlying storage of this sample

indexFortran

int indexFortran(int[] position,
                 int element)

Return the index in the underlying storage of an element at a particular position in the MultiArray. This method uses Fortran style 1 to N based indexing.

Parameters:

position - position of the sample to be accessed using Fortran indices

element - index of the "sample" "element" that will be accessed

Returns:

Fortran index in the underlying storage of the element

ints

int[] ints()

Returns:

int array for this MultiArray, null if undefined

longs

long[] longs()

Returns:

long array for this MultiArray, null if undefined

objects

<T> T[] objects()

Return the underlying storage for this MultiArray as a 1D array

Returns:

Object array for this MultiArray, null if undefined

putFrame

void putFrame(byte[][] buf,
              int[] position)

putFrame

void putFrame(double[][] buf,
              int[] position)

putFrame

void putFrame(float[][] buf,
              int[] position)

putFrame

void putFrame(int[][] buf,
              int[] position)

putFrame

void putFrame(long[][] buf,
              int[] position)

putFrame

void putFrame(short[][] buf,
              int[] position)

putFrame

<T> void putFrame(T[][] buf,
                  int[] position)

Place a 2-dimensional array of values into the multiarray

Parameters:

buf - array to be placed into the multiarray

position - zero-based index location in fortran order

putTrace

void putTrace(byte[] buf,
              int[] position)

putTrace

void putTrace(double[] buf,
              int[] position)

putTrace

void putTrace(float[] buf,
              int[] position)

putTrace

void putTrace(int[] buf,
              int[] position)

putTrace

void putTrace(long[] buf,
              int[] position)

putTrace

void putTrace(short[] buf,
              int[] position)

putTrace

<T> void putTrace(T[] buf,
                  int[] position)

Place a 1-dimensional array of values into the multiarray

Parameters:

buf - array to be placed into the multiarray

position - zero-based index location in fortran order

range

int[] range(int[] position,
            int dimension)

Return a zero-based index triplet defining start,end,increment that will traverse a specified dimension for this MultiArray. If the SeisDataType defines "samples" that are arrays (i.e. complex or multicomponent samples) the range points to the first element of each "sample". The dimension argument defines which dimension will be traversed. The corresponding element of the "position" argument is ignored (in favor of the "start" value).

Parameters:

position - starting position in Fortran style indexing

dimension - the dimension that will be traversed

Returns:

zero based index triplet for the requested dimesion

range

int[] range(int[] position,
            int dimension,
            int start,
            int end,
            int increment)

Return a zero-based index triplet defining start,end,increment that can be used to access the elements of the underlying 1D array storage for this MultiArray. If the SeisDataType defines "samples" that are arrays (i.e. complex or multicomponent samples) the range points to the first element of each "sample". The dimension argument defines which Fortran dimension will be traversed. The corresponding element of the "position" argument is ignored (in favor of the "start" value).

Parameters:

position - starting position in Fortran style indexing

dimension - the dimension that will be traversed

start - start index along the requested dimension

end - ending index

increment - index increment

Returns:

offset triplet for the requested range

range

int[] range(int[] position,
            int dimension,
            int start,
            int end,
            int increment,
            int element)

Return a zero-based index triplet defining start,end,increment that can be used to access individual elements of the underlying 1D array storage for this MultiArray. This method is used to access the individual "elements" of "samples" that contain multiple values (i.e. complex or multicomponent).

Parameters:

position - starting position in Fortran style indexing

dimension - the dimension that will be traversed

start - start index along the requested dimension

end - ending index

increment - index increment

element - the index of the element that will be accessed for the range selection

Returns:

offset triplet for the requested range

rangeFortran

int[] rangeFortran(int[] position,
                   int dimension)

Return a zero-based index triplet defining start,end,increment that will traverse a specified dimension for this MultiArray. If the SeisDataType defines "samples" that are arrays (i.e. complex or multicomponent samples) the range points to the first element of each "sample". The dimension argument defines which dimension will be traversed. The corresponding element of the "position" argument is ignored (in favor of the "start" value).

Parameters:

position - starting position in Fortran style indexing

dimension - the dimension that will be traversed

Returns:

zero based index triplet for the requested dimesion

rangeFortran

int[] rangeFortran(int[] position,
                   int dimension,
                   int start,
                   int end,
                   int increment)

Return a Fortran index triplet defining start,end,increment that can be used to access the elements of the underlying 1D array storage for this MultiArray. If the SeisDataType defines "samples" that are arrays (i.e. complex or multicomponent samples) the range points to the first element of each "sample". The dimension argument defines which Fortran dimension will be traversed. The corresponding element of the "position" argument is ignored (in favor of the "start" value).

Parameters:

position - starting position in Fortran style indexing

dimension - the dimension that will be traversed

start - start index along the requested dimension

end - ending index

increment - index increment

Returns:

Fortran index triplet for the requested range

rangeFortran

int[] rangeFortran(int[] position,
                   int dimension,
                   int start,
                   int end,
                   int increment,
                   int element)

Return a Fortran style index triplet defining start,end,increment that can be used to access individual elements of the underlying 1D array storage for this MultiArray. This method is used to access the individual "elements" of "samples" that contain multiple values (i.e. complex or multicomponent).

Parameters:

position - starting position in Fortran style indexing

dimension - the dimension that will be traversed

start - start index along the requested dimension

end - ending index

increment - index increment

element - the index of the element that will be accessed for the range selection

Returns:

Fortran index triplet for the requested range

setArray

void setArray(byte[] buf)

setArray

void setArray(double[] buf)

setArray

void setArray(float[] buf)

setArray

void setArray(int[] buf)

setArray

void setArray(long[] buf)

setArray

void setArray(short[] buf)

setArray

<T> void setArray(T[] buf)

Provide the array that is used for underlying storage The "object" version is a generic method that handles arbitrary objects The rest of the methods are for primitive types

Parameters:

buf - array that is used for underlying storage

setClassType

void setClassType(java.lang.Class classType)

Set the class type of this MultiArray

Parameters:

classType - - the class type for this array

setDimensions

void setDimensions(int ndim)

Set the number of dimensions for this MultiArray

Parameters:

ndim - number of dimensions

setElementCount

void setElementCount(int elementCount)

Set the element count for this MultiArray

Parameters:

elementCount - - the number of "elements" per "sample"

setOffset

void setOffset(int offset)

Set the zero-based offset within the underlying storage for this array

Parameters:

offset - zero based offset to the start of this array

setShape

void setShape(int[] lengths)

Set the shape of this MultiArray, in Fortran style with the "fast" dimension first

Parameters:

lengths - length of each dimension

shorts

short[] shorts()

Returns:

short array for this MultiArray, null if undefined

transpose

void transpose(TransposeType type)

Transpose the array

Parameters:

type - the type of transpose to apply