// ----------------------------------------------------------------------------
// Copyright (C) 2019 Louise A. Dennis, Michael Fisher, and Vincent Koeman
//
// This file is part of the Gwendolen
// 
// Gwendolen is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 3 of the License, or (at your option) any later version.
// 
// Gwendolen is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
// 
// You should have received a copy of the GNU Lesser General Public
// License along with the AIL; if not, write to the Free Software 
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
// 
// To contact the authors:
// http://www.csc.liv.ac.uk/~lad
//
//----------------------------------------------------------------------------

These are files for the examples reported in The ``Why did you do that?'' Button: Answering Why-questions for end users of Robotic Systems in Koeman et al.  Proceedings of EMAS 2019.

This deposit consists of three tar.gz file containing the contents of the gwendolen.tracing and the gwendolen.orca.Prototype6VK packages and an automated test package (ail.tracing) distributed as part of the mcapl framework (https://github.com/mcapl/mcapl).  The version of the system used
to generate the results can be found in the branch tagged omniscient.

Agent Files:
============

The reported results were based on tutorial examples from the gwendolen distribution and a prototype agent developed for the ORCA project.

pickuprubble_goal.gwen (in gwendolen.tracing) - example from the Gwendolen tutorials featuring a search and rescue robot 
pickuprubble_achieve.gwen (in gwendolen.tracing) - example from the Gwendolen tutorials featuring a search and rescue robot 
Executive.gwen (in gwendolen.orca.Prototype6VK) - example agent to control a UA inspecting an oil rig 

AIL Configuration Files:
========================

pickuprubble_goal.ail - runs the pickuprubble_goal agent configured to generate a trace in the folder /src/examples/gwendolen/tracing/traces
pickuprubble_achieve.ail - runs the pickuprubble_achieve agent configured to generate a trace in the folder /src/examples/gwendolen/tracing/traces
Executive.ail - runs the Executive agent configured to generate a trace in the folder /src/examples/orca/Prototype6VK/traces

Description Files:
==================

pickuprubble_achieve.desc - Natural language versions of predicates used in the pickup rubble examples.
Executive.desc - Natural language versions of the predicates used in the UA example.

Java Files (in gwendolen.orca.Prototype6VK):
============================================

FlightControlSystem.java 
ORCAEnv.java
RoutePlanner.java

All these provide an  environment and route planner to be controlled by the Executive agent in the ORCA example.  They should be run automatically by AIL when generating the example and their behaviour is not relevant to explainability.

Java Files (in ail.tracing):
============================

BasicQuickTests.java - two basic JUnit tests that check thaht pickuprubble_goal.ail and Executive.ail produce traces without generating errors.
EventTableTestRig.java - A generic test framework to read in trace that can be used to generate explanations.
GwendolenExplanatinQuickTests.java - A set of JUnit tests, mostly based on the pickuprubble_goal example to check explanations are being generated correctly.  These can be inspected, if desired, to see the output of various queries.  Some of these are presented as example results in the paper.

Traces:
======= 

robot_19-05-28_17-06-15-054.db - trace of the pickuprubble_goal example generated on the 28th May 2019 and used as part of the unit tests.
executive_19-05-28_18-11-31-199.db - trace of the ORCA example generated on 28th May 2019 and used as part of the unit tests.

BRIEF INSTRUCTIONS:

Traces can be generated by running the AIL configuration files in the AIL (as described in the MCAPL Framework Manual)

If investigating other examples (not those supplied in this deposit) then the following properties need to be set in the AIL configuration file.

tracing.enabled = true
tracing.descriptions = (path to a relevant .desc file if one exists)
tracing.directory = (path to the directory where traces are to be stored).

Traces will be generated in files with the naming format AGENT_DATE_TIMESTAMP.db

Traces can be viewed either by running gwendolen.tracing.GwendolenEventTable.java and then selecting a trace in the file chooser box displayed, or using the Eclipse launch configuration run-GwendolenEventTable.launch (from the eclipse folder of the MCAPL framework) with the relevant trace selected in eclipse.

An interface will appear showing the space-time view (as described in the paper) and allowing a choice of explanations to be generated.  Note that in the ORCA example some explanations fail because the system does not yet handle plans generated when goals are dropped.  This is discussed in the paper.
