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.
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);
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 |
| 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 |
Array3D(int i, int j, int k)
You can use a constructor with the dimensions of the 3-D array.
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);
Class Array3D
Array3D.hxx Array3D.cxx
operator ()(int i, int j, int k) operator = (const Array3D<T>& )
The access operator () can be used to modify A(i, j, k).
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;
Class Array3D
Array3D.hxx Array3D.cxx
int GetLength1() const
This method returns the first dimension of the 3-D array.
Array3D<double> A, B(5, 6, 3); // GetLength1() should return 5 cout << "First dimension of B " << B.GetLength1() << endl;
Class Array3D
Array3D.hxx Array3D.cxx
int GetLength2() const
This method returns the second dimension of the 3-D array.
Array3D<double> A, B(5, 6, 3); // GetLength2() should return 6 cout << "Second dimension of B " << B.GetLength2() << endl;
Class Array3D
Array3D.hxx Array3D.cxx
int GetLength3() const
This method returns the third dimension of the 3-D array.
Array3D<double> A, B(5, 6, 3); // GetLength3() should return 3 cout << "Third dimension of B " << B.GetLength3() << endl;
Class Array3D
Array3D.hxx Array3D.cxx
int GetSize() const int GetDataSize() const
This method returns the number of elements effectively stored in the 3-D array.
Array3D<double> A, B(5, 6, 3); // GetSize() should return 5*6*3 = 90 cout << "Number of elements of B " << B.GetSize() << endl;
Class Array3D
Array3D.hxx Array3D.cxx
size_t GetMemorySize() const
This method returns the memory used to store the array in bytes.
Array3D<double> A, B(5, 6, 3); // GetMemorySize() should return 5*6*3*sizeof(double) cout << "Memory used to store B " << B.GetMemorySize() << endl;
Class Array3D
Array3D.hxx Array3D.cxx
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.
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();
Class Array3D
Array3D.hxx Array3D.cxx
T* GetDataPointer(int i, int j, int k) const
This method is equivalent to &A(i, j, k)
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();
Class Array3D
Array3D.hxx Array3D.cxx
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.
Array3D<double> A(5, 6, 3); A.Fill(); // then changing the size of A A.Reallocate(7, 2, 5);
Class Array3D
Array3D.hxx Array3D.cxx
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.
// 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;
Class Array3D
Array3D.hxx Array3D.cxx
void Nullify()
This method clears the 3-D array without releasing the memory. This low-level method should be used cautiously
// 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();
Class Array3D
Array3D.hxx Array3D.cxx
void Clear()
This method clears the 3-D array.
// 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();
Class Array3D
Array3D.hxx Array3D.cxx
void Copy(const Array3D<T>& )
This method copies a 3-D array into the current object.
// 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);
Class Array3D
Array3D.hxx Array3D.cxx
void Fill() void Fill(const T& x)
This method fills the 3-D array with 0, 1, 2, ... or with a given value.
// 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|
Class Array3D
Array3D.hxx Array3D.cxx
void Zero()
This method initializes all the entries to 0.
// 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();
Class Array3D
Array3D.hxx Array3D.cxx
void FillRand()
This method fills the 3-D array with random values.
// 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();
Class Array3D
Array3D.hxx Array3D.cxx
void Print()
This method displays the 3-D array.
// 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();
Class Array3D
Array3D.hxx Array3D.cxx
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.
// 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");Class Array3D
Array3D.hxx Array3D.cxx
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.
// 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");Class Array3D
Array3D.hxx Array3D.cxx