ALLEGRO: A Scheme repository from vaishakbelle

###################################################################
ALLEGRO: Belief-based Programming in Stochastic Dynamical Domains
###################################################################

CONTACT:
Vaishak Belle <vaishak@cs.toronto.edu>

LITERATURE REFERENCE FOR CITATION AND FOUNDATIONS: 

Vaishak Belle, Hector J. Levesque:
ALLEGRO: Belief-Based Programming in Stochastic Dynamical Domains. IJCAI 2015: 2762-2769

PREREQUISITES: 

Racket version 5.3.6 or higher 

INSTALLATION: 

> git clone https://github.com/vaishakbelle/ALLEGRO
> cd ALLEGRO  
> racket -if examples/bat0.scm 



----------------------------------------------------------------------------
DESCRIPTION

This is a belief estimator for a version of a probabilistic basic action
theory.  Given a basic action theory and a program, execute the program online
and adjust the probabilities and fluents accordingly. 

THE BASIC ACTION THEORY

The BAT is specified by three functions:

1.  (define-fluent flu gen-expr)
  This defines flu to be a fluent whose value can be generated by gen-expr.
  The gen-expr can mention other fluents, but these need to have been defined
  by earlier define-fluent expressions.

Together, the set of define-fluent expressions specify a Bayes net. (The
parents of a fluent flu are the fluents mentioned in the gen-expr.)

2.  (define-ss-exprs flu act quoted-expr act quoted-expr ...)  
  This determines the successor state expressions for the given fluent flu.
  The act is of the form (name var var ...) where the vars are the arguments
  of the action.  In the quoted-expr, those arguments will be replaced by
  their values if back-quote and comma are used.  If the act takes place, the
  new value of the fluent is as given by the quoted-expr. If an action is left
  off the list, the fluent is assumed to be unchanged by the action.

3.  (define-l-exprs act quoted-expr act quoted-expr ...)  
  The format of the act and quoted-expr are as in #2.  For each act, the
  quoted-expr is numerical and determines the likelihood for that action.  If
  an action is left off the list, it gets a likelihood of 1.0.

The following functions are useful for generating random values:
     (UNIFORM-RAND low high)         a uniform density
     (GAUSSIAN-RAND mu sigma)        a Gaussian density
     (DISCRETE-RAND v1 p1 v2 p2 ...) a discrete distribution
     (BINARY-RAND p)                 a binary discrete distribution   

The following are useful in likelihood expressions:
     (UNIFORM x low high)
     (GAUSSIAN x mu sigma)
     (DISCRETE-RAND x v1 p1 v2 p2 ...)
     (BINARY-RAND x p)

THE ESTIMATOR

The values of terms and degrees of belief are estimated by sampling.  Here are
the main functions:

1.  (set-samples n)
  This controls how many world samples are used for estimation.  This 
  function must be called before execution of any program.

2.  (eval-bel phi)
  Estimate the current degree of belief in phi.  This can be affected by
  running an online program.

3.  (expected-val expr)
  Obtain the current expected value for the expr. This can be affected by
  running an online program.

4.  (conf expr fract)
  Obtain the degree of belief that the value of the expr is within the given
  fraction of its expected value

PROGRAM EXECUTION

1.  (online-do prog) 
  This runs the program in online mode.  Actions to be executed are printed as
  they occur, and sensing results are read in as needed.  During program
  execution, the world fluent values and likelihoods are adjusted.

2.  (expand-do prog)
  Print the program compilation for debugging.

3.  (tcp-online-do prog) 
  This is just like internal-online-do except that actions to be executed are
  sent over TCP to an action server, and sensing results are read over TCP
  from the action server.  The action server must already be running.  

THE PROGRAMS 

The programs here are one of the following:

  - (if phi prog1 prog2)
  - (let ((v1 expr1) ... (vk exprk)) prog1 ... progn)
  - (let var ((v1 expr1) ... (vk exprk)) prog1 ... progn)
  - (while phi prog1 ... progn)
  - (when phi prog1 ... progn) 
  - (begin prog1 ... progn)
  - primitive actions: (name arg1 ... argk), where the args are either
      variables or constants.

The "phi" here must be a subjective formula like (< (eval-bel expr) .3)
or (> (expected-val expr) .5). 

LOADING A BAT

    > racket -if bat0.scm

RUNNING THE ACTION SERVER

An action server for tcp-online-do can be written in any language.  For ease
of testing, a simple action server that simulates a world with one fluent and
three actions is provided.  To run it, in another window run

    > racket -fm action-server.scm

This will start up the server that waits for connections on port 8123 as
required by tcp-online-do.