sim.engine
Class SimState

java.lang.Object
  extended bysim.engine.SimState
All Implemented Interfaces:
java.io.Serializable

public class SimState
extends java.lang.Object
implements java.io.Serializable

SimState represents the simulation proper. Your simulations generally will contain one top-level object which subclasses from SimState.

A SimState contains the random number generator and the simulator's schedule. You should not change the schedule to another Schedule object.

When a simulation is begun, SimState's start() method is called. Then the schedule is stepped some N times. Last, the SimState's finish() method is called, and the simulation is over.

SimStates are serializable; if you wish to be able to checkpoint your simulation and read from checkpoints, you should endeavor to make all objects in the simulation serializable as well. Prior to serializing to a checkpoint, preCheckpoint() is called. Then after serialization, postCheckpoint() is called. When a SimState is loaded from a checkpoint, awakeFromCheckpoint() is called to give you a chance to make any adjustments. SimState also implements several methods which call these methods and then serialize the SimState to files and to streams.

A number of the methods below have default empty implementations; but you should remember to always call super.foo() for any such method foo(), as later versions of this library may add features in the SimState's top-level methods.

See Also:
Serialized Form

Field Summary
 MersenneTwisterFast random
          The SimState's random number generator
 Schedule schedule
          SimState's schedule
 
Constructor Summary
SimState(MersenneTwisterFast random, Schedule schedule)
           
 
Method Summary
 void awakeFromCheckpoint()
          Called after the SimState was created by reading from a checkpointed object.
 void finish()
          Called either at the proper or a premature end to the simulation.
 void postCheckpoint()
          Called just after the SimState was checkpointed (serialized out to a file to be unserialized and fired up at a future time).
 void preCheckpoint()
          Called just before the SimState is being checkpointed (serialized out to a file to be unserialized and fired up at a future time).
static SimState readFromCheckpoint(java.io.File file)
          Creates a SimState from checkpoint.
static SimState readFromCheckpoint(java.io.InputStream stream)
          Creates and returns a new SimState object read in from the provided stream.
 void setRandom(MersenneTwisterFast random)
           
 void start()
          Called immediately prior to starting the simulation, or in-between simulation runs.
 SimState writeToCheckpoint(java.io.File file)
          Writes the state to a checkpoint and returns the state.
 void writeToCheckpoint(java.io.OutputStream stream)
          Serializes out the SimState, and the entire simulation state (not including the graphical interfaces) to the provided stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

random

public MersenneTwisterFast random
The SimState's random number generator


schedule

public Schedule schedule
SimState's schedule

Constructor Detail

SimState

public SimState(MersenneTwisterFast random,
                Schedule schedule)
Method Detail

setRandom

public void setRandom(MersenneTwisterFast random)

start

public void start()
Called immediately prior to starting the simulation, or in-between simulation runs. This gives you a chance to set up initially, or reset from the last simulation run. The default version simply replaces the Schedule with a completely new one.


finish

public void finish()
Called either at the proper or a premature end to the simulation. If the user quits the program, this function may not be called.


preCheckpoint

public void preCheckpoint()
Called just before the SimState is being checkpointed (serialized out to a file to be unserialized and fired up at a future time). You should override this to prepare your SimState object appropriately.


postCheckpoint

public void postCheckpoint()
Called just after the SimState was checkpointed (serialized out to a file to be unserialized and fired up at a future time). You cam override this as you see fit.


awakeFromCheckpoint

public void awakeFromCheckpoint()
Called after the SimState was created by reading from a checkpointed object. You should set up your SimState in any way necessary (reestablishing file connections, etc.) to fix anything that may no longer exist.


writeToCheckpoint

public void writeToCheckpoint(java.io.OutputStream stream)
                       throws java.io.IOException
Serializes out the SimState, and the entire simulation state (not including the graphical interfaces) to the provided stream. Calls preCheckpoint() before and postCheckpoint() afterwards. Throws an IOException if the stream becomes invalid (prematurely closes, etc.). Does not close or flush the stream.

Throws:
java.io.IOException

writeToCheckpoint

public SimState writeToCheckpoint(java.io.File file)
Writes the state to a checkpoint and returns the state. If an exception is raised, it is printed and null is returned.


readFromCheckpoint

public static SimState readFromCheckpoint(java.io.File file)
Creates a SimState from checkpoint. If an exception is raised, it is printed and null is returned.


readFromCheckpoint

public static SimState readFromCheckpoint(java.io.InputStream stream)
                                   throws java.io.IOException,
                                          java.lang.ClassNotFoundException,
                                          java.io.OptionalDataException,
                                          java.lang.ClassCastException
Creates and returns a new SimState object read in from the provided stream. Calls awakeFromCheckpoint(). Throws an IOException if the stream becomes invalid (prematurely closes etc.). Throws a ClassNotFoundException if a serialized object is not found in the CLASSPATH and thus cannot be created. Throws an OptionalDataException if the stream is corrupted. Throws a ClassCastException if the top-level object is not actually a SimState. Does not close or flush the stream.

Throws:
java.io.IOException
java.lang.ClassNotFoundException
java.io.OptionalDataException
java.lang.ClassCastException