Notes on options

Author: Jeff Dalton

Updated: Mon Mar  7 14:56:46 2005 by Jeff Dalton

This is a discussion of options and how they can be used in I-Plan
and I-P2, intended for what we might call "technical users".

Options
-------

I-Plan and I-P2 now support multiple options.

An option represents a state of the entire <I-N-C-A> process model.
Such a state is what's saved when you save a plan, and it's
what's (partially) shown in the Issue, Activity, State,
and Annotation tables in a process panel frame.  It doesn't
include the I-Space state, the domain, the test menu, or
various other things that exist in I-X systems.

In the past, the process model was of course in different states at
different times; now a number of different states can exist at the
same time, and you can switch between them.  (Internally, these states
form a tree, but only the leaves are visible as options.)

Each option can also change over time.  For example, you can add an
activity in one option (changing it) and a different activity (or an
issue or something else) in another option.

So you can think of options as like having several separate panels,
except that some things are shared.

If you have used the O-Plan "matrix" interface (as in some of the
demos usable over the Web), you have seen something very similar.
An I-X option is like a column in the matrix.

Options are manipulated via the "Options" menu in a panel's menu bar.
You can:

  * Select which option is the "current option" -- the one that's
    shown in the panel's main display.

  * Create a new option.

  * Split the current option into two initially identical siblings.

  * Copy the current option.

  * Rename the current option.

  * Clear the current option, either removing everything or
    removing everything but the (world-)state.

  * Delete the current option.

  * Copy the current option's world state into all the other
    options ("Sync State").

  * Set which option should receive input from external sources.

  * Turn all the files in a directory of plan files into options.

  * Save all of the panel's options as plan files in a directory.

In addition, you can use the I-Plan Tool to try to complete the
current option's plan and to create new options by replanning.

The name of the current option is shown just below the menu bar.

By default, the initial current option is called "Option-1".

Command-line arguments / props file entries:

  show-options=true or false

     Tells I-P2 and I-Plan to allow multiple options and to show
     the option GUI.  "show-options" defaults to false in I-P2
     and true in I-Plan.

  option-directory=pathname

     Gives the agent a a set of initial options.  All of the files
     in the directory should contain plans, using any of the available
     syntaxes, and the file names will become option names.

     This parameter takes precedence over "show-options" and causes
     the agent to behave as if "show-options" is true.

  option-for-input=name

     Designates which option should initially receive input from
     external sources.  If an option-directory was specified and
     contains an option with that name, it will be used; otherwise,
     an option with that name will be created.

     If no option-for-input is specified, the behaviour depends
     on whether an option-directory was given.  If it was, and
     contains some plans, then the initial option for input
     is the one that was first in alphabetical order in the
     option directory.  Otherwise, an option named "Option-1"
     is created and becomes the initial input option.

     In all cases, the initial option for input also becomes
     the initial current option.

  plan=resource-name

     Designates a plan to load into the initial current option
     when no option-directory was specified.

  plan-splits-option=true or false (default false)

     [This is an experimental feature that will not be described
     in detail.]

     If plan-splits-option is true, it changes the way the "Plan"
     command treats options to be different from the standard
     behaviour  described in a later section.  Instead of changing
     the plan in the current option, it creates a child of the
     current option and puts the new plan there.  If your current
     option is Option-1, for example, a "Plan" would creates an
     Option-1.1 but also leaves Option-1 as it was.

Notes:

* I-X options are not quite the same as O-Plan's. O-Plan's
  options do not directly correspond to columns in the matrix.
  Instead they're used at a lower level, and the columns represent
  different objects, called "COAs", that refer to different O-Plan
  options at different times.  I-X options have taken something from
  both O-Plan's options and the matrix interface's "COAs".  They can't
  do all of the things that can be done with O-Plan options, but they
  can do the things that are done via the matrix interface.

Splitting options
-----------------

Splitting an option is a way to try variations and ask "what if?".
The result is two sibling options that initially both have the same
contents as the original.  Each can then be independently changed
by adding activities, issues, or constraints, expanding activities,
and so on.  (Merely adding an annotation does not count as a change.)

It's also possible to create more identical siblings by splitting any
of the existing siblings before they're changed.  Options can also
be split after a change, and then you get two siblings in the next
generation (nieces or nephews of the earlier ones).

These two cases are called splitting "across" and "down",
respectively, just as a convenient way to talk about them.
The "Split" entry in the "Options" menu always says which
sort of split it will do.

The rationale for splitting "down" after an option has been
changed, for instance by adding an activity, is you are now
exploring variations on the changed option rather than on
its parent.

The system tries to produce option names that reflect these
relationships.  For example, suppose you create an option
and name it COA-1.  It counts as having changed (from nothing),
and so if you split it, it splits "down" to give you COA-1.1
and COA-1.2.  [Internally, COA-1 is renamed to COA-1.1 and
a new option is created and called COA-1.2.  This difference
matters if you're working with the Java objects.  However, it's
often better to think of COA-1.1 and COA-1.2 as children
of a COA-1 that is no longer visible to the user.]

If you then split either of those options before changing them,
they split "across", and you get COA-1.3, then COA-1.4, and so on.
[Splitting across just creates a new option each time, with
no renaming.]

Now suppose you change COA-1.2 and then split it.  This
is another split "down", because of the change, giving you
COA-1.2.1 and COA-1.2.2.  However, COA-1.1, COA-1.3, and
any others you created at that level, will still split "across",
because you haven't changed them.

The newer (also higher-numbered) option becomes the current
option after a split, so that you see a name change and know
something has happened.

The choice of names is complicated by the possibility that
some other option is already using one of the desired names
(you might have created an unrelated option earlier and
called it COA-1.3, for some reason) and by the user's
ability to rename options.

For a split down, both of the desired names must be available,
and if they aren't you will have to do some renaming before you
can split the option.  A split across, however, always gets
the next available sibling name.  (Here "available" means not
only that no option has the name, but also that no option
has a name that looks like that of a descendent.)

A user-requested rename counts as a "change" when deciding whether
to split down or across.  So if you rename COA-3 to By-Sea, and
then split it, you get By-Sea-1 and By-Sea-2.

"Reset" when there are options
------------------------------

The "File" -> "Reset" menu items remain "big" resets: they set
everything in the process model and viewers back to a restored
version of their initial state.  That's what those commands
have always been for, and they retain that purpose.  All existing
options are eliminated, and a new, empty option is created.
The new option gets the name specified by the "option-for-input"
parameter, defaulting to "Option-1".

If you use "Reset All But State", it's the state in the current
option that is preserved.

If you want to clear out a single option instead, use the
"Clear" entry in the "Options" menu.  It provides both
"Clear All" and "Clear All But State".

Planning and replanning
-----------------------

The I-X planner takes a plan as input and produces a series
of refined plans as output.  The operation that gets the first
plan is called "Plan", the one that gets subsequent plans is
called "Replan".  The planner has to make various choices on
the way to producing a result.  For example, it might be possible
to expand an activity in more than one way.  When it's asked
to replan, it goes back to one of those "choice points",
picks a different possibility, and resumes its search.

When replanning with options, it's helpful to think that
there's a plan generator or "replan chain" that's controlled
by the I-Plan Tool.  (In fact, in the implementation there
actually is a PlanGen class that has this role.)

In I-Plan and I-P2, "Plan" modifies the current option,
and each "Replan" creates a new option.  "Plan" creates
a new plan generator, and each new option created from that
one by replanning shares the same plan generator.
A "Replan" in any of them will produce the next plan
in the sequence as a new sibling option.

If an option is changed, however, it drops the plan-generator
(if it has one) and the "Replan" command becomes disabled
for that option in the I-Plan Tool.

A replan usually splits across.  "Plan" changes an option.
Think of a "Replan" as going back to a sibling of that option
and making a different change.  If you use "Plan" followed
by "Replan"s to get a three plans, say, in three options,
it should be as if you had made three sibling options at
the start and then manually changed each one in the way
that the planner did.  So they should all be siblings at the
same level and should all be marked as changed (so that
each will split down).

The first replan after a plan is trickier.  According to the
as-if just sketched, it would depend on how the plan option
would have split before "Plan" was done -- because that's what
would have happened if we'd made the siblings then by hand.
Instead, we always split down on the first replan, so that
the options created by the plan generator are set off as
more closely related to each other than to other options.
This also depends on less "history" and tends to be less
confusing.

Notes:

* The various rules above mean that if you repeatedly press
  "Replan" in the I-Plan Tool, you will keep moving to a
  new current option that contains the most recently produced
  plan, which tends to be easy to understand.

* "Plan" always creates a new plan generator, dropping any
  that the option already has.  The plan in, plan out nature
  of the planner means that "Plan" is always available.
  Make sure you don't press "Plan" when you mean to press
  "Replan".

* There is a "plan filter" that causes automatic replanning
  until a satisfactory plan is found, creating only one new
  option at the end, or none if no suitable plan is obtained.
  This could be used to implement the sort of automatic
  replanning provided by the O-Plan matrix interface in
  which the user can specify criteria the plan must meet.
  At present, however, it just rejects plans that are the
  same as one already produced by the same plan generator.
  The current planning algorithm has a somewhat annoying
  tendency to produce such plans in some cases.  [Time that
  might have been spent on strengthening the algorithm there
  has instead been spend on implementing options. :)]

  To see whether any plans have been rejected by the filter,
  look for a line that gives the "Number of rejected plans"
  in the statistics that appear in the I-Plan Tool's window
  after a plan or replan.  (The line appears only if some
  plans have been rejected.)

  To turn off the filter, use a command-line argument or props
  file entry "filter-duplicate-plans" with value "false".

Communications
--------------

There are four cases.  They have been arranged so that many
things will continue to work in familiar ways.

Anything sent to "me" using the Messenger will go into the issues,
activities, etc shown on the panel, just as it always has.  That means
it goes to the current option.  The Messenger has to work that way,
because we use it to add to the items shown on the screen.  For
example, a "Transform to activity" action moves an issue to the
Messenger where the user can turn it into an activity.

The assumption here is that the user controls when these messages
are sent and so can arrange for the current option to be the right one
to receive them.

This way, the Messenger also allows items to be copied from one
option to another.

Messages from other agents, however, might arrive at any time,
and there's no reason to believe they should always affect the
current option.  However, it's likely that panels will often
be used much as they were before.  If someone delegates an
activity to you, for example, it should go into your list of
things to do.

The model adopted here is that one of the options represents what
you are doing (in pretty much the same sense that single-option panels
did), and hence that issues etc that are sent to you should go to that
option, even though it won't always be the current option.

The "Options" --> "Preferences" menu item lets the user select
which option should receive input.  (At present, that is the only
preference that can be set, but others might be added later.)

A popup will appear to tell the user of external input when the
option-for-input isn't the current option.

There are two special cases for messages from other agents
(giving us our third and fourth case overall).

First, reports are handled in a slightly different from issues,
activities, and constraints.  Instead of going only to the option
selected for input, they are also delivered in any option that has
a relevant issue or activity.

The final case is when another agent sends you a plan.  That's
done by sending a load-plan activity containing the plan.
However, the user who receives such an activity often just
wants what's in the plan and has no use for the load-plan activity.

Moreover, it's unlikely that there's any particular option that
should always receive plans.  For example, now that there's a
built-in automatic planner, an I-Plan (or even an I-P2) might be
acting as a planning service.

Therefore, when a load-plan activity is received, it is not given to
any option.  Instead, the plan is extracted and a little "Load Plan"
window appears.  It allows the user to look at the plan.  The usual
XML and Tree views are available; others (such as HTML, text, or
graphs) might be added later.  The little window stays around until
the user decides what to do with the plan, and in the meantime the
user can do other things -- such as change the current option to one
that should take the plan.  Various possible actions are presented as
buttons.  They affect whatever option is current when the button is
pressed.  The choices include loading the plan, replacing the option's
current plan, and replacing the plan while saving the option's current
state.

Notes:

* A load-plan activity sent to "me" using the messenger is not
  treated specially.  It is added to the current option just like
  any other activity.

* All messages received via the communication strategy count as
  external messages for the purposes of the above rules.  This
  includes messages you send to yourself by sending to your
  panel's own IPC-name (which can be a useful thing to do).

* For technical reasons, messages that arrive when the selected
  option-for-input is not the current option cannot be allowed to
  affect the input option until it next becomes the current option.
  They are therefore kept in a queue until that time.  However, they
  are attached to that particular option, and that is not affected by
  changing which option is the one designated as the option-for-input.
  (That change affects only later messages.)

  This is to make the behaviour as close as it can be to what would
  happen if those technical reasons (which chiefly concern the
  viewers) did not exist.

* At present, a "Load Plan" window stays up until the user
  presses "Finished".  That allows the same plan to be put
  into more than one option.

* An issue or activity is set up to receive reports when it
  is forwarded to another agent, so copies made by splitting etc
  before that point won't receive the reports, but ones made
  after will.
