.. -*- rst -*-

external interfaces to the Envisioner
=====================================

 | $URL: https://svn.parc.com/svn/era/Projects/META/envisioner/interface/ReadMe.txt $
 | $Id: ReadMe.txt 11284 2011-03-15 01:45:03Z jhanley $

META's lisp implementation of the Envisioner
accepts the name of a test, such as expt9,
executes it, computes some projection of the envisionment,
and returns that string to the web client.
Here is an example test function, experiment 9::

  (defun expt9 ()
    (analyze 'o
             'lcr-oscillator
             '(((>> i L o) . Q+)
               ((>> v C o) . Q+)
               ((deriv (>> i C o) 1) . Q+))
             :interval
             '((>> i L o) (>> v C o))
             :display? nil))

It gives initial conditions where three values
are increasing: current through inductor, voltage across capacitor,
and first derivative of current through capacitor.

A projection function, env-summary, converts an envisioned situation
to a string, which will be returned to the web client.  For example,
the query::

  $ lynx -dump http://localhost:8000/envisionment-service/summary?name=expt9

yields the response::

  {"states":8,"values":14}

Equivalently, one can run Allegro's mlisp from the command line
with argument -e '(env-summary (expt9))' to elicit the same result.
So if startup cost is uninteresting, envisionment service via the web
or the command line is the same.  If the cost of loading or computing
an envisionment is much larger than the cost of a bunch of small queries
made against it, then the web service will start to look more attractive.

.. mlisp -batch -L ~/clinit -L ../loader -e '(load-env-system)' -e '(print (env::env-summary (env::expt9)))'

GraphViz-style views are available.

::

  $ lynx -dump http://localhost:8000/envisionment-service/graph?name=expt9

yields a response starting "digraph G" which may be saved locally and rendered with `dot`.


Recommendations
---------------
* Need more detailed client queries.  What does the client want to know?