// -*- Mode: text -*-
// File: $CVSROOT/IDEA-DEV/Documentation/XIDDL/xiddl.txt
// Date: Wed Nov 16 23:04:49 2005
//  CVS: $Id: xiddl.txt,v 1.12 2006/01/24 06:29:29 plaunt Exp $

/*!

\page xiddl XIDDL User's Guide

<hr>

\section xiddl_modeling Modeling in XIDDL

\subsection xiddl_overview An Overview of XIDDL

XIDDL is an acronym for XML Idea Domain Definition Language, which is
an XML encoding of the Idea Domain Definition Language, a "generic"
modeling language for simultaneous constraint based planning and
execution.

This User's Guide is intended to provide you with an overview of \ref
xiddl_modeling and the \ref xiddl_support.

This guide does not cover the following important topics:

\li building and configuring an agent executable (required)
\li building the Comm Relay layer (optional)
\li building and configuring a token based simulator (optional)
\li running an agent (including timing services (required), any
    required subsystems and simulators, etc.)
\li testing the system (optional)

Modeling in XIDDL depends on the modeler having some familiarity with
the following subjects:

\li the domain to be modeled
\li constraint based modeling (as opposed to imperative programming)
\li xml editing and encoding tools
\li using the \ref xiddl_support

Of these, the first is by far the most important.  If you don't know
your domain, you end up encoding constraints that, not being part of a
well understood system, probably don't make much sense.  However, once
the domain is will in mind, the modeling and XIDDL support tools start
to make sense and are not difficult to use.

A complete model for an Idea Agent will require more than just an
XIDDL model.  In addition, a Europa based Agent requires an initial
state (still true as of 03/02/05) and heuristics for each of the
(Europa based) planners.  The XIDDL model includes all of the other
necessary information, including both the model itself, and the agent
topology declaration.

<hr>

\section xiddl_language The XIDDL Language

XIDDL is an XML encoding of the Idea Domain Description Language
(IDDL).  IDDL was in turn based on DDL, the HSTS and Europa Domain
Description Language.  For an overview of modeling in DDL (which will
be \e very helpful here), see the Europa 1 User's Guide.

The most complete and accurate definition of XIDDL can currently be
found in the <a href="../../XIDDL/xiddl.xsd">XIDDL schema</a>.

\subsection xiddl_doc_strings XIDDL Internal Model Documentation

In order to support internal model documentation about many of the
model components, XIDDL supports a <tt><doc/></tt> tag in many places
throughout the XIDDL <a href=../../XIDDL/xiddl.xsd>schema</a>.

The <tt><doc/></tt> is always the first (optional) tag in the tag
which it documents:

\verbatim
<define_label_set>
  <doc>
    In this model, all closed loop external entities return either
    "OK" or "Failed".  "OK" indicates success, "Failed" indicates
    failure.
  </doc>
  <name>ReturnStatus</name>
  <value>OK</value>
  <value>Failed</value>
</define_label_set>
\endverbatim

The tags which support the <tt><doc/></tt> tag are the following:

\li <tt><define_duration_constant/></tt>
\li <tt><define_object_class/></tt>
\li <tt><define_label_set/></tt>
\li <tt><define_procedure/></tt>
\li <tt><call_args/></tt>
\li <tt><internal_modes/></tt>
\li <tt><return_args/></tt>
\li <tt><return_status/></tt>
\li <tt><define_member_values/></tt>
\li <tt><define_compatibility/></tt>
\li <tt><master/></tt>
\li <tt><guard/></tt>
\li <tt><duration_bounds/></tt>
\li <tt><function/></tt>
\li <tt><subgoals/></tt>
\li <tt><or/></tt>
\li <tt><case/></tt>
\li <tt><constraint/></tt>
\li all of the \ref temporal_constraints
\li <tt><define_agent/></tt>
\li <tt><subsystem/></tt>
\li <tt><channel/></tt>
\li <tt><process/></tt>

\subsection xiddl_constants XIDDL Constants

XIDDL supports the following constants.

\li numeric constants
\li duration constants

Constants are intended to stand in for "magic numbers" sprinkled
throughout the model.  Use constants.  Don't not use constants.  There
is some checking for magic numbers, and where they are found, they
will be reported as errors when you run the semantic tests.  It is
possible to bypass the tests, but doing so will cause lots of problems
in the long run.

\subsubsection numeric_constants Numeric Constants

Numeric constants need units perhaps...  Numeric constants are
intended to be used in place of "magic numbers" in the code which
represent quantities other than durations.

Example:

\verbatim
  <define_numeric_constraint>
    <name>*max_thrust*</name>
    <value>40</value>
  </define_numeric_constraint>
\endverbatim

\subsubsection duration_constants Duration Constants

Duration constants are rounded up to the nearest latency boundary
during translation to Europa/DDL.  In addition, they also support an
optional <tt><unit/></tt> tag.  The currently supported time units are
documented in the \ref latency_time_units section.  The default value
is <tt>seconds</tt>.

\verbatim
  <define_duration_constant>
    <name>*thrust_time*</name>
    <unit>milli_seconds</unit>
    <value>400</value>
  </define_duration_constant>
\endverbatim

All duration constants are "rounded" up to the next multiple of
latency (with respect to the time unit of latency).  For example,
using the default <tt>seconds</tt> time unit and a latency of 3, a
duration constant of 400 seconds would be rounded up to 402.

As an example of the use of both explicit and default time units,
consider the following (illustrative rather than useful) definitions:

\verbatim
    <define_agent>
      [...]
      <agent_latency>30</agent_latency>
      <time_unit>deci_seconds</time_unit>
    </define_agent>

    <define_duration_constant>
      <name>*epsilon*</name>
      <value>1</value>
    </define_duration_constant>

    <define_duration_constant>
      <name>*max_planning_duration*</name>
      <value>3600</value>
    </define_duration_constant>

    <define_duration_constant>
      <name>*min_get_path_duration*</name>
      <value>1</value>
    </define_duration_constant>

    <define_duration_constant>
      <name>*max_get_path_duration*</name>
      <value>10</value>
    </define_duration_constant>

    <define_duration_constant>
      <name>*four_seconds*</name>
      <unit>centi_seconds</unit>
      <value>400</value>
    </define_duration_constant>
\endverbatim

Latency is set here to 30 deci_seconds, i.e., 3 seconds,
<tt>*epsilon*</tt> to 1 second (using the default time unit of
seconds), <tt>*max_planning_duration*</tt> to 3600 seconds,
<tt>*min_get_path_duration*</tt> to 1 second,
<tt>*max_get_path_duration*</tt>, to 10 seconds, and
<tt>*four_seconds*</tt> is defined as 400 centi_seconds (4 seconds).
Given these inputs, the following DDL output is produced:

\verbatim
  ;;; Duration Constants (latency of 30 in deci_seconds)

  ;; duration of 1 (in seconds) scaled to latency of 30 (in deci_seconds)
  (Define_Constant *epsilon* 30)
  ;; duration of 3600 (in seconds) scaled to latency of 30 (in deci_seconds)
  (Define_Constant *max_planning_duration* 36000)
  ;; duration of 1 (in seconds) scaled to latency of 30 (in deci_seconds)
  (Define_Constant *min_get_path_duration* 30)
  ;; duration of 10 (in seconds) scaled to latency of 30 (in deci_seconds)
  (Define_Constant *max_get_path_duration* 120)
  ;; duration of 400 (in centi_seconds) scaled to latency of 30 (in deci_seconds)
  (Define_Constant *four_seconds* 60)
\endverbatim

Take a moment to read and understand these, and to convince yourself
that they are indeed correct.  They are a bit anti-intuitive,
particularly since this example is meant to be illustrative.

An alternative translation scheme might be instead to have the agent
latency automatically set to the smallest time unit used in the model,
and all other time scaled to that unit.  Given that the IDEA-DEV
infrastructure always prints times uniformly (regardless of the unit
used to define them), the output would still be readable and would
make sense with respect to the model.

Do I need to point out that using these facilities requires care and
thought in relation not only to the agent latency and various
definitions duration constants, but in particular, to the values used
in the Europa1 style initial state files.  Be absolutely sure to put
those in terms of the agent latency time units!

It is also dangerous to use a definition of <tt>*epsilon*</tt> which
is not identical to latency (in terms both of magnitude and units) if
there are any transitive relationships which might produce unexpected
results as the result of propagation.  For example, suppose you set
latency to "2" <tt>deci_seconds</tt>, but leave <tt>*epsilon*</tt> as
"1" and allow it to use the default unit of <tt>seconds</tt>.  Now, if
there is some process, such as deliberative planning, which lasts a
minimum of <tt>*epsilon*</tt>, you have created a situation in which
it is possible for deliberative planning to take less time than your
model says it will.  Believe me, this is not what you want to be
doing.  Think very carefully about what your model says.

\subsection objects_and_types XIDDL Types and Objects

\subsubsection xiddl_objects XIDDL Objects

Objects are declared with <tt><define_object_class/></tt>.  An
consists of name (i.e., class name), an optional "dynamic" flag (on
the "type" attribute), and zero or more attributes (<attr> elements).

I'm leaving this whole "object" mechanism somewhat undefined since I
don't really know where we're heading with respect to PLASMA, in
particular static object data, dynamic objects, and so on.

\verbatim
  <define_object_class>
    <name>Class_Name</name>
    <attr>Timeline_Name</attr>
  </define_object_class>
\endverbatim

\subsubsection xiddl_types XIDDL Types

XIDDL supports the following types:

\li Objects
\li Boolean
\li Real
\li Integer
\li Label Sets (similar to enumerations, e.g., OK)
\li Strings (strings are dynamic label sets which require "double
    quotes", e.g. "OK")

Boolean, Real, Integer and String are built in, and need not be
declared, but user define Objects and Label Sets must be.  Note that
in Europa1 (and probably Europa2) the "built-in" String type is
automatically translated into a dynamic label sets with a single
value, "none".  This single "none" is included to make the Europa
parsers happy.

Label sets can be used for both "enumerations" and "strings", however,
the "string" usage is now deprecated (05/11/05).  The build-in String
type is the better way to use strings.  However, both are declared
using the <tt><define_label_set/></tt> tag.  A label set consists of a
"type name" in the <tt><name/></tt> tag and one or more "values" in
<tt><value/></tt> tags.  Non-string labels are, like enumerations,
limited in the characters that can be included and may well be further
limited by back-end in which they will be used (e.g., something like
"<tt>[a-zA-Z0-9_]+</tt>").

\verbatim
  <define_label_set>
    <name>Label_Name</name>
    <value>Value1</value>
    <value>Value2</value>
  </define_label_set>
\endverbatim

More complex labels can be represented as double quoted "stings" in
label sets.  Note the required use of "double quotes" in the following
example.

\verbatim
  <define_label_set>
    <name>CameraNames</name>
    <value>"rsr1.xml"</value>
  </define_label_set>
\endverbatim

\subsection xiddl_procedures XIDDL Procedures

Procedures are also often called "predicates" or "tokens",

Unfortunately, with the current Europa back-ends, all token names must
be unique (i.e., they can not be shared on similar timelines).

Procedures have zero or more parameters.  Each parameters consists of
one of four types:

\li <tt><call_args/></tt>
\li <tt><internal_modes/></tt>
\li <tt><return_args/></tt>
\li <tt><return_status/></tt>

The semantics of all but <tt><internal_modes/></tt> are inverted
depending on whether they are used on an "executable" timeline or a
"goal" timeline.  An executable timeline is one which an agent uses to
represent a subsystem that it can control by sending commands out to
it, and from which it may receive some number of return values and a
status.  A goal timeline is a timeline which an agent uses to
represent a "super-system" which exerts control over the agent itself.
That is, the agent with the goal timeline is a "subsystem" being
controlled by some other external entity.

In the following discussion, the point of view taken is the former
(the semantics of executable timelines), but keep in mind that the
semantics are inverted if the these parameter types are used on goal
timelines.

\subsubsection call_args Call Args

Call args are parameters which must be sent out to controlled
subsystems.  When the procedure starts, these arguments will be passed
to the Agent Relay, which will pass them to the Comm Relay, which will
in turn send the out of the agent to the system specified in the Agent
Declared (see \ref xiddl_agents).

<tt><call_args/></tt> consist of one or more <tt><arg/></tt> elements,
each of which have one <tt><type/></tt> element which specifies the
type of the arg, zero or one <tt><range/></tt> elements which, in the
case of Integer and Real types, constrains the domain over which the
numbers can range, and one <tt><name/></tt> elements which names the
parameter.

More than one group of call args may be declared in a procedure,
though the most elegant style would group them all together.

Example:

A <tt>set_mode</tt> procedure which sends one of four modes and a flag which
allows (or forbids) retries:

\verbatim
  <define_procedure>
    <name>set_mode</name>
    <call_args>
      <arg>
        <type>Integer</type>
        <range> <lb>0</lb> <ub>3</ub> </range>
        <name>mode</name>
      </arg>
      <arg>
        <type>Boolean</type>
        <name>allow_retries</name>
      </arg>
    </call_args>
  </define_procedure>
\endverbatim

\subsubsection internal_modes Internal Modes

Internal modes are parameters which are sent neither to other systems
nor received from other systems.  <tt><internal_modes/></tt> consist
of one or more <tt><mode/></tt> elements, each of which consists of a
<tt><type/></tt>, an optional <tt><range/></tt>, and <tt><name/></tt>.

Example:

A <tt>current_mode</tt> procedure which uses a label set for internal
reasoning:

\verbatim
  <define_label_set>
    <name>Agent_Mode</name>
    <value>Standby</value>
    <value>Nominal</value>
  </define_label_set>

  <define_procedure>
    <name>current_mode</name>
    <internal_modes>
      <mode>
        <type>Agent_Mode</type>
        <name>mode</name>
      </mode>
    </internal_modes>
  </define_procedure>
\endverbatim

\subsubsection return_args Return Args

Return args are intermediate (i.e., not the final return status)
values returned from external subsystems via the Agent Relay.

<tt><return_args/></tt> consist of one or more <tt><arg/></tt>
elements, each of which has a <tt><type/></tt>, and optional
<tt><range/></tt> constraint, a required <tt><name/></tt>, and a
required <tt><flag/></tt>.  The <tt><flag/></tt> arg may (or may not)
be predicted (set) by planners, but it will be set by PSL if and when
the return value is actually received.

Example:

In this example, the <tt>FSC_IPS_MISSION_PRESSURIZE</tt> token can
receive an intermediate <tt>Interim_Pressure_Value</tt> while it is
executing.  Note that in this particular case, this would be an open
loop token, since there is no explicit <tt><return_status/></tt> arg.
The only reason for this is that <tt><return_status/></tt> will be in
the following section.

\verbatim
  <define_label_set>
    <name>Interim_Pressure_Value</name>
    <value>XFS_INIT_STATE</value>
    <value>PRES1_FAILED</value>
  </define_label_set>

  <define_procedure>
    <name>FSC_IPS_MISSION_PRESSURIZE</name>
    <return_args>
      <arg>
        <type>Interim_Pressure_Value</type>
        <name>pres1Value</name>
        <flag>pres1ValueFlag</flag>
      </arg>
    </return_args>
  </define_procedure>
\endverbatim

\subsubsection return_status Return Status

There is, by definition, only one <tt><return_status/></tt> for a procedure.
The return status is the mechanism Idea uses for doing closed loop
execution.  

A <tt><return_status/></tt> consists of a required <tt><type/></tt>,
and optional <tt><range/></tt>, a required <tt><name/></tt> and a
required <tt><flag/></tt>.  The planner (or planners) in an agent are
free to predict if (<tt><flag/></tt>), what (<tt><type/></tt>) and
when (via token duration) the return status will be received, however,
the final disposition of these will ultimately be determined by
whether, what and when they actually are received (which is enforced
by PSL).

\verbatim
  <define_label_set>
    <name>ReturnStatus</name>
    <value>OK</value>
    <value>Failed</value>
  </define_label_set>

  <define_procedure>
    <name>MICAS_Turning_Off<name>
    <return_status>
      <type>ReturnStatus</type>
      <name>status</name>
      <flag>statusFlag</flag>
    </return_status>
  </define_procedure>
\endverbatim

\subsection xiddl_compats XIDDL Compatibilities

Compatibilities are the heart of the XIDDL modeling language.  Most,
though not all constraints, are specified in the compatibility
declarations.  Constraints can be specified:

\li as temporal constraints between tokens (\ref compat_subgoals)
\li as guards on token instantiation (\ref compat_guards)
\li as temporal constraints on tokens (\ref duration_bounds)
\li as relations between token parameters (\ref parameter_functions)
\li as guards on subgoal instantiation (\ref conditional_subgoals)

\subsubsection compat_master Compatibility Masters

A compatibility master is a pattern which can be matched by a token
instantiated in the plan database.  If the master is matched, the \e
all of the constraints and subgoals specified in the compatibility in
question \e must be satisfied.  If any of the constraints or subgoals
can not be satisfied, the master must be retracted from the plan
database.

In its simplest form, a master looks like this:

\verbatim
  <define_compatibility>
    <master>
      <class>Agent_Class</class>
      <attr>Agent_Mode</attr>
      <pred>Standby_Mode</name>
    </master>
    [one or more constraints or subgoals]
  </define_compatibility>
\endverbatim

A compatibility may not be empty.  Every compatibility must specify at
least one of the above types of constraint or subgoal.

\subsubsection compat_guards Compatibility Guards

A compatibility guard allows the modeler greater control over the
"signature" of the master to be matched in the plan database.  The
signature of a <tt><master/></tt> can only match tokens if the plan
database if \e all of the guards are satisfied.

In the above <tt><master/></tt> example, since there are no guards, \e
all <tt>Standby_Mode</tt> tokens are matched, regardless of the
bindings of any of the parameters of that token.  However, if more
than one disjunctive decomposition is needed for such a token, one way
to control which constraints and subgoals (decomposition) are tried by
the planner is to refine the pattern matching with guards.  For
example, consider:

\verbatim
  <define_compatibility>
    <master>
      <class>Agent_Class</class>
      <attr>Agent_Mode</attr>
      <pred>Standby_Mode</name>
      <guard name="eq">
        <arg>successor</arg>
        <value>Nominal_Mode</value>
      </guard>
    </master>
    [one or more constraints or subgoals]
  </define_compatibility>
\endverbatim

Here, the intent is that the "one or more constraints or subgoals"
will only be tried if the value of the "successor" parameter is
specified as "Nominal_Mode".

\subsubsection duration_bounds Duration Bounds

Every compatibility may have a duration bounds.  A duration bounds
limits how long the a token matching the master of the compatibility
may last.  The upper and lower bounds of a duration bound may only be
specified with built-in or declared constants (due to the limitations
of the currently supported back-ends).  The built-in constants are
_plus_infinity_ and _minus_infinity_.

\verbatim
  <define_duration_constant>
    <name>*epsilon*</name>
    <value>1</value>
  </define_duration_constant>

  <define_compatibility>
    <master>
      <class>Agent_Class</class>
      <attr>Agent_Mode</attr>
      <pred>Standby_Mode</name>
    </master>
    <duration_bounds>
      <range> <lb>*epsilon*</lb> <ub>_plus_infinity_</ub> </range>
    </duration_bounds>
  </define_compatibility>
\endverbatim

Note that, since this has explicit constraints on the duration of the
token, this is a complete compatibility (i.e., it does have one or
more constraints or subgoals).

Duration bounds, like all constraints and subgoals, can be guarded by
\ref compat_guards.

\subsubsection parameter_functions Parameter Functions

Parameter functions allow the modeler to use arbitrary relations among
the parameters of a token, including the following built-it
parameters:

\li <tt>?_object_</tt>
\li <tt>?_start_time_</tt>
\li <tt>?_end_time_</tt>
\li <tt>?_duration_</tt>

There are many built in parameter functions, e.g., "eq", "addeq",
"neq", and so on.  For Europa1, see NewPlan/ConstraintNetwork for
forty or so examples.

This section only covers how to \e use such constraints, not how to
write them.

To use such a constraint, the constraint must already be compiled and
registered in the agent executable.  Once this is done, it is only a
matter of encoding the "signature" of the constraint in XIDDL.

Here, for example, is how to constraint an explicit parameter of a
token to be the same as the built-in duration parameter
(<tt>?_duration_</tt>) of that token:

\verbatim
  <define_procedure>
    <name>Standby_Mode</name>
    <internal_mode>
      <type>Integer</type>
      <name>duration</name>
    </internal_mode>
  </define_procedure>

  <define_compatibility>
    <master>
      <class>Agent_Class</class>
      <attr>Agent_Mode</attr>
      <pred>Standby_Mode</name>
    </master>
    <parameter_functions>
      <function>
        <name>eq</name>        <!-- a built in parameter function -->
        <arg>duration</arg>    <!-- an explicit arg of Standby_Mode -->
        <var>?_duration_</var> <!-- the built-in duration variable -->
      </function>
    </parameter_functions>
  </define_compatibility>
\endverbatim

Now, the <tt>duration</tt> parameter of the <tt>Standby_Mode</tt> token will
always track the value of the built-in <tt>?_duration_</tt> variable.

\subsubsection compat_subgoals Compatibility Subgoals

\subsubsection conditional_subgoals Conditional Subgoals

\subsubsection temporal_constraints Temporal Constraints

A Temporal constraint is a relation between two tokens which has zero,
one or two duration bounds which specify temporal distance between the
two tokens in the relation.

The best overview of the temporal relations is the following:

<img src="../Images/temporal-relations.jpg" align=center>

There are three types of temporal relations, those with no distance
bounds, those with zero or one distance bound, and those with zero or
two distance bounds.

Those with no bounds are:

\li <tt>equal</tt>
\li <tt>meets</tt>
\li <tt>met_by</tt>

These three relations are a short hand for some of the other relations
below where the temporal distances are "<tt>[0 0]</tt>".

\li <tt> T1 equal T2 == T1 contains [0 0] [0 0] T2 </tt>
\li <tt> T1 meets T2 == T1 before [0 0] T2 </tt>
\li <tt> T1 met_by T2 == T1 after [0 0] T2 </tt>

The temporal relations with zero or one bounds are the following:

\li <tt>after</tt>
\li <tt>before</tt>
\li <tt>ends</tt>
\li <tt>ends_after</tt>
\li <tt>ends_after_start</tt>
\li <tt>ends_before</tt>
\li <tt>starts</tt>
\li <tt>starts_after</tt>
\li <tt>starts_before</tt>
\li <tt>starts_before_end</tt>
\li <tt>starts_during</tt>

When a temporal distance "<tt>[d D]</tt>" is specified with any of
these, these are interpreted as "the minimum temporal distance
<tt>d</tt>, and the maximum temporal distance <tt>D</tt>".

Where a temporal distance is not given, it defaults to <tt>[0
_plus_infinity_]</tt>, which is the maximum flexibility possible.

\li <tt> T1 after [d D] T2 == T2 before [d D] T1 </tt>
\li <tt> T1 starts_before [d D] T2 == T2 starts_after [d D] T1 </tt>
\li <tt> T1 ends_before [d D] T2 == T2 ends_after [d D] T1 </tt>
\li <tt> T1 starts_before_end [d D] T2 == T2 ends_after_start [d D] T1 </tt>

The remainder of the inverse relations are left as an exercise for the
reader.

The following are the temporal relations with zero or two bounds:

\li <tt>contained_by </tt>
\li <tt>contains</tt>
\li <tt>contains_end</tt>
\li <tt>contains_start</tt>
\li <tt>ends_during</tt>
\li <tt>paralleled_by</tt>
\li <tt>parallels</tt>

For these relations, the model must specify either zero or two
relations.  Though the case of specifying one isn't particularly
ambiguous, it is poor style and is likely to confuse later readers and
maintainers of the model.

These relation have similar inverses, for example

\li <tt> T1 contains [d1 D1] [d2 D2] T2 == T2 contained_by [d1 D1] [d2 D2] T1 </tt>
\li <tt> T1 parallels [d1 D1] [d2 D2] T2 == T2 paralleled_by [d1 D1] [d2 D2] T1 </tt>

\subsubsection codesignation Parameter Codesignation

\subsection xiddl_agents XIDDL Agents

\subsubsection latency_time_units Agent Latency and Time Units

An agent declaration is required to have a <tt><agent_latency/></tt>
tag, and may optionally have <tt><time_unit/></tt> tag.  

Latency is always expressed as an integer, so in order to support
sub-second response times, the optional <tt><time_unit/></tt> tag can
be used to define exactly what is meant by the integer latency.

The value of the <tt><time_unit/></tt> tag defaults to
<tt>seconds</tt>, which it the typical unit used by agents.  However,
there are (currently) five supported time units:

\li <tt>seconds</tt>
\li <tt>deci_seconds</tt>
\li <tt>centi_seconds</tt>
\li <tt>milli_seconds</tt>
\li <tt>micro_seconds</tt>

For example:

\verbatim
  <agents>
    <define_agent>
      <name>Example_Agent</name>
      <agent_latency>1</agent_latency>
      <time_unit>centi_seconds</time_unit>
      [...]
    </define_agent>
  </agents>
\endverbatim

\subsubsection timeline_types Goal Timelines

All timelines are of one of three types:

\li Goal Timelines are those which receive tokens (commands) from
    other agents or software artifacts
\li Executable Timelines are those which send commands (tokens) out to
    other agents or software artifacts
\li Internal Timelines are those which are used solely for the
    planner's internal reasoning

A timeline is declared as a goal timeline by including a
<tt><channel/></tt> with a <tt><type>goal</type></tt> in the master
agent declaration and an executable timeline with
<tt><type>executable</type></tt>.  For example:

\verbatim
  <channel>
    <object>RSR_Channel_1</object>
    <attr>Requests</attr>
    <type>goal</type>
    <relay>BOGUS_BOOMERANG_RELAY</relay>
    <target>Sim</target>
  </channel>
\endverbatim

All other timelines are (implicitly) internal.

<hr>

\section xiddl_initial_state XIDDL Initial State

The initial state specification in XIDDL is similar in content to the
previous Europa (and PLASMA) initial state languages.

The following small but complete initial state which follows is given
in both the old Europa/PLASMA language and in XIDDL.

\verbatim
[0 200]

Object_Timelines MyClass objectName
(
 Timeline1 ([0 0] token1 (True)
            [4 6] token2 () ...)
 Timeline2 ([0 0] token3 () ...
            [8 10] token4 [10 20] () ...)
)
\endverbatim

This example give most of the required idioms needed for initial
states.  

The first timeline, <tt>Timeline1</tt>, has two tokens,
<tt>token1</tt> and <tt>token2</tt> which are joined by a
<tt>meets</tt> relation.  The first token is required to start at time
0, while the second is allowed to start anywhere from time 4 to 6.
Further, the first token has its first (positional) arg bound to
"True".  There is no information give about then the second can end.
The ellipsis ("...") after <tt>token2</tt> indicates that this
timeline is "open" after that token.

The second timeline, <tt>Timeline2</tt>, also has two tokens,
<tt>token3</tt> and <tt>token4</tt>, but these tokens are separated by
a "gap" on the timeline, indicated by the intervening ellipsis.  The
first token (<tt>token3</tt>), starts at time 0, and ends anywhere
from 2 to 4.  The second token starts anywhere from 8 to 10, and is
required to last at least 10 and at most 20 time units.  Note that
there was no way to specify time units, though they were generally
assumed to be "seconds".

Here follows the same initial state, now given in XIDDL as the
<tt><subsystem/></tt> element of the <tt><define_agent/></tt> tag.

\verbatim
<subsystem>
  <class>MyClass</class>
  <name>objectName</name>
  <attr>
    <name>Timeline1</name>
    <pred>
      <name>token1</name>
      <start> <lb>0</lb> <ub>0</ub> </start>
      <constraint> <arg>arg1</arg> <value>True</value> </constraint>
    </pred>
    <pred>
      <name>token2</name>
      <start> <lb>4</lb> <ub>6</ub> </start>
    </pred>
  </attr>
  <attr>
    <name>Timeline2</name>
    <pred>
      <name>token2</name>
      <start> <lb>0</lb> <ub>0</ub> </start>
    </pred>
    <gap/>
    <pred>
      <name>token3</name>
      <start> <lb>8</lb> <ub>10</ub> </start>
    </pred>
  </attr>
</subsystem>
\endverbatim

Note that the <tt><gap/></tt> is still explicitly represented.

Although this particular initial state doesn't do so, the time units,
which by default are <tt>seconds</tt>, can be conveniently expressed
here in <tt><start/></tt> (or <tt><end/></tt> or <tt><duration/></tt>)
tag thus:

\verbatim
  <start> <unit>deci_seconds</unit> <lb>5</lb> <ub>10</ub> </start>
\endverbatim

See \ref duration_constants for details on how these durations are
handled with respect to \ref latency_time_units.

\subsection initial_state_tags XIDDL Initial State Tags

\li A <tt><subsystem/></tt> consists of a <tt><class/></tt>, a <tt><name/></tt>,
    and one or more <tt><attr/></tt> tags.
\li An <tt><attr/></tt> consists of a <tt><name/></tt> at least one
    <tt><pred/></tt>, and zero or more <tt><gap/></tt> tags.
\li A <tt><pred/></tt> consists of a <tt><name/></tt>, a
    <tt><start/></tt>, and optional <tt><duration/></tt>, and optional
    <tt><end/></tt>, and zero or more <tt><constraint/></tt> tags.
\li <tt><start/></tt>, <tt><duration/></tt> and <tt><end/></tt> tags
    consists of an optional <tt><units/></tt> (see \ref
    latency_time_units for legal values) tag, a <tt><lb/></tt> tag and
    an <tt><ub/></tt> tag (\ref duration_constants).
\li a <tt><constraint/></tt> consists of one <tt><arg/></tt> tag and
    one <tt><value/></tt> tag.
\li an <tt><arg/></tt> consists of the name of a defined parameter of
    the containing <tt><pred/></tt>, and a <tt><value/></tt> tag
    consists of a well defined member of one of the \ref xiddl_types.

\section xiddl_heuristics XIDDL Heuristics

\section xiddl_plasma XIDDL and PLASMA

\subsection plasma_caveats XIDDL to PLASMA Caveats

\li Numeric constants are strongly typed.  The translator guesses,
    based on whether your "number" has a "." in it, whether it is an
    int or a float.  Constants should/will required a type (soon).
\li All duration constants must be integers.
\li constants must be translated to magic numbers in interval domains
\li all identifiers have to be translated to [a-zA-Z_0-9], i.e., "*"
    to "$", "-" to "_", and so on
\li String type translates to __DDL__String (class)
\li translate ?_object_ to object.__DDL__object
\li translate ?_duration_ to duration
\li translate duration to __DDL_duration
\li translate ?_start_time_ to start
\li translate ?_end_time_ to end
\li translate _plus_infinity_ to +inf
\li translate _minus_infinity_ to -inf
\li explicitly map all 16 temporal relations which can have a temporal
    distance argument on to the positionally dependent NDDL
    temporaldistance "relations"
\li be careful to translate all <value/> fields correctly (via xlate-nddl-value)

\subsection plasma_to_do Things Remaining To Be Done

\li add "initial_state_horizon" (and possibly other planner config
    stuff) to the schema
\li add initial state to schema (done, but not yet checked in)
\li verify that nothing more is needed for dynamic label sets
\li verify that the '.object.specify()' idiom is allowed in all
    initial tokens
\li add sematic checks for xiddl->nddl
\li add semantic checks for (nddl) initial state
\li design heuristics language and translation
\li add heuristics to schema
\li add heuristics translation to xiddl2nddl.xsl
\li add semantic checks for (nddl) heuristics

<hr>

\section xiddl_idioms Common XIDDL Idioms

I haven't used Europa2 (PLASMA) yet, so I don't really know what
idioms there may be there to document at this point.

\subsection goal_timeline_idiom Goal Timeline Idioms

The semantics of all parameter types (<tt><call_args/><tt>,
<tt><internal_modes/></tt>, <tt><return_args/></tt> and
<tt><return_status/></tt>) are inverted on goal timelines.

I don't have an example of how to do the heuristics (and other bits
and pieces) for this just now, but keep it in mind.

\subsubsection Connecting Goal Timeline Tokens

For reasons which at this particular moment escape me, it can be tricky
to get tokens on goal timelines to connect.  For the present, these
are as much notes to myself as anything, so please forgive their
brevity.

Goal <tt><met_by/></tt> GoalIdle on a goal timeline (\ref
timeline_types) needs the following heuristics:

\verbatim
  [Goal() After GoalIdle()] (full)
\endverbatim

You might also have to use a value ordering to minimize search.

\subsection open_loop_idiom Open Loop Idioms

\subsection closed_loop_idiom Closed Loop Idioms

\subsection telemetry_idiom Telemetry Idioms

\subsection guarded_functions Guarded Parameter Functions

Use multiple masters, putting the guarded parameter function in a
master with the appropriate (implicit) guard(s).

\verbatim
  <define_procedure>
    <name>Whatever</name>
    <internal_modes>
      <mode>
        <type>Boolean</type>
        <name>FireGuardedFunction</name>
      </mode>
    </internal_modes>
  </define_procedure>

  <define_compatibility>
    <class></class>
    <attr></attr>
    <pred>Whatever</name>
    <guard type="eq">
      <arg>FireGuardedFunction</arg>
      <value>True</value>
    </guard>
    <parameter_functions>
      <function>
        <name>GuardedFunction</name>
        <arg>FireGuardedFunction</arg>
      </function>
    </parameter_functions>
  </define_compatibility>
\endverbatim

\subsection successor_selectors Successor Selectors

\subsection optimization Europa1 Optimizations

\subsubsection fewer_decisions Make Fewer Decisions

The Europa1 planner can only make decisions at a certain rate, which
depends primarily on the size of the token network.  My experience is
that it can make about 30 decisions a second with some reliability.
Starting with an empty database, I've seen as much as an average of 55
decisions per second for up to around 10 seconds.  If you have a
problem which the planner is having trouble solving in the given time,
the only way to "optimize" it (that I know of) is to reduce the number
of decisions the planner is making.  Some ways to do this are listed
below.

Note that these "optimizations" are all hacks, kludges, or work
arounds.  Use them when you must, but not as a steady diet.

\li comment out symmetrical temporal constraints (e.g., mets/met_by,
    contained/contained_by)
\li comment out symmetrical parameter co-designations
\li use No_Branch as much as makes sense
\li don't introduce unnecessary parameters or tokens
\li use a deliberative planner to do search (instead of the reactive
    planner) when it makes sense

<hr>

\section xiddl_support XIDDL Support Tools

To get from a model in XIDDL to an agent, there is a set of support
tools that live in the <a href="../../XIDDL">IDEA-DEV/XIDDL</a>
directory.

Currently, this directory contains a
<a href="../../XIDDL/README>README</a> file, the
<a href="../../XIDDL/xiddl.xsd">XIDDL schema</a>, the
<a href="../../XIDDL/xiddl-tests.xsl">XIDDL semantic tests</a>, shell
scripts <a href="../../XIDDL/build-xiddl>to build the pre-processed
xiddl model file</a> and <a href="../../XIDDL/run-xiddl2ddl>to run the
semantic tests and target translations</a>,
<a href="../../XIDDL/europa-tests.xsl>Europa specific tests</a>, and
several files related to translating to xnddl.

The steps to get from an XIDDL model are:

\li check the well-formedness of the model
\li validate the model
\li run the XIDDL "semantic" tests
\li run any application/back-end tests (e.g., Europa)
\li generate the output files required by the back-end (e.g. ddl, model
    and relay info files)

\subsection xiddl_scripts The XIDDL Scripts

\subsubsection shell_scripts Shell Scripts

Currently, these script are, by convention, copied in to XIDDL/bin for
use by applications, since this directory will be needed in any case
for various other binaries.

\verbatim

  build-xiddl <agent-xiddl> <output-xiddl> <error-report> [debug]

  run-xiddl2ddl <output-xiddl> [debug]

\endverbatim

\subsubsection XSLT Scripts

\subsection xiddl_schema The XIDDL Schema

The XIDDL schema lives in
<a href="../../XIDDL/xiddl.xsd>IDEA-DEV/XIDDL/xiddl.xsd</a>.  It
includes a fair amount of useful documentation, so do feel free to
consult it.

\subsection xiddl_tests XIDDL "Semantic" Tests

The current XIDDL generic semantic tests live in
<a href="../../XIDDL/xiddl-tests.xsl">IDEA-DEV/XIDDL/xiddl-tests.xsl</a>.
There are brief descriptions of all of the implemented test therein
(and a few old tests that haven't been removed yet).

\subsection backend_tests Backend Specific Tests

\subsection xiddl_translation XIDDL Translation

*/

// EOF
