BEAM How-to-get-started

This document gives you an introduction on how to use the EAM withing YAP. 
We start by explaining how to prepare YAP to use the EAM.
Then we present some code examples that you can use to try 
out the EAM.


WARNING:
THE BEAM WITHING YAP IS STILL IN EARLY DEVELOPMENT, 
SO DON'T EXPECT IT TO RUN SMOOTHLY... 
WE ARE WORKING TO IMPROVE THE INTEGRATION OF BEAM WITHIN
YAP, BUT THIS THINGS TAKE TIME. SO PLEASE BE PATIENT...


---------------------------------------------------------------------------
1. Compiling Yap to support the EAM.
---------------------------------------------------------------------------
If you want to use the BEAM prototype you must compile YAP using the 
flag --enable-eam 

tar -xvzf yapfile.tar.gz           <- will extract yap to $YAPDIR
mkdir tmp                          
cd tmp
../YAPDIR/configure --enable-eam   <- prepare yap to compilation
make                               <- compile yap
su                                 <- enter as root
make install                       <- install yap

You are now ready to try YAP-BEAM. Just run "yap" on the
command line. 


---------------------------------------------------------------------------
2. Quick start + Examples...
---------------------------------------------------------------------------
Quick example on how to run a Prolog program using the EAM.

-FIRST ALTERNATIVE:
Consult your program using eamconsult(+File)
?- eamconsult(qsort).

then you should write your queries using ?- eam(query).
You can write the query normally as in normal Prolog mode, but
in this case you will only receive the first solution (or yes or no).

The eamconsult will pre-compile your prolog code to control
cases where changing the order in execution can be problematic...
For example consider the query:  ?- g(X), f(X).
Supose that g/1 is non-deterministic and that f/1 has a single clause.
The EAM engine will try to execute f/1 first, since it is deterministic.
Now supose that f/1 depends on a bound argument, for example:
f(X):- X > 1, ...

The eamconsult will be transform this code into 
f(X):- skip_while_var([X]), X>1, ...

The skip_while_var/1 will not allow the comparision X>1 to be executed
while X is unbound. 



-SECOND ALTERNATIVE:


First you must enable the EAM using the comand 
?- eam.
yes

then you should load your program, and make your queries 
using ?- eam(query).
You can write the query normally as in normal Prolog mode, but
in this case you will only receive the first solution (or yes or no).


Small example:
Supose that you have the file Example.pl with the Prolog code:
f(1).
f(2).
f(3).

Here is an execution example:
[user]$ ./yap
% Restoring file /.../startup
YAP version Yap-5.0.0
   ?- eam.
yes
   ?- [t].
 % consulting /.../t.pl...
 % consulted /.../t.pl in module user, 1 msec 1328 bytes
yes
   ?- eam(f(X)).
[ EAM execution started to solve f/1 ]
X = 1 ? ;
X = 2 ? ;
X = 3 ? ;
no
   ?- f(X).
[ EAM execution started to solve f/1 ]
X = 1 ? ;
no
   ?-

---------------------------------------------------------------------------
A first example:

You can try out the next example, the well-known benchmark scanner.pl
that behaves badly in standard Prolog systems.
Just run the demos... (demo1, demo2, demo3 or demo4).
Remember to enable the EAM before loading the program.
After running the examples, try restarting YAP and 
loading the program without the EAM enabled. Try to run
the demo4... :)

demo1:- demo(tiny).
demo2:- demo(small).
demo3:- demo(data).
demo4:- demo(snake).

demo(Data):- 
	scannerdata(Data,R,C,D1,D2), 
	write('Rows '), write(R),nl,
	write('Columns '), write(C),nl,
	write('Left diagonals '), write(D1),nl,
	write('Right diagonals '), write(D2),nl,nl,
	scanner(R,C,D1,D2,Image), !,
	displi(Image).

sequence(Spec):-
	samples(Spec,Samples),
	cat(Samples,Images), !,
	displ(Images).

samples([],Samples):- !, Samples=[].
samples([S|Spec],Samples):- !, 
	scannerdata(S,R,C,D1,D2),
	Samples=[sample(R,C,D1,D2)|Smpls],
	samples(Spec,Smpls).

cat([],Images):- !, Images=[].
cat([Sample|Samples], Images):- !, 
	image(Sample,Image),
	Images=[Image|Imgs],
	cat(Samples,Imgs).

image(sample(R,C,D1,D2), Image):-
	scanner(proc,R,C,D1,D2,I), !,
	Image=I.


displ([]):- nl, nl.
displ([I|Imgs]):- nl, displi(I), nl, displ(Imgs).

displi([]):- nl .
displi([R|Rws]):- write('    '),displr(R), displi(Rws).

displr([]):- nl.
displr([on|R]):- write('X '), displr(R).
displr([off|R]):- write('_ '), displr(R).


scannerdata(tiny, [1,1],[2,0],[1,1,0],[0,1,1]).

scannerdata(small, [1,2,1],[2,1,1],[1,1,1,0,1],[0,0,3,1,0]).

scannerdata(double, 
	[2,2,3,2,2,1],
	[1,3,3,1,3,1], 
	[0,1,1,2,1,2,3,1,1,0,0],
	[0,2,0,1,2,2,2,1,2,0,0]).

scannerdata(snake, 
	[4,2,6,2,4,4,3,2],
	[3,5,5,3,2,3,3,3],
	[1,2,2,1,1,2,5,2,2,3,3,2,1,0,0],
	[0,1,0,3,2,2,4,3,3,3,1,3,2,0,0]).

scanner(RwData,ClData,D1Data, D2Data, Rws):- 
	llength(RwData,R),
	llength(ClData,C),
	board(R,C,All,Rws,Cls,D1,D2), 
	check(RwData,Rws),
	check(ClData,Cls),
	check(D1Data,D1),
	check(D2Data,D2).

pixle(on).
pixle(off).


check([],[]).
check([K|RwsD],[R|Rws]):-
	llength(R,L),
	line(K,L,R),
	check(RwsD,Rws).

line(0,0,[]).
line(K,L,[on|R]):-
	K > 0,    
	K1 is K - 1,
	L1 is L - 1,
	line(K1,L1,R).
line(K,L,[off|R]):-
	L > K,  
	L1 is L - 1,
	line(K,L1,R).

board(0,C,[],[],Cls,D,D):- 
	C > 0, 
	C1 is C - 1,
	seed(C,Cls),
	seed(C1,D).
board(R,C,All,[Row|Rws],Cols,Rdiag,Ldiag):- 
	R > 0,
	R1 is R - 1,
	row(C, Row),
	all2(Row,Al,All),
	column(Row,Cls,Cols),
	diagonal(Row,Rdg,Rdiag),
	rev(Row,[],Rev),
	diagonal(Rev,Ldg,Ldiag),
	board(R1,C,Al,Rws,Cls,Rdg,Ldg).

seed(0,[]).
seed(C,[[]|S1]):- C > 0, C1 is C -1 , seed(C1,S1).

all2([],Al,Al).
all2([H|Row],Al,[H|All]):- all2(Row,Al,All).

row(0,[]).
row(C,[_|R]):- C > 0, C1 is C -1, row(C1,R).

column([],X,X).
column([H|R],[Cl|Cls],[[H|Cl]|Columns]):-  column(R,Cls,Columns).

diagonal([H|Row],Dg, [[H]|Diag]):- column(Row,Dg,Diag).

rev([],Y,Y).
rev([H|T],Y,Z):- rev(T,[H|Y],Z).

llength([],0).
llength([A|R],N):- llength(R,M), N is M+1.



---------------------------------------------------------------------------
Another example:

The famours queens...


Try to evaluate in normal Prolog que query:
?- queens([1,2,3,4,5,6,7,8,9,10,11,12,13,14,15],X).
Now quit YAP and enable eam before loading the queens program
Here is the code for you to try it:

demo1:- queens([1,2,3,4,5,6,7,8,9],L), write(L), nl, fail.
demo2:- queens([1,2,3,4,5,6,7,8,9,10,11,12,13,14,15],L), write(L), nl.

queens(L,C):-	
	perm(L,P),
	pair(L,P,C),
	safe([],C).

perm([],[]).
perm(Xs,[Z|Zs]):-
	select(Z,Xs,Ys), 
	perm(Ys,Zs).

select(X,[X|Xs],Xs).    
select(X,[Y|Ys],[Y|Zs]):-
	select(X,Ys,Zs).

pair([],[],[]).
pair([X|Y],[U|V],[p(X,U)|W]):-
	pair(Y,V,W).

safe(X,[]).
safe(X,[Q|R]):-
	test(X,Q),
	safe([Q|X],R).

test([],X).
test([p(C1,R1)|S],p(C2,R2)):-
	test(S,p(C2,R2)),
	nd(p(C1,R1),p(C2,R2)).

nd(p(C1,R1),p(C2,R2)):-
	wait_while_var([C1,C2,R1,R2]),
	C is C1-C2, 
	R is R1-R2, 
	C=\=R,
	NR is R2-R1, 
	C=\=NR.

Note that on the nd predicate, we have used wait_while_var
to force the EAM to wait while C1, C2, R1, R2 are not bound,
because the operations in this predicate can't be done with 
those variables unbound.
Alternatively, and if you don't want to use wait_while_var,
you can compile the prolog code using eamconsult.
eamconsult will insert this instructions for you automatically.

---------------------------------------------------------------------------
3. Some notes...
---------------------------------------------------------------------------

- A lot of builtins/code are not yet supported...
For example var(X), not , ; (or), ... 
You will have a internal compiler error for these cases. 
and the clause that uses the builtin/code not supported  will always fail.
Example: consider the code:
  tst(X):- var(X), X=1.
  tst(2).

You will receive a warning that there is unsupported code.
Although you can still use the tst predicate, the first alternative
will always fail...

  ?- tst(X).
[ EAM execution started to solve tst/1 ]
X = 2 ? ;
no


---------------------------------------------------------------------------
- The EAM prefers deterministic instead of non-deterministic.
and thus can change the order of goals of your code to delay
non-deterministic bindings.

So, you must be careful when using builtins that have side-effects,
or that may expect variables to be bound.

For example, supose that you have  the following Prolog code:
f(1). 
f(2).

tst(Y):- f(X), Y is X+1.

Normal prolog would be fine, but the EAM can not execute this
code correctly because since f(X) is non-deterministic, 
Y is X+1 is executed before X being bound. The result would be:

?- tst(X).
[ EAM execution started to solve tst/1 ]
% INSTANTIATION ERROR- in arithmetic at user:tst/1 (clause 1): expected bound value


The solution for this case is to force the EAM to wait for X to be bound.
This can be done by using eamconsult(File) instead of the normal
consult, or by inserting the control instructions explicitly in the code.

So the code correct code would be:
tst(Y):- f(X), skip_while_var(X), Y is X+1.

That means that the code Y is X+1 should be skipped 
while X is var. Note that in this case there is no more
after Y is X+1. If there were, execution would continue
on that code. 

Another alternative is to use:
tst(Y):- f(X), wait_while_var(X), Y is X+1.

that means what execution can not proceed while X is not bound.



---------------------------------------------------------------------------

- To support the EAM within the YAP the WAM compilation was 
specially the classification of permanent variables.
This code was adapted from the initial BEAM implementation and is not
yet completed. 
I've have already discover some code examples where the variables
should are not being classified as permanent, and as result the BEAM
returns false solutions. We are also working on this problem...

---------------------------------------------------------------------------
Expect more info soon...
...