1cd .. include:: replace.txt 2 3 4++++++++++++++++++++++++++++++++++++++ 5Design documentation 6++++++++++++++++++++++++++++++++++++++ 7 8 9Overview 10++++++++ 11 12The Buildings module provides: 13 14 #. a new class (``Building``) that models the presence of a building in a simulation scenario; 15 #. a new class (``MobilityBuildingInfo``) that allows to specify the location, size and characteristics of buildings present in the simulated area, and allows the placement of nodes inside those buildings; 16 #. a container class with the definition of the most useful pathloss models and the correspondent variables called ``BuildingsPropagationLossModel``. 17 #. a new propagation model (``HybridBuildingsPropagationLossModel``) working with the mobility model just introduced, that allows to model the phenomenon of indoor/outdoor propagation in the presence of buildings. 18 #. a simplified model working only with Okumura Hata (``OhBuildingsPropagationLossModel``) considering the phenomenon of indoor/outdoor propagation in the presence of buildings. 19 #. a channel condition model (``BuildingsChannelConditionModel``) which determined the LOS/NLOS channel condition based on the ``Building`` objects deployed in the scenario. 20 #. hybrid channel condition models (``ThreeGppV2vUrbanChannelConditionModel`` and ``ThreeGppV2vHighwayChannelConditionModel``) specifically designed to model vehicular environments (more information can be found in the :ref:`documentation of the propagation module <sec-3gpp-v2v-ch-cond>`) 21 22The models have been designed with LTE in mind, though their implementation is in fact independent from any LTE-specific code, and can be used with other ns-3 wireless technologies as well (e.g., wifi, wimax). 23 24The ``HybridBuildingsPropagationLossModel`` pathloss model included is obtained through a combination of several well known pathloss models in order to mimic different environmental scenarios such as urban, suburban and open areas. Moreover, the model considers both outdoor and indoor indoor and outdoor communication has to be included since HeNB might be installed either within building and either outside. In case of indoor communication, the model has to consider also the type of building in outdoor <-> indoor communication according to some general criteria such as the wall penetration losses of the common materials; moreover it includes some general configuration for the internal walls in indoor communications. 25 26The ``OhBuildingsPropagationLossModel`` pathloss model has been created for simplifying the previous one removing the thresholds for switching from one model to other. For doing this it has been used only one propagation model from the one available (i.e., the Okumura Hata). The presence of building is still considered in the model; therefore all the considerations of above regarding the building type are still valid. The same consideration can be done for what concern the environmental scenario and frequency since both of them are parameters of the model considered. 27 28 29The Building class 30++++++++++++++++++ 31 32The model includes a specific class called ``Building`` which contains a ns3 ``Box`` class for defining the dimension of the building. In order to implements the characteristics of the pathloss models included, the ``Building`` class supports the following attributes: 33 34 * building type: 35 36 * Residential (default value) 37 * Office 38 * Commercial 39 40 * external walls type 41 42 * Wood 43 * ConcreteWithWindows (default value) 44 * ConcreteWithoutWindows 45 * StoneBlocks 46 47 * number of floors (default value 1, which means only ground-floor) 48 * number of rooms in x-axis (default value 1) 49 * number of rooms in y-axis (default value 1) 50 51The Building class is based on the following assumptions: 52 53 * a buildings is represented as a rectangular parallelepiped (i.e., a box) 54 * the walls are parallel to the x, y, and z axis 55 * a building is divided into a grid of rooms, identified by the following parameters: 56 57 * number of floors 58 * number of rooms along the x-axis 59 * number of rooms along the y-axis 60 61 * the z axis is the vertical axis, i.e., floor numbers increase for increasing z axis values 62 * the x and y room indices start from 1 and increase along the x and y axis respectively 63 * all rooms in a building have equal size 64 65 66 67The MobilityBuildingInfo class 68++++++++++++++++++++++++++++++ 69 70The ``MobilityBuildingInfo`` class, which inherits from the ns3 class ``Object``, is in charge of maintaining information about the position of a node with respect to building. The information managed by ``MobilityBuildingInfo`` is: 71 72 * whether the node is indoor or outdoor 73 * if indoor: 74 75 * in which building the node is 76 * in which room the node is positioned (x, y and floor room indices) 77 78The class ``MobilityBuildingInfo`` is used by ``BuildingsPropagationLossModel`` class, which inherits from the ns3 class ``PropagationLossModel`` and manages the pathloss computation of the single components and their composition according to the nodes' positions. Moreover, it implements also the shadowing, that is the loss due to obstacles in the main path (i.e., vegetation, buildings, etc.). 79 80It is to be noted that, ``MobilityBuildingInfo`` can be used by any other propagation model. However, based on the information at the time of this writing, only the ones defined in the building module are designed for considering the constraints introduced by the buildings. 81 82 83 84 85ItuR1238PropagationLossModel 86++++++++++++++++++++++++++++ 87 88This class implements a building-dependent indoor propagation loss model based on the ITU P.1238 model, which includes losses due to type of building (i.e., residential, office and commercial). 89The analytical expression is given in the following. 90 91.. math:: 92 93 L_\mathrm{total} = 20\log f + N\log d + L_f(n)- 28 [dB] 94 95where: 96 97 :math:`N = \left\{ \begin{array}{lll} 28 & residential \\ 30 & office \\ 22 & commercial\end{array} \right.` : power loss coefficient [dB] 98 99 :math:`L_f = \left\{ \begin{array}{lll} 4n & residential \\ 15+4(n-1) & office \\ 6+3(n-1) & commercial\end{array} \right.` 100 101 :math:`n` : number of floors between base station and mobile (:math:`n\ge 1`) 102 103 :math:`f` : frequency [MHz] 104 105 :math:`d` : distance (where :math:`d > 1`) [m] 106 107 108 109 110BuildingsPropagationLossModel 111+++++++++++++++++++++++++++++ 112 113The BuildingsPropagationLossModel provides an additional set of building-dependent pathloss model elements that are used to implement different pathloss logics. These pathloss model elements are described in the following subsections. 114 115 116 117External Wall Loss (EWL) 118------------------------- 119 120This component models the penetration loss through walls for indoor to outdoor communications and vice-versa. The values are taken from the [cost231]_ model. 121 122 * Wood ~ 4 dB 123 * Concrete with windows (not metallized) ~ 7 dB 124 * Concrete without windows ~ 15 dB (spans between 10 and 20 in COST231) 125 * Stone blocks ~ 12 dB 126 127 128Internal Walls Loss (IWL) 129------------------------- 130 131This component models the penetration loss occurring in indoor-to-indoor communications within the same building. The total loss is calculated assuming that each single internal wall has a constant penetration loss :math:`L_{siw}`, and approximating the number of walls that are penetrated with the manhattan distance (in number of rooms) between the transmitter and the receiver. In detail, let :math:`x_1`, :math:`y_1`, :math:`x_2`, :math:`y_2` denote the room number along the :math:`x` and :math:`y` axis respectively for user 1 and 2; the total loss :math:`L_{IWL}` is calculated as 132 133.. math:: 134 135 L_{IWL} = L_{siw} (|x_1 -x_2| + |y_1 - y_2|) 136 137 138 139 140 141Height Gain Model (HG) 142----------------------- 143 144This component model the gain due to the fact that the transmitting device is on a floor above the ground. In the literature [turkmani]_ this gain has been evaluated as about 2 dB per floor. This gain can be applied to all the indoor to outdoor communications and vice-versa. 145 146 147Shadowing Model 148--------------- 149 150The shadowing is modeled according to a log-normal distribution with variable standard deviation as function of the relative position (indoor or outdoor) of the MobilityModel instances involved. One random value is drawn for each pair of MobilityModels, and stays constant for that pair during the whole simulation. Thus, the model is appropriate for static nodes only. 151 152The model considers that the mean of the shadowing loss in dB is always 0. For the variance, the model considers three possible values of standard deviation, in detail: 153 154 * outdoor (``m_shadowingSigmaOutdoor``, defaul value of 7 dB) :math:`\rightarrow X_\mathrm{O} \sim N(\mu_\mathrm{O}, \sigma_\mathrm{O}^2)`. 155 * indoor (``m_shadowingSigmaIndoor``, defaul value of 10 dB) :math:`\rightarrow X_\mathrm{I} \sim N(\mu_\mathrm{I}, \sigma_\mathrm{I}^2)`. 156 * external walls penetration (``m_shadowingSigmaExtWalls``, default value 5 dB) :math:`\rightarrow X_\mathrm{W} \sim N(\mu_\mathrm{W}, \sigma_\mathrm{W}^2)` 157 158The simulator generates a shadowing value per each active link according to nodes' position the first time the link is used for transmitting. In case of transmissions from outdoor nodes to indoor ones, and vice-versa, the standard deviation (:math:`\sigma_\mathrm{IO}`) has to be calculated as the square root of the sum of the quadratic values of the standard deviatio in case of outdoor nodes and the one for the external walls penetration. This is due to the fact that that the components producing the shadowing are independent of each other; therefore, the variance of a distribution resulting from the sum of two independent normal ones is the sum of the variances. 159 160.. math:: 161 162 X \sim N(\mu,\sigma^2) \mbox{ and } Y \sim N(\nu,\tau^2) 163 164 Z = X + Y \sim Z (\mu + \nu, \sigma^2 + \tau^2) 165 166 \Rightarrow \sigma_\mathrm{IO} = \sqrt{\sigma_\mathrm{O}^2 + \sigma_\mathrm{W}^2} 167 168 169 170 171 172Pathloss logics 173+++++++++++++++ 174 175In the following we describe the different pathloss logic that are implemented by inheriting from BuildingsPropagationLossModel. 176 177 178HybridBuildingsPropagationLossModel 179----------------------------------- 180 181The ``HybridBuildingsPropagationLossModel`` pathloss model included is obtained through a combination of several well known pathloss models in order to mimic different outdoor and indoor scenarios, as well as indoor-to-outdoor and outdoor-to-indoor scenarios. In detail, the class ``HybridBuildingsPropagationLossModel`` integrates the following pathloss models: 182 183 * OkumuraHataPropagationLossModel (OH) (at frequencies > 2.3 GHz substituted by Kun2600MhzPropagationLossModel) 184 * ItuR1411LosPropagationLossModel and ItuR1411NlosOverRooftopPropagationLossModel (I1411) 185 * ItuR1238PropagationLossModel (I1238) 186 * the pathloss elements of the BuildingsPropagationLossModel (EWL, HG, IWL) 187 188The following pseudo-code illustrates how the different pathloss model elements described above are integrated in ``HybridBuildingsPropagationLossModel``:: 189 190 if (txNode is outdoor) 191 then 192 if (rxNode is outdoor) 193 then 194 if (distance > 1 km) 195 then 196 if (rxNode or txNode is below the rooftop) 197 then 198 L = I1411 199 else 200 L = OH 201 else 202 L = I1411 203 else (rxNode is indoor) 204 if (distance > 1 km) 205 then 206 if (rxNode or txNode is below the rooftop) 207 L = I1411 + EWL + HG 208 else 209 L = OH + EWL + HG 210 else 211 L = I1411 + EWL + HG 212 else (txNode is indoor) 213 if (rxNode is indoor) 214 then 215 if (same building) 216 then 217 L = I1238 + IWL 218 else 219 L = I1411 + 2*EWL 220 else (rxNode is outdoor) 221 if (distance > 1 km) 222 then 223 if (rxNode or txNode is below the rooftop) 224 then 225 L = I1411 + EWL + HG 226 else 227 L = OH + EWL + HG 228 else 229 L = I1411 + EWL 230 231 232 233 234We note that, for the case of communication between two nodes below rooftop level with distance is greater then 1 km, we still consider the I1411 model, since OH is specifically designed for macro cells and therefore for antennas above the roof-top level. 235 236For the ITU-R P.1411 model we consider both the LOS and NLoS versions. In particular, we considers the LoS propagation for distances that are shorted than a tunable threshold (``m_itu1411NlosThreshold``). In case on NLoS propagation, the over the roof-top model is taken in consideration for modeling both macro BS and SC. In case on NLoS several parameters scenario dependent have been included, such as average street width, orientation, etc. The values of such parameters have to be properly set according to the scenario implemented, the model does not calculate natively their values. In case any values is provided, the standard ones are used, apart for the height of the mobile and BS, which instead their integrity is tested directly in the code (i.e., they have to be greater then zero). In the following we give the expressions of the components of the model. 237 238We also note that the use of different propagation models (OH, I1411, I1238 with their variants) in HybridBuildingsPropagationLossModel can result in discontinuities of the pathloss with respect to distance. A proper tuning of the attributes (especially the distance threshold attributes) can avoid these discontinuities. However, since the behavior of each model depends on several other parameters (frequency, node height, etc), there is no default value of these thresholds that can avoid the discontinuities in all possible configurations. Hence, an appropriate tuning of these parameters is left to the user. 239 240 241OhBuildingsPropagationLossModel 242------------------------------- 243 244The ``OhBuildingsPropagationLossModel`` class has been created as a simple means to solve the discontinuity problems of ``HybridBuildingsPropagationLossModel`` without doing scenario-specific parameter tuning. The solution is to use only one propagation loss model (i.e., Okumura Hata), while retaining the structure of the pathloss logic for the calculation of other path loss components (such as wall penetration losses). The result is a model that is free of discontinuities (except those due to walls), but that is less realistic overall for a generic scenario with buildings and outdoor/indoor users, e.g., because Okumura Hata is not suitable neither for indoor communications nor for outdoor communications below rooftop level. 245 246In detail, the class ``OhBuildingsPropagationLossModel`` integrates the following pathloss models: 247 248 * OkumuraHataPropagationLossModel (OH) 249 * the pathloss elements of the BuildingsPropagationLossModel (EWL, HG, IWL) 250 251The following pseudo-code illustrates how the different pathloss model elements described above are integrated in ``OhBuildingsPropagationLossModel``:: 252 253 if (txNode is outdoor) 254 then 255 if (rxNode is outdoor) 256 then 257 L = OH 258 else (rxNode is indoor) 259 L = OH + EWL 260 else (txNode is indoor) 261 if (rxNode is indoor) 262 then 263 if (same building) 264 then 265 L = OH + IWL 266 else 267 L = OH + 2*EWL 268 else (rxNode is outdoor) 269 L = OH + EWL 270 271We note that OhBuildingsPropagationLossModel is a significant simplification with respect to HybridBuildingsPropagationLossModel, due to the fact that OH is used always. While this gives a less accurate model in some scenarios (especially below rooftop and indoor), it effectively avoids the issue of pathloss discontinuities that affects HybridBuildingsPropagationLossModel. 272