3D Arrays

Definition

3D arrays are instances of the class Array3D. Class Array3D is a template class: Array3D<T, Allocator>. As for vectors, T is the type of the elements to be stored (e.g. double). Allocator defines the way memory is managed. It is close to STL allocators. See the section "Allocators" for further details.

Declaration

There is a default Allocator (see the section "Allocators"). It means that the last template parameter may be omitted. Then a 3D array of integers may be declared thanks to the line:

Array3D<int> A;

This defines an array of size 0 x 0 x 0, that is to say an empty array. To define a 3D array of size 5 x 3 x 6, one may write:

Array3D<int> A(5, 3, 6);

Use of 3D arrays

Only a few methods are available for 3D arrays because they are not the main concern of Seldon. Mainly, the access to elements is achieved through the operator(int, int, int), and indices start at 0:

Array3D<double> A(5, 6, 3);
A(0, 1, 3) = -3.1;
A(0, 0, 5) = 1.2 * A(0, 1, 3);

One may point out some methods:

  • GetLength1(), GetLength2() and GetLength3() return lengths in dimensions #1, #2 and #3.

  • Fill fills with 0, 1, 2, 3, etc. or fills the array with a given value.

  • Reallocate resizes the array (warning, data may be lost, depending on the allocator).

  • Copy enables to duplicate an array.

A comprehensive test of this class is done in file test/unit/array3d_test.cc. In the table below, we have listed the method of this class

constructors
operators
GetLength1 returns the first dimension of the 3-D array
GetLength2 returns the second dimension of the 3-D array
GetLength3 returns the third dimension of the 3-D array
GetSize returns the number of elements stored in the 3-D array
GetDataSize returns the number of elements stored in the 3-D array
GetMemorySize returns the memory used to store the array
GetData returns the pointer to the elements stored in the 3-D array
GetDataPointer returns a pointer to A(i, j, k)
Reallocate modifies the size of the 3-D array
SetData sets the pointer storing the 3-D array
Nullify sets the pointer to zero without releasing memory
Clear removes all elements of the 3-D array
Copy copies a 3-D array
Fill sets elements to 0, 1, 2, etc or to a given value
Zero sets all the elements to 0
FillRand sets randomly elements of the 3-D array
Print displays the 3-D array
Write writes the 3-D array in a binary file
Read reads the 3-D array from a binary file



constructors of Array3D

Syntax :

  Array3D(int i, int j, int k)

You can use a constructor with the dimensions of the 3-D array.

Example :

Array3D<double> A, B(5, 6, 3);
// then you can modify entries of B
B(2, 0, 4) = 2.5;

// you can use a copy constructor
Array3D<double> C(B);

Related topics :

Reallocate
operator =

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Operators of Array3D

Syntax :

  operator ()(int i, int j, int k)
  operator = (const Array3D<T>& )

The access operator () can be used to modify A(i, j, k).

Example :

Array3D<double> A, B(5, 6, 3);
// then you can modify entries of B
B(2, 0, 4) = 2.5;

// you can use a copy constructor
Array3D<double> C(B);

// or operator =
C = B;

Related topics :

Reallocate
Copy

Location :

Class Array3D
Array3D.hxx Array3D.cxx

GetLength1

Syntax :

  int GetLength1() const

This method returns the first dimension of the 3-D array.

Example :

Array3D<double> A, B(5, 6, 3);
// GetLength1() should return 5
cout << "First dimension of B " << B.GetLength1() << endl;

Related topics :

Reallocate
GetSize

Location :

Class Array3D
Array3D.hxx Array3D.cxx

GetLength2

Syntax :

  int GetLength2() const

This method returns the second dimension of the 3-D array.

Example :

Array3D<double> A, B(5, 6, 3);
// GetLength2() should return 6
cout << "Second dimension of B " << B.GetLength2() << endl;

Related topics :

Reallocate
GetSize

Location :

Class Array3D
Array3D.hxx Array3D.cxx

GetLength3

Syntax :

  int GetLength3() const

This method returns the third dimension of the 3-D array.

Example :

Array3D<double> A, B(5, 6, 3);
// GetLength3() should return 3
cout << "Third dimension of B " << B.GetLength3() << endl;

Related topics :

Reallocate
GetSize

Location :

Class Array3D
Array3D.hxx Array3D.cxx

GetSize, GetDataSize

Syntax :

  int GetSize() const
  int GetDataSize() const

This method returns the number of elements effectively stored in the 3-D array.

Example :

Array3D<double> A, B(5, 6, 3);
// GetSize() should return 5*6*3 = 90
cout << "Number of elements of B " << B.GetSize() << endl;

Related topics :

Reallocate
GetLength1

Location :

Class Array3D
Array3D.hxx Array3D.cxx

GetMemorySize

Syntax :

  size_t GetMemorySize() const

This method returns the memory used to store the array in bytes.

Example :

Array3D<double> A, B(5, 6, 3);
// GetMemorySize() should return 5*6*3*sizeof(double)
cout << "Memory used to store B " << B.GetMemorySize() << endl;

Related topics :

Reallocate
GetLength1

Location :

Class Array3D
Array3D.hxx Array3D.cxx

GetData

Syntax :

  T* GetData() const

This method returns the pointer to the array storing all the elements. This method is a low-level routine and should be used cautiously.

Example :

Array3D<double> A(5, 6, 3);
// If you wish to manipulate the vector containing all the elements of A :
Vector<double> V;
V.SetData(A.GetSize(), A.GetData());

// to avoid segmentation fault
V.Nullify();

Related topics :

SetData
Nullify

Location :

Class Array3D
Array3D.hxx Array3D.cxx

GetDataPointer

Syntax :

  T* GetDataPointer(int i, int j, int k) const

This method is equivalent to &A(i, j, k)

Example :

Array3D<double> A(5, 6, 3);
// If you wish to manipule a sub-matrix of A
Matrix<double> A;
A.SetData(6, 3, A.GetDataPointer(1, 0, 0));
// you could also write &A(1, 0, 0)

// to avoid segmentation fault
A.Nullify();

Related topics :

SetData
Nullify

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Reallocate

Syntax :

  void Reallocate(int i, int j, int k);

This method resizes the 3-D array with the new dimensions given in argument. If NewAlloc is used, the previous elements are lost, whereas they are kept if you are using MallocAlloc or CallocAlloc allocator.

Example :

Array3D<double> A(5, 6, 3);
A.Fill();

// then changing the size of A
A.Reallocate(7, 2, 5);

Related topics :

SetData
Nullify

Location :

Class Array3D
Array3D.hxx Array3D.cxx

SetData

Syntax :

  void SetData(int i, int j, int k, T* data);

This method initializes the pointer to the 3-D array. This low-level method should be used carefully.

Example :

// dealing with a vector
int m = 10, n = 4, p = 7;
Vector<double> V(m*n*p);

// manipulating the vector
V.Fill();

// then you can reshape the vector into a 3-D array
A.SetData(m, n, p, V.GetData());
V.Nullify();

A(3, 1, 2) = 1.5;

Related topics :

constructor
Nullify

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Nullify

Syntax :

  void Nullify()

This method clears the 3-D array without releasing the memory. This low-level method should be used cautiously

Example :

// constructing a 3-D array
int m = 10, n = 4, p = 7;
Array3D<double> A(m, n, p);

// filling A
A(2, 0, 0) = 1.2;
// ...

// then reshaping it to a vector
Vector<double> V;
V.SetData(A.GetSize(), A.GetData());

// Nullify is called to avoid multiple deallocations
A.Nullify();

Related topics :

SetData
Clear

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Clear

Syntax :

  void Clear()

This method clears the 3-D array.

Example :

// constructing a 3-D array
int m = 10, n = 4, p = 7;
Array3D<double> A(m, n, p);

// filling A
A(2, 0, 0) = 1.2;
// ...

// if you want to free the memory for other computations
A.Clear();

Related topics :

SetData
Reallocate

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Copy

Syntax :

  void Copy(const Array3D<T>& )

This method copies a 3-D array into the current object.

Example :

// constructing a 3-D array
int m = 10, n = 4, p = 7;
Array3D<double> A(m, n, p);
// filling A


// then you can copy this 3-D array into B
// you could also use operator =
Array3D<double> B;
B.Copy(A);

Related topics :

operator
constructor

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Fill

Syntax :

  void Fill()
  void Fill(const T& x)

This method fills the 3-D array with 0, 1, 2, ... or with a given value.

Example :

// constructing a 3-D array
int m = 3, n = 2, p = 4;
Array3D<double> A(m, n, p);
// filling A with 0, 1, 2, ...
A.Fill();
// A should be equal to
// A(0, :, :) = |0, 1, 2, 3|
//              |4, 5, 6, 7|
// A(1, :, :) = |8, 9, 10, 11|
//              |12, 13, 14, 15|
// A(2, :, :) = |16, 17, 18, 19|
//              |20, 21, 22, 23|



// you can also set all the entries to a same value
A.Fill(1.0);
// A should be equal to
// A(0, :, :) = |1, 1, 1, 1|
//              |1, 1, 1, 1|
// A(1, :, :) = |1, 1, 1, 1|
//              |1, 1, 1, 1|
// A(2, :, :) = |1, 1, 1, 1|
//              |1, 1, 1, 1|

Related topics :

Zero
FillRand

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Zero

Syntax :

  void Zero()

This method initializes all the entries to 0.

Example :

// constructing a 3-D array
int m = 3, n = 2, p = 4;
Array3D<double> A(m, n, p);
// A is not initialized, for example you could set all
// the values to 0
A.Zero();

Related topics :

Fill
FillRand

Location :

Class Array3D
Array3D.hxx Array3D.cxx

FillRand

Syntax :

  void FillRand()

This method fills the 3-D array with random values.

Example :

// constructing a 3-D array
int m = 3, n = 2, p = 4;
Array3D<double> A(m, n, p);
// A is not initialized, for example you could set 
// randomly the values
A.FillRand();

Related topics :

Fill
Zero

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Print

Syntax :

  void Print()

This method displays the 3-D array.

Example :

// constructing a 3-D array
int m = 3, n = 2, p = 4;
Array3D<double> A(m, n, p);
A.FillRand();

cout << "A = " << endl;
A.Print();

Related topics :

Fill
Zero

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Read

Syntax :

  void Read(string file_name);
  void Read(istream& in);
  void Read(string file_name, bool with_size);
  void Read(istream& in, bool with_size);

This method reads a 3-D array from a file or an input stream (binary format). If with_size is set to false, the dimensions of the 3-D array are not read in the file.

Example :

// constructing a 3-D array
int m = 3, n = 2, p = 4;
Array3D<double> A(m, n, p), B;
A.FillRand();

// you can write it on a file
A.Write("test.dat");

// then read it
B.Read("test.dat");

Related topics :

Write
Reallocate

Location :

Class Array3D
Array3D.hxx Array3D.cxx

Write

Syntax :

  void Write(string file_name);
  void Write(ostream& in);
  void Write(string file_name, bool with_size);
  void Write(ostream& in, bool with_size);

This method writes a 3-D array in a file or in an input stream (binary format). If with_size is set to false, the dimensions of the 3-D array are not written in the file.

Example :

// constructing a 3-D array
int m = 3, n = 2, p = 4;
Array3D<double> A(m, n, p), B;
A.FillRand();

// you can write it on a file
A.Write("test.dat");

// then read it
B.Read("test.dat");

Related topics :

Read
Reallocate

Location :

Class Array3D
Array3D.hxx Array3D.cxx