Chapter 3. Getting started

After Tablix has been installed on your workstation follow these steps to test your installation. These are the basic steps required to obtain a solution to a timetabling problem. You will repeat them every time you will use Tablix (unless you will be using some front-end other than the default command line interface, in which case the front-end will do these steps for you).

If you are running Tablix on a cluster, choose one machine to be the master node. You will control Tablix from that machine. Do the following steps only on that computer.

1. First you have to describe your timetabling problem in the format that Tablix understands. Tablix uses an unified XML format to describe problem definitions and solutions to these problems.

   You can find some example configuration files in the examples/ subdirectory. These steps presume that you are using the examples/sample2.xml configuration. See sections later in this document for instructions on how to write your own problem definitions.

   $ cd examples
   

2. If you are running Tablix on a single machine and you have installed Tablix system-wide (e.g. you didn't supply any --prefix options to the ./configure script) you probably do not need a PVM hostfile and you can skip this step. If you have problems starting Tablix later on one of the reasons can be that you need a hostfile with a correct ep parameter.

   If you are running Tablix on a cluster a hostfile is usually unavoidable. See PVM3 documentation for details. Following is an example hostfile for a cluster composed of three different machines.

   orion   ep=/home/avian/tablix/src \
           sp=7000
   dolphin ep=/home/avian/tablix/src \
           sp=1600
   europa  ep=/home/avian/tablix-0.0.1/src \
           sp=800 \
           dx=/home/avian/src/pvm3/lib/pvmd
   

   Note: The sp field is important. Try to match relative speeds of your machines as accurately as possible. This will help Tablix balance the load more evenly and will increase performance.

3. Start pvm. If you don't need a hostfile, you can omit it on the command line.

   $ pvm hostfile
   

   Note: Tablix does not automatically detect if new nodes have been added to the cluster while it is running. All nodes must be properly configured before Tablix starts.

4. Start Tablix. See tablix2 -h or the man page for a list of the available command line arguments.

   $ tablix2 -n 10 -o test1_ sample2.xml
   

   The -n specifies the number of computational nodes Tablix will start on the cluster. For a single machine the default number (4) will usually be sufficient for simple problems. On a cluster of machines a good guess is N*4, where N is the number of machines.

   The -o option instructs Tablix to prefix all output files with test1_.

5. Now you have to wait for Tablix to find a solution. Time depends on your configuration file, number of nodes, speed and architecture of nodes, etc. See below for the explanation of numbers that show up the screen. On a reasonably fast machine (e.g. single Athlon XP 2500+) the example problem sample2.xml will take around 30 minutes to solve.

   You can track the progress of a running Tablix process by running tablix2_plot utility. It can draw a number of different graphs that show how successful is the algorithm at finding the solution to the problem. You have to run it from a terminal emulator running on X Window System.

   $ tablix2_plot --conv-fitness test1_
   

6. If Tablix found the solution, it has written the solution to a number of files with names test1_result0.xml, test1_result1.xml and so on. The number of files should match the number of computational nodes specified with the -n. Each computational node will return its own result. These results will usually be very similar of even identical.

   XML files can be read directly, but in most cases you will want to convert them into a format that is easier to read by humans. One available option is to convert it to a web page (XHTML format) and open it in a browser.

   $ tablix2_output -o my_timetable.html htmlcss test1_result1.xml
   

7. You can now open the resulting timetable in you favorite browser and check the results:

   $ firefox file://`pwd`/my_timetable.html