avrora.sim
Class Simulation

java.lang.Object
  avrora.util.help.HelpCategory
      avrora.sim.Simulation

All Implemented Interfaces:

HelpItem

Direct Known Subclasses:

SensorSimulation, SingleSimulation

public abstract class Simulation

extends HelpCategory

The Simulation class represents a complete simulation, including the nodes, the programs, the radio model (if any), the environment model, for simulations of one or many nodes. This is meant as a major extension point in Avrora for adding new types of simulations; for example a sensor network simulation, a robotics simulation, etc.

Nested Class Summary

static interface	Simulation.Monitor The Monitor interface represents a monitor for a simulation.
class	Simulation.Node The Node class represents a node in a simulation, which has an ID and a program to be loaded onto it.

Field Summary

Option.Long	CLOCKSPEED
Option.Long	EXTCLOCKSPEED
Option.Str	MCU
protected java.util.LinkedList	monitorFactoryList
Option.List	MONITORS
protected Simulation.Node[]	nodes
protected int	num_nodes
protected Options	options
protected boolean	paused
Option.Str	PLATFORM
protected java.util.Random	random
Option.Long	RANDOMSEED
protected boolean	running
Option.Str	SCHEDULE
Option.Double	SECONDS
protected Synchronizer	synchronizer

Fields inherited from class avrora.util.help.HelpCategory

COMPARATOR, help, name

Constructor Summary

protected

Simulation(java.lang.String str, java.lang.String h, Synchronizer s) The construcotr for the Simulation class creates a new simulation.

Method Summary

Simulation.Node	createNode(PlatformFactory pf, LoadableProgram pp) The createNode() method creates a new node in the simulation with the specified platform, with the specified program loaded onto it.
Simulation.Node	getNode(int node_id) The getNode() method gets a reference to the node with the specified id number.
java.util.Iterator	getNodeIterator() The getNodeIterator() method returns an iterator over all of the nodes of the simulation.
int	getNumberOfNodes() The getNumberOfNodes() method returns the number of nodes in this simulation.
protected PlatformFactory	getPlatform() The getPlatform() method is a helper method for extensions of the Simulation class.
java.util.Random	getRandom() The getRandom() method returns a reference to a random number generator that is used in the simulation.
protected void	instantiateNodes()
boolean	isPaused() The isPaused() method checks whether the simulation is currently paused.
boolean	isRunning() The isRunning() method checks whether the simulation is currently running.
void	join() The join() method waits for the simulation to terminate before returning.
protected Simulation.Node	newNode(int id, PlatformFactory pf, LoadableProgram pp) The newNode() method is intended to be overridden by subclasses of Simulation.
void	pause() The pause() method pauses the simulation.
abstract void	process(Options o, java.lang.String[] args) The process() method is called when the simulation is created from the command line.
protected void	processMonitorList() The processMonitorList() method builds a list of MonitorFactory instances from the list of strings given as an option at the command line.
void	removeNode(int node_id) The removeNode() method removes a node from this simulation.
void	resume() The resume() method resumes the simulation after it has been paused.
void	start() The start() method starts the simulation execution.
void	stop() The stop() method stops the simulation.
void	stopNode(int id) The stopNode() method can be used to stop (and remove) a single node from the simulation while the simulation is running.

Methods inherited from class avrora.util.help.HelpCategory

addCommandExample, addListSection, addOptionSection, addSection, addSubcategorySection, getHelp, getName, printHelp, setName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

options

protected final Options options

PLATFORM

public final Option.Str PLATFORM

CLOCKSPEED

public final Option.Long CLOCKSPEED

EXTCLOCKSPEED

public final Option.Long EXTCLOCKSPEED

MCU

public final Option.Str MCU

RANDOMSEED

public final Option.Long RANDOMSEED

SECONDS

public final Option.Double SECONDS

MONITORS

public final Option.List MONITORS

SCHEDULE

public final Option.Str SCHEDULE

num_nodes

protected int num_nodes

nodes

protected Simulation.Node[] nodes

running

protected boolean running

paused

protected boolean paused

random

protected java.util.Random random

monitorFactoryList

protected java.util.LinkedList monitorFactoryList

synchronizer

protected Synchronizer synchronizer

Constructor Detail

Simulation

protected Simulation(java.lang.String str,
                     java.lang.String h,
                     Synchronizer s)

The construcotr for the Simulation class creates a new simulation. This is intended to be called only by subclasses of Simulation, and expects a short string representing the name of the simulation type, a String representing the help item, as well as a node factory (if null, the StandardNodeFactory will be used), and a Synchronizer instance used to synchronize the starting and stopping of multiple nodes.

Parameters:

str - the name of the simulation as a short string

h - the help item for this simulation

s - the synchronizer instance used to start and stop all of the nodes

Method Detail

process

public abstract void process(Options o,
                             java.lang.String[] args)
                      throws java.lang.Exception

The process() method is called when the simulation is created from the command line. This gives the simulation instance a chance to read in options from the command line, instantiate nodes, and configure the simulation from the user's input.

Parameters:

o - the options processed so far from the command line

args - the command line arguments from the user

Throws:

java.lang.Exception - if any type of exception occurs during this processing (e.g. FileNotFound)

createNode

public Simulation.Node createNode(PlatformFactory pf,
                                  LoadableProgram pp)

The createNode() method creates a new node in the simulation with the specified platform, with the specified program loaded onto it.

Parameters:

pf - the platform factory used to create the platform for the node

pp - the program for the node

Returns:

a new instance of the Node class representing the node

newNode

protected Simulation.Node newNode(int id,
                                  PlatformFactory pf,
                                  LoadableProgram pp)

The newNode() method is intended to be overridden by subclasses of Simulation. Since some simulations may have special types of nodes with more information attached (e.g. a sensor simulation where radios are attached to nodes), overriding this method allows new types of nodes to be instantiated.

Parameters:

id - the id number of the new node

pf - the platform factory for the new node

pp - the the loadable program for the new node

Returns:

a reference to a new node instance for this new node

getNumberOfNodes

public int getNumberOfNodes()

The getNumberOfNodes() method returns the number of nodes in this simulation.

Returns:

the number of nodes in this simulation

getRandom

public java.util.Random getRandom()

The getRandom() method returns a reference to a random number generator that is used in the simulation. The random number generator may be used to randomly perturb node start times, drop packets, etc. This random number generator has a user-selectable random seed for reproducibility.

Returns:

a reference to the random number generator for this simulation

getNode

public Simulation.Node getNode(int node_id)

The getNode() method gets a reference to the node with the specified id number.

Parameters:

node_id - the node's id number as an integer

Returns:

a reference to the node if it exists; null otherwise

removeNode

public void removeNode(int node_id)

The removeNode() method removes a node from this simulation. This operation can only be performed when the simulation is not running.

Parameters:

node_id - the node's id number specifying which node to remove

start

public void start()

The start() method starts the simulation execution. This method will return immediately and the simulation will continue to run in the background in one or more other threads. The simulation can be paused and stopped with the corresponding methods.

instantiateNodes

protected void instantiateNodes()

pause

public void pause()

The pause() method pauses the simulation. This method is synchronous in the sense that it will not return until all nodes in the simulation are guaranteed to be paused (i.e. no longer making progress).

resume

public void resume()

The resume() method resumes the simulation after it has been paused.

stop

public void stop()

The stop() method stops the simulation. This method will terminate the simulation, causing each node and its monitor's states to be deconstructed. After calling stop(), subsequent calls to start() will result in the creation of a new simulation run.

join

public void join()
          throws java.lang.InterruptedException

The join() method waits for the simulation to terminate before returning. After this method returns, the nodes are all guaranteed to be have terminated.

Throws:

java.lang.InterruptedException

stopNode

public void stopNode(int id)

The stopNode() method can be used to stop (and remove) a single node from the simulation while the simulation is running. This may be useful for simulating node failure or reconfiguring the simulation while it is running. This method has no effect when the simulation is not running.

Parameters:

id - the node_id of the node to stop

isPaused

public boolean isPaused()

The isPaused() method checks whether the simulation is currently paused.

Returns:

true if the simulation is currently paused; false otherwise

isRunning

public boolean isRunning()

The isRunning() method checks whether the simulation is currently running.

Returns:

true if the simulation is currently running; false otherwise.

getNodeIterator

public java.util.Iterator getNodeIterator()

The getNodeIterator() method returns an iterator over all of the nodes of the simulation.

Returns:

an iterator that can traverse all of the nodes of the simulation

getPlatform

protected PlatformFactory getPlatform()

The getPlatform() method is a helper method for extensions of the Simulation class. This method will consult the value of the \"platform\" command line option and construct an appropriate PlatformFactory instance that can be used for a node.

Returns:

an instance of the PlatformFactory interface

processMonitorList

protected void processMonitorList()

The processMonitorList() method builds a list of MonitorFactory instances from the list of strings given as an option at the command line. The list of MonitorFactory instances is used to create monitors for each simulator as it is created.