Using the Livingstone2 Engine

Back to Main Page

This document describes how to run Livingstone from the command line, in contrast to running it from Stanley's GUI environment. Three types of files are involved:

• Model files
• Scenario files (optional)
• Executable files

Model Files

A Livingstone model is represented by either 3 or 4 model files, which must reside in the same directory and have file names that are identical except for the file extension.

Type	Extension	Purpose
Main Model File	.l2, .l2bin, .xmpl	Specifies Variables, Transitions and constraint Clauses.
Harness File	.hrn	Distinguishes which Assignable Variables are Observables and which are Commands. These are also called the monitored Variables.
Initialization File	.ini	Assignments to Assignable Variables that are asserted at start-up. Typically, only the Transitioned (mode) Variables are given initial assignments.
Parameters File	.params	This file is optional, although it is preferred since it ensures that the configuration parameters associated with the model are used, each time it is run. Configuration parameters are parameter-value pairs. See the documentation for Livingstone's configuration parameters.

Livingstone models can be expressed in four different formats. You must decide which one you are going to pass to the Livingstone engine.

Name	Human Readable?	L2 Readable?	Size	Remarks
JMPL	Yes	No	Large	Translated to XMPL by the JMPL compiler for use by Livingstone. Represents component structure.
L2	Yes	Yes	Medium.	xmpl2l2 translates XMPL to L2. Represents Variables, domains and Clauses.
L2bin	No	Yes	Small	A more compact version of the L2 format for flight. Can be read from an array into L2.
XMPL	Yes	Yes	Large	xmpl2l2 translates XMPL to L2. Represents component structure.

Scenario Files

Scenarios are not considered to be model files; they are simply files containing command-line-interface commands. By convention, scenarios have file extension .scr, but no code requires or even prefers this.

You do not have to store a scenario in a file; you may type the commands to the Livingstone executable command-line interface. But if you want to run the same scenario (or very similar ones) repeatedly, you would save a lot of time and effort by redirecting command-line input from a scenario file.

Executable Files

The Livingstone API is supplied as a class library. The API for flight code is class Livingstone. Flight code represents Variables and their domains only as integers. The API for interactive code is Livingstone_debug. Interactive code represents Variables and their domains both as integers and as human-readable name strings.

You can build an executable by creating an instance of a Livingstone API class and calling methods on it. Your executable must be able to read a model into the Livingstone engine, accept commands and observations, and respond to requests to produce diagnoses.

Two executables are supplied, corresponding to the two APIs.

The l2test Executable

The Unix executable is named l2test and the Win32 executable is named l2test.exe.

l2test is intended for interactive or batch use in non-embedded environments in which human readability of input and output are important.

It is invoked with the command line

l2test <options> <model file pathname>

Its only required argument is the pathname to the model file. Input may be optionally redirected from a scenario file and output may be optionally redirected to save it to a file.

It accepts the following command-line options.

Short Form	Long Form	Argument	Description
-h	--help		Print a help message and exit.
-v	--verbose	[r][o][w]	Read, optimize and/or write verbosely.
	--version		Print version number and exit.
-y	--history	unsigned int	Set maximum history; 0 is unbounded.
	--max-truncate	unsigned int	Maximum number of Candidates to retain in truncation.
-p	--progress	min | full	Set progress style.
	--cbfs		Use the CBFS Tracker. (default)
	--cbfs-candidates	unsigned int	Set the maximum number of Candidates returned by the CBFS Tracker.
	--cbfs-search	unsigned int	Maximim number of nodes to search for the CBFS Tracker.
	--cover		Use the Conflict Coverage Tracker.
	--cover-max-rank	unsigned int	Maximum-rank Candidate to consider for the Cover Tracker.
	--optimize		Optimize the model. Automatically true for progress style "min".

Note that the contents of the *.params file overrides command-line options.

l2test supplies a rich command-line interface. Enter the command help to see a list of command lines.

The l2flight Exectuable

The Unix executable is named l2flight and the Win32 executable is named l2flight.exe.

l2flight is intended for embedded environments (such as flight) in which a very small footprint is important.

It is invoked with the command line

l2flight <L2bin model file pathname>

It reads model files only in the L2bin format and does not accept command-line options. The only command-line argument is the pathname to the L2bin model file. Input may optionally be redirected from a scenario file, and output may optionally be redirected to save it to a file.

l2flight has a minimal command-line interface. The commands consist of an opcode of one alphabetic character and up to two unsigned int arguments. Enter the command h to see a list of command lines.

Back to Main Page