The Livingstone API

Back to Main Page

The Livingstone API has been centralized into class Livingstone. All applications that use the Livingstone engine should create an instance either of class Livingstone (for stripped-down flight code) or of class Livingstone_debug (for human-readable interactive applications).

In previous versions of Livingstone, the only API involved the Tracker or Transition system. Such direct access is now deprecated. First, the API functions are now more centralized. But, more important, the interface to these lower-level classes contain public methods that users should never invoke because improper use may corrupt the tracker, transition system, conflict data base or truth maintenance system.

An Example

The following code shows how to use the API methods to create, initialize, and run a Livingstone engine.

In this code fragment illustrates a system in which the Livingstone operations are specified programmatically, by method invocations.

    int main(int argc, char** argv) {
      // Create an instance of class Livingstone
      Livingstone livingstone;
      const MBA_string modelFilePathname("/here/is/my/model");
      livingstone.set_file(modelFilePathname);
      // Reading the model also reads in the configuration parameters
      if (livingstone.read_file()) {
        // Do this after reading the file so the correct Tracker is created
        livingstone.create_tracker();
        if (livingstone.initialize_tracker()) {
          // Here is where you perform operations such as
          // livingstone.observe(), livingstone.command(), livingstone.idle(),
          // livingstone.diagnose()
        } else {
          cerr << "Failed to initialize tracker" << endl;
        }
      } else {
        cerr << "Failed to read model file" << endl;
      }
    }
    

The next code fragment illustrates a system in which the command-line interpreter of class Livingstone_debug supplies interactivity.

    int main(int argc, char** argv) {
      // Create an instance of class Livingstone_debug
      Livingstone_debug livingstone;
      const MBA_string modelFilePathname("/here/is/my/model");
      livingstone.set_file(modelFilePathname);
      // Reading the model also reads in the configuration parameters
      if (livingstone.read_file()) {
        // Do this after reading the file so the correct Tracker is created
        livingstone.create_tracker();
        if (livingstone.initialize_tracker()) {
          // To map between indices and print names
          livingstone.create_debugger();
          // Run the command-line interpreter
          livingstone_debug.run();
        } else {
          cerr << "Failed to initialize tracker" << endl;
        }
      } else {
        cerr << "Failed to read model file" << endl;
      }
    }
    

There are other variations on running Livingstone, especially with regard to reading in the model and setting the configuration parameters. But these examples are close to the existing uses in executables l2flight and l2test.

Class Livingstone

Livingstone()

Preconditions: none

Effect: Does nothing but set some instance variables to default values.

Returns: Does not apply.

bool read_file()

Preconditons: (1) set_filename() has already been called; (2) the supplied filename is the path of a readable model file with a recognizable file extension.

Effect: The contents of the model file are read into an object of class L2_file. If the Progress style is Minimal Progress, the L2_file object will undergo a set of model-shrinking transformations called "optimization."

Returns: true if the model file was read into the L2_file object; otherwise false.

NOTE: After reading a model file, it is necessary to create and initialize the Tracker if the Livingstone engine is to use the model.

void create_tracker()

Preconditions: none, but if read_file() has not been called previously, the Tracker will be of the default type, and not of the type desired by the programmer.

Effect: Creates either a Cover Tracker or a CBFS (Conflict-Directed Best-First Search) Tracker, according to the current Tracker style.

Returns: void

bool initialize_tracker()

Preconditions: (1) create_tracker() has already been called and (2) read_file() has already been called successfully.

Effect: The model that the reader read from a file or array into an L2_file object is transferred to the Transition System, and the model is intialized.

Returns: true if no exceptions were thrown; false otherwise.

bool observe(unsigned int variableIndex, int valueIndex)

Preconditions: (1) initialize_tracker() has been called successfully; (2) variableIndex is the index of an Observable Variable; (3) valueIndex is the index of a member of the specified Observable Variable's domain.

Effect: Assign the specified value to the specified Observable Variable.

Returns: true if the assignment was made; false if either (1) variableIndex is not the index of any Variable; (2) variableIndex is the index of a Variable but not of an Observable Variable; or (3) valueIndex is not the index of a value in the domain of the Observable Variable.

bool command(unsigned int commandIndex, unsigned int valueIndex)

Preconditions: (1) initialize_tracker() has been called successfully; (2) variableIndex is the index of a Command Variable; (3) valueIndex is the index of a member of the specified Command Variable's domain.

Effect: Set the currently-installed Candiate to NULl, assign the specified value to the specified Command Variable and progress to the next time step.

Returns: true if the assignment was made; false if either (1) variableIndex is not the index of any Variable; (2) variableIndex is the index of a Variable but not of a Command Variable; or (3) valueIndex is not the index of a value in the domain of the Command Variable.

void idle()

Preconditions:initialize_tracker() has been called successfully.

Effect: Set the currently-installed Candidate to NULL and progress to the next time step.

Returns: void

unsigned diagnose()

Preconditions: initialize_tracker() has been called successfully.

Effect: Set the currently-installed Candidate to NULL and find the set of Candidate diagnoses that explain the current observations, according the to currently-set Find-Candidates style.

Returns: The number of Candidate diagnoses found.

unsigned int ncandidates() const

Preconditions: initialize_tracker() has been called successfully.

Effect: No side effects.

Returns: The number of Candidate diagnoses found on the most recent diagnose() action; if there has been no diagnose() action, returns 0.

bool install(unsigned int candidateIndex)

Preconditions: (1) initialize_tracker() has been called successfully and (2) candidateIndex is the index of a Candidate in the set of Candidate diagnoses found by the most recent diagnose action. Method diagnose() must have been called for there to be any Candidates to install.

Effect: Install (incorporate into the Propositional Theory) the specified Candidate.

Returns: true if the Candidate was installed; false if candidateIndex is not the index of any Candidate in the current Candidate set.

bool have_installed() const

Preconditions: initialize_tracker() has been called successfully.

Effect: No side effect.

Returns: true if a Candidate has been installed since the last action that clears the installed Candidate; false otherwise.

int get_value(unsigned int variableIndex, boolean ok) const

Preconditions: (1) initialize_tracker() has been called successfully and (2) variableIndex is the index of a Variable.

Effects: sets parameter validID to false if variableIndex is not the index of any Variable; otherwise sets parameter validID to true.

Returns: -1 if either (1) variableIndex is not the index of any Variable or (2) the Variable is currently unassigned; otherwise the index of the specified Variable's value at the current Time Step.

int get_value(unsigned int variableIndex, unsigned int timeStep, boolean validID) const

Preconditions: (1) initialize_tracker() has been called successfully; (2) variableIndex is the index of a Variable; and (3) timeStep is less than or equal to the current Time Step.

Effects: sets parameter validID to false if variableIndex is not the index of any Variable or the Variable has no value at the specified Time Step; otherwise sets parameter validID to true.

Returns: -1 if either (1) there is an error in the parameters (bad Variable index or Time Step) or (2) the Variable is unassigned at the specified Time Step; otherwise the index of the Variable's value at the specified Time Step.

unsigned int nfailures() const

Preconditions: initialize_tracker() has been called successfully.

Effects: No side effects.

Returns: 0 if there is no currently-installed Candidate; otherwise, the number of failures in the currently-installed Candidate.

failure get_failure(unsigned failureIndex) const

Preconditions: initialize_tracker() has been called successfully.

Effects: No side effects

Returns: If there is no currently-installed Candidate or failureIndex is not the index of a Failure in the currently-assigned Candidate, returns a special Failure object designated "invalid"; otherwise, returns the Failure in the currently-installed Candidate with index failureIndex.

const L2_parameters *get_parameters() const

Preconditions: None, but the L2_parameters will have only default values until either (1) the model file is read; (2) n mutator method of class L2_parameters has been called; or (3) a parameter mutator method in class Livingstone has been called.

Effects: No side effects.

Returns: A pointer to the Livingstone object's L2_parameters data member.

void print_search_parameters() const

Preconditions: None, but the L2_parameters will have only default values until either (1) the model file is read; (2) a mutator method of class L2_parameters has been called; or (3) a parameter mutator method in class Livingstone has been called.

Effects: Pretty-prints the configuration parameters to cout

Returns: void

void print_search_parameters(ostream& os) const

Preconditions: None, but the L2_parameters will have only default values until either (1) the model file is read; (2) a mutator method of class L2_parameters has been called; or (3) a parameter mutator method in class Livingstone has been called.

Effects: Pretty-prints the configuration parameters to output stream os.

Returns: void

bool verbose_writer() const

Preconditions: None

Effects: No side effects

Returns: true if the writer is operating in verbose mode; false otherwise.

void set_verbosity(bool readerIsVerbose, bool optimizerIsVerbose, bool writerIsVerbose)

Preconditions: None

Effects: Sets the verbosity level of the reader, the optimizer, and the writer to the levels specified by readerIsVerbose, optimizerIsVerbose, and writerIsVerbose, respectively.

Returns: void

void set_verbose_writer(bool writerIsVerbose)

Preconditions: None

Effects: Sets the verbosity level of the writer to the level specified by writerIsVerbose.

Returns: void

void set_filename(const MBA_string& modelFilePathname)

Preconditions: None

Effects: Sets the model file pathname.

Returns: void

NOTE: If modelFilePathname must not have a file extension. If the extension is not set by a call to set_filetype(const MBA_string&), the reader will search for files with extensions of a pre-enumerated set ( .bin, .hrn, .ini, .l2, .l2s, .l2sbin, .xmpl).

const MBA_string& get_filename() const

Preconditions: None

Effects: No side effects.

Returns: The current model file pathname, set by the most recent call to set_filename(const MBA_string&). The default value is the empty string.

void set_filetype(const MBA_string& format)

Preconditions: None

Effects: On any subsequent calls to Livingstone::read_file, the reader will look only for files of the specified model file format, rather than looking, in a pre-specified order, for files of any known format. The format parameter can be "l2", "l2s" (stripped), "xmpl", "l2bin", or "bin". If any other value is given, the default value of "xmpl" is assumed.

Returns: void

const MBA_string& get_filetype() const

Preconditions: None

Effects: No side effects.

Returns: The current model file format, set by the most recent call to set_filetype(const MBA_string&). The default value is the empty string.

MBA_string get_search_style_str() const

Preconditions: None

Effects: No side effects.

Returns: The current search style as a string. The default value depends on how Livingstone was configured. If the Cover Tracker is disabled, the default value is L2_parameters::cbfs; otherwise, the default value is L2_parameters::cover.

void set_search_style(L2_parameters::Search_style searchStyle

Preconditions: None

Effects: Sets the current value of the search style configuration parameter to searchStyle, which may be either L2_parameters::cbfs or L2_parameters::cover, depending on which search styles are enabled.

Returns: void

NOTE: Once Livingstone::create_tracker() is called, changing the value of the search style has no retroactive effect.

bool get_use_cbfs_tracker() const

Preconditions: None

Effects: No side effects

Returns: True if the current search style is L2_parameters::cbfs. If not, it must be L2_parameters::cover.

unsigned get_cbfs_maxcand() const

Preconditions: none

Effects: No side effects

Returns: the current setting for the maximum number of Candidates returned by the CBFS Tracker. The default value is 5.

void set_cbfs_maxcand(unsigned max_value)

Preconditions: none

Effects: Sets the maximum number of Candidates returned by the CBFS Tracker. The default value is 5.

Returns: void

unsigned get_cbfs_search() const

Preconditions: none

Effects: No side effects

Returns: the maximum size of the search space for the CBFS tracker. The default value is 1000.

void set_cbfs_search(unsigned max_value)

Preconditions: none

Effects: Sets the maximum size of the search space for the CBFS tracker. The default value is 1000.

Returns: void

unsigned get_cbfs_max_cutoff_weight() const

Preconditions: none

Effects: No side effects

Returns: the maximum rank of a Candidate returned by the CBFS Tracker. The default value is 100.

void set_cbfs_max_cutoff_weight(unsigned max_value)

Preconditions: none

Effects: Sets the maximum rank of a Candidate returned by the CBFS Tracker. The default value is 100.

Returns: void

unsigned get_cover_maxrank() const

Preconditions: none

Effects: No side effects

Returns: the maximum rank of a Candidate returned by the Cover Tracker. The default value is 8.

void set_cover_maxrank(unsigned max_value)

Preconditions: none

Effects: Sets the maximum rank of a Candidate returned by the Cover Tracker. The default value is 8.

Returns: void

unsigned get_history() const

Preconditions: none

Effects: No side effects

Returns: the maximum number of time steps for which Variable values are retained. The default value is 3.

void set_history(unsigned historyLength)

Preconditions: none

Effects: Sets the maximum number of time steps for which Variable values are retained. The default value is 3.

Returns: void

L2_parameters::Progress_style get_progress_style() const

Preconditions: none

Effects: No side effects

Returns: the current value of the progress style. The default value depends on how Livingstone was configured. If full progress was disabled, the default value is L2_parameters::min; otherwise, the default value is L2_parameters::full.

MBA_string get_progress_style_str() const

Preconditions: none

Effects: No side effects

Returns: the current value of the progress style as a string. The default value depends on how Livingstone was configured. If full progress was disabled, the default value is "min"; otherwise, the default value is "full".

void set_progress_style(L2_parameters::Progress_style progress_style)

Preconditions: none

Effects: Sets the current value of the progress style. The progress_style parameter can be either L2_parameters::full (if full progress is not disabled) or L2_parameters::min (if min progress is not disabled). The default value depends on how Livingstone was configured. If full progress was disabled, the default value is L2_parameters::min; otherwise, the default value is L2_parameters::full. If the progress style is set to L2_parameters::min optimization is enabled.

Returns: void

void set_progress_style_str(const MBA_string& progressStyleString)

Preconditions: none

Effects: Sets the current value of the progress style. The progressStyleString parameter can be either "full" (if full progress is not disabled) or "min" (if min progress is not disabled). The default value depends on how Livingstone was configured. If full progress was disabled, the default value is "min"; otherwise, the default value is "full". If the progress style is set to "min" optimization is enabled.

Returns: void

get_use_full_progress() const

Preconditions: none

Effects: No side effects

Returns: true if the current progress style is full progress; otherwise false.

unsigned get_max_truncated_candidates() const

Preconditions: none

Effects: No side effects

Returns: the maximum number of Candidates to retain through truncation. The default value is 5.

void set_max_truncated_candidates(unsigned max_value)

Preconditions: none

Effects: Set the maximum number of Candidates to retain through truncation. The default value is 5.

Returns: void

L2_parameters::FC_style get_fc_style() const

Preconditions: none

Effects: No side effects

Returns: The current find-candidates style, one of L2_parameters::tracker_default, L2_parameters::extend, L2_parameters::prune_and_search and L2_parameters::find_fresh. The default value is L2_parameters::tracker_default.

void set_fc_style(L2_parameters::FC_style fc_style)

Preconditions: none

Effects: Sets the find-candidates style, one of L2_parameters::tracker_default, L2_parameters::extend, L2_parameters::prune_and_search and L2_parameters::find_fresh. The default value is L2_parameters::tracker_default.

Returns: void

MBA_string get_fc_style_str() const

Preconditions: none

Effects: No side effects

Returns: The current find-candidates style as a string, one of "the tracker default fc", "extend", "prune-and-search" and "find-fresh". The default value is "the tracker default fc.

void set_fc_style_str(const MBA_string& fc_style)

Preconditions: none

Effects: Sets the find-candidates style from a string, one of "the tracker default fc", "extend", "prune-and-search" and "find-fresh". The default value is "the tracker default fc".

Returns: void

bool get_use_optimizer() const

Preconditions: none

Effects: No side effects

Returns: true if the optimization flag is set; otherwise false. The default is false, but if Livingstone::set_progress_style(L2_parameters::Progress_style) or Livingstone::set_progress_style_str(const MBA_string&) is ever called, the default will become true.

NOTE: The Livingstone engine itself does not automatically perform the optimization; the application may decide to call Livingstone_reader::optimize() on its instance of class Livingstone or class Livingstone_debug (for example, if optimization is enabled).

void set_use_optimizer(bool b)

Preconditions: none

Effects: Set the flag to optimize.

Returns: void

NOTE: The Livingstone engine itself does not automatically perform the optimization; the application may decide to call Livingstone_reader::optimize() on its instance of class Livingstone or class Livingstone_debug (for example, if optimization is enabled).

WARNING: If the progress style is set to min progress and optimization is not performed (e.g., because this flag is set to false), the Livingstone engine will give incorrect results.

const Tracker* get_tracker()

Preconditions: none, but the return value will be the NULL pointer before Livingstone::create_tracker() is called.

Effects: No side effects

Returns: a const pointer to the Tracker, if it has been created; otherwise, the NULL pointer.

Tracker* get_tracker()

Preconditions: none, but the return value will be the NULL pointer before Livingstone::create_tracker() is called.

Effects: No side effects

Returns: a pointer to the Tracker, if it has been created; otherwise, the NULL pointer.

SearchTermination get_search_termination_reason() const

Preconditions: none

Effects: No side effects

Returns: the reason the last find-candidates search (if any) terminated. The value can be SEARCH_CONTINUE, EMPTY_AGENDA, WEIGHT_CUTOFF or MAX_OVERRUN. The value is meaningless before any search has been performed.

Class Livingstone_debug

Livingstone_debug()

Preconditions: none

Effect: Allocates a buffer for parsing command lines.

Returns: Does not apply.

void create_debugger()

Preconditions: The Tracker must already have been created with a call to Livingstone::create_tracker() and the present method must not have been previously invoked.

Effects: Creates an L2_string_map object for mapping between objects in the Livingstone engine and their print names. Creates a debugging (that is, command-line enabled) Tracker of the type that was most recently chosen. Sets the find-candidates style in the debugging Tracker.

Returns: void

Tracker_debug* get_debugger()

Preconditions: none, but if create_debugger() hadn't been successfully called, a NULL pointer is returned.

Effects: No side effects

Returns: a pointer to the debugging (that is, command-line enabled) Tracker, if there is one.

L2_string_map* get_string_mapping()

Preconditions: none, but if create_debugger() hadn't been successfully called, a NULL pointer is returned.

Effects: No side effects

Returns: a pointer to the L2_string_map object for mapping between objects in the Livingstone engine and their print names.

bool run()

Preconditions: create_debugger() must have been successfully called.

Effects: executes a command-line interpreter with input coming from cin

Returns: true if it received the "restart" command; false otherwise

bool run(istream& input, bool is_interactive = false)

Preconditions: create_debugger() must have been successfully called.

Effects: executes a command-line interpreter with input coming from parameter input.

Returns: true if (1) parameter is_interactive is true and it received the "restart" command; false otherwise

MBA_string search_termination_string(SearchTermination searchTermination) const

Preconditions: none

Effects: No side effects

Returns: A string mapping of the search termination reason, as follows:

parameter	return value
SEARCH_CONTINUE	"in progress"
EMPTY_AGENDA	"empty agenda"
WEIGHT_CUTOFF	"weight cutoff"
MAX_OVERRUN	"max overrun"
[anything else]	"unknown SearchTermination"

Class L2_parameters

An object of class L2_parameters is an instance variable in class Livingstone. Its purpose is to hold the current values of confliguration parameters for Livingstone. These parameters are given meaningful default, and can be set in any combination of three ways:

• When a model is read in, a file in the same directory whose name is that of the model and whose file extension is ".params" contains attribute-value pairs for the configuration parameters; the reader parses these and sets the corresponding configuration parameter.
• There are several public accessors and mutators in class L2_parameters; a pointer to the L2_parameters member can be obtained with method Livingstone::get_parameters(). Alternatively, the entire L2_parameters object can be replaced with method Livingstone::set_parameters(const L2_parameters&).
• There are several accessors and mutators in class Livingstone that in turn delegate to the corresponding accessors and mutators in class L2_parameters

Since this API is not used very much (in favor of the .params file and the Livingstone API), it will not be described here. The API is very similar to that of class Livingstone for the configuration parameters. See file mba/cpp/include/api/parameters.h for the exact API.

Back to Main Page