[wiki:Documentation]
| [wiki:Documentation/NodeHandler NodeHandler]
| [wiki:Documentation/NodeHandler/Commands Commands]
| defTopology

= defTopology: Define a Topology =

This command defines a topology consisting of a set of nodes and optional noise injection settings to configure a specific topology. 

An experiment can normally only contain a single topology with noise settings, but may create additional topology declarations which are a sub set of existing topologies.

== Syntax: ==
=== defTopology( name , nodeArray = nil , &block = nil ) ===

  * '''name:''' Name of the defined topology.
  * '''nodeArray:''' Selects the nodes used in this topology (optional).
  * '''block:''' Additional modifications on the create topology (optional).

The 'name' argument is a uri string identifying the topology. For instance, it can be used in 'defNodes' commands. The following naming convention is encouraged: ''projectName'':'''topo''':''topologyName''

The optional 'nodeArray' argument defines which nodes are in the topology. The following array patterns are supported:

  * [x,y]: Describes a single node at location x@y
  * [x1..x2, y]: Describes a set of nodes along a line starting at x1@y and ending at x2@y. For instance, [2..4, 5] defines the nodes [2,5], [3,5], [4,5].
  * [x, y1..y2]: Same as previous, but for the y coordinate.
  * [x1..x2, y1..y2]: This defines a rectangle area of nodes within the grid.
  * [[x1,y1], [x2,y2], [x3,y3]]: An arbitrary long list of single nodes. Obvioulsy, any entry in this list can also use any of the above defined syntaxes.

The optional 'block' allows the experimenter to further configure the topology. The following commands are defined inside the block:

  * '''addNode(x,y)'''  Add node at location x@y to the topology.

  * '''removeNode(x,y)'''  Remove node at location x@y from the topology.

  * '''size()'''  Return the number of nodes in this topology.

  * '''getNode(index)'''  Return the node at the position ''index'' in this topology. Return ''nil'' if ''index'' is greater than the number of nodes in the topology.

  * '''getFirstNode()'''  Return the node at the 1st position in this topology.

  * '''getLastNode()''' Return the node at the last position in this topoly.
   
  * '''getRandomNode()''' Return a random node from this topology. Subsequent calls to this method may return the same node.

  * '''getUniqueRandomNode()''' Return a unique random node from this topology. Subsequent calls to this method will never return the same node, i.e. once a node is randomly selected it is "removed from the bag of nodes" of this topology. When all the available nodes in this topology have been drawn, this method will return ''nil'' and output a warning message to the console.

  * '''eachNode(&block)''' Execute the commands in ''block'' on each node within this topology.

  * '''setStrict()''' Set the ''strict'' flag for this topology. When the ''strict'' flag is set, adding or removing a node from this topology is not permitted, and will result in an error message on the console and the termination of the experiment. Typically a user sets this flag when s/he wants an experiment to proceed only if all the required nodes are present in this topology. By default, the ''strict'' flag is NOT set for a topology.
  
  * '''unsetStrict()''' Unset the "strict" flag. By default, the ''strict'' flag is NOT set for a topology.

  * '''hasNode(x, y)''' Return ''true'' if the node at location x@y is part of this topology, return ''false'' otherwise.



== Noise Injection: == 

--- Instructions on how to incorporate noise are missing ---

== Usage ==

{{{
# Define a topology that contains 4 specific nodes
#
defTopology('test:topo:origin', [[1, 1],[2,5],[10,4],[15,1]]) 

# Define a topology where nodes on the testbed are arranged 
# in a circle
#
defTopology('test:topo:circle') { |t|
  # use simple 4-way algorithm
  radius = 8
  xCenter = 10
  yCenter = 10

  r2 = radius * radius
  t.addNode(xCenter, yCenter + radius)
  t.addNode(xCenter, yCenter - radius)
  (1..radius).each { |x|
    y = (Math.sqrt(r2 - x*x) + 0.5).to_i
    t.addNode(xCenter + x, yCenter + y)
    t.addNode(xCenter + x, yCenter - y)
    t.addNode(xCenter - x, yCenter + y)
    t.addNode(xCenter - x, yCenter - y)
  }
}


# Define a topology that will have 8 nodes randomly selected from 
# a previously defined topology (''topo_grid_active'' which includes all the 
# currently active node on the grid testbed)
#
defTopology('myTopo8Nodes') { |t|
  
  # Load the 'topo_grid_active' 
  baseTopo = Topology['topo_grid_active']
  # Print the size of the base topology
  puts "Size of the Base Topology: #{baseTopo.size}"
  
  # Repeat the following 8 times
  for count in 1..8
    # Draw a random node from the base topology
    aNode = baseTopo.getUniqueRandomNode
    # Add this random node to this 'myTopo8Nodes' topology
    t.addNode(aNode.x, aNode.y)
  end
  
  # Print the nodes that belongs to this topology
  puts "Size of the 'myTopo8Nodes' Topology: #{t.size}"
  t.eachNode { |n|
    puts " - Node: #{n}"
  }
}
}}}

== See Also ==

A tutotial with an example on how to use user-defined topologies within an experiment script can be found here:

  * [wiki:Tutorial/HowToTopology How use Topologies in an experiment script]