%
%  $Id$
%
%  Copyright (c) 2004, RIACA, Technische Universiteit Eindhoven (TU/e).
%  All Rights Reserved.
%
%
\documentclass{monet}

%\RequirePackage[T1]{fontenc}

%% \usepackage[screen]
\usepackage{graphicx}
\usepackage[english]{babel}
\usepackage{url}


\title{Explanation and Debugging Tool} 
\author{O. Caprotti}
\author{M. N. Riem} 
\author{Mike Dewar}
\date{}

\begin{document}




\task{3.3}
\version{1.0}
\deliverable{D19}
\status{Internal}


\begin{abstract}
The Explanation and Debugging tool is an application client to the
Execution Manager. By switching the tracing option on the execution of
plans, the result is a document written using the Mathematical
Explanation Ontology produced in task 2.4. This document provides a
unified depiction of how the execution of the plan achieved the
solution.  The user may use the client to replay the plan or modify
certain steps.
\end{abstract}

\maketitle



\section{General Description}

The Explanation and Debugging tool is an application developed as a
client to the Execution Manager. We recall that the Execution Manager
is a component of the MONET Broker, implemented as a web service, and
delivering the following functionality

  \begin{itemize}
   \item execution of handwritten or generated plans
   \item invocation (mathematical) of web services as specified in a
   plan
   \item generation of an explanation of an execution
   \item workflow management for plans
  \end{itemize}

  
  In the MONET architecture the Execution Manager is the component at
  the end of the pipeline consisting additionally of the Registry
  Manager and the Planning Manager.  Mathematical plans can be
  generated by the Planning Manager as the result of a user query and
  in \emph{resolved} form they can be submitted to the Execution
  Manager for execution on behalf of the client. In order to obtain a
  \emph{resolved} plan, the Planning Manager invokes the Registry
  Manager for resolving the mathematical queries by actual service
  URIs that match the requirements.
  
  Due to this high interdependence with the other components, the
  Execution Manager and consequently the Tracing and Debugging Tool
  have been tested last and this release provides a partial
  implementation of all the features present in the protocols.  We
  like to remark however, that the initial design choice made for the
  MONET architecture that every component should be implemented as a
  webservice, meant that most of the work was done independently by
  considering all componenets as blackboxes delivering specific
  services.

  As a blackbox, the Execution Manager is transforming a plan written
  in the Mathematical Plan Language to an explanation written in the
  Mathematical Explanation Language. Both languages have an XML syntax
  defined by a schema that is part of the MONET namespace.  The
  explanation can simply be the result of the execution, or a trace of
  the execution plus the result, or a more elaborate result document
  in MEL.


  \begin{center}
   \includegraphics[angle=270]{em}
  \end{center}

  \section{Mathematical Planning Language (MPL)} 

        
The syntax and semantics of MPL are similar to the Business Process
Execution Language (BPEL). There were three good reasons for MPL to
have a syntax similar to BPEL:
\begin{enumerate} 
\item it is a web standard used for non-mathematical processes and as
  such borrowing from its syntax makes it easier for users to
  understand MPL
  
\item it is possible to write an Execution Manager based on existing
  BPEL engines
        
\item integration of the Execution Manager into existing BPEL
  environments is easier when the language that is understood is the
  same language.
\end{enumerate}

Figure~\ref{fig:mpl} gives an example of a deterministic hand-written
plan consisting of a sequence of assignments, one of which performs a
direct call of a mathematical web service at a certain URL. In this
example the plan gives all the details necessary for the call to be
performed.

\begin{figure}[htbp]
  \centering
  \begin{small}
  \begin{verbatim}
<plan name="Plan for IGCD" problem="http://monet.nag.co.uk/problems/igcd" 
  xmlns="http://monet.nag.co.uk/monet/ns" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation= "http://monet.nag.co.uk/monet/ns 
  http://monet.nag.co.uk/cgi-bin/cvsweb.cgi/%7echeckout%7e/xsd/mpl.xsd">
  <sequence>
    <assign>
      <varref name="a"/><object><OMOBJ><OMI>34</OMI></OMOBJ></object>
    </assign>
    <assign>
      <varref name="b"/><object><OMOBJ><OMI>12</OMI></OMOBJ></object>
    </assign>
    <assign>
      <varref name="r"/>
      <call
        service="Gcdws"
        port="GcdWebServiceIFPort"
        namespace="http://echoservice.org/wsdl"
        endpoint="http://localhost:8080/gcdws/gcdws"
        operation="gcdStringOM"
        returnType="xsd:string">
        <String_1 type="xsd:string"><varref name="a"/></String_1>
        <String_2 type="xsd:string"><varref name="b"/></String_2>
      </call>
    </assign>
    <return><varref name="r"/></return>
  </sequence>
</plan>
  \end{verbatim}
  \end{small}  
  \caption{Example of a deterministic mathematical plan}
  \label{fig:mpl}
\end{figure}

Figure~\ref{fig:nagopt} is the non-deterministic (in the sense that a
choice of services is given) resolved plan returned by the Planning
Manager when queried about a very specific instance of a constrained
minimisation problem. In this plan, there are two possible choices for
a service: the Execution Manager chooses always the first service
listed.


\begin{figure}[htbp]
  \centering
  \begin{tiny}
    \begin{verbatim}
<plan xmlns="http://monet.nag.co.uk/monet/ns" 
      problem="http://monet.nag.co.uk/problems/constrained_minimisation" 
      name="Plan for http://monet.nag.co.uk/problems/constrained_minimisation"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xsi:schemaLocation= "http://monet.nag.co.uk/monet/ns 
      http://monet.nag.co.uk/cgi-bin/cvsweb.cgi/%7echeckout%7e/xsd/mpl.xsd">
    <parameters>
        <parameter name="objective"/>
        <parameter name="simple_bounds"/>
        <parameter name="linear_constraint_functions"/>
        <parameter name="linear_constraint_bounds"/>
        <parameter name="non_linear_constraint_functions"/>
        <parameter name="non_linear_constraint_bounds"/>
    </parameters>
    <variables>
        <var name="result"/>
    </variables>
    <monet:sequence xmlns:monet="http://monet.nag.co.uk/monet/ns">
       <monet:assign><monet:paramref name="objective"/><monet:object>
          <om:OMOBJ xmlns:om="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <om:OMBIND><om:OMS name="lambda" cd="fns1"/>
              <om:OMBVAR><om:OMV name="x"/></om:OMBVAR>
              <om:OMA><om:OMS name="divide" cd="arith1"/>
                <om:OMA><om:OMS cd="transc1" name="sin"/>
                   <om:OMV name="x"/>
                </om:OMA>
                <om:OMV name="x"/>
              </om:OMA>
            </om:OMBIND>
          </om:OMOBJ>
        </monet:object></monet:assign>
        <monet:assign><monet:paramref name="simple_bounds"/><monet:object>
          <om:OMOBJ xmlns:om="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <om:OMA><om:OMS name="list" cd="list1"/>
              <om:OMA><om:OMS name="interval" cd="interval1"/>
                <om:OMF dec="3.5"/>
                <om:OMF dec="5.0"/>
              </om:OMA>
            </om:OMA>
          </om:OMOBJ>
        </monet:object></monet:assign>
        <monet:assign><monet:paramref name="linear_constraint_functions"/>
        <monet:object.../></monet:assign>
        <monet:assign><monet:paramref name="linear_constraint_bounds"/>
        <monet:object.../></monet:assign>
        <monet:assign><monet:paramref name="non_linear_constraint_functions"/>
        <monet:object.../></monet:assign>
        <monet:assign><monet:paramref name="non_linear_constraint_bounds"/>
        <monet:object.../></monet:assign>
        <assign>
            <varref name="result"/>
            <invoke problem="http://monet.nag.co.uk/problems/constrained_minimisation">
                <services>
                    <url>http://wolfix.essi.fr:8080/msdl/http___monet.nag.co.uk_8180_axis_services_OMNagServerOptStr.msdl</url>
                    <url>http://wolfix.essi.fr:8080/msdl/http___monet.nag.co.uk_8180_axis_services_OMNagServerOpt.msdl</url>
                </services>
                <mapping>
                    <map inputname="objective"><paramref name="objective"/></map>
                    <map inputname="simple_bounds"><paramref name="simple_bounds"/></map>
                    <map inputname="linear_constraint_functions"><paramref name="linear_constraint_functions"/></map>
                    <map inputname="linear_constraint_bounds"><paramref name="linear_constraint_bounds"/></map>
                    <map inputname="non_linear_constraint_functions"><paramref name="non_linear_constraint_functions"/></map>
                    <map inputname="non_linear_constraint_bounds"><paramref name="non_linear_constraint_bounds"/></map>
                </mapping>
            </invoke>
        </assign>
        <return><varref><varref name="result"/></varref></return>
     </monet:sequence>
</plan>

    \end{verbatim}
  \end{tiny}
  \caption{Example of a non-deterministic resolved mathematical plan}
  \label{fig:nagopt}
\end{figure}


Both plans are instances of the XML schema available at
\url{http://monet.nag.co.uk/cgi-bin/cvsweb.cgi/\%7echeckout\%7e/xsd/mpl.xsd}
and documented in~\cite{monet:d16-d18}.




  
\section{Mathematical Explanation Language (MEL)}

The result of executing a plan via the Execution Manger is a document
written using the Explanation Ontology described
in~\cite{monet:d07_final}.  Such a document could describe anyone of
the following:
  \begin{itemize}
    \item the answer to the problem query
    \item the answer plus the traces of the which calls were made to
      webservices 
    \item the answer plus several explanations given by the invoked
      webservices and/or the plan itself.
  \end{itemize}
  
  
  The Execution Manager triggers tracing by default and it returns as
  response a copy of the plan being executed.




\section{Installation}
\label{sec:installation}

The Execution Manager has been developed in a Java environment,
specifically J2SE 1.4+ (\url{http://java.sun.com}) and tested on
Tomcat 5.0.18+ (\url{http://jakarta.apache.org}). It requires the
libraries distributed with the Java Web Services Developer Pack JWSDP
1.3 (``Typical'' installation), also available from the Java website.
Compilation and installation is achieved via Apache Ant Java-based
build tool \url{http://ant.apache.org/}.

The Debugging and Tracing tool is a client to the Execution Manager.
Therefore the distribution contains also the Execution Manager
service. The installation and compilation has to be carried out in
this exact order.

\textbf{Installing the Execution Manager Service} To install the
Execution Manager service on \texttt{localhost}, set the build
property \texttt{jwsdp.root} to the local JWSDP 1.3 directory. The ant
target \texttt{deploy} generates the deployable WAR file under
\texttt{build/doc/execmgr.war}. Deploy this WAR file using the Tomcat
manager client, or drop it in the webapps directory of Tomcat.  After
restarting Tomcat, the execution manager service should be available
at \url{http://localhost:8080/execmgr/execmgr}. Make sure it is
available before trying to compile the client.


\textbf{Installing the Tracing and Debugging Client} The ant target
\texttt{client} generates and compiles the classes needed for the
client whereas the \texttt{deploy} target packs them into the
deployable WAR file \texttt{build/doc/execmgr.war} overwriting the
file produced in the step above.  As before, deploy the WAR file
(build/doc/execmgr.war) using the Tomcat manager client, or drop it in
the webapps directory of Tomcat after removing the old execmgr
directory. Restarting Tomcat and browsing to
\url{http://localhost:8080/execmgr} opens the page of the tracing and
debugging tool.


\section{Tracing and Debugging}
\label{sec:tracing}

The trace of the execution of a plan is represented by the explanation
returned by the Execution Manager. 

This explanation is rendered using the standard MONET stylesheet which
allows to contract and expand the view. 


Debugging the actual internal working of the Execution Manager may
involve looking at the Jelly script which is executed since the
implementation is based on the Jelly engine.  Such scripts are
obtained via a transformation of the input plan using the stylesheet
\texttt{src/share/xdocs/xsl/mpl2jelly.xsl} included in the
distribution. The tool provides, under the input text area, the
buttons labelled \texttt{Show Jelly} and \texttt{Execute It},
respectively yielding the transformation of the plan into a Jelly
script and the explanation result after execution of the plan. The
output is displayed in a second textarea along with buttons labelled
\texttt{Render Result} and \texttt{View Source}, respectively for
pretty printing explanation in XHTML and for opening the browser DOM
viewer on the source.
 
 


\bibliographystyle{plain}
\bibliography{monet}
 

\end{document}
