
PyModel Commands

PyModel provides three main programs:

 pma.py, PyModel analyzer: generates a finite state machine (FSM) 
   and computes properties by exploring a model program, FSM, test suite, 
   or a product of these.
 
 pmg.py, PyModel graphics: generates a file of graphic commands from an FSM.
 
 pmt.py, PyModel tester: displays traces, generates tests offline, 
   executes offline tests, or generates and executes tests on-the-fly.
 
Use pma and pmg to visualize and preview the behavior of pmt.  Every
path through the graph created by pma (and drawn by pmg) is a trace
(test run) that may be generated by pmt, when pma and pmt are invoked
with the same arguments.

PyModel also provides these programs and scripts:

 dotsvg: converts dot file output from pmg.py to SVG file that can be displayed 
          in a browser.

 dotps: converts dot file output from pmg.py to PostScript file that can be 
         printed or displayed in PostScript viewer.

 trun.py: runs sample demonstrations and scripts that test PyModel itself.

 clogdiff: works with trun.py to execute and check regression tests on PyModel.

To prepare to use the programs, put the pymodel directory on your
execution path.  Put the current directory (whatever it is) on the
PYTHONPATH by executing the tpath command ("source tpath" in bash,
systems, just "tpath" in Windows).

For usage examples with many combinations of options and arguments,
see the test*.py test script modules in the samples directories.

Here is a brief description of each program.  To display the same
information online (where PyModel is installed), just type the command
name without arguments: pma.py etc.


PyModel Analyzer

 pma.py [options] models  

models is a list of one or more module names (with no .py suffix).
Each module named in models must contain a model, that is: a model
program, an FSM, or a test suite.  In addition, a module named in
models can contain additional configuration information for a model
program.  Multiple models (model programs including configuration,
FSMs, and test suites) are composed into a product.  The analyzer
generates a finite state machine from the product and writes an FSM
module that includes the generated FSM, the explored states, and other
results of the analysis.  The FSM module contents can be displayed
using the PyModel Graphics program, pmg.py

Options:
  -h, --help            show this help message and exit
  -a ACTION, --action=ACTION
                        Action to include in generated FSM, as many as needed,
                        if no -a include all actions
  -e EXCLUDE, --exclude=EXCLUDE
                        Action to exclude from generated FSM, as many as
                        needed
  -m MAXTRANSITIONS, --maxTransitions=MAXTRANSITIONS
                        Maximum number of transitions to include in the
                        generated FSM, default 100
  -o OUTPUT, --output=OUTPUT
                        Output module name (with no .py suffix), default is
                        <first argument>FSM

PyModel Graphics

  pmg.py [options] fsm

The single argument fsm is one finite state machine (FSM) module name
(without the .py suffix).  The FSM is typically produced by the
PyModel Analyzer, pma.py.  From the FSM, pmg generates a file of
commands in the dot graph-drawing language.  This .dot file can then
be processed by the dot program in the Graphviz package from
www.graphviz.org.  Use the PyModel commands dotps, dotpdf, or dotsvg to run dot
and produce PostScript, PDF, or SVG, respectively. SVG files can be viewed
in a web browser.

Control clutter in the graph with the -l --transitionLabels option.
-l action shows the action name, argumentss, and return value.
-l name shows only the action name, and -l none shows no labels.

In the generated graphics, the initial state is gray.  Accepting
states have a double border.  Unexplored or incompletely explored
states are orange (these may have outgoing transitions that are not
shown).  Terminal states (with no outgoing transitions) that are
accepting states are green.  Terminal states that are not accepting
states are yellow; runs that end in these states are considered
failures.

In the browser, hover the pointer over a state to display a tooltip
that shows the state variables and their values.  Place the point of
the pointer over any pixel on a transition vector to display a tooltip
that shows the transition.

Options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output=OUTPUT
                        Output file name (not including .dot), default is <fsm argument>
  -l TRANSITIONLABELS, --transitionLabels=TRANSITIONLABELS
                        Transition labels: action, name, or none, default is action
  -x, --noStateTooltip  Omit tooltips from state bubbles (to work around dot svg problem)
</pre>

PyModel Tester

 pmt.py [options] models  

models is a list of one or more module names (with no .py suffix).
Each module named in models must contain a model, that is: a model
program, an FSM, or a test suite.  In addition, a module named in
models can contain additional configuration information for a model
program.  Multiple models (model programs including configuration,
FSMs, and test suites) are composed into a product.  The tester
generates traces by executing the product, at random or guided by the
strategy option.  To just view the traces, omit the implementation
option.  To use pmt as an offline test generator, omit the
implementation option and use the output option to save the traces in
a test suite module.  To execute tests, provide the implementation
option.  To execute tests generated offline, provide that test suite
module as the single command argument.  To generate and execute tests
on-the-fly, provide one or more model programs and/or scenario FSMs as
command line arguments.  To save on-the-fly tests so they can be
reproduced later, use the output option to save them in a test suite
module.

Limitations: pmt can only execute traces consisting of controllable
actions that the tester can call to make the implementation do
something.  Future versions will also support observable actions:
events that the tester can detect in the implementation.

Options:
  -h, --help            show this help message and exit
  -a ACTION, --action=ACTION
                        Action to execute, as many as needed, if no -a execute
                        all actions
  -c CLEANUPSTEPS, --cleanupSteps=CLEANUPSTEPS
                        Maximum number of steps in the cleanup phase, default
                        0 for no cleanup
  -d, --debug           Run the main function in the debugger
  -e EXCLUDE, --exclude=EXCLUDE
                        Action to exclude from execution, as many as needed
  -g STRATEGY, --strategy=STRATEGY
                        Strategy (module name), omit to use random strategy
  -i IUT, --iut=IUT     Implementation (stepper module name), omit to just run
                        model
  -n NSTEPS, --nsteps=NSTEPS
                        Number of steps in a single test run before beginning
                        cleanup phase, default 0 for no limit
  -o OUTPUT, --output=OUTPUT
                        Output test suite module name (with no .py suffix), no
                        default (no output file if omitted)
  -q, --quiet           Omit arguments and return value from progress messages
                        (to suppress printing very large buffers etc.)
  -r NRUNS, --nruns=NRUNS
                        Number of test runs, default 1, 0 for no limit
  -s SEED, --seed=SEED  Random seed, use any nonzero value to make runs
                        reproducible


Revised July 2011
