Configuration Parameters

Livingstone has 9 configuration parameters. These determine how Livingstone uses resources and what algorithms it uses.

The configuration parameters are not independent of one another; some are meaningful only if others have been specified.

The Choices

These are the 9 configuration parameters for Livingstone. One of them (maximum rank) is implemented under two different names in Livingstone, though they are mutually exclusive (one for each search method) and one parameter would have sufficed.

1. Find-Candidates Style

The choice has to do with clearing the existing set of candidates before searching for new ones. Either there is no clearing ("extend"), only outdated ones are cleared ("prune and search") or all candidates are cleared ("find fresh"). The preferred method, for correctness and efficiency, is "tracker default", which is "prune and search" for the CBFS tracker.

2. History Length

An upper bound can be placed on the number of time steps for which complete information is kept. When this limit is reached, the transition system "truncates" the history and summarizes the truncated information in a special assumption variable called the "state variable." The default value is 3. A zero value means that there is no upper bound; that is, truncation will not be performed.

3. Maximum Candidates

An upper bound can be placed on the number of candidate diagnoses returned by a "find candidates" tracker operation when the search method is CBFS. The default value is 5. A zero value means that there is no upper bound.

4. Maximum Candidate Rank

An upper bound can be placed on the "rank" of candidate diagnostes returned by a "Find Candidates" tracker operation. For the CBFS search method, the default value is 100; for the cover search method, the default value is 8.

5. Maximum Search Space

An upper bound can be placed on the number of nodes searched when the search method is CBFS. The default value is 1000. A zero value means that there is no upper bound.

6. Maximum Truncated Candidates

Neither tracker currently uses this configuration parameter. The default value is 5.

7. Progress Style

The choice is between Full Progress and Minimal Progress. Since the latter is simply an optimization of the former, and should yield identical results, it is preferred. Note, however, that Minimal Progress requires, and automatically enables, model optimization. The default is Full Progress unless Full Progress has been disabled at compile time.

Note on optimization Sets of variables that are constrained to have the same value can be represented by only one "representative" variable in the set, the others being excluded from the system. This can result in reductions of up to 50% of the variables in a model. Similarly, logical equivalences (such as (TRUE || P) == TRUE and (TRUE && P) == P) can be exploited to reduce the number of clauses in the model.

optimization.

8. Search Method

The choice is between the Conflict-Directed Best-First Search (CBFS) and conflict coverage (cover), implemented by two trackers. Only the former is now used. The default is CBFS unless this has been disabled at compile time.

Note that once the tracker has been created, changing the search method will have no further effect.

9. Maximum Candidate Classes

When the search method is CBFS, an upper bound can be placed on the number of Candidates that differ in more than time step. Candidates are partitioned into equivalence classes, defined by the equivalence relation that two Candidates are equivalent if, ignoring time steps, their Assignments are identical. The default value is zero, meaning that there is no upper bound to the number of equivalence classes.

How the Choices are Conveyed

Configuration parameters are conveyed to Livingstone in three different ways.

1. Programmatically

Methods on class Livingstone and on class L2_parameters can be called to set the configuration parameters. To use this method, you will have to write an alternative to l2test and l2flight. Be sure to call these methods after the file is read in, or the *.params file will over-write your settings.

Method	Value domain
void Livingstone::set_cbfs_maxcand (unsigned max_value)
void Livingstone::set_cbfs_max_candidate_classes(unsigned maxClassCount)
void Livingstone::set_cbfs_max_cutoff_weight (unsigned max_value)
void Livingstone::set_cbfs_search (unsigned max_value)
void Livingstone::set_cover_maxrank (unsigned max_value)
void Livingstone::set_fc_style (L2_parameters::FC_style style	`L2_parameters::tracker_default, L2_parameters::extend, L2_parameters::find_fresh, L2_parameters::prune_and_search`
void Livingstone::set_fc_style_str (const MBA_string& fc_style)	`"default", "extend", "ff", "find-fresh", "findfresh", "none", "prune-and-search", "prune-search", "ps", "the tracker default fc"`
void Livingstone::set_history (unsigned value)
void Livingstone::set_max_truncated_candidates (unsigned max_value)
void Livingstone::set_progress_style (L2_parameters::Progress_style style)	`L2_parameters::full, L2_parameters::min`
void Livingstone::set_progress_style_str (const MBA_string& style_str)	`"full", "min"`
void Livingstone::set_search_style(L2_parameters::Search_style style)	`L2_parameters::cbfs, L2_parameters::cover`
void Livingstone::set_use_optimizer(bool val)
void L2_parameters::set_cbfs_max_candidates(unsigned maxcand)
void L2_parameters::set_cbfs_max_rank(unsigned weight)
void L2_parameters::set_cbfs_search_space(unsigned nsearched)
void L2_parameters::set_cover_max_rank(unsigned weight)
void L2_parameters::set_find_candidates_style(L2Parameters::FC_style style)	`L2_parameters::tracker_default, L2_parameters::extend, L2_parameters::find_fresh, L2_parameters::prune_and_search`
void L2_parameters::set_history(unsigned h)
void L2_parameters::set_max_truncated_candidates(unsigned n)
void L2_parameters::set_progress_style(L2Parameters::Progress_style style)	`L2_parameters::full, L2_parameters::min`
void L2_parameters::set_search_style(L2Parameters::Search_style style)	`L2_parameters::cbfs, L2_parameters::cover`

2. Via the `*.params` file

A file with extension .params may be placed in the model file directory. When the model file is read, the parameters file is also read. This file need not exist.

One configuration parameter is declared per line. Each line is of the form <parameter>=<value>. Blank lines are ignored, as is whitespace within lines and as are lines whose first two non-whitespace characters are not "L2".

Parameter Name	Value Domain
L2FindCandidatesCmdType	`default, extend, ff, find-fresh, findfresh, none, prune-and-search, prune-search, ps`
L2MaxCBFSCandidates	int
L2MaxCBFSCandidateClasses	int
L2MaxCBFSCutoffWeight	int
L2MaxCBFSSearchSpace	int
L2MaxCoverCandidateRank	int
L2MaxHistorySteps	int
L2ProgressCmdType	`full, min`
L2NumTrajectoriesTracked	int
L2SearchMethod	`cbfs, cover`

Stanley creates a *.params file when it creates the *.hrn, *.ini, and *.xmpl files in the model file directory. Stanley has its own set of default values to write the the *.params file. These defaults (as well as many other Stanley-specific configuration parameters) are saved in a file named skunkworks/preferences/prefDefaults. Do not modify this file. An extract from the file is:

#
# LIVINGSTONE PREFERENCES
#
L2SearchMethod = cbfs
# 0 indicates unbounded classes
L2MaxCBFSCandidateClasses = 0
L2MaxCBFSCandidates = 5
L2MaxCBFSSearchSpace = 1000
L2MaxCBFSCutoffWeight = 100
L2MaxCoverCandidateRank = 8
# 0 indicates no history
L2MaxHistorySteps = 3
L2ProgressCmdType = min
L2NumTrajectoriesTracked = 5
L2FindCandidatesCmdType = prune-search

Stanley's default values for the Livingstone configuration parameters can be changed using the Stanley dialogs: Edit->Preferences->Skunkworks/User/Workspace->Edit User ... or Edit->Preferences->Skunkworks/User/Workspace->Edit Workspace ...

3. Via the command-line interface

The build script for Livingstone creates two executables, l2test and l2flight, the first of which takes command-line options that set the configuration parameters. These options are prefixed on the command line by a double hyphen (--), for example, --history=5.

`l2test`

Command-line configuration parameters to the l2test executable must precede the model file pathname. Note that the command-line configuration parameters do not override those in the *.params file; the latter dominate.

The command-line configuration parameters to l2test come from the following set.

Option (long form)	Option (short form)	Value Domain	Meaning	Remarks
`cbfs`		[no value]	Use the CBFS search style	Unless disabled at compile time
`cbfs-candidates`		int	Maximum number of candidates	Used with `--cbfs` unless disabled at compile time
`cbfs-candidate-classes`		int	Maximum number of candidate classes	Used with `--cbfs` unless disabled at compile time
`cbfs-search`		int	Maximum number of nodes to search	Used with `--cbfs` unless disabled at compile time
`cover`		[no value]	Use the cover search style	Unless disabled at compile time.
`cover-max-rank`		int	Maximum-rank candidate to consider	Used with `--cover` unless disabled at compile time
`help`	`h`	[no value]	Print usage message and exit	Not a configuration parameter
`history`	`y`	int	Set the maximum history to hold
`max-truncate`		int	The maximum number of candidates to keep through truncation	Neither tracker currently uses this value
`optimize`	`O`	[no value]	Optimize the model between reading in and loading	Not needed if `--progress=min`
`progress`	`p`	`full, min`	Set progress style
`verbose`	`v`	`[o][r][w]`	Print information when reading, optimizing and writing	Not a Livingstone configuration parameter; specific to `l2test`
`version`		[no value]	Print version number and exit	Not a configuration parameter

`l2flight`

There are no command-line parameters to the l2flight executable; use the *.params file.

Lee S. Brownston

Last modified: Thu Dec 5 09:56:05 PST 2002

Back to Main Page