PILOTS: Running Tutorial

Tutorial index (Basic Examples Programming Running Learning Model Overview Linear Regression Example)

Introduction

This part of the tutorial deals with running a generic PILOTS application. This can be particularly confusing because PILOTS is not very flexible, and depends on a very specific data format. If the PILOTS application is being run in simulated mode, and all data is originated from a file, then execution is relatively straightforward. Real-time PILOTS applications can be difficult to set up, unless an appropriate external software component is already in place. In this tutorial we will first introduce the PILOTS data format. Then the differences between real-time mode and simulated mode will be discussed. Finally, the external software components provided in the PILOTS distribution will be described.

Input data file format

PILOTS applications handle spatio-temporal input/output data of a specific format. All input/output in a PILOTS application looks like:

#var0, var1, ... varn \r\n
< space > : < time > :val0,...,valn \r\n
...
< space > : < time > :val0,...,valn \r\n

var0,...,varn identifies the name of the data being received from in the inputs clause of a PILOTS program.
val0,...,valn are the associated values of the variables for the given spatio-temporal coordinates.
<space> may have up to three dimensions (latitude, longitude, height) separated by commas, and <time> is specified in Java date/time format (using 24-hour time).
Additionally, each specification of <space> or <time> may be a single point or a range between two points separated by '~'. Examples of the spatio-temporal data format can be found in $PILOTS_HOME/data/*

Real-Time mode vs. Simulated mode

At compilation PILOTS programs must be designated as real-time programs or simulated programs. The reason for this is that the PILOTS compiler generates different code for each situation. In a real-time program, time is associated with the processor's internal clock. This mode is appropriate for real-time systems where new input data is continuously arriving and future data is unknown. Simulated programs assume that all data for an experiment is available ahead of time, so processing can occur as fast as possible without busy waiting. We have found that both real-time and simulated mode are necessary and useful. Real-time mode is the obvious choice for most applications of stream processing. Simulated mode has the advantage of being able to quickly evaluate potential data error scenarios, which helps in devising error correcting code.

External software components

PILOTS applications assume all input and output are communicated over TCP/IP sockets. Thus PILOTS applications require you to run external programs that act as data input producers or output handlers. The PILOTS distribution provides simple input/output handler programs which can be found in $PILOTS_HOME/pilots/util.

ChartServer.java is an output handler (data sink) that, given a port number, listens to a socket on that port and graphs the data over time (using jfreechart).
Parameters: <port_number>

FileInputProducer.java is an input handler (data source) that simply relays the contents of a file which contains spatio-temporal data over a designated socket on port 8888 of the local machine.
arameters: <filename>

LinearInputProducer.java is an input handler (data source) that generates temporal data incrementing linearly over time (with optional timing jitter). The data is relayed over a designated socket on port 8888 of the local machine.
Parameters (all required, in order): <num_iterations> <variable_name> <initial_value> <increment_value> <random_timing_jitter>

Compiling and running a program

Compile your PILOTS program (YourProgram.plt) into Java source code by the following:

$ java pilots.compiler.PilotsCompiler YourProgram.plt
OR
$ plc YourProgram (`plc` is an alias for the above java command)
OR
$ plcsim YourProgram (if your program produces a simulation rather than using real-time streaming of data)

The command line options for the PILOTS compiler are:

Dstdout : sends generated code to standard output instead
Dsim : compilation switch for simulation mode
Dpackage : changes the generated code's target package

Compile the generated Java code. The result is the PILOTS application and can be run using Java.

$ javac YourProgram.java

The resulting java class, YourProgram.class, is the executable pilots application. Note that you can not simply run \"$ java YourProgram\" because PILOTS applications use TCP/IP sockets for input and output. In order for the input and output to be received correctly, external software components must be configured to handle the data in the PILOTS spatio-temporal format. The external software components (found in $PILOTS_HOME/pilots/util) are elementary examples of input producers and output handlers.

To run an application, all data sinks must be initialized before sources. Thus the order of process execution must be:

output handlers
PILOTS application
data input producers

The IP addresses that will be used for socket communication between the PILOTS application and the external programs must be specified. The PILOTS application takes -input and -outputs arguments along with error detection parameters -tau and -omega as follows:

$ java <your PILOTS application> -input=<port> -outputs=<ipaddr:port>+ -tau=<t> -omega=<w>

(Where + means one or more)

Simulation mode, as opposed to real-time mode, relies on a different algorithm that uses simulated time. When running a PILOTS application in simulation mode, the -Dtimespan=tb~te (where tb and te are both java date/time format strings) argument must be specified.

Predictive Function

The machine learning component i.e. predictive function, could be installed and used following the instruction provided here

Tutorial index (Basic Examples Programming Running Learning Model Overview Linear Regression Example Bayes Classifier Example)

PILOTS home WCL home

Worldwide Computing Laboratory

Department of Computer Science

Rensselaer Polytechnic Institute