org.mates.sim
Class Simulator

java.lang.Object
  org.mates.sim.Simulator

public class Simulator

extends java.lang.Object

Simulator class. This is the kernel of MATES.

Author:

Evan Sultanik

Nested Class Summary

class

Simulator.MigrationInfo Internal class for agent migration bookkeeping.

Constructor Summary

Simulator()
Builds a simulator with a DefaultTransportModel and FullyConnectedLinkModel

Simulator(LinkModel link_model)
Builds a simulator with a DefaultTransportModel

Simulator(LinkModel link_model, TransportModel transport_model)
Primary constructor.

Simulator(TransportModel transport_model)
Builds a simulator with a FullyConnectedLinkModel

Method Summary

void	addEventListener(EventListener listener, java.lang.Class event_class) Adds an event listener to the simulator.
void	addEventListener(EventListener listener, Event event_type) Adds an event listener to the simulator.
void	addEventListener(EventListener listener, java.lang.String event_class) Adds an event listener to the simulator.
void	addExperiment(Experiment experiment) Adds a new experiment that is controlling this simulator.
void	addHost(Host host) Adds a host to the simulator
void	agentCreated(Agent agent) Sends an AgentCreatedEvent to all event listeners.
void	clearEventListeners() Removes all event listeners.
java.util.Hashtable	getAgentsInTransit() Returns a the agents currently in transit.
long	getCurrentIteration() Returns the current iteration of the simulator.
double	getDefaultRadioRange() Returns the default radio range of a host.
Bounds	getDomainBounds() Returns the bounds object for the domain.
double	getDomainHeight() Returns the height of the domain.
double	getDomainWidth() Returns the width of the domain.
Experiment	getExperiment() Returns the first experiment controlling this simulator.
Experiment[]	getExperiments() Returns an array containing all of the experiments controlling this simulator.
java.util.Vector	getHosts() Returns the hosts in the simulator.
LinkModel	getLinkModel() Accessor for the simulation's link model.
double	getLinkQuality(Host host1, Host host2) Returns the link quality between two hosts, according to the link model.
java.io.OutputStream	getLogStream() Returns the output stream for the log.
java.util.Vector	getNeighbors(Host host) Returns the neighbors of a host.
static int	getNumThreads() Returns the current number of threads each simulator is to run concurrently.
java.util.Random	getRandom() Accessor for the random number generator of the simulator.
Topology	getTopology() Returns the current network topology.
void	hostClicked(Host host, java.awt.event.MouseEvent mouse_event) Raises a new HostClickedEvent.
boolean	isValidPosition(Position position) Returns true if position is within the bounds of the domain.
void	iterate() Iterates the entire simulation.
void	killAgent(Agent agent) Kills an agent.
void	log(java.lang.Object source, java.lang.String message) Records a log message.
boolean	migrate(Agent agent, Host destination) Initiates an agent migration.
UniqueID	newUniqueID() Creates a new unique identifier for an object.
long	numAgentsInTransit() Returns the number of agents currently in transit.
protected void	raiseEvent(Event event) Forwards an event to all event listeners
boolean	removeExperiment(Experiment experiment) Removes an experiment that is controlling this simulator.
void	removeHost(Host host) Removes a host from the simulator.
void	reset() Removes all of the hosts, agents, and event listeners, resets the iteration counter to 0, and resets all of the statistics (e.g. average host degree).
void	setDefaultRadioRange(double radio_range) Sets the default radio range of a host.
void	setDomainBounds(Bounds bounds) Sets the object that defines the bounds of the domain.
void	setDomainHeight(double height) Sets the height of the domain bounds.
void	setDomainWidth(double width) Sets the width of the domain bounds.
void	setLinkModel(LinkModel link_model) Sets this simulator's link model.
void	setLogStream(java.io.OutputStream stream) Sets the output location for all log messages.
static void	setNumThreads(int new_num_threads) Sets the number of threads that each simulator should run concurrently.
void	updateTopology() Updates the topology based upon the current host positions and the link model.

Methods inherited from class java.lang.Object

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

Constructor Detail

Simulator

public Simulator(LinkModel link_model,
                 TransportModel transport_model)

Primary constructor.

Parameters:

link_model - the link model to use

transport_model - the transport model to use

Simulator

public Simulator(LinkModel link_model)

Builds a simulator with a DefaultTransportModel

Parameters:

link_model - the link model to use

Simulator

public Simulator(TransportModel transport_model)

Builds a simulator with a FullyConnectedLinkModel

Parameters:

transport_model - the transport model to use.

Simulator

public Simulator()

Builds a simulator with a DefaultTransportModel and FullyConnectedLinkModel

Method Detail

addHost

public void addHost(Host host)

Adds a host to the simulator

Parameters:

host - the host to add

removeHost

public void removeHost(Host host)

Removes a host from the simulator. All agents on that host are also removed.

Parameters:

host - the host to be removed.

addExperiment

public void addExperiment(Experiment experiment)

Adds a new experiment that is controlling this simulator. Generally, there should only ever be one experiment controlling a single simulator; the ability to add multiple experiments is allowed for unpredicted future modifications to MATES. This function is not used internally by MATES; it is strictly for the user's convenience. When a new Experiment is created, its constructor automatically adds itself to its simulator by calling this function.

See Also:

getExperiments(), getExperiment(), removeExperiment(org.mates.sim.Experiment)

getExperiments

public Experiment[] getExperiments()

Returns an array containing all of the experiments controlling this simulator.

See Also:

addExperiment(org.mates.sim.Experiment)

getExperiment

public Experiment getExperiment()

Returns the first experiment controlling this simulator. By "first," we mean the first experiment that was added that has not yet been removed. This function is equivalent to calling getExperiments()[0], however a check is performed to make sure getExperiments() does not return an empty list. If there are no experiments associated with this simulator, null is returned.

See Also:

getExperiments()

removeExperiment

public boolean removeExperiment(Experiment experiment)

Removes an experiment that is controlling this simulator.

Returns:

true if the experiment was controlling this simulator (and was therefore successfully removed)

See Also:

addExperiment(org.mates.sim.Experiment)

setNumThreads

public static void setNumThreads(int new_num_threads)

Sets the number of threads that each simulator should run concurrently. This value defaults to 1. It is recommended that non-SMP systems use only 1 thread.

getNumThreads

public static int getNumThreads()

Returns the current number of threads each simulator is to run concurrently. This value defaults to 1. It is recommended that non-SMP systems use only 1 thread.

numAgentsInTransit

public long numAgentsInTransit()

Returns the number of agents currently in transit.

Returns:

the number of agents currently in transit.

getAgentsInTransit

public java.util.Hashtable getAgentsInTransit()

Returns a the agents currently in transit. The keys of this hashtable are the actual Agent objects, while the values are the Simulator.MigrationInfo bookkeeping objects associated with each agent.

Returns:

the agents currently in transit.

getHosts

public java.util.Vector getHosts()

Returns the hosts in the simulator.

Returns:

the hosts in the simulator.

reset

public void reset()

Removes all of the hosts, agents, and event listeners, resets the iteration counter to 0, and resets all of the statistics (e.g. average host degree). However, this function does not reset the seed of the random number generator.

getRandom

public java.util.Random getRandom()

Accessor for the random number generator of the simulator. All random number generation should be done through the object returned from this function. By always using this single random number generator, its seed can be manually set to reproduce individual simulations.

Returns:

the random number generator for this simulation.

getLinkQuality

public double getLinkQuality(Host host1,
                             Host host2)

Returns the link quality between two hosts, according to the link model.

Returns:

the link quality between host1 and host2

setLinkModel

public void setLinkModel(LinkModel link_model)

Sets this simulator's link model.

getLinkModel

public LinkModel getLinkModel()

Accessor for the simulation's link model.

getTopology

public Topology getTopology()

Returns the current network topology.

getNeighbors

public java.util.Vector getNeighbors(Host host)

Returns the neighbors of a host.

newUniqueID

public UniqueID newUniqueID()

Creates a new unique identifier for an object.

Returns:

a new unique identifier.

updateTopology

public void updateTopology()

Updates the topology based upon the current host positions and the link model.

setDomainBounds

public void setDomainBounds(Bounds bounds)

Sets the object that defines the bounds of the domain. To have an unbounded domain, pass in a new Bounds object.

getDomainBounds

public Bounds getDomainBounds()

Returns the bounds object for the domain.

getDomainWidth

public double getDomainWidth()

Returns the width of the domain.

Throws:

java.lang.IllegalStateException - if getDomainBounds() is not instanceof BoundingBox.

setDomainWidth

public void setDomainWidth(double width)

Sets the width of the domain bounds. If the current bounds are not already instanceof BoundingBox, they will be made one, with dimensions of a square.

setDomainHeight

public void setDomainHeight(double height)

Sets the height of the domain bounds. If the current bounds are not already instanceof BoundingBox, they will be made one, with dimensions of a square.

getDomainHeight

public double getDomainHeight()

Returns the height of the domain.

Throws:

java.lang.IllegalStateException - if getDomainBounds() is not instanceof BoundingBox.

isValidPosition

public boolean isValidPosition(Position position)

Returns true if position is within the bounds of the domain. This is equivalent to calling getDomainBounds().contains(position).

See Also:

getDomainBounds(), Bounds.contains(org.mates.util.Position)

iterate

public void iterate()

Iterates the entire simulation. This function will first move all of the hosts based upon their associated mobility models. Note that for efficiency's sake updateTopology() will only be called once, after all of the hosts have been moved. Next, currently-migrating agents are processed, and those that are done migrating arrive at their destination hosts. Agents that have timed out are sent back to their originating host. Finally, hosts are iterated, which in turn schedule iterations for their agents.

getCurrentIteration

public long getCurrentIteration()

Returns the current iteration of the simulator.

clearEventListeners

public void clearEventListeners()

Removes all event listeners.

setDefaultRadioRange

public void setDefaultRadioRange(double radio_range)

Sets the default radio range of a host.

getDefaultRadioRange

public double getDefaultRadioRange()

Returns the default radio range of a host.

addEventListener

public void addEventListener(EventListener listener,
                             Event event_type)

Adds an event listener to the simulator.

addEventListener

public void addEventListener(EventListener listener,
                             java.lang.Class event_class)

Adds an event listener to the simulator.

addEventListener

public void addEventListener(EventListener listener,
                             java.lang.String event_class)

Adds an event listener to the simulator.

killAgent

public void killAgent(Agent agent)

Kills an agent. The agent will be removed from the simulator.

Parameters:

agent - the agent to be killed.

agentCreated

public void agentCreated(Agent agent)

Sends an AgentCreatedEvent to all event listeners.

Parameters:

agent - the agent that was created

migrate

public boolean migrate(Agent agent,
                       Host destination)

Initiates an agent migration. It is important to note that this function does not ensure that the agent's current host and new_host are in communication range. This function returns true if the migration is valid. In other words, new_host is a valid destination and this agent is not already in the process of migrating. This return value ensures that the migration process has started; it has nothing to do with the success or completion of the migration.

Parameters:

agent - the agent to be migrated

destination - the host to which the agent is migrating

Returns:

the validity of the migration

raiseEvent

protected void raiseEvent(Event event)

Forwards an event to all event listeners

setLogStream

public void setLogStream(java.io.OutputStream stream)

Sets the output location for all log messages. This defaults to System.out. If null, logging is suppressed in the simulator and is left up to the experiment to implement by registering to receive LogEvent messages.

getLogStream

public java.io.OutputStream getLogStream()

Returns the output stream for the log. Note that this may return null.

hostClicked

public void hostClicked(Host host,
                        java.awt.event.MouseEvent mouse_event)

Raises a new HostClickedEvent.

Throws:

java.lang.NullPointerException - if host is null

log

public void log(java.lang.Object source,
                java.lang.String message)

Records a log message.