Textual TAEMS
-------------

Rules:
  * Each kind of object has its own unique definer name (e.g., spec_agent, 
    spec_task, spec_method, . . .)

  * The entire definition of an object consists of attribute/value pairs.

  * Each attribute/value pair appears on its own line with no internal newlines.  
  * Objects can appear in any order.  References to objects defined
    later are allowed.  **NOTE, this does imply attributes are orderless.**

  * Any line whose first nonblank character is a ";" is a comment line.  
    Everything appearing on that line is ignored.

  * Datatypes of all values are in parentheses after the attribute
    name.  Symbol means an arbitrary sequence of alphanumeric characters
    with no internal spaces.

  * Semantically, many of the attributes require symbols from a
    particular set.  Where the set is static, that list is given after a
    pair of dashes.  Where the set is dynamic (e.g., the set of tasks
    defined in the same file), the kind of attribute is indicated (e.g.,
    [task symbol]).

   * Generic attributes may be associated with any top-level object (agents, 
     tasks, methods, nles, resources, etc.).  Attribute specifications are
     OPTIONAL and they MUST appear immediately before the label specification.  
     See the task group and agent specification
     for examples.  The general format is:
         (spec_attribute (name value)(name value))

     Attributes can also appear independently from the objects, i.e.,
     at the top-level in ttaems, however, there can only be one top level
     attribute specification per file currently on the java implementation
     side.


Details
-------

Agent
  - attribute (optional) -- see bulleted paragraph above.
  - label [symbol]

example,
(spec_agent
    (spec_attributes )
    (label a1)
)

with generic, situation specific, attributes:
(spec_agent
    (spec_attributes 
         (agent_capabilities can_move)
          (agent_size 3-feet-tall))
    (label a1)
)


Task Group
  - attribute (optional) -- see bulleted paragraph above.
  - label [symbol]
  - agent [agent symbol]
  - subtasks [list of 0 or more task or method symbols]
  - qaf [symbol -- q_min, q_max, q_sum, q_sigmoid, q_exactly_one]
  - arrival time [integer]
  - earliest start time [integer]
  - deadline [integer]

example,
(spec_task_group
   (label tg1)
   (agent a1)
   (subtasks task2 task3 task4 task5)
   (qaf q_min)
   (arrival_time 0)
   (earliest_start_time  0)
   (deadline  34)
)


(spec_task_group
   (spec_attributes (task_group_is_backuop true))
   (label tg1)
   (agent a1)
   (subtasks task2 task3 task4 task5)
   (qaf q_min)
   (arrival_time 0)
   (earliest_start_time  0)
   (deadline  34)
)


Task
  - attribute (optional) -- see bulleted paragraph above.
  - label [symbol]
  - agent [agent symbol]
  - supertasks [list of 1 or more task or task group symbol]
  - subtasks [list of 0 or more task or method symbol]
  - qaf [symbol -- q_min, q_max, q_sum, q_sigmoid, q_exactly_one]
  - arrival time [integer]
  - earliest start time [integer]
  - deadline [integer]

example,
(spec_task
   ;; This task is really special.
   (label task2)
   (agent a1)
   (supertasks task1)
   (subtasks task2 task3 task4 task5)
   (qaf q_min)
   (arrival_time 0)
   (earliest_start_time  0)
   (deadline  34)
)

Method
  - attribute (optional) -- see bulleted paragraph above.
  - label [symbol]
  - agent [agent symbol]
  - supertasks [list of 1 or more task or task group symbol]
  - outcomes [list of 0 or more complete outcome specs]
  - arrival time [integer]
  - earliest start time [integer]
  - deadline [integer]
  - start time [integer]
  - finish time [integer]
  - accrued time [integer]
  - method is non local - no value following.  Existence of this tag indicates method is remote only.

example,
(spec_method
   (label method12)
   (agent a1)
   ;; This comment is in a different place.
   (supertasks task4)
   ;; note that outcomes are now nested inside of their method,
   ;; but they still have unique id, to allow them to be used as
   ;; the from side of nonlocal_effects
   (outcomes
	(o1
	   (density 0.6)
	   (quality_distribution 10 0.7 12 0.3)
	   (duration_distribution 3 0.5 4 0.5)
	   (cost_distribution 0 0.8 1 0.2)
	)
	(o2
	   (density 0.4)
	   (quality_distribution 5 0.7 7 0.3)
	   (duration_distribution 8 0.5 10 0.5)
	   (cost_distribution 0 0.8 1 0.2)
	)
   )
   ;; Do we want to have agreed upon defaults for some of these?
   (arrival_time 0)
   (earliest_start_time 0)
   (deadline 34)
   ;; Not used by the Lisp scheduler.
   (percentage_of_cpu_used 100)
   ;; These are for methods that have started (and perhaps finished)
   ;; executing.  If finish_time has a value, then the method has
   ;; completed execution, outcome_distribution will have information
   ;; about the resulting outcome, and that outcome (or set of
   ;; outcomes if we are uncertain) will have information about the
   ;; resulting quality.
   (start_time 5)
   (finish_time)
   (accrued_time 2)
   (method_is_non_local) ; if this parameter is absent, the method is considered local
)

enables
  - label [symbol]
  - agent [agent symbol]
  - from [task or method symbol]
  ;; only use this if the enables actually comes from the outcome of
  ;; the from_task_or_method 
  - from outcome [optional outcome symbol]
  - to [method symbol]
  - delay [distribution]

example,
(spec_enables
   (label enables42)
   (agent a1)
   (from method10)
   (from_outcome m10o3)
   (to method34)
   (delay 0)
)

facilitates
  - attribute (optional) -- see bulleted paragraph above.
  - label [symbol]
  - agent [agent symbol]
  - from [task or method symbol]
  - from outcome [optional outcome symbol]
  - to [method symbol]
  - quality power distribution [list of 0 or more pairs of floats]
  - duration power distribution [list of 0 or more pairs of floats]
  - cost power distribution [list of 0 or more pairs of floats]
  - delay [integer]

example,
(spec_facilitates
   (label fac56)
   (agent a1)
   (from task4)
   (to method12)
   (quality_power 0.7 1.0)
   (duration_power 0.7 1.0)
   (cost_power 0.5 0.5 0.7 0.5)
   (delay 3)
)


Tom and Brett's Temporary Commitment:
  - attribute (optional) -- see bulleted paragraph above.
  - label [symbol]
  - type [symbol -- do, dont, deadline, earliest_start_time, est_and_dl_and_do ]
  - agent [agent symbol]
  - task [list of one or more task or method symbols], if more than
                        one symbol is given, the commitment is satisfied
                        if one or more of the methods is performed in such
                        a way as to satisfy the commitment.
  - importance [int], negative value indicates what-if question, 0 = normal, 
                        1 indicates that the commitment cannot be broken.
  - minimum quality [float], value should be *greater than* zero
  - earliest start time [integer], negative value indicates no start time
  - deadline [integer], negative value indicates no deadline
  - dont_interval_start [integer], negative value indicates no interval
  - dont_interval_end [integer], negative value indicates no interval
  - time_satisfied [integer], negative value indicates not yet satisfied

example,
(spec_commitment
   (label com12)
   ;; one of do, deadline, earliest_start_time, dont, or est_and_dl_and_do
   (type deadline)
   (agent a1)
   (task t23 t24) ; two tasks may satisfy the commitment
   (importance 10)
   (minimum_quality .01)
   (earliest_start_time -1)
   (deadline 14)
   (dont_interval_start -1)
   (dont_interval_end -1)
   (time_satisfied -1)
)



Alan's Commitment
  - label [symbol]
  - type [symbol -- do, deadline, earliest_start_time]
  - agent [agent symbol]
  - task [task or method symbol]
  - negotiability [float]
  - utility [float]
  - importance [float]
  - minimum quality [float]
  - earliest start time [integer]
  - deadline [integer]
  - satisfied [symbol -- true, false, unknown]

example,
(spec_commitment
   (label com12)
   ;; one of do, deadline or earliest_start_time
   (type deadline)
   (agent a1)
   (task t23)
   (negotiability 7)
   (utility 34)
   (importance 10)
   ;; together these make this a deadline commitment
   (minimum_quality 22)
   (earliest_start_time)
   (deadline 14)
   ;; possible values are false, true or unknown.  Indicates whether
   ;; the commitment has already been satisfied or violated.
   (satisfied false)
)

Nonlocal commitment
  - label [symbol]
  - task [task or method symbol]
  - from agent [agent symbol]
  - to agent [agent symbol]
  - quality distribution [list of 0 or more pairs of floats]
  - time distribution [list of 0 or more pairs of floats]

    Note: when determining which agent this data item belongs to
    when building the structures for a given agent, the to-agent
    slot is the determiner.  If you think about it, a nonlocal commitment
    is just a commitment for the commitment provider.. 
 
    Note 2: The local and non-local commitment defs are inconsistent 
    in that both should either include from/to agents or not include
    the from/to information.  In other words, if the nonlocal commitment
    enables the agent to tell who is going to provide the results, 
    the commitment structure should enable the agent to indicate who it
    is providing the data to, i.e., who it has given the commitment to...

example,
(spec_nonlocal_commitment
   (label nlc3)
   (task task3)
   (from_agent a2)
   (to_agent a1)
   (quality_distribution 12 0.5 15 0.5)
   ;; expected arrival time of nlc
   (time_distribution 13 1.0)
)






Resources and Resource NLEs
------------------------------

Non-consumable Resource 
  This means a resource that is depleted
  when it is in use, but, when it is no longer in use, it returns back to
  its original state.  Examples of this would be network bandwidth or
  electricity to one's home (though the electricity is consumed, the amperage
  available returns to normal once you turn off the consuming appliance like
  the hairdryer.)

   - label [symbol]
   - agent [label] *Optional* field specifies the agent that owns the resource.
                    If agent is unspecified, it is assumed that the agent 
                    reading the file owns the resource.  
   - state [float] ;; defines the qty of the resource that is 
                   ;; available initially.
   - depleted_at [float] ;; defines the point at which any limits nles coming
                     ;; from the resource to other tasks come into play.
                     ;; in other words, defines when the resource is
                     ;; considered depleted.
   - optional attribute supported by DTC and the simulator
     (overproduced_at type value)

example,
(spec_non_consumable_resource
    (label electric_amperage)
    (agent electric_plant_agent)
    (state 125.2)
    (depleted_at 0.)
)



Consumable Resource 
  This means a resource that is depleted when it is 
  in use and that the consumed units are not automatically
  restored when the method has completed execution.  Units can be put
  back via the "produces" resource nle below.
   - label [symbol]
   - agent [label] *Optional* field specifies the agent that owns the resource.
                    If agent is unspecified, it is assumed that the agent 
                    reading the file owns the resource.
   - state [float] ;; defines the qty of the resource that is
                   ;; available initially.
   - depleted_at [float] ;; defines the point at which any limits nles coming
                     ;; from the resource to other tasks come into play.
                     ;; in other words, defines when the resource is
                     ;; considered depleted.
   - optional attribute supported by DTC and the simulator
     (overproduced_at type value)

example,
(spec_consumable_resource
    (label hot_water)
    (agent hot_water_heater_agent)
    (state 100.)
    (depleted_at 2.)
)





Uses/consumes resource relationship
   - label [symbol]
   - agent [agent symbol]
   - from task [task symbol]
   - to resource [resource symbol]
   - consumes [distribution]
   - (resource_model [resource_model_type]) where
               resource_model_type is either duration_independent
               or per_time_unit

example,
(spec_uses 
   (label fac56)
   (agent a1)
   (from task4)
   (to electricity)
   (consumes 10.2 1.0)
   (resource_model duration_independent)
)
or
(spec_consumes   ; alternate keyword
   (label fac56)
   (agent a1)
   (from task4)
   (to electricity)
   (consumes 10.2 1.0)
   (resource_model duration_independent)
)







Limits resource relationship
   - label [symbol]
   - agent [agent symbol]
   - from resource [resource symbol]
   - to task [task symbol]
   - quality power [distribution]
   - duration power [distribution]
   - cost power [distribution]
   - (resource_model [resource_model_type]) where
               resource_model_type is either duration_independent
               or per_time_unit

example,
(spec_limits
   (label limits21)
   (agent a1)
   (from electricity)
   (to taska)
   (quality_power 0.7 1.0)
   (duration_power 0.7 1.0)
   (cost_power 0.5 0.5 0.7 0.5)
   ;;
   ;; note, limits are like hinders so these specify negative effects
   ;; on the distributions of the task in question if the resource has
   ;; insufficient widgets to satisfy its needs.  the above specifies
   ;; that quality will be reduced by 70%, duration increased by 70%,
   ;; and cost increased by 60% (on average).
   ;;
   (resource_model per_time_unit)
)





Produces resource relationship
   - label [symbol]
   - agent [agent symbol]
   - from task [task symbol]
   - to resource [resource symbol]
   - produces [distribution]
   - (resource_model [resource_model_type]) where
               resource_model_type is either duration_independent
               or per_time_unit

	The semantics are that if the task producing the good has quality,
    the good is produced.

example,
(spec_produces
   (label prod56)
   (agent a1)
   (from task4)
   (to hot_water)
   (produces 10.2 1.0)
   (resource_model per_time_unit)
)








Textual Schedules
-----------------

Simple Schedule Format (most widely used)

  The file contains entries for each method in the schedule as follows:
  method_id, expected start_time, expected stop_time, expected_quality, 
  expected_cost, expected_duration.  Its default name is output.simple_schedule.
  
  There will be no extra white space or blank lines and the file will
  start with a number denoting the number of methods in the schedule.  If
  said number is 0, then no schedule was produced, otherwise you can expect
  to read the specified number of lines, etc.  The last line contains the
  performance characteristics of the overall schedule (i.e., the expected 
  quality it will produce, its expected cost, and its expected duration).
  
  For example:
  --------------------------------------------------------
  3
  method_a   0     999    9    99    999
  method_b   999   1998   9    99    999
  method_c   1998  2997   9    99    999
  27 297 2997
  --------------------------------------------------------
  For the first row, 3 indicates the number of methods to execute.  The
  second row gives the characteristics for method_a, where 0 = expected start
  time, 999=expected finish time (finish < 10), 9 = expected quality, 99 = expected cost, 
  and 999 = expected duration.  The last row specifies that the schedule is expected to
  produce quality 27, cost 297, and duration 2997.
  
  All "fields" will be separated by white space and the method ids won't contain
  white space.  This should be very simple to parse, e.g., the c route would
  be:
  
      scanf("%s %d %d %d %d %d", name, &start, &stop, etc..)..




Schedule
  - schedule elements [ordered list of 0 or more embedded schedule elements
	method or IDLE
	     start_time_distribution [distribution]
	     finish_time_distribution [distribution]
	     quality_distribution [distribution]
	     duration_distribution [distribution]
	     cost_distribution  [distribution]
  - NOT CURRENTLY EMITTED BY DTC
        - task quality infos [list of 0 or more task/quality pairs]
        - commitment satisfaction/violation 
                      infos [list of 0 or more commitment infos TBD]
  - start time distribution [list of 0 or more pairs of floats]
  - finish time distribution [list of 0 or more pairs of floats]
  - qualtiy distribution [list of 0 or more pairs of floats]
  - duration distribution [list of 0 or more pairs of floats]
  - cost distribution [list of 0 or more pairs of floats]
  - rating [float]

example,
(spec_schedule
        (schedule_elements
            (Method4
                (start_time_distribution  0.000000 1.000000)
                (finish_time_distribution  10.000000 1.000000)
                (quality_distribution  50.000000 1.000000)
                (cost_distribution  8.000000 1.000000)
                (duration_distribution  10.000000 1.000000)
            )
            (MethodB2
                (start_time_distribution  10.000000 1.000000)
                (finish_time_distribution  20.000000 1.000000)
                (quality_distribution  35.000000 1.000000)
                (cost_distribution  6.000000 1.000000)
                (duration_distribution  10.000000 1.000000)
            )
        )
        (start_time_distribution 0.000000 1.0)
        (finish_time_distribution 20.000000 1.000000)
        (quality_distribution  85.000000 1.000000)
        (duration_distribution  20.000000 1.000000)
        (cost_distribution  14.000000 1.000000)
        (rating 1.0)
)



Schedule Setting Bundle
  - label [symbol]
  - quality value [float or symbol -- min, max, mean, median]
  - duration value  [float or symbol -- min, max, mean, median]
  - cost value [float or symbol -- min, max, mean, median]

example,
(spec_schedule_setting_bundle
   (label ssb2)
   ;; possible values are min, max, mean, median or some arbitrary percentile
   (quality_value 0.5)
   (duration_value mean)
   (cost_value max)
)

Evaluation Criteria
  - label [symbol]
  - all values are floats.
  - see example for the fields.

example,
(spec_evaluation_criteria
   (label toto)
   (goodness_quality_slider .60)
   (goodness_cost_slider 0.30)
   (goodness_duration_slider 0.10)
   (threshold_quality_slider 0.33)
   (threshold_cost_slider 0.33)
   (threshold_duration_slider 0.34)
   (quality_threshold 25)
   (cost_limit 5)
   (duration_limit 10)
   (uncertainty_quality_slider 0.2)
   (uncertainty_cost_slider 0.7)
   (uncertainty_duration_slider 0.1)
   (threshold_certainty_quality_slider .1)
   (threshold_certainty_cost_slider    .2)
   (threshold_certainty_duration_slider   .3)
   (quality_certainty_threshold  1)
   (cost_certainty_threshold  2)
   (duration_certainty_threshold  3)
   (meta_goodness_slider 1.0)
   (meta_threshold_slider 0.0)
   (meta_uncertainty_slider 0.0)
   (meta_uncertainty_threshold_slider 0.0)
)


Misc. Scheduler Parameters:
   - label [symbol] (optional)
   - time to schedule for [float] (optional)
   - cost accrued so far [float] (optional)
   - use advanced analyzer [integer]  (optional) 0=false, positive=true; 

The preferred approach for specifying these is as a top-level
attribute in the following format:

(spec_attributes
    (time_to_schedule_for 36.0)
    (cost_accrued  0.0)
    (use_advanced_analysis 1)
)