Using L2 Tools

Candidate Manager
- Candidate Classes Table (the Classes tab)
- Candidates Table (the Candidates tab)
- Time-step List
- Assignment Tree (the Assignments tab)
- Discrepant Commands And Observations Pane
History Table
- Justification Tool
L2 Tools Command Line

Candidate Manager

The Candidate Manager displays information about the candidates and the candidate equivalence classes returned by Livingstone, and allows a user to select a particular candidate and time-step for display. Candidate equivalence classes are unique in their mode components, but not unique in their time permutations. The tool consists of four basic parts, the Classes Table, the Candidates Table, the Time-step List, and the Assignment Tree. The Time-step List and the Assignment Tree will not work unless there is a selected candidate. There are also two panes at the bottom of the tool: "Discrepant Commands and Observations" which displays observations responsible for conflicts; and a one line pane displaying the search termination information.

Candidate Classes Table (the Classes tab)

The table has five columns. For each candidate class it displays:

Num: number of the candidate class in the ranked list (lowest rank is best);
Ra : total rank for all the failures in that candidate class;
nk : individual rank for each failure in that candidate class;
Time: blank, since the equivalence class discards time permutations;
Failures: component attribute name and assignment for each failure in that candidate.

By clicking on one of the rows of the table, the Candidate Manager will select that equivalence class. This will cause the "Candidates" tab to be presented with the time permutations of the selected class highlighted in yellow. The user then selects one of the time permutations, and that candidate is installed by Livingstone. If the candidate class has only one instance of time permutation, the Candidate Manager will automatically select the one candidate instance for installation. Also, if there is only one candidate class (which may be <the-empty-candidate>) it will be automatically be installed.

Candidates Table (the Candidates tab)

The table has five columns. For each candidate it displays:

Num: number of the candidate in the ranked list (lowest rank is best);
Ra : total rank for all the failures in that candidate;
nk : individual rank for each failure in that candidate;
Time: the time step at which the failure occurred (- means prior to time horizon [history truncation]);
Failures: component attribute name and assignment for each failure in that candidate.

By clicking on one of the rows of the table, the Candidate Manager will select that candidate. This will cause the Time-step List to update with a list of all time-steps from the point of truncation to the current time, and send the Livingstone model state for the selected candidate, at the currently selected time, to all active L2 tools. At the bottom of the frame is the Search Termination String which tells the user how Livingstone's search method completed it's diagnosis. If no time-step selection has previously been made, the Candidate Manager will assume the user is interested in the latest time-step and display that information. If the user selects a different time-step and then a new set of candidates are returned by Livingstone, followed by a new candidate selection, the time-step selection will persist.

Time-step List

At the top of the Candidate Manager, the Time-step List consists of a box with a pull-down list and a left and right browse button. When there is no selection the box will appear empty. If there are no data to select from, (most likely because no candidate has been selected) the pull-down list will also appear empty. If a candidate has been selected, the list will be updated and the selection will go by default to the latest time-step. By pressing on the down arrow and displaying the list of alternate choices, the user can select a different time-step. After selection the data will be sent to all active L2 tools. Also the user can step to the previous or next time-step with the left and right arrow buttons, respectively. However, if a selection is not possible the arrow will go grey and become unresponsive. If the user selects a time-step other than the last, and then makes a new candidate selection, the time-step selection will persist.

Assignment Tree (the Assignments tab)

This is simply a tree of the components attributes and their assignments. After a candidate and time-step selection, the user can use this tree structure to browse the model and see the assignments. This part of the Candidate Manager is mostly unused and may vanish in future versions.

Discrepant Commands And Observations Pane

The "discrepancy" command output has been integrated into the L2 Tools GUI. Previously it was available only through the Livingstone command line interface. When a "find-candidates" is requested, Livingstone returns all discrepant commands/observations related to a candidate set. The discrepant commands and observations appear in this pane, which is scrollable. The user can resize the window by clicking (single mouse click) on the unidirectional arrows, or dragging the "separator" (located between this pane and the classes/ candidates table). The discrepancy set is refreshed along with the classes/ candidates table. The "discrepancy" command returns a list of commands and observations responsible for the current inconsistency", in the following manner:

if the model is consistent, there is no conflict, and the pane will be blank.
if the model is inconsistent, but no commands or observations are associated with the conflict, the pane will be blank.
otherwise the pane will display the assignments for command variables and observable variables, one per line. as <variable-name> = <value-name>:<weight/rank/cost>

Example Scenario:

progress cbAndLed.cb.cmdIn=on       
assign cbAndLed.led.ledState=off
fc

The first line is intended to turn the CB on. The second line observes
that the LED is off. The third line finds candidates that can explain the
inconsistency in the system. In addition it queries for the observations 
responsible for the conflict. Here is the output:

test.cbAndLed.led.ledState = off:0

The number 0 indicates the cost/rank/weight of the assignment. Only
autonomous (failure) transitions have nonzero cost/rank/weight. Command
and observable assignments will always have a 0 cost/rank/weight.

Notes:

The "discrepancy" command performs a single propagation, which may result in one conflict (or no conflict at all).
It examines the commands and observations related to that single conflict (if it exists).
It does not attempt to examine systematically the space of all conflicts.

History Table

The History Table displays the variables (attributes) of the currently loaded Livingstone model as a spread sheet, with the left-most column containing the variable names, and the second to nth columns containing the values at each time step. It is updated by L2 Tools at model load time, and afterwards when it processes Livingstone commands 'fc' and 'progress'.

The input slot labeled "Disjunctive Filter" can be used to reduce the number of variables displayed, by filtering the variable names with the entered substring.

The "Copy" button can be used to make a copy of the History Table widget.

Each value "cell" responds to Mouse-right clicks with a menu:

Print Connected Clauses - print to the L2 Tools command line all clauses which mention this value's variable name, and consequent clauses.
Show Justification - puts up a window which details why Livingstone assigned that value, and what was its chain of reasoning.
Set Value background color - allows the setting of a background color for all cells which contain this value.

Justification Tool

The Justification Tool provides a graphical explanation of a particular attribute (inferred by the Livingstone Engine). In other words, why did Livingstone assign a particular value to a model attribute? The tool is invoked via the History Table. For any displayed History Table attribute, the user can right-click on a table cell (column: time step, rows:attribute values) to display a popup menu. One of the pop-up menu options (Show Justification) is an explanation of this model attribute.

The Justification tool contains three main windows and a menu bar. The window pane labeled "attribute list" displays all model attributes involved in Livingstone's chain of reasoning. Each model attribute is marked with a specific icon. The icon marker designates whether the attribute assignment is the proposition to be explained, an assumption, or an immediate supporting clause proposition. The icons are itemized at the top of the list. Their tooltip provides their individual meanings. In some inference trees, various assumptions and propositions occur multiple times. The attribute list displays only unique attribute assignments. Therefore, the user may select an attribute from the "attribute list" and the tree will highlight all occurrences of this attribute assignment. By default the tree will highlight the path from the proposition to explain (root) to the selected proposition. If there is more than one occurrence of the same selected proposition, the tool highlights the one with a minimum number of inference steps.

The Inference Tree pane contains a summary of the attribute explanation. The user can expand the tree and select propositions of interest. For the selected proposition, the tree highlights the path from the selected proposition to the proposition to be explained (root). In addition, any identical occurrences of the selected proposition are also marked.

The Supporting Clause pane displays immediate supporting propositions (clause) that Livingstone used to explain the selected attribute.

In the main menu, the VIEW option allows the user to toggle between the JTree outline view and a graph/lattice view. The Graph view draws a summarization of the expanded inference tree. Since labeling the nodes with the actual attribute assignments makes the tree unwieldy. An alternate technique has been implemented. Instead each node is given a numerical value. Each numerical value maps to an attribute description in the "attribute list" pane. In addition, tooltips are provided for each of the graph nodes. When an attribute is selected in the graph, its path is also highlighted.

Under the main menu, there is a DETAIL submenu. It allows the user to reconfigure the view of the tree. By default Livingstone's entire chain of reasoning is displayed (proposition level). In addition there are two alternate views. The Assumption Level view displays the justified proposition with all of Livingstone's assumptions. The Attribute Level view extracts a summarized view of the entire chain of reasoning. It attempts to filter out attributes that are repeated in the inference tree. Additional filtration methods could be added to this submenu in future releases.

Errors are categorized under three classes. One, Livingstone errors (example, invalid attribute values) are reported under L2NativeException. Two, Livingstone engine state errors are reported under DataModelStateExceptions. Three, runtime exceptions are reported in the third category.

L2 Tools Command Line

Typing `help' at the command line will list the available L2 Tools
commands, and if a Livingstone engine is running, the Livingstone commands.

The following commands, entered at the command line, will be
handled by L2 Tools:

  newEngine CBFS <maxCandidateClasses>
      <maxCandidates> <maxSearch>
      <maxCutoffWeight> <maxHistory>
      <maxTrajectories>
      <progressCmdType> <fcCmdType>  - specify CBFS engine params
  newEngine COVER <maxRank> 100 100
      100 <maxHistory>
      <maxTrajectories>
      <progressCmdType> <fcCmdType>  - specify COVER engine params 
  loadModel <model-pathname>         - load model files (.xmpl, .ini, .hrn),
                                         allocate engine
  destroyEngine                      - deallocate current engine

  historyTable                   - start a History Table tool

  refresh                        - current L2 state
  modelBrowser                   - start browser for jmpl code of loaded model

  stanleyViewer                  - start Stanley in Viewer mode
  stanleyViewer modelState       - initialize current model state in Stanley Viewer

Livingstone commands like assign, progress, and fc are intercepted by
L2 Tools, before being passed on to Livingstone via the Java
Native Interface (JNI).  This will be noted thusly:
======> assign test.led1.ledState=on
L2Tools.command(assign test.led1.ledState=on)

Other commands are passed directly on to Livingstone.  If they are not
valid Livingstone commands, the user will be prompted to type
`help' to see a list of valid commands.

Back to Main Page