1.1 --- a/doc/main.h Wed Jun 01 13:03:21 2011 -0400
1.2 +++ b/doc/main.h Wed Jun 01 13:46:37 2011 -0400
1.3 @@ -38,6 +38,7 @@
1.4 * - aodv
1.5 * - applications
1.6 * - bridge
1.7 + * - brite
1.8 * - click
1.9 * - config-store
1.10 * - core
2.1 --- a/doc/models/Makefile Wed Jun 01 13:03:21 2011 -0400
2.2 +++ b/doc/models/Makefile Wed Jun 01 13:46:37 2011 -0400
2.3 @@ -20,6 +20,7 @@
2.4 $(SRC)/aodv/doc/aodv.rst \
2.5 $(SRC)/applications/doc/applications.rst \
2.6 $(SRC)/bridge/doc/bridge.rst \
2.7 + $(SRC)/brite/doc/brite.rst \
2.8 $(SRC)/click/doc/click.rst \
2.9 $(SRC)/csma/doc/csma.rst \
2.10 $(SRC)/dsdv/doc/dsdv.rst \
3.1 --- a/doc/models/source/index.rst Wed Jun 01 13:03:21 2011 -0400
3.2 +++ b/doc/models/source/index.rst Wed Jun 01 13:46:37 2011 -0400
3.3 @@ -23,6 +23,7 @@
3.4 aodv
3.5 applications
3.6 bridge
3.7 + brite
3.8 click
3.9 csma
3.10 dsdv
4.1 --- a/src/brite/doc/brite.h Wed Jun 01 13:03:21 2011 -0400
4.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
4.3 @@ -1,104 +0,0 @@
4.4 -/* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
4.5 -/*
4.6 - * Copyright (c) 2011 Josh Pelkey
4.7 - *
4.8 - * This program is free software; you can redistribute it and/or modify
4.9 - * it under the terms of the GNU General Public License version 2 as
4.10 - * published by the Free Software Foundation;
4.11 - *
4.12 - * This program is distributed in the hope that it will be useful,
4.13 - * but WITHOUT ANY WARRANTY; without even the implied warranty of
4.14 - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4.15 - * GNU General Public License for more details.
4.16 - *
4.17 - * You should have received a copy of the GNU General Public License
4.18 - * along with this program; if not, write to the Free Software
4.19 - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
4.20 - *
4.21 - * Authors: Josh Pelkey <jpelkey@gatech.edu>
4.22 - */
4.23 -
4.24 -/**
4.25 -* \ingroup topology
4.26 -* \defgroup brite Brite
4.27 -*
4.28 -* \section model Model
4.29 -*
4.30 -* This model implements an interface to BRITE, the Boston university
4.31 -* Representative Internet Topology gEnerator. BRITE is a standard tool for
4.32 -* generating realistic internet topologies. The ns-3 model, described herein,
4.33 -* provides a helper class to facilitate generating ns-3 specific topologies
4.34 -* using BRITE configuration files. BRITE builds the original graph which is
4.35 -* stored as nodes and edges in the ns-3 BriteTopolgyHelper class. By accessing
4.36 -* these nodes and edges, an ns-3 specific topology can easily be built, as
4.37 -* seen in the example provided, brite-generic-example.
4.38 -*
4.39 -* \section build Build Instructions
4.40 -*
4.41 -* The first step is to download and build the ns-3 specific BRITE repository:
4.42 -*
4.43 -* $: hg clone http://code.nsnam.org/jpelkey3/BRITE
4.44 -* $: cd BRITE
4.45 -* $: make
4.46 -*
4.47 -* This will build BRITE and create a library, libbrite.so, within the BRITE
4.48 -* directory.
4.49 -*
4.50 -* Once BRITE has been built successfully, we proceed to configure ns-3 with
4.51 -* BRITE support. Change to your ns-3 directory:
4.52 -*
4.53 -* $: ./waf configure --with-brite=/path/to/brite/source
4.54 -*
4.55 -* Make sure it says 'enabled' beside 'BRITE Integration'. If it does not, then
4.56 -* something has gone wrong. Either you have forgotten to build BRITE first
4.57 -* following the steps above, or ns-3 could not find your BRITE directory.
4.58 -*
4.59 -* Next, build ns-3.
4.60 -*
4.61 -* $: ./waf
4.62 -*
4.63 -* Next, try running the brite-generic-example
4.64 -*
4.65 -* $: ./waf --run 'brite-generic-example --verbose=1'
4.66 -*
4.67 -* By enabling the verbose parameter, the example will print out the node and
4.68 -* edge information in a similar format to standard BRITE output. There are
4.69 -* many other command-line parameters including confFile, seedFile, newseedFile,
4.70 -* tracing, and nix, described below:
4.71 -*
4.72 -* confFile: A BRITE configuration file. Many different BRITE configuration
4.73 -* file examples exist in the BRITE/conf_files directory, for
4.74 -* example, RTBarabasi20.conf and RTWaxman.conf. Please refer to
4.75 -* the conf_files directory for more examples.
4.76 -*
4.77 -* seedFile: BRITE specific seed file to seed a psuedo-random number genrator
4.78 -* from BRITE.
4.79 -*
4.80 -* newseedFile: BRITE automatically generates a new seed file for you, if you
4.81 -* would like to randomize subsequent runs. If you would like
4.82 -* this to happen automatically, simply use the same file for
4.83 -* seedFile and newseedFile. This way, BRITE will run with the
4.84 -* current seeds and then overwrite them for the next run.
4.85 -*
4.86 -* verbose: Prints out the node and edge information in a similar format
4.87 -* to standard BRITE output.
4.88 -*
4.89 -* tracing: Enables ascii tracing.
4.90 -*
4.91 -* nix: Enables nix-vector routing. Global routing is used by default.
4.92 -*
4.93 -* \section usage Usage
4.94 -*
4.95 -* The brite-generic-example can be referenced to see basic usage of the BRITE
4.96 -* interface. In summary, the BriteTopologyHelper is used as the interface point
4.97 -* by passing in a BRITE configuration and seed file. The BRITE generated nodes
4.98 -* and edges can then be accessed through this helper to create ns-3 nodes and
4.99 -* edges.
4.100 -*
4.101 -* Within the brite-generic-example, assigning IPs and creating applications
4.102 -* are done fairly simply, as topology generation is the main topic of the
4.103 -* BRITE interface. It is very likely that the user will need to change the
4.104 -* way in which IP addresses are assigned or applications are installed.
4.105 -*
4.106 -*/
4.107 -
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/src/brite/doc/brite.rst Wed Jun 01 13:46:37 2011 -0400
5.3 @@ -0,0 +1,136 @@
5.4 +.. include:: replace.txt
5.5 +
5.6 +BRITE Integration
5.7 +------------------
5.8 +
5.9 +This model implements an interface to BRITE, the Boston university
5.10 +Representative Internet Topology gEnerator [1]_. BRITE is a standard tool for
5.11 +generating realistic internet topologies. The ns-3 model, described herein,
5.12 +provides a helper class to facilitate generating ns-3 specific topologies
5.13 +using BRITE configuration files. BRITE builds the original graph which is
5.14 +stored as nodes and edges in the ns-3 BriteTopolgyHelper class. By accessing
5.15 +these nodes and edges, an ns-3 specific topology can easily be built, as
5.16 +seen in the example provided, brite-generic-example.
5.17 +
5.18 +
5.19 +Model Description
5.20 +*****************
5.21 +
5.22 +The model relies on building an external BRITE library,
5.23 +and then building some ns-3 helpers that call out to the library.
5.24 +The source code for the ns-3 helpers lives in the directory
5.25 +``src/brite/helper``.
5.26 +
5.27 +Design
5.28 +======
5.29 +
5.30 +The BRITE ns-3 helpers call out to the external BRITE library, and using a standard
5.31 +BRITE configuration file, the BRITE code builds a graph with nodes and edges
5.32 +according to this configuration file. Please see the BRITE documenation or the
5.33 +example configuration files in src/brite/examples/conf_files to get a better
5.34 +grasp of BRITE configuration options. The graph built by BRITE is returned to
5.35 +ns-3, and these nodes and edges are stored in ns-3 structures for use by the
5.36 +user.
5.37 +
5.38 +The ns-3 data structures holding all of the returned BRITE information are
5.39 +BriteNodeInfoList and BriteEdgeInfoList. Both of these are simply a vector
5.40 +of structs with each Node and Edge struct holding all of the individual
5.41 +node and edge information returned from the BRITE graph.
5.42 +
5.43 +Finally, these two data structures are used to build ns-3 specific topologies.
5.44 +It is up to the user to use these nodes and edges and connect them correctly.
5.45 +An example, brite-generic-example, is provided to show the user how to do this.
5.46 +
5.47 +Note: BRITE accepts a seed file to seed its psuedo-random number generator. It also
5.48 +spits out a new seed file after every run -- overwriting your old seed file --
5.49 +in case you wish to randomize subsequent runs. Finally, it saves the most
5.50 +recently used seed file in a file called "last_seed_file." Rather than
5.51 +overwriting your old seed file, we have changed it in the ns-3
5.52 +interface. You still pass in a seed file, but you also pass in another file for
5.53 +BRITE to write the new seed file. This keeps BRITE from overwriting your seed
5.54 +file. We believe this makes it easier to run the exact same simulation over and
5.55 +over, which may be important to some users. Finally, if you wish to overwrite the seed file
5.56 +each run, randomizing each subsequent run as before, you can simply pass in the
5.57 +same file name for the seed file and new seed file in ns-3
5.58 +
5.59 +References
5.60 +==========
5.61 +
5.62 +.. [1] Alberto Medina, Anukool Lakhina, Ibrahim Matta, and John Byers. BRITE: An Approach to Universal Topology Generation. In Proceedings of the International Workshop on Modeling, Analysis and Simulation of Computer and Telecommunications Systems- MASCOTS '01, Cincinnati, Ohio, August 2001.
5.63 +
5.64 +Usage
5.65 +*****
5.66 +
5.67 +The brite-generic-example can be referenced to see basic usage of the BRITE
5.68 +interface. In summary, the BriteTopologyHelper is used as the interface point
5.69 +by passing in a BRITE configuration and seed file. The BRITE generated nodes
5.70 +and edges can then be accessed through this helper to create ns-3 nodes and
5.71 +edges.
5.72 +
5.73 +Within the brite-generic-example, assigning IPs and creating applications
5.74 +are done fairly simply, as topology generation is the main topic of the
5.75 +BRITE interface. It is very likely that the user will need to change the
5.76 +way in which IP addresses are assigned or applications are installed.
5.77 +
5.78 +Building BRITE Integration
5.79 +==========================
5.80 +
5.81 +The first step is to download and build the ns-3 specific BRITE repository:::
5.82 +
5.83 + $ hg clone http://code.nsnam.org/jpelkey3/BRITE
5.84 + $ cd BRITE
5.85 + $ make
5.86 +
5.87 +This will build BRITE and create a library, libbrite.so, within the BRITE
5.88 +directory.
5.89 +
5.90 +Once BRITE has been built successfully, we proceed to configure ns-3 with
5.91 +BRITE support. Change to your ns-3 directory:::
5.92 +
5.93 + $ ./waf configure --with-brite=/your/path/to/brite/source --enable-examples
5.94 +
5.95 +Make sure it says 'enabled' beside 'BRITE Integration'. If it does not, then
5.96 +something has gone wrong. Either you have forgotten to build BRITE first
5.97 +following the steps above, or ns-3 could not find your BRITE directory.
5.98 +
5.99 +Next, build ns-3:::
5.100 +
5.101 + $ ./waf
5.102 +
5.103 +Examples
5.104 +========
5.105 +For an example demonstrating BRITE integration
5.106 +run:::
5.107 +
5.108 + $ ./waf --run 'brite-generic-example --verbose=1'
5.109 +
5.110 +By enabling the verbose parameter, the example will print out the node and
5.111 +edge information in a similar format to standard BRITE output. There are
5.112 +many other command-line parameters including confFile, seedFile, newseedFile,
5.113 +tracing, and nix, described below:
5.114 +
5.115 + confFile: A BRITE configuration file. Many different BRITE configuration
5.116 + file examples exist in the src/brite/examples/conf_files directory, for
5.117 + example, RTBarabasi20.conf and RTWaxman.conf. Please refer to
5.118 + the conf_files directory for more examples.
5.119 +
5.120 + seedFile: BRITE specific seed file to seed a psuedo-random number genrator
5.121 + from BRITE.
5.122 +
5.123 + newseedFile: BRITE automatically generates a new seed file for you, if you
5.124 + would like to randomize subsequent runs. If you would like
5.125 + this to happen automatically, simply use the same file for
5.126 + seedFile and newseedFile. This way, BRITE will run with the
5.127 + current seeds and then overwrite them for the next run.
5.128 +
5.129 + verbose: Prints out the node and edge information in a similar format
5.130 + to standard BRITE output.
5.131 +
5.132 + tracing: Enables ascii tracing.
5.133 +
5.134 + nix: Enables nix-vector routing. Global routing is used by default.
5.135 +
5.136 +The generic BRITE example also support visualization using pyviz, assuming
5.137 +python bindings in ns-3 are enabled:::
5.138 +
5.139 + $ ./waf --run brite-generic-example --vis