A Guide to the simdiag package



This document is a guide to displaying simulation results using the simdiag package for simjava.

For further information on writing simulations see the simjava guide. For further information on writing animations see the simanim guide. The design document includes more detail on the implementation of simdiag.

The simdiag package is used in conjunction with simanim. It includes a flexible collection of "Java Beans" for displaying simulation results. Currently the following beans are included:

Any number of these beans may be connected to the simulation output stream, and user defined output processing beans may also be added.

Two example simulations show timing diagrams and graphs in action.

The TimingDiagram bean

The timing diagram displays how the states of entities change over time, providing a Gantt chart display. The left mouse button can be used to move a couple of vertical rules, and the right mouse button zooms into the space between. Unzoom resets the display to all events.

If your browser supports JDK1.1, an active diagram should appear below.

To display an entity's state on a timing diagram, call add_param in the entity's constructor (see the Worker source code for a complete example).

    // in user's entity constructor...
    String[] wstate = {"idle","busy"};
    add_param(new Anim_param( "State", 
                             new Param_type("wstate", wstate)

This example adds a state type wstate with values idle and busy.

The timing window itself should be created in the user's anim_init() method which sets up the simulation. See also the applet source code

For example, the following attaches a timing diagram display to the output:-

    TimingWindow tw = new TimingWindow();
    trace_out.addTraceListener( tw.getDiag() );

And the following attaches a trace saver:-

    trace_out.addTraceListener( new TraceSaver("tracefile") );

The simjava output processing model is based on a JavaBeans event interface. This means that a simulation's trace output may be processed by any number of "output beans", including a timing diagram, a file saver, a graph generator etc.

simjava generates a stream of TraceEventObjects, each containing the trace line and a command:-

public class TraceEventObject extends EventObject {
  String traceline;
  int cmd;
The commands are defined as follows:-
  static final int TRACE  = 0;
  static final int LAYOUT = 1;
  static final int RUN    = 2;
  static final int PAUSE  = 3;
  static final int STOP   = 4;
  static final int DISPLAY= 5;

They mean:-

The GraphDiagram bean

The Graph performs autoscaling of any number of 2D data lines. Each line has a name. More details are included in the design document.

A GraphWindow will normally be created in the anim_init() method, and be driven by some output from the simulation.

How the graph is used is very much up to the user. The source code for the sine wave generator used to produce the above image should illustrate how to generate graphs; similar code in a user's simulation can be used to make user defined graphs. The example simulation may be useful as a basis.

Growing more beans

User beans can be created by implementing the TraceListener interface and adding them as above. The one below simply prints out all events to the console.
public class UserBean implements Traceable, TraceListener {
  public void handleTrace(TraceEventObject e) {
    System.out.println("Event type "+e.getCmd() +
                       " contents:"+ e.getLine());

Known bugs

Fred Howell - fwh@dcs.ed.ac.uk
Department of Computer Science
University of Edinburgh