/* -*- C++ -*- */
/** @mainpage TREX A Teleo-Reactive Executive 


This is the documentation of TREX codename
<a href="http://www.youtube.com/watch?v=RM9o4VnfHJU&feature=channel_page">barreleye</a>. 
This version is the first TREX version that do not rely on Europa for
its core functionalities as a result one can use TREX with which ever 
planner he wants - as long as this one can hanlde properly the goal 
representation expected by TREX.

@section start Getting started
@li @ref general : Presents the how T-REX software is organized 
@li @ref install : A quick view on how to install T-REX on your pltafrom along 
  with the thrid party liabries you'll need to download
@li @ref tutorial : Walks you through a simple mission where to europa based 
  reactors are fighting other a light state.


@page general TREX general structure 

@image html SWarchi.png "TREX Software architecture" width=10cm

This version of TREX is composed of multiples libraries and
components which are organized as follow:
@li <b> Main libraries: </b> They are also called @e module. All of
them are compiled into the @c lib directory. There's 4 of them
described more in detail in this document :
<ul>
<li> @c TREXutils (trex/utils): A set of classes that represent basic
functionallities that are used by TREX but are more based on 
generic programming paradigms and design patterns that could be
used for other programs.</li>
<li> @c TREXdomains (trex/domain): Definition of domains and variables as manipulated
by TREX for information exchange between reactors. A variabl is
defined by a name and a domain. A domain is a typed, possibly continuous,
set of possible values for this varaible. A domain cannot be empty and
can only be restricted.</li>
<li> @c TREXtransaction (trex/transaction): This library define the reactors which is the
basic component that can be composed inside TREX. It defines also
Obsevations and Goals which are the data that can be exchanged between
reactors.</li>
<li> @c TREXagent (trex/agen): Defines the TREX agent. The agent is the main
entity that manages the loading and execution of the reactors as their
interaction.</li>
</ul>
@li <b> TREX commands (trex/cmds): </b> A set of simple commands that can be used
to execute a TREX agent. They are compiled into the @c bin
directory. There's two generic commands that gives a simple
illustration on how one can create and manipulate an Agent :
<ul>
<li> @c amc : This program takes a configuration file as
argument. Provided that this file defines correctly an Agent it will
execute this agent until its end.</li>
<li> @c sim : This program takes similar argument as @c amc. The
difference here is that it provides a simple interface to run the
agent in an interactive way allowing to step through clock ticks.
</li>
</ul>
@li <b> TREX plug-ins: </b> These are optionnally compiled and the
source is usually located under @c extra/@<name@>. You can comile them
by calling @c jam @c @<name@>. The result will be put under @c extra
directory  as a dynamic library named @c TREX@<name@>.
@li <b> TREX documentation: </b> Generated from the source using @c
jam @c doc. It will be installed on the @c doc directory.
@li <b> TREX logs: </b> Usually generated under the @c log directory
after any run of a TREX agent.
@li <b> TREX utilities and scripts: </b> Under @c offboard. Provides a 
set of scripts and utilities to help the processing  of TREX logs.
@li <b> nightly build: </b> Under @c nightly,. Used to run nightly builds 
of the head.
@li <b> Configurations files </b> Usually under @c cfg. A set of configuration files that can be used to define new agents and/or reactors.

@page install Installing TREX

@section install-requirement Third party requirements

TREX uses third party utilities and libraries. Here's sa list of them
: 
@li @b boost (http://www.boost.org) This library is widely used for
basic utilities and compatibility with C++11 standard. As we use
flyweight, boost graph and property tree the earliest version 
to be used is 1.47.0 (we tested it with boost 1.47.0 and 1.49.0). 
We also support boost 1.46.1 provided that the c++ compiler support some 
c++11 impovement (especially the chrono classes) are supported.

Others utilies are of interrest but not necessary to use TREX:
@li @e doxygen (http://www.doxygen.org/) This utility is needed only
if you want  to generate this documentation.
@li @e graphviz (http://www.graphviz.org/) Recommended for
documentation but it may also be used for plan visualization by
showing tokens and their relations as a graph.

To compile trex libraries there's currently one approach supported:
@li @b cmake (http://www.cmake.org/) newly added which -- among other things --
   allows to integrate trex2 in multiple IDEs such as Eclipse, Xcode, ...

We also provide two plug-ins in the extr directory that are set o be compiled by default. While none 
of these 2 are part of the core of T-REX they are providing an inital set of features that makes T-REX more practical.
These two plug-ins require the following libraries :
@li the @e europa plug-in requires @b europa-pso (http://code.google.com/p/europa-pso/) version 2.4 or above. It provides a reactor 
  that uses europa planner to plan and execute within trex
@li the @e witre plug-in requires @b Wt library (http://www.webtoolkit.eu/wt) version 3.2.0 or above. It provides a reactor that acts 
as a web interface to the agent showing observations exchanged between reactors and allowing to pos new goals.

@section install-cmake Compiling with cmake

More details can be found on cmake <a href="http://www.cmake.org/cmake/help/runningcmake.html">
 official documentation</a>. But here's a quick tutorial to use make as the end
 compilation tool.

Create your working directory :
@code 
> mkdir trex2.build
> cd trex2.build 
@endcode
run cmake by passing the location of the source tree as argument 
(we'll assume that trex2.build is ate the same level as trex2-agent source
directory)
@code 
> cmake ../trex2-agent/
-- The C compiler identification is GNU
-- The CXX compiler identification is GNU
-- Checking whether C compiler has -isysroot
-- Checking whether C compiler has -isysroot - yes
-- Checking whether C compiler supports OSX deployment target flag
-- Checking whether C compiler supports OSX deployment target flag - yes
-- Check for working C compiler: /usr/bin/gcc
-- Check for working C compiler: /usr/bin/gcc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Checking whether CXX compiler has -isysroot
-- Checking whether CXX compiler has -isysroot - yes
-- Checking whether CXX compiler supports OSX deployment target flag
-- Checking whether CXX compiler supports OSX deployment target flag - yes
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- trex VERSION = 0.3.3
-- Looking for dlopen in dl
-- Looking for dlopen in dl - found
-- Looking for pthread_self in pthread
-- Looking for pthread_self in pthread - found
-- Looking for shm_unlink in rt
-- Looking for shm_unlink in rt - not found
-- Boost version: 1.49.0
-- Found the following Boost libraries:
--   thread
--   system
--   signals
--   chrono
--   filesystem
-- Europa found : include directory is /Users/fpy/Coding/europa-2/include
-- Found Doxygen: /opt/local/bin/doxygen 
-- Found the Wt libraries at /usr/local/lib/libwt.dylib;/usr/local/lib/libwtext.dylib;/usr/local/lib/libwthttp.dylib;/usr/local/lib/libwtdbo.dylib;/usr/local/lib/libwtdbosqlite3.dylib;/usr/local/lib/libwtfcgi.dylib
-- Found the Wt headers at /usr/local/include
-- Found the Wt debug libraries at /usr/local/lib/libwt.dylib;/usr/local/lib/libwtext.dylib;/usr/local/lib/libwthttp.dylib;/usr/local/lib/libwtdbo.dylib;/usr/local/lib/libwtdbosqlite3.dylib;/usr/local/lib/libwtfcgi.dylib
-- Found the Wt debug headers at /usr/local/include
-- Configuring done
-- Generating done
-- Build files have been written to: /Users/fpy/Coding/trex2.build
@endcode
If no error occured, you can just run make as usual 
@code 
> make
Scanning dependencies of target TREXutils
[  3%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/ErrnoExcept.cc.o
[  6%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/Exception.cc.o
[  9%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/LogManager.cc.o
[ 12%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/Pdlfcn.cc.o
[ 15%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/PluginLoader.cc.o
[ 18%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/RStat.cc.o
[ 21%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/SingletonDummy.cc.o
[ 25%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/SingletonServer.cc.o
[ 28%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/TextLog.cc.o
[ 31%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/TREXversion.cc.o
[ 34%] Building CXX object CMakeFiles/TREXutils.dir/trex/utils/XmlUtils.cc.o
Linking CXX shared library libTREXutils.dylib
[ 34%] Built target TREXutils
Scanning dependencies of target TREXdomain
[ 37%] Building CXX object CMakeFiles/TREXdomain.dir/trex/domain/BasicEnumerated.cc.o
[ 40%] Building CXX object CMakeFiles/TREXdomain.dir/trex/domain/BasicInterval.cc.o
[ 43%] Building CXX object CMakeFiles/TREXdomain.dir/trex/domain/DomainBase.cc.o
[ 46%] Building CXX object CMakeFiles/TREXdomain.dir/trex/domain/DomainImpl.cc.o
[ 50%] Building CXX object CMakeFiles/TREXdomain.dir/trex/domain/Variable.cc.o
Linking CXX shared library libTREXdomain.dylib
[ 50%] Built target TREXdomain
Scanning dependencies of target TREXtransaction
[ 53%] Building CXX object CMakeFiles/TREXtransaction.dir/trex/transaction/Goal.cc.o
[ 56%] Building CXX object CMakeFiles/TREXtransaction.dir/trex/transaction/LogPlayer.cc.o
[ 59%] Building CXX object CMakeFiles/TREXtransaction.dir/trex/transaction/Observation.cc.o
[ 62%] Building CXX object CMakeFiles/TREXtransaction.dir/trex/transaction/Predicate.cc.o
[ 65%] Building CXX object CMakeFiles/TREXtransaction.dir/trex/transaction/reactor_graph.cc.o
[ 68%] Building CXX object CMakeFiles/TREXtransaction.dir/trex/transaction/Relation.cc.o
[ 71%] Building CXX object CMakeFiles/TREXtransaction.dir/trex/transaction/TeleoReactor.cc.o
[ 75%] Building CXX object CMakeFiles/TREXtransaction.dir/trex/transaction/TransactionLogger.cc.o
Linking CXX shared library libTREXtransaction.dylib
[ 75%] Built target TREXtransaction
Scanning dependencies of target TREXagent
[ 78%] Building CXX object CMakeFiles/TREXagent.dir/trex/agent/Agent.cc.o
[ 81%] Building CXX object CMakeFiles/TREXagent.dir/trex/agent/Clock.cc.o
[ 84%] Building CXX object CMakeFiles/TREXagent.dir/trex/agent/RealTimeClock.cc.o
[ 87%] Building CXX object CMakeFiles/TREXagent.dir/trex/agent/StepClock.cc.o
Linking CXX shared library libTREXagent.dylib
[ 87%] Built target TREXagent
Scanning dependencies of target TREXlightswitch
[ 90%] Building CXX object CMakeFiles/TREXlightswitch.dir/extra/lightswitch/LightSwitch.cc.o
Linking CXX shared library libTREXlightswitch.dylib
[ 90%] Built target TREXlightswitch
Scanning dependencies of target TREXvitre
[ 93%] Building CXX object CMakeFiles/TREXvitre.dir/extra/vitre/Vitre.cc.o
Linking CXX shared library libTREXvitre.dylib
[ 93%] Built target TREXvitre
Scanning dependencies of target amc
[ 96%] Building CXX object CMakeFiles/amc.dir/trex/cmds/AMC.cc.o
Linking CXX executable amc
[ 96%] Built target amc
Scanning dependencies of target sim
[100%] Building CXX object CMakeFiles/sim.dir/trex/cmds/Sim.cc.o
Linking CXX executable sim
[100%] Built target sim
@endcode 

You can install the output using the usual :
@code 
> make install
@endcode 
By default everything iis installed under @c /usr/local and tou can source the file
@c /usr/local/shared/trex/trex_init.bash to setup you environment. To change the 
target directory you can either use ccmake command and change CMAKE_INSTALL_PREFIX
value or look on how to change this value with the cmake command you are using.

Finally, if you want ot generate this doc just do :
@code 
> make doc
@endcode

@page tutorial Running a simple example

So far this version of TREX do not provide that much illustrations but at least a simple one exist with the lightswitch, vitre and europa plug-ins. To use it you first need to compile your source :
@code 
~$ cd trex2.build 
trex2.build$ make 
[...]
trex.build$
@endcode

After having compile you can either install the binaries or set-up your enviroment 
to run the code from the build directory. For the later we generate locally the 
trex-devel.bash file that can be sourced
@code 
trex2.build$ source trex_devel.bash
@endcode


You can now start the simulation but beforehand we are going to give a look at 
the configuration files on $TREX_HOME/cfg used for this short test. 
We are going to use 3 of them :
@li @c sample.cfg Is the mission config file
@li @c lighton.req and @c lightoff.req are files describing goals 
    that one can post interactivelly through the sim interface

The content of @c sample.cfg should looks similar to this :
@code  
<Agent name="sample" finalTick="100" >
       <Plugin name="witre_pg"/>
       <Plugin name="lightswitch_pg"/>
       <Plugin name="europa_pg"/>

       <Light name="light" latency="0" lookahead="1" log="1" state="1"/>

       <EuropaReactor name="test" lookahead="20" latency="3" 
		      solverConfig="test.solver.xml" />
       <EuropaReactor name="test2" lookahead="20" latency="3" 
		      solverConfig="test.solver.xml" />

       <WitreReactor name="switchView" latency="0" lookahead="0"
                     log="0">
         <External name="light" goals="0"/>
         <External name="switch" goals="0"/>
         <External name="lum" goals="0"/>
         <External name="lum2" goals="0"/>
       </WitreReactor>

      <Goal on="lum" pred="Bright">
        <Variable name="end"><int min="50"/></Variable>
      </Goal>

      <Goal on="lum2" pred="Dim">
	<Variable name="start"><int min="20"/></Variable>
        <Variable name="end"><int min="10000"/></Variable>
      </Goal>
</Agent>
@endcode
The @c Agent tag declare the global agent with its @c name and @c finalTick both of them can be freely modified.

The @c Plugin tag indicates that this mission need to load the @c lightswitch_pg plug-in. Based on that @c sim will automatically look on local directory and @c TREX_PATH to locate this plug-in.

The @c Light declare a reactor which is implemented in @c lightswitch_pg. This one starts with a @c state of 1 which mean that its light is on. You can change it to 0 if you want to start with the light off.

The @c EuropaReactor declare a reactor which is implemented in @c europa_pg. These 
two reactors are keeping track on the light to know if the luminance is bright or 
dark. and can switch the light on the desired state according to their objectives.

The @c WitreReactor declare a reactor that will create a web server providing an 
interface to TREX in order to track the observations from the dirfferent timelines in the agent, post goals, ... The "External" tags 
specifies which timelines this reactor needs to look at. Feel free to change these.

Finally the two Goal at the end gives the objectives for each EuropaReactor. 
Quickly stated : @c test will want to be on a Bright state at the end of the mission 
while @c test2 will want to be Dim at the end of the mission starting from the tick 20

@section sample_run the sample mission

To start the sample mission you can do the following :
@li start the simulation in "debug" mode :
@code 
trex2.build$ sim sample
This is TREX v0.1.3
Options:
  Q :- quit
  N :- next tick
  G :- goto tick (e.g. g100)
  P :- post the goals from the attached file
       (e.g P goal.req)
  K :- kill one reactor (e.g K foo)
  H :- print this help message
[sample:0]> 
@endcode
The mission is loaded and the prompt indicate the name of the agent (sample) and
the current tick value 0. You can use commands to interact with the agent by advancing of one tick (N), go to a given tick in the future (G) or post a request described in a file (P)

You can already look at this agent by typing the url http://localhost:8080/witre which should display a web page with the current tick value, a set of buttons llowing to show hid the different timelines of the agent, few links to other informations pages for this agent. This specific page will display a stream of all the observations received -- displayed in text form.

you can also in an alternate terminal look on the activity of the agent redirected
in @c $TREX_LOG_DIR/latest/TREX.log
@code 
~$ cd $TREX_LOG_DIR
log$ tail -F latest/TREX.log
[lightswitch] LightSwitch loaded.

@endcode
At this stage it indicate the lightsiwtch plug-in was successfully loaded. But as the mission you'll see other messages including new observations on timelines (ASSERT), requests, ...

This is especially true as the two reactors test and test2 will compete to have 
the light on or off starting from the tick 20.

Going back to the sim shell you can then uses the command to switch the lights on or off on your reactor. For example 
@code 
Options:
  Q :- quit
  N :- next tick
  G :- goto tick (e.g. g100)
  P :- post the goals from the attached file
       (e.g P goal.req)
  K :- kill one reactor (e.g K foo)
  H :- print this help message
[sample:0]> n
[sample:1]> P lighton
Loading "/Users/fpy/Coding/TREX2/cfg/lighton.req"... done
Extracting goals:
 - light.Light.On
[sample:1]> n
[sample:2]> g10
[sample:10]> p lightoff
Loading "/Users/fpy/Coding/TREX2/cfg/lightoff.req"... done
Extracting goals:
 - light.Light.Off
[sample:10]> n
[sample:11]> g1000
Mission completed.
TREX2$
@endcode

@note The ticks are not in real-time in @c sim. This is related to the fact that
@c sim needs to be able to interrupt the clock and restart it. We plan to implement a
pseudo real-time clakc but most of the time the we use @c sim to replay a past mission (using a LogPlayer reactor which is not provided yet on this version) and as these can be long (hours) the fast sim clock is a better fit.

*/





/** @defgroup core TREX core 
 * @brief Core components of TREX
 *
 * This module embeds all the components considered as the core of TREX.
 *
 * @author Conor McGann @& Frederic Py <fpy@mbari.org>
 */

/** @defgroup utils Basic utilities
 * @brief simple utilities library
 *
 * This library embeds all the basic utilities manipulated by higher
 * level TREX components. They are all provided by the library named
 * @c lib/libTREXutils
 *
 * @author Frederic Py <fpy@mbari.org>
 * @ingroup core
 */

/** @defgroup domains Domains
 * @brief generic constrained variables 
 *
 * This library embeds all the basic utilities to defined constrained
 * variables used for defining TREX goals and observations. All of these
 * are provided by the library  @c lib/libTREXdomain
 *
 * @author Frederic Py <fpy@mbari.org>
 * @ingroup core
 */

/** @defgroup transaction TREX transaction 
 * @brief TREX reactors and messaging types
 *
 * This module offers all the utilities to help define and implements
 * new reactors. It also defines goals and observations excahnged
 * between reactor as the abstract definition of a clock. All of these
 * are provided by the library  @c lib/libTREXteransaction.
 *
 * Usually plug-ins are based on this library and can then defines new
 * reactors, observations, goals or clocks.
 *
 * @author Conor McGann @& Frederic Py <fpy@mbari.org>
 * @ingroup core
 */
/** @page license License 
Copyright (c) 2011, MBARI
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    @li Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    @li Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    @li Neither the name of the TREX Project nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY MBARI ''AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL MBARI BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
