..  -*- rst -*-

QRM envisioner
==============
The simplest way to run envisionments is to execute the Bourne script
  envisioner/interface/jenkins.sh

This will probe the current directory and related parts of the
filesystem for dependencies, such as the QRG package from
Northwestern University. It relies on Allegro Common Lisp 8.2,
a licensed product from Franz.com.

First envisionments of several systems will be computed, producing output like:

  envision-door-d-c-door-open-2
  Envisionment complete.

Then a collection of unit tests will run, producing output like:

  door-opening-1-test: 3 assertions passed, 0 failed.

The Lisp system runs portably in several environments. An optional
library, zgraph, layered upon the Common Graphics library, is available
only under Windows. Load it interactively with (load "loader") and
(start-env), and then any envisionment graph may be viewed interactively.
To do this for the example system above, use
(envision-door-d-c-door-open-2 :display? t)


design metrics
--------------

Simplified results from envisionments may be obtained by running
a pair of Bourne scripts:

  $ ./controller-4-metric.sh

  $ ./controller-3-metric.sh

The respective expected outputs are 0.25 for the controller with
a singularity and 0.5 for the simpler controller 3.

A controlled actuator may have kinematic singularities, regions in state
space where the controller loses command authority. A simple example is a
steam locomotive that, when stopped with its single driving piston fully
extended, cannot restart. Depending on the design and the terrain beneath
the vehicle, a hydraulic ramp actuator could similarly be faced with
operating the ramp when it is nearly parallel to the piston. Since increased
stress and possible overloads are experienced near such regions, designers
want to understand singularities and verify they will be avoided during
anticipated operating conditions. Cooperating components, with
non-overlapping singularities, may be required for a robust design.

We qualitatively modeled a ramp actuator with such a parallel piston
singularity, and computed the envisionment of all states to which this
"controller 4" might transition during Use Case 1. This includes a
qualitative failure state due to possible overshoot and two
singularity-induced failure states, plus a success state where the door
opens as required.

We also modeled an actuated revolute joint, "controller 3", that lacks
singularities. Its envisionment has just one failure state, due to possible
overshoot, plus a success state.

A simple design metric, the success fraction, helps programs or people to
compare competing designs. It is the ratio of number of success states to
total number of terminal states in an envisionment. Here, controller 3 is
judged better than controller 4 because 1/2 is greater than 1/4. A system
envisionment may contain many transitions to failure states and grow to be
much larger than the graphs found in this illustrative example. One way to
think of a metric that penalizes failure states is it accounts for the
additional effort needed after part selection to quantitatively verify that
potential transitions to failure states will not be possible during
operation.