Iterations through 3d containers

Introduction

Here, we present various ways to computes the mean of a 3d container denoted S3d. It illustrates the different uses to iterate throw tridimensional containers 3d Containers like: slip::block3d, slip::Array3d, slip::Matrix3d, slip::Volume and multicomponent tridimensional containers Multi-component 3d Containers. Here are the axis conventions used in the library:

The classical loop

slip::Array2d<double> S3d(3,4,5);
double mean = 0.0;
const std::size_t slices = S3d.slices();
const std::size_t rows   = S3d.rows();
const std::size_t cols   = S3d.cols();

for(std::size_t k = 0; k < slices; ++k)
{
 for(std::size_t i = 0; i < rows; ++i)
   {
    for(std::size_t j = 0; j < cols; ++j)
      {
       mean += S3d[k][i][j];
       //mean += S3d(k,i,j);
      }
   }
}
mean = mean / double(S3d.size());

1d iterators

These iterators follow the RandomAccessIterator concept of the standard template library.

Direct global 1d iterators

slip::Array3d<double> S3d(3,3,4);
double m = slip::mean<double>(S3d.begin(),S3d.end());

Reverse global 1d iterators

slip::Array3d<double> S3d(3,3,4);
double m = slip::mean<double>(S3d.rbegin(),S3d.rend());

Direct slice, row and column iterators

slip::Array3d<double> S3d(3,3,4);
double m_green = slip::mean<double>(S3d.slice_begin(0,1),S3d.slice_end(0,1));
double m_red = slip::mean<double>(S3d.row_begin(0,1),S3d.row_end(0,1));
double m_blue = slip::mean<double>(S3d.col_begin(1,3),S3d.col_end(1,3));

Reverse slice, row and column iterators

slip::Array3d<double> S3d(3,3,4);
double m_green = slip::mean<double>(S3d.slice_rbegin(0,1),S3d.slice_rend(0,1));
double m_red  = slip::mean<double>(S3d.row_rbegin(0,1),S3d.row_rend(0,1));
double m_blue = slip::mean<double>(S3d.col_rbegin(1,3),S3d.col_rend(1,3));

2d iterators

These iterators follow the BidirectionalIterator concept of the standard library. They are specific bidimensional iterators that iterate within a plane of the 3d container. The plane orientation is defined by an enumerator. Those iterators are less fast than RandomAccessIterator one because they verify that the iteration stay within the defined ranges. See the internal classes slip::iterator3d_plane and slip::const_iterator3d_plane for more details. The convention of plane iterators are given below:

Direct plane iterators

double m_IJ = slip::mean<double>(S3d.upper_left(slip::IJ_PLANE,1), S3d.bottom_right(slip::IJ_PLANE,1));
double m_KI = slip::mean<double>(S3d.upper_left(slip::KI_PLANE,1), S3d.bottom_right(slip::KI_PLANE,1));
double m_KJ = slip::mean<double>(S3d.upper_left(slip::KJ_PLANE,1), S3d.bottom_right(slip::KJ_PLANE,1));

Reverse plane iterators

double m_IJ = slip::mean<double>(S3d.rupper_left(slip::IJ_PLANE,1), S3d.rbottom_right(slip::IJ_PLANE,1));
double m_KI = slip::mean<double>(S3d.rupper_left(slip::KI_PLANE,1), S3d.rbottom_right(slip::KI_PLANE,1));
double m_KJ = slip::mean<double>(S3d.rupper_left(slip::KJ_PLANE,1), S3d.rbottom_right(slip::KJ_PLANE,1));

Box iterators

These iterators follow the BidirectionalIterator concept of the standard library. They are specific tridimensional iterator that store the k(x1), i (x2) and j (x3) positions of the iterator within the container. These coordinates are accessible by the method k() (x1()), i() (x2())and j() (x3()). These iterators are less fast than RandomAccessIterator because a verification that the position stays within the defined box is done at every iteration. See the internal classes slip::iterator3d_box and slip::const_iterator3d_box for more details.

slip::Array3d<double> S3d(3,3,4);
slip::Box3d<int> box(0,0,2,1,1,3)
double m = slip::mean<double>(S3d.front_upper_left(box),S3d.back_bottom_right(box)); 

slip::Array3d<double> S3d(3,3,4);
slip::Box3d<int> box(0,0,2,1,1,3)
double m = slip::mean<double>(S3d.rfront_upper_left(box),S3d.rback_bottom_right(box)); 

Range iterators

These iterators follow the BidirectionalIterator concept of the standard library. Specific triidimensional iterator that store the k(x1), i (x2) and j (x3) positions of the iterator within the container. These coordinates are accessible by the method k()(x1()), i() (x2())and j() (x3()). These iterators are less fast than RandomAccessIterator because they verify that the iteration stay within the defined ranges. See the internal classes slip::iterator3d_range and slip::const_iterator3d_range for more details.

slip::Array3d<double> S3d(3,3,4);
slip::Range<int> range_slice(0,1,1);
slip::Range<int> range_row(0,2,2);
slip::Range<int> range_col(2,3,1);
double m = slip::mean<double> (S3d.front_upper_left(range_slice,range_row,range_col),S3d.back_bottom_right(range_slice,range_row,range_col)); 

slip::Array3d<double> S3d(3,3,4);
slip::Range<int> range_slice(0,1,1);
slip::Range<int> range_row(0,2,2);
slip::Range<int> range_col(2,3,1);
double m = slip::mean<double>(S3d.rfront_upper_left(range_slice,range_row,range_col),S3d.rback_bottom_right(range_slice,range_row,range_col));  

Multi-component iterators

To iterate throw a specific component of a multi-component container. It suffies to add first the number of the component to all the previous iterator methods. See slip::GenericMultiComponent3d for a more detail description.

slip::RegularVector3dField3d<double> S3d(3,3,4);
const std::size_t component = 1;
//iterate throw the second component (component 1) of the 3d vector field
double m = slip::mean<double>(S3d.begin(component),S3d.end(component));