Adaptools README

AdapTools 1.2 - Tools for Adaptive Devices Design and Execution

Hemerson Pistori (pistori@ec.ucdb.br) BE CAREFUL!!! This readme is outdated, it refers to an old version of AdapTools. A new version is under construction

1. Installation:

If you are reading this file chances are that the software is already installed and ready to be executed. If you are in a MS-Windows environment just open the run.bat file and the application should start. For linux user:

Open a shell, inside Xwindow
Enter the directory where the adaptools-....zip was unzipped
Type: chmod +x run.sh
Type: ./run.sh // Java must have been installed previously

2. Getting started:

Adaptools.vm.viewer, the program that is called from run.bat, is a virtual machine emulator, with graphical interface, whose object code is essentially an adaptive structured pushdown automata. A structured pushdown automata (SPA) is a kind of "bag of finite state automata" that can "call" each other and itself recursively. Roughly speaking, an adaptive SPA is an SPA that can change its structure dinamicaly (adding and subtracting rules).

Object code file structure of SPA:

It's a simple text file, with each line representing an automata rule (transition). Each component of the rue must be separated by "spaces". A rule is composed by 5 elements:

[1] Origin State (Current State)
[2] Input Symbol
[3] Destination State (Next State)
[4] State to be pushed into the stack (Here is a difference between the usual finite automata and the structured one. The SPA needs a stack to hold the return state of a sub-machine call).
[5] Output Symbol (One can easily build a transducer using this field). This same field is also used to keep the names of semantic routines that should be associated to the transition. As of now, the treatment of semantic routines must be done "by hand", in a java program that must specialize the adaptools.vm.Semantics class (It is not an easy task but we plain to improve it in the near future).

Some special symbols can appear as rule elements (the numbers appearing in brackets indicates the columns in which they can be put):

nop = indicates that nothing must be pushed into the stack [4] or no output symbol must be written. [5]
eps = the empty string. [2]
pop = used to indicate that the next state will be popped from stack [3] (The rule becomes a sub-machine return).
fin = When the rule is a sub-machine return, this tag indicates that the Origin State is a final state [4]. Otherwise, the Destination State is the final state
spc = input symbol is a space or a new-line [2] (The default lexical analyzer returns an "spc" token when reading a space or a new-line. All other ASCII symbols are returned unchanged).

Object code file structure of Adaptive SPA:

The same SPA structure enhanced with 2 more elements:

[0] Header Field: The name of a sub-machine or the name of an adaptive function preceded by one of the following symbols: ? (Query action), + (Insert action) or - (Remove action). The name of the adaptive function is repeated in each of its primitive action component.
[6] Adaptive Action Field: The name of an adaptive function preceded (after action), or followed (before action) by a dot (.). Two names of adaptive function can be put in the same field (with a dot between them), indicating the rule in linked to both before and after actions.

Symbols in primitive adaptive action preceded by ? or * indicates variables and generators, respectively. There are also two special variables, ?sta, for current state, and ?inp, for current input symbol.

Graphical Interface Components:

The viewer window title shows the name of the object code file that is currently opened. The window widgets are:

Object Code (Editable Scrollable Table) : Shows the adaptive SPA rules and adaptive actions. The time column (first column) carries information about the time when new rules where created or removed by adaptive actions. Different sub-machines and adaptive functions are shown in different colors. A right-click popup menu is available over this table with the following options:

Sub-Machine Graph : Shows a graphical representation of the sub-machine on a new window.
New Rule : Open a line in the table so that a new rule or primitive action can be added.
Remove Rule : Remove a rule or primitive action.

Stack : Shows the execution stack (upside-down).
Input: The input string on which the SPA is to be run.
Transducer Output: The output string of the SPA.
Output : The stream "outputted" by the semantic routines associated to the SPA.
Speed (Slider Bar) : Controls the execution speed of the virtual machine (starts at maximum speed - top). You may take the slider to the bottom to run "step by step".
Finals : Final states of the SPA.
State : The current state at execution time.
Run (button) : Starts execution of the SPA or "Step in" when a "step by step" mode is selected (using the Speed Slider Bar).
Menu Bar (on top) : Mainly open, save, saveas and new options for Machine (SubMenu), Input (SubMenu) and Output (SubMenu) widgets. Non "common" options are:

Project->Attach Help File : Attaches a text file (created using any text editor) to the project, so that, any time this project is opened, a new menu item is added to Adaptools' Help Menu. This new menu item will have the name of the attached help file.
Input->Connect : Opens a new viewer connected to another SPA, that will provide the input tokens to the current machine. One can use this option to connect a lexical analyzer to a syntactic analyzer, for instance.
Input->Disconnect : Close the viewer opened by Connect and sets the input for the current machine to the default mode (a trivial lexical analyzer that returns each ascii symbol as a token - except for space and new-line that are returned as "spc" tokens).
Output->As new machine : Opens a new viewer and takes the current machine output as the object code for the machine attached to the new viewer. This option turns the testing of SPA compilers easier.
Options->Step by Step : Disable/Enable step by step execution. Important: The machine will be executed on the LAST SAVED input file.
Options->Animation : Disable/Enable step by step showing of a graphical visualization of machine adaptation..

3. Tutorial:

* vm/aNcbN.spa : This object code represents an SPA that recognizes the aⁿcbⁿ formal language (n "a"'s followed by one "c" followed by n "b"'s) and that output the "a"'s and "b"'s in capital letter. Change the input text and repeat the experiment. Use the speed slider (it can be used during the run-time, to slow it down or speed it up dynamically). Set the speed to the bottom and run the SPA in step by step mode (use the RUN button to step in). States 0-3, 100-101 and 200-201 represents 3 different sub-machines. A graphical representation of this SPA using Neto's notation would look like:

   +---+        +-----+       +-----+       +-----+
   |   |  100   |     |  0    |     |  200  |+---+|
-->| 0 |=======>|  1  |======>|  2  |======>|| 3 ||
   |   |        |     |       |     |       |+---+|
   +---+        +-----+       +-----+       +-----+
     |                                        /^\
     |                    c                    |
     +-----------------------------------------+

   +-----+      +-----+
   |     |  a   |+---+|
-->| 100 |----->||101||
   |     |      |+---+|
   +-----+      +-----+

   +-----+      +-----+
   |     |  b   |+---+|
-->| 200 |----->||201||
   |     |      |+---+|
   +-----+      +-----+

* ccl/lexico.spa: This is a lexical analyzer for a Wirth grammar. Open (Menu->Machine->Open) the machine named "lexico.spa", located in the ccl subdirectory, and the Input named "lista.in" (Menu->Input->Open). Run the machine on this input (just click the RUN button and compare the input with the output). Important: The machine semantics is encoded in a java program (adaptools.ccl.Semantics).

* cc/sintatico.spa: Sintatico.spa is compiler that takes a specification written in Wirth notation and translates it to a SPA (ready to be executed by the virtual machine). Experiment:

- Open the "sintatico.spa" machine (Menu->Machine->Open). // "cc" sub-directory
- Open the "aNbN.in" input (Menu->Input->Open). You should see the following grammar in the input widget: S = "a" S "b" | & . // The "&" symbol is used in place of the epsilon symbol, to facilitate keyboard typing
- Connect the input to the lexico.spa machine: (Menu->Input->Connect -> ccl / lexico.spa) // Observe that a new window is open, with lexico.spa as the object code and that the input is copied to this new window.
- Return to the sintatico.spa window (click on the title bar of it).
- RUN the machine.
- Observe that the output is another machine: a recognizer for aⁿbⁿ
- Open the generated machine in a new window (Menu->Output->As New Machine -> NewMachineFileName).
- RUN the new machine on different strings. HINT: The two machines, together with a sample input file, can be opened all at once, using the "project menu", and opening the cc/sintatico.prj file.

* cc/sintatico.spa: Use the "lista.in" Wirth grammar and the "sintatico.spa" to produce a recognizer for list of numbers. Important: The input must be opened in the lexico window (or be opened before the lexic connection is made).

* vm/adaptive.spa: An adaptive SPA that recognizes aⁿbⁿ. Observe that the execution of primitive adaptive actions is marked with a magenta bar and that results of query actions are marked with pink bars.

* voice/talker.spa: This is a prototype of a text-to-speach system implemented as an SPA. To run this experiment, open the talker.prj project, located in the voice directory. The sound files (.WAV) are located in the "voice/phonemes" sub-directory. To substitute the phonemes files just record new WAV samples using, for instance, your own voice, and replace the existing ones. To add new phonemes (the system is far from being complete) just increment the automata with new rules and record new phonemes wave files. You must use the "output" field of the rule to link the output symbol with the sound file name, without extension (Observe, in talker.spa, how the output symbol matches the sound files name. This is not incidental). Important: The semantics of all this example machines are "hard-wired" in java programs which are linked to the machine by its names. So, don't change the names of this machines. (Or jump into the viewer.java source and change it).

* contrib/copy.spa (see also copy2.spa and copy3.spa): Adaptive automata that are able to clone themselves. The copy generated by these examples recognizes the same language, but with some new empty transitions. These examples are usefull as tools to learn about primitive queries with multiples results.

* Others The contrib directory contains some other examples.

4. Compiling:

Basic steps in order to recompile Adaptools:

- Download Adaptools sources from http://www.pcs.usp.br/~lta (download section)
- Download and Install the complete java package (J2SE) from http://java.sun.com/j2se/downloads.html (Hint: jikes is a much faster alternative to javac)
- Download and Install openjgraph from x http://openjgraph.sourceforge.net/
- Download and Install the full version of SkinLF from http://www.l2fprod.com/
- Adjust the CLASSPATH system variable so that openjgraph and SkinLF classes and jar files can be found by the java compiler.
- Run the atualiza script in the thirdPartModifications/OpenJGraph directory. (set the $OpenJHome before running this script, or change it)
- Compile all java programs in the adaptools folders.

5. Source code:

Under construction.

6. Credits:

Hemerson Pistori - Kernel.java, Viewer.java, cc.Semantics.java ccl.Semantics.java

7. Call for code and bug reports:

If you have implemented a new virtual machine, samples, tutorials, using or referring to AdapTools, and you think it should be included in AdapTools, send us the files, and we can put it in the next AdapTools distribution. If you find any bugs, send a fix to pistori@ec.ucdb.br If that's too hard, just send us a bug report.

8. Copyright:

AdapTools is distributed under the GNU public license. Please read the file GPL.txt

9. Acknowledgments

João José Neto: A great amount of techniques and theories applied in this project was developed by Dr. João José Neto and the Adaptive Language and Technologies Research Group (http://www.pcs.usp.br/~lta)

Universidade Católica Dom Bosco: These works is partially funded by this institution (http://www.ucdb.br )

Jesus M. Salvo Jr: The graphical visualization was implemented using the OpenJGraph package (http://openjgraph.sourceforge.net/)

Eibe Frank: This README file was based on Weka's README.

Eduardo Rocha Costa (eduardo.rocha@poli.usp.br): Conducted tests under linux plataform and created the run.sh script.