Notes on Options

Author: 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".


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:

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.


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.


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.


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.


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.



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.

Jeff Dalton <>