Improve efficiency of 3D arrays in ns-3 for MIMO

The channel matrix in the current implementation of the 3GPP channel model is implemented as a 3D structure whose dimensions depend on the number of the TX antenna, RX antenna, and the number of clusters. This channel matrix is oriented toward the time domain. For the future extension of 3GPP models to support full MIMO, we will need to consider 3D structures in which we will have the three dimensions: the number of TX ports, the number of RX ports, and the number of resource blocks. Hence, there is a shift from time to frequency domain. While in the current 3GPP channel model structure the third dimension is relatively small, e.g., the number of clusters is between 10 and 20, the future 3D structure to support MIMO will have the third dimension quite large, e.g. 275 resource blocks.

In the development of MIMO, we have found out that this third dimension can affect significantly the computational performance if we use the same 3D structures that are available currently in the ns-3 and the spectrum module. Currently, in ns-3, the 3GPP channel model, uses a vector of vector of vectors to represent 3D arrays, such as the channel matrix. Matteo Pagin has improved the efficiency of this by allowing the usage of Eigen to represent matrices, so when Eigen is available the 3GPP channel is represented as std::vector of Eigen matrices. This already improves the performance of the current models. However, we have found out that this is not enough for future usages, especially for extending the ns-3 spectrum to support full MIMO models.

Based on our evaluations, we have found out that using the vector of matrices (regardless they are C++ or Eigen) becomes inefficient when the third dimension increases which will be the case in the MIMO models. For this reason, we have investigated and propose to use a new type in ns-3 that can allow much more efficient storage/access and linear algebra operations on 3D structures, i.e., arrays of matrices, which are typically used either in the current SISO or future MIMO models. In this respect, we propose a new class called ValArray that leverages std::valarray to represent 3D structures. We extend this interface, by an additional class called MatrixArray, which treats this 3D array, as an array of matrices, on which linear algebra operations on matrices can be performed. We have created tests for ValArray and MatrixArray to test all the implemented functionalities. We have performed profiling that shows that this new type MatrixArray that we propose to represent SISO and MIMO channels is much more efficient than other approaches when the third dimension increases.

Apart from proposing a more efficient representation of 3D structures for SISO and MIMO, we are improving significantly the interfaces that are using Eigen, because we are wrapping them inside of the MatrixArray functions, instead of having different wrappers for Eigen 3D structure and ns-3 default 3D structures. We have performed the profiling to check whether this wrapping that we propose is less efficient than the current Eigen implementation, and we have found that it is depending on setup or is equally good or better. Better comes from the usage of underlying std::valarray to represent the 3D structure instead of the usage of std::vector of matrices. And, additionally, our approach when using Eigen leverages the Eigen::Map function to which we provide the piece of memory where the matrix is placed, so there we don't add some additional inefficiency by our approach.

Here is the profiling when varying the third dimension and while keeping the first two dimensions very small 2x2, for different cases of the representation of 3D structures:

1. Currently in ns3: std::vector<std::vector<std::vector>>>
2. Proposed in MR !1046 (merged) std::vector<Eigen::Matrix>
3. MatrixArray when Eigen is disabled
4. MatrixArray when Eigen is enabled

Profiling is carried out by using the optimized mode (./ns3 configure --enable-examples --enable-tests -d optimized) and for enabling/disabling Eigen we used --enable-eigen or --disable-eigen (ns3 option that we added in this MR). For profiling, we have created the example that performs 1e5 multiplications of two 3D arrays and assigns the value to the third 3D array. For that purpose we created the following examples: 1) For simulating the usage of MatrixArray matrix-array-benchmark.cc and 2) For simulating the usage of currently used structures in ns-3/spectrum: std::vector<std::vector<std::vector>>> and std::vector<Eigen::Matrix> matrices: vector3d-benchmark.cc. We run 1) and 2) in the two compilation modes --enable-eigen and --disable-eigen. For each value of the third dimension (10, 50, 100, 200, 300), we run 20 independent repetitions.

Approach	Without Eigen	With Eigen
Current ns-3
MatrixArray

This MR depends on the MR !1046 (merged), because !1046 (merged) adds the possibility of using Eigen in ns-3. But, as we explain above we simplify the interfaces introduced in !1046 (merged), when Eigen is used and when not, and we unify them in MatrixArray class.

So, for reviewers of this MR, this MR contains only the 4 commits that are under my name, the rest of the commits are from !1046 (merged) MR.