F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

revised buildings documentation

Browse Source
This commit is contained in:
Nicola Baldo
2012-01-12 17:23:56 +01:00
parent 84248ec1d8
commit 675c34b604
3 changed files with 25 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
src/buildings/doc/source/buildings-design.rst
View File

@@ -10,7 +10,8 @@ Overview
++++++++
The Buildings module provides:
#. a new class (Building) that models the presence of a building in a simulation scenario;
#. a new mobility model (BuildingsMobilityModel) 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;
#. a new propagation model (BuildingsPropagationLossModel) working with the mobility model just introduced, that allows to model the phenomenon of indoor/outdoor propagation in the presence of buildings.
@@ -18,16 +19,17 @@ Both models have been designed with LTE in mind, though their implementation is
The 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. Finally, the frequency also represent an important parameter since it spans from 600 MHz up to 2600 MHz according to [TS36.101]_.
Description of the Included Models
++++++++++++++++++++++++++++++++++
The Building class
++++++++++++++++++
For discriminate indoor and outdoor users, the 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 provides support for:
The 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:
* building type:
* Residential (default value)
* Office
* Commercial
* external walls type
* Wood
@@ -37,7 +39,7 @@ For discriminate indoor and outdoor users, the model includes a specific class c
* number of floors (default value 1, which means only ground-floor)
* number of rooms in x-axis (default value 1)
* number of rooms in x-axis (default value 1)
* number of rooms in y-axis (default value 1)
By means of the number of rooms in x and y axis it is possible the definition of buildings where rooms are organized in grids, typical reference scenario for femto-cells in 3GPP called dual-strip.
@@ -45,7 +47,10 @@ The ``Building`` class is included in ``BuildingsMobilityModel`` class, which in
The class ``BuildingsMobilityModel`` 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.).
In the following we present the link pathloss models included.
Pathloss models used in BuildingsPropagationLossModel
+++++++++++++++++++++++++++++++++++++++++++++++++++++
In the following we present the pathloss models that are included in the BuildingsPropagationLossModel
Okumura Hata (OH)
-----------------
@@ -133,7 +138,7 @@ Therefore, also in this case, the suburban and openareas environment scenarios a
Short Range Communications ITU-R P.1411 (I1411)
---------------------------------------
-----------------------------------------------
This model is designed for short range outdoor communication in the frequency range 300 MHz to 100 GHz. It is divided in LOS and NLoS models and NLoS is split in roof-tops and canyons. The model implemented considers the LoS propagation for short distances according to 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.
@@ -328,11 +333,10 @@ The pathloss model characterizes the hybrid cases (i.e., when an outdoor node tr
Pathloss Logic Model
++++++++++++++++++++
Pathloss Model Logic of BuildingsPropagationLossModel
+++++++++++++++++++++++++++++++++++++++++++++++++++++
In the following the pseudo-code of the model is presented::
The following pseudo-code illustrates how the different pathloss models described above are integrated in the BuildingsPropagationLossModel::
if (txNode is outdoor)
then
@@ -376,12 +380,7 @@ In the following the pseudo-code of the model is presented::
L = I1411 + BEL
Some considerations that apply when the Buildings model is used in an LTE FDD context:
* in the uplink, the txNode will be an UE, whereas the rxNode will be a
where ``txNode`` and ``rxNode`` can be one of the elements eNB, SC and UE.
We note that for SC nodes in case that the distance is greater then 1 km, we still consider the I1411 model since it better models the transmissions with antenna below the roof-top level and moreover due to the fact that OH is specifically designed for macro cells and therefore for antennas above the roof-top level. Finally, we introduced a threshold also or SC transmissions (called ``m_itu1411DistanceThreshold``) for pruning the communications between SCs and UEs too far (the default values is fixed to 2 km).
We 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. Finally, we introduced a threshold called ``m_itu1411DistanceThreshold``) for pruning the communications between nodes below rooftop when the distance is too large (the default values is 2 km).
Shadowing Model

22
src/buildings/doc/source/buildings-testing.rst
View File

@@ -6,13 +6,12 @@
Overview
********
To test and validate the ns-3 Building Pathloss module, a test suites is provided which are integrated with the ns-3 test framework in the lte module.
To run them, you need to have configured the build of the simulator in this way::
To test and validate the ns-3 Building Pathloss module, some test suites is provided which are integrated with the ns-3 test framework. To run them, you need to have configured the build of the simulator in this way::
./waf configure --enable-tests --enable-modules=lte --enable-examples
./waf configure --enable-tests --enable-modules=buildings
./test.py
The above will run not only the test suites belonging to the LTE module, but also those belonging to all the other ns-3 modules on which the LTE module depends. See the ns-3 manual for generic information on the testing framework.
The above will run not only the test suites belonging to the buildings module, but also those belonging to all the other ns-3 modules on which the buildings module depends. See the ns-3 manual for generic information on the testing framework.
You can get a more detailed report in HTML format in this way::
@@ -28,16 +27,13 @@ For more details about ``test.py`` and the ns-3 testing framework, please refer
Description of the test suite
*****************************
Description of the test suites
******************************
The test suite ``lte-pathloss-model`` creates different test cases with
both unit and system tests. The formers validate the single component model and the pathloss logic behavior. The latter proof the integration of the pathloss model in the ns3 framework and more in specifically in the lte module. Finally. a unit test is provided in order to test the shadowing characterization.
Pathloss tests
~~~~~~~~~~~~~~
Unit Tests
~~~~~~~~~~
The unit tests are carried out by comparing the expected results of the pathloss module in specific scenarios with pre calculated values obtained offline with an Octave script (/test/reference/lte-pathloss.m). The tests are considered passed if the two values differs only for a predefined tolerance (0.1) that accounts for the approximations due to floating point arithmetics.
The test suite ``buildings-pathloss-model`` provides different unit tests that compare the expected results of the buildings pathloss module in specific scenarios with pre calculated values obtained offline with an Octave script (test/reference/buildings-pathloss.m). The tests are considered passed if the two values are equal up to a tolerance of 0.1, which is deemed appropriate for the typical usage of pathloss values (which are in dB).
In the following we detailed the scenarios considered, their selection has been done for covering the wide set of possible pathloss logic combinations. The pathloss logic results therefore implicitly tested.
@@ -96,6 +92,6 @@ This test validates the outdoor to indoor transmissions for short distances. In
Shadowing Test
~~~~~~~~~~~~~~
This unit test is intended to verify the statistics distribution characteristics of the shadowing are the one expected. The shadowing is modeled according to a normal distribution with mean 0 and variable standard deviation (usually called sigma), according to the standard models used in literature.
The test suite ``buildings-shadowing-test`` is a unit test intended to verify the statistics distribution characteristics of the shadowing are the one expected. The shadowing is modeled according to a normal distribution with mean :math:`\mu = 0` and variable standard deviation :math:`\sigma`, according to models commonly used in literature.
The test generates 10,000 samples of shadowing by subtracting the deterministic component from the total loss returned by the ``BuildingPathlossModel``. The mean and variance of the shadowing samples are then used to verify whether the 99% confidence interval is respected by the sequence generated by the simulator.

110
src/buildings/doc/source/buildings-user.rst
View File

@@ -6,37 +6,6 @@
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Background
**********
We assume the reader is already familiar with how to use the ns-3
simulator to run generic simulation programs. If this is not the case,
we strongly recommend the reader to consult [ns3tutorial]_.
Usage Overview
**************
The ns-3 LTE model is a software library that allows the simulation of
LTE networks. The process of performing such simulations typically involves the following
steps:
1. *Define the scenario* to be simulated
2. *Write a simulation program* that recreates the desired scenario
topology/architecture. This is done accessing the ns-3 LTE model
libraryusing the ``ns3::LenaHelper`` API defined in ``src/lte/helper/lena-helper.h``.
3. *Specify configuration parameters* of the objects that are being
used for the simulation. This can be done using input files (via the
``ns3::ConfigStore``) or directly within the simulation program.
4. *Configure the desired output* to be produced by the simulator
5. *Run* the simulation.
All these aspects will be explained in the following sections by means
of practical examples.
Main configurable parameters
----------------------------
@@ -70,85 +39,6 @@ The ``BuildingPropagationModel`` class has the following configurable parameters
* ``CitySize``: the dimension of the city among Small, Medium, Large (default Large).
Basic simulation program
------------------------
In what following, a few guidelines for the usage of the ``BuildingMobilityModel`` and the ``BuildingPropagationModel`` classes with an example based on the lte module.
.. highlight:: none
#. Inheritance::
#include <ns3/buildings-mobility-model.h>
#include <ns3/buildings-propagation-loss-model.h>
#include <ns3/building.h>
#. Propagation model selection::
Ptr<LenaHelper> lena = CreateObject<LenaHelper> ();
lena->SetAttribute ("PropagationModel", StringValue ("ns3::BuildingsPropagationLossModel"));
#. EUTRA Band Selection
The selection of the working frequency of the propagation model has to be done with the standard ns-3 attribute system as described in the correspond section ("Configuration of LTE model parameters") by means of the DlEarfcn and UlEarfcn parameters, for instance::
lena->SetEnbDeviceAttribute ("DlEarfcn", UintegerValue (100));
lena->SetEnbDeviceAttribute ("UlEarfcn", UintegerValue (18100));
It is to be noted that any other configuration (i.e., with BuildingsPropagationLossModel attributes) might generates conflicts in the frequencies definition in the modules during the simulation.
#. Mobility model selection::
MobilityHelper mobility;
mobility.SetMobilityModel ("ns3::BuildingsMobilityModel");
#. Node creation and positioning::
ueNodes.Create (1);
mobility.Install (ueNodes);
NetDeviceContainer ueDevs;
ueDevs = lena->InstallUeDevice (ueNodes);
Ptr<BuildingsMobilityModel> mm = enbNodes.Get (0)->GetObject<BuildingsMobilityModel> ();
double x_axis = 0.0;
double y_axis = 0.0;
double z_axis = 0.0;
mm->SetPosition (Vector (x_axis, y_axis, z_axis));
#. Building creation::
double x_min = 0.0;
double x_max = 10.0;
double y_min = 0.0;
double y_max = 20.0;
double z_min = 0.0;
double z_max = 10.0;
Ptr<Building> building = Create<Building> (x_min, x_max, y_min, y_max, z_min, z_max);
building->SetBuildingType (Building::Residential);
building->SetExtWallsType (Building::ConcreteWithWindows);
building->SetFloorsNumber (3);
building->SetNumberRoomX (3);
building->SetNumberRoomY (2);
This will instantiate a residential building with base of 10 x 20 meters and height of 10 meters with concrete with windows as external walls, three floors and a grid of rooms of 3 x 2.
#. Building and nodes interactions::
mm->SetIndoor (building, 2, 1, 1);
which is equivalent to the form::
mm->SetIndoor (building);
mm->SetFloorNumber (2);
mm->SetRoomNumberX (1);
mm->SetRoomNumberY (1);
This informs node's mobility model the fact that the node is inside the building at the second floor in the corner room of the 3 x 2 grid.
We suggest the usage of the first form since it performs a consistency check of the node position with the building bounds.
It has to be noted that the simulator does not check the consistence between the node's position (x,y,z coordinates) and the building position and size for outdoor nodes. The responsibility of this consistency is completely left to the user.