Crawly Crypt Collection 2/crawlyvol2.bin/program/compiler/clips/clip_doc/refman.man

Text File | 1993-09-01 | 64.6 KB | 2,986 lines

CLIPS







"C" Language Integrated Production System



A product of the

Mission Planning & Analysis Division's

Artificial Intelligence Section

CLIPS Reference Manual

Version 3.0   July 1986



Table of Contents



    Section
Page

1.0    Introduction      4



2.0    CLIPS Overview

    2.1    Rules          5

    2.2    Facts          5

    2.3    Reference Manual Syntax      6

    2.4    defrule      6

    2.5    deffacts      7

    2.6    Commenting CLIPS Rules      7

    2.7    Integration with External Languages      8



3.0    LHS Syntax- Patterns

    3.1    salience      9

    3.2    Literal Patterns      9

    3.3    Wildcard: Single and Multi-field    10

    3.4    Variables: Single and Multi-field    11

    3.5    Field Constraints    13

        3.5.1    Logical operators    13

        3.5.2    Predicate functions    15

    3.6    test Function    16

    3.7    Logical Pattern Blocks    19

        3.7.1    Inclusive or    19

        3.7.2    Explicit and    21

    3.8    Pattern Negation- not    21

    3.9    Pattern Bindings    22



4.0    RHS Syntax: Actions

    4.1    assert    24

    4.2    retract    24

    4.3    printout    25

    4.4    bind        25

    4.5    Pattern Expansion    26

    4.6    Defined Functions    26

        4.6.1    read    27

        4.6.2    gensym    27

        4.6.3    Functions for Multi-field Variables    27



Table of Contents



    Section
Page

4.0    RHS Syntax: Actions (cont'd)

    4.7    call        28

        4.7.1    setgen    29

    4.8    if..then..else    29

    4.9    while        30



5.0    Integrating CLIPS with External Functions

    5.1    Declaring User Defined External Functions to CLIPS    31

    5.2    Passing variables from CLIPS to External Functions    31

    5.3    Passing data from an External Function to CLIPS    33

    5.4    Extended Function LIbraries for CLIPS    33



6.0    Using CLIPS

    6.1    Interactive Interface commands    34

    6.2    Embedded CLIPS commands    36





    Appendices

A     Defined Functions Provided by CLIPS    37



B    Installing CLIPS    38



C    Performance Notes    40



D    Glossary        42

Section 1: Introduction



The CLIPS is a tool or shell for developing expert systems. It is a forward
chaining rule-based language using the Rete algorithm. CLIPS was designed
to allow expert system development and delivery on conventional computers.
The primary design goals were portability, efficiency and functionality. To
meet these goals, CLIPS is written in and fully integrated with the C
language. Future versions of CLIPS may be provided in other languages. An
Ada version is currently under development.



This document is the Reference Manual to CLIPS. It provides the definitive
description of CLIPS syntax and examples of usage. A separate manual, the
CLIPS User's Guide, provides an introduction to rule-based systems using
CLIPS.



CLIPS was developed by the Artificial Intelligence Section of the Mission
Planning and Analysis Division at NASA/Johnson Space Center. The
Artificial Intelligence Section is headed by Bob Savely. The initial version
of CLIPS was created by Frank Lopez. Gary Riley reworked the initial version
and developed the release version. Chris Culbert wrote the Reference Manual
and Joseph Giarratano wrote the Users Guide. Suggestions, testing and other
additional aids were provided by Marlon Boarnet, Lui Wang, Brian Donnell,
and Kirt Fields.





Section 2: CLIPS Overview



2.1    Rules

The primary knowledge representation methodology in CLIPS is the rule
system.  A rule is a collection of conditions and the actions to be taken if
the conditions are met. The developer of an expert system defines the rules
which describe how to solve a problem. CLIPS provides the mechanism which
attempts to match the rules to the current state of the system. The current
state is represented by a list of facts.



2.2    Facts

Facts are the basic form of data in a CLIPS system. Each fact represents a
piece of information which has been asserted into the current list of
facts, called the fact-list. Rules execution (or firing) is based on the
existence or non-existence of facts. A fact is constructed of a number of
fields separated by spaces. CLIPS facts are free form, which means that
any kind of information may be put into any field. Any number of fields may
be stored in a fact. Facts may be asserted into the fact-list prior to
starting execution and may be added (asserted) or removed (retracted) as
the action of a rule firing.



CLIPS represents fields in the form of floating point numbers or character
strings. A field in CLIPS is any string that starts with an alphanumeric
character  and is followed by zero or more letters, numbers, underscores, or
dashes. CLIPS is case sensitive, i.e. a pattern with upper-case letters will
only match a field with upper-case letters. Spaces or other special
characters can only be included by placing double quotes (") before and after
the field. Double quotes may be embedded within a field by placing a
backslash (\) in front of the quotes. Note that a string surrounded by double
quotes will only match another string that has the same exact set of
characters, including the double quotes.



Any field which uses a number as the first character will be converted to
single precision floating point, regardless of whether or not a decimal point
was included. The number of significant digits will depend upon the machine
implementation. Double quotes can be used to make a string field that starts
with a numeric character.



The first fact in the fact-list is always asserted by the system prior to  the
start of a program's execution. This fact, (initial-fact), can be treated
like any other fact and may be matched or retracted. If a fact is asserted
into the fact-list that exactly matches a fact that already exists, then the
new assertion will be ignored.

2.3  Reference Manual Syntax

The terminology used throughout this manual to describe CLIPS syntax is
fairly common to computer reference manuals. Plain words or symbols are
to be typed exactly as they appear, particularly parentheses. Symbols
enclosed in single angle brackets, such as <name>, represent a single field
to be defined by the user. Symbols enclosed in double angle brackets, such as
<<pattern>>, represent one or more fields which must be defined by the user.
Symbols enclosed within square brackets, such as [<<comment>>] are
optional parameters. White spaces (tabs, spaces, carriage returns) are used
by CLIPS only as delimiters between fields and are otherwise ignored
(unless inside double quotes). Examples in this manual show recommended
indentation style.



2.4  defrule

Each rule in CLIPS must have at least one condition and one action. There is
no limit to the number of conditions or actions a rule may have. To declare a
rule, the defrule construct is used.



All constructs in CLIPS are surrounded by parenthesis. The entire defrule
opens with a left parentheses, and closes with a right parentheses. Each
pattern or action also opens and closes with parenthesis.



Syntax:



       (defrule <name> ["<<comment>>"]

        (<<pattern 1>>)

        [    %

            %                 ; Left-Hand Side

            %                   ;       (LHS)

        (<<pattern n>>)]

             =>

        (<<action 1>>)

        [    %

            %            ; Right-Hand Side

            %     ;       (RHS)

        (<<action m>>)])



where <name> is the name of the rule and is an alphanumeric word of any
length. The comment is optional and can be any string enclosed within
double quotes.  The Left-Hand side (LHS) is  made up of a series of one or
more patterns which represent the condition elements for the rule. There is
always an implicit AND surrounding all the patterns on the LHS. On the
Right-hand side (RHS) we have a list of one or more actions to be performed
when the LHS of the rule is satisfied. The arrow (=>) separates the LHS from
the RHS. Actions are performed sequentially if and only if all condition
elements on the LHS are satisfied.



Example:



    (defrule example-rule   "This is an example of a simple rule"

        (foo bar 1)

        (foo bar 2)

        =>

        (assert (foo bar 3)))





2.5  deffacts

Facts can be added to the initial fact-list prior to the execution of any
rules. This is done with the deffacts construct:



Syntax:



    (deffacts <name> ["<<comment>>"]

        (<<fact 1>>)

        [    %

            %

            %

        (<<fact n>>)])



where <name> is the name given to the deffacts construction. An optional
comment may also be included. There may be multiple deffacts constructs.
Any number of facts may be asserted into the initial fact-list in each
deffacts statement. Facts asserted through deffacts may be retracted or
pattern matched like any other fact. The initial fact-list, including any
defined deffacts, is always reconstructed after a reset.



Example:



    (deffacts initial-facts

       "This is a set of facts needed prior to execution"

        (foo bar 1)

        (foo bar 2))





2.6  Commenting CLIPS Rules

As with any programming language, it is highly beneficial to comment the
code. Both defrule and deffacts allow a comment directly following the
construct name. Also, comments can be placed after CLIPS code lines by
using a semicolon, ";".  Everything from the ";" until the next return
character will be ignored by the CLIPS reader. If the ";" is the first
character in the line, the entire line will be treated as a comment. The
examples in sections 2.4 and 2.5 provide examples of commented code.



2.7  Integration with External Languages

CLIPS is fully integrated with external languages. Currently, the only
language supported is C. Users may define their own C functions and call
them from within CLIPS. There are two types of external functions which
can be called from within a CLIPS rule:



1)    a defined function can be used on the LHS of a rule inside a test or as
a predicate, or a defined function can be used on the RHS of a rule in a
number of ways (see sections 3.5, 3.6 and 4.6)



2)    an effect function used on the RHS of a rules in a call statement (see
section 4.7)



How the function is called will determine how the return value is
interpreted. All external function are defined in the same way and may do
anything the user desires. Only the return value is of importance to CLIPS.
Defined functions are called for their return value and typically should  not
have side effects. Effect functions are called for their side effect and their
return value is not meaningful. This is discussed in more detail in Section
5.0.



CLIPS may also be fully embedded within a user program and called as a
subroutine. This use of CLIPS is discussed in Section 6.2.

Section 3: LHS Syntax- Patterns



3.1    salience

A salience statement allows the user to assign a priority to a rule. When
multiple rules are in the agenda, the rule with the highest priority will fire
first.



Syntax:



    (declare (salience <num>))



where <num> must be an integer. If a salience statement is used, it must be
the first pattern on the LHS of a rule. If not specified, the salience value for
a rule defaults to zero. Salience values may be either positive or negative.
The largest allowed value is 10000. The smallest allowed value is -10000.



Example:



    (defrule test

        (declare (salience 99))     ; salience declaration

        (initial-fact)                    ; matches the initial fact

        =>

        (printout "I Have a salience value of 99." crlf))





3.2    Literal Patterns

The most basic pattern is one that precisely defines the exact fact that will
match.  This is called a literal pattern. All fields in a literal pattern must
be matched by all fields in a pattern in the fact-list. There are no variables
in a literal pattern.



Examples:

  Pattern on LHS of rule              Fact in the fact-list
Matches?

       (NASA AI Section)                (NASA AI Section)    Y

       (NASA AI SECTION)                (NASA AI Section)    N

    (Lisp Machines)                  (Lisp Machines)    Y

    (Symbolics)                      (Lisp Machine Inc)    N

       (Prolog Ada C)                   ("Prolog Ada C")    N

    ("John loves Mary")              ("John loves Mary")    Y



(Note that space or control characters inside double quotes could cause
problems)



3.3  Wildcards: Single and Multi-field

CLIPS has two kinds of wildcard symbols that may be used to represent
fields in a pattern. These are the question, "?" and dollar-question, "$?"
wildcards.  CLIPS interprets these wildcard symbols as standing in place of
some part of a fact. The question wildcard matches any value (numeric or
string) stored in exactly one field in the fact. It is a single-field wildcard
symbol. The dollar-question wildcard matches any value in zero or more
fields in a fact. It is a multi-field wildcard symbol, standing in the place
of multiple fields. Single and multi-field wildcards may be combined in a
single pattern in any combination.



Examples:



  Pattern on LHS of rule              Fact in the fact-list
Matches?

    (foo bar ?)    (foo bar)    N

    (foo bar ?)    (foo bar mumble)    Y

    (foo bar ?)    (foo bar "mumble")    Y

    (foo bar ?)    (foo bar mumble mumble)    N

    (foo bar ?)    (foo mumble bar)    N



    (foo bar $?)    (foo bar)    Y

    (foo bar $?)    (foo bar mumble)    Y

    (foo bar $?)    (foo bar "mumble")    Y

    (foo bar $?)    (foo bar mumble mumble)    Y

    (foo bar $?)    (foo mumble bar)    N



    (foo ? ?)    (foo bar)    N

    (foo ? ?)    (foo bar mumble)    Y

    (foo ? ?)    (foo bar "mumble")    Y

    (foo ? ?)    (foo bar mumble mumble)    N

    (foo ? ?)    (foo mumble bar)    Y



    (foo ? $?)    (foo bar)    Y

    (foo ? $?)    (foo bar mumble)    Y

    (foo ? $?)    (foo bar "mumble")    Y

    (foo ? $?)    (foo bar mumble mumble)    Y

    (foo ? $?)    (foo mumble bar)    Y



    (foo $? ?)    (foo bar)    Y

    (foo $? ?)    (foo bar mumble)    Y

    (foo $? ?)    (foo bar "mumble")    Y

    (foo $? ?)    (foo bar mumble mumble)    Y

    (foo $? ?)    (foo mumble bar)    Y





Multi-field wildcard and literal fields can be combined to provide very
powerful constructs. A pattern to match all the facts that have the word
CLIPS in any field could be written as:



($? CLIPS $?)



Some examples of what this pattern would match are:



(CLIPS foo bar mumble)

(foo CLIPS bar)

(foo bar CLIPS)

(CLIPS)

(CLIPS foo CLIPS)



The last fact will match twice, for "CLIPS" appears twice in the fact. The
use of the multi-field wildcard should be confined to cases of patterns in
which the single-field wildcard cannot create a pattern that satisfies the
match required, since the multi-field wildcard produces every possible
match combination that can be derived from a fact. This derivation of
matches requires a significant amount of time to perform compared to the
time needed to perform a single-field match.





3.4    Variables: Single and Multi-field

Wildcard symbols replace portions of a fact pattern and accept any value.
The value of the field being replaced may be captured in a variable for
comparison, display, or other manipulations. This is done by directly
following the wildcard symbol with a variable name.



Syntax:



    ?<name>    ; a single value variable

    $?<name>    ; a multi-value variable



where <name> is an alphanumeric string. It must start with an alphabetic
character, and cannot include any spaces. Double quotes are not allowed as
part of a variable name. The rules for pattern matching are exactly the same
as those for wildcard symbols. A variable will bind the field's value(s) to
that name from its first binding until the end of all actions for that rule.
The binding will only be true within the scope of the rule in which it occurs.
Each rule has its own private list of variable names with their associated
values (i.e. variables are local to a rule). The variables can be passed to
external functions.



Examples:



  Pattern on LHS       Fact in the fact-list          ?x bound to:

    (foo bar ?x)    (foo bar mumble)    mumble

    (foo bar ?x)    (foo bar "mumble")    "mumble"



  Pattern on LHS      Fact in the fact-list          $?x bound to:

    (foo bar $?x)    (foo bar)    NIL

    (foo bar $?x)    (foo bar mumble)    (mumble)

    (foo bar $?x)    (foo bar "mumble")    ("mumble")

    (foo bar $?x)    (foo bar dig dig)    (dig dig)



  Pattern on LHS       Fact in the fact-list          ?x bound to:      ?y
bound to:

    (foo ?x ?y)    (foo bar mumble)    bar    mumble

    (foo ?x ?y)    (foo bar "mumble")    bar    "mumble"

    (foo ?x ?y)    (foo bar mumble mumble)         --No match!--

    (foo ?x ?y)    (foo mumble bar)    mumble    bar



  Pattern on LHS       Fact in the fact-list          ?x bound to:      $?y
bound to:

    (foo ?x $?y)    (foo bar)    bar    (nothing)

    (foo ?x $?y)    (foo bar mumble)    bar    mumble

    (foo ?x $?y)    (foo bar "mumble")    bar    "mumble"

    (foo ?x $?y)    (foo bar dig dig)    bar    dig, dig

    (foo ?x $?y)    (foo mumble bar)    mumble    bar



  Pattern on LHS       Fact in the fact-list          $?x bound to:      ?y
bound to:

    (foo $?x ?y)    (foo bar)    (nothing)    bar

    (foo $?x ?y)    (foo bar mumble)    bar    mumble

    (foo $?x ?y)    (foo bar "mumble")    bar    "mumble"

    (foo $?x ?y)    (foo bar dig dig)    bar, dig    dig

    (foo $?x ?y)    (foo mumble bar)    mumble    bar



Once the initial binding of a variable occurs, all references to that same
variable have to match the same value that the first binding matched. This
applies to both single and multi-field variables. It also applies across
patterns.



  Pattern on LHS of rule              Fact in the fact-list
Matches?

    (foo ?x bar ?x)    (foo dig bar dig)    Y

    (foo ?x bar ?x)    (foo dig bar get)    N

    (foo ?x bar ?x)    (foo dig dig dig)    N

    (foo ?x bar ?x)    (foo dig bar "dig")    N



 Multiple pattern examples:



 Patterns on LHS of rule           Facts in the fact-list
Fires?

(defrule ..........

    (foo bar ?x)    (foo bar mumble)    Y

    (foo get ?x)    (foo get mumble)

    => ......



(defrule ..........

    (foo bar ?x)    (foo bar mumble)    N

    (foo get ?x)    (foo get dig)

    => ......



(defrule ..........

    (foo bar $?x)    (foo bar dig mumble)    Y

    (foo get $?x)    (foo get dig mumble)

    => ......



(defrule ..........

    (foo bar $?x)    (foo bar dig mumble)    N

    (foo get $?x)    (foo get dug baby)

    => ......





3.5  Field Constraints

Field constraints are functions which constrain the range of values a
particular field within a pattern may have. There are two types of field
constraints: logical operators or predicate functions.



3.5.1  Logical Operators

There are three logical operators available for constraining values inside a
pattern. These are the & (AND), | (OR), and ~ (NOT) operators. The logical
operators can be combined in almost any manner or number to carefully
constrain the value of specific fields while pattern matching.



Syntax:



    (<relation>  ~<value>)    ; the NOT operator

    (<relation>  <value1>|<value2>)    ; the OR operator

    (<relation>  ~<value1>&~<value2>)    ; the AND operator



The AND operator is typically used only in conjunction with the other
logical operators or variable bindings. Variable binding may be used along
with logical operators.



More Syntax:



    (<relation>  ?x&<value1>|<value2>)    ; the OR operator with variable

    (<relation>  ?x&~<value>)    ; the NOT operator with variable



If this is the first occurrence of the variable name, then the field will be
constrained according to the logical operators only. The resulting value will
be stored in the variable. If the variable has been previously bound, then it
is considered an additional constraint along with the logical operators, i.e.
the field must have the same value already bound to the variable and it must
additionally match the constraints defined by the logical operators.



Examples:

  Pattern on LHS of rule              Fact in the fact-list
Matches?

    (foo ~bar)    (foo bar)    N

    (foo ~bar)    (foo mumble)    Y



    (foo bar|dig)    (foo bar)    Y

    (foo bar|dig)    (foo dig)    Y

    (foo bar|dig)    (foo mumble)    N



    (foo ~bar&~dig)    (foo bar)    N

    (foo ~bar&~dig)    (foo dig)    N

    (foo ~bar&~dig)    (foo mumble)    Y



    (foo ~bar&dig|get)    (foo bar)    N

    (foo ~bar&dig|get)    (foo dig)    Y

    (foo ~bar&dig|get)    (foo get)    Y

    (foo ~bar&dig|get)    (foo mumble)    N



Examples with variables/single patterns:

   Pattern on LHS        Fact in the fact-list          ?x bound to
Matches?

    (foo ?x&~bar)    (foo bar)    ---    N

    (foo ?x&~bar)    (foo mumble)    mumble    Y



    (foo ?x&bar|dig)    (foo bar)    bar    Y

    (foo ?x&bar|dig)    (foo dig)    dig    Y

    (foo ?x&bar|dig)    (foo mumble)    ---    N











Examples with variables/multiple patterns:

   Pattern on LHS        Fact in the fact-list          ?x bound to
Fires?

(defrule .......

    (foo1 ?x)    (foo1 bar)    bar    N

    (foo2 ?x&~bar)    (foo2 bar)

    => ......



(defrule .......

    (foo1 ?x)    (foo1 bar)    bar    N

    (foo2 ?x&~bar)    (foo2 mumble)

    => ......



(defrule .......

    (foo1 ?x)    (foo1 dig)    dig    Y

    (foo2 ?x&~bar)    (foo2 dig)

    => ......



(defrule .......

    (foo1 ?x)    (foo1 bar)    bar    Y

    (foo2 ?x&bar|dig)    (foo2 bar)

    => ......



(defrule .......

    (foo1 ?x)    (foo1 bar)    bar    N

    (foo2 ?x&bar|dig)    (foo2 dig)

    => ......



(defrule .......

    (foo1 ?x)    (foo1 mumble)    mumble    N

    (foo2 ?x&bar|dig)    (foo2 mumble)

    => ......





3.5.2  Predicate Functions

Sometimes it becomes necessary to constrain a field to more complex
values than can be defined by logic operators. CLIPS allows the use of
predicate functions to accomplish this. Predicate functions check to see
if the value of the field meets the constraints defined in the function. If it
does, the function returns true (non-zero) and pattern matching continues.
Otherwise, it returns false (0) and the pattern fails to match. Predicate
functions are called with a special form of the AND operator (&:). The value
of the field must be bound to a variable and passed to the function.





Syntax:



    (<relation> ?x&:(<function> <<arguments>>))



Multiple predicate functions may be used to constrain a single field. They
are evaluated from left to right. A number of predicate functions are
provided by CLIPS and users may also develop their own predicate functions.
Predicate functions operate on the value attempting to be matched or may
have arguments passed to them. The predicate functions provided by CLIPS
are:



    Function    Purpose

    (numberp <arg>)    Is the value a number?

    (stringp <arg>)    Is the value a string (non-number)?

    (evenp <arg>)    Is the value an even number?

    (oddp <arg>)    Is the value an odd number?



User defined predicate functions must take arguments as defined in Section
5.2 and should return zero (0) for false and a non-zero number for true.



In addition to these functions, any defined function may be used as predicate
function, though only the comparison functions are generally meaningful.
Use of defined functions as predicates will be described with examples in
section 3.6. A complete list of defined functions can be found in Appendix A.



Examples:

  Pattern on LHS of rule              Fact in the fact-list
Matches?

    (foo ?x&:(numberp ?x))    (foo 2)    Y

    (foo ?x&:(numberp ?x))    (foo bar)    N



    (foo ?x&:(stringp ?x))    (foo 2)    N

    (foo ?x&:(stringp ?x))    (foo bar)    Y





3.6    test Function

The field functions allow very descriptive constraints to be applied to
pattern matching. An additional constraint capability is provided with the
test function. With test you can compare the variable bindings that have
already occurred in any manner. You can do mathematical comparisons on
variables (e.g. is the difference between ?x and ?y greater than some
value?), you can do complex logical or equality comparisons, or you can call
external functions which compare variables in any way the user desires.





Any kind of defined functions (see section 4.6) may be embedded within a
test operation. All defined functions use the prefix notation, so the operands
to a test function always appear after the function name. A number of
logical, comparison, and arithmetic functions are provided by CLIPS.



Syntax:



    (test    (<defined-function> <<arguments>>))



Test functions can be nested and are evaluated from the inside out. The
functions inherit their syntax and terminology from both LISP and C. They
are:



Symbol    Function      Use    Means
                              Logical

       !         not (inverse)    logical       -

        &&        and     logical        -

        ||        or     logical        -



                           Comparison

       =         equal (numeric)    (test (= ?x ?y))    ?x = ?y

    eq    equal (any)    (test (eq ?x ?y))    ?x eq ?y

        !=        not equal     (test (!= ?x ?y))    ?x - ?y

        >=        greater than or equal     (test (>= ?x ?y))    ?x >= ?y

        >         greater than     (test (> ?x ?y))    ?x > ?y

        <=        less than or equal     (test (<= ?x ?y))    ?x <= ?y

        <         less than     (test (< ?x ?y))    ?x < ?y



                         Arithmetic

        /         division     (test (/ ?x ?y))    ?x / ?y

        *         multiplication     (test (* ?x ?y))    ?x * ?y

        **        exponentiation     (test (** ?x ?y))    ?x^?y

        +         addition     (test (+ ?x ?y))    ?x + ?y

        -         subtraction     (test (- ?x ?y))    ?x - ?y



The comparison functions (=, !=, >=, etc) are only valid for comparing
numeric fields. When checking for equality of strings, the eq comparison
function should be used. eq can compare strings or numbers and will not
produce an error when comparing a string to a number.



Examples:



The following example checks to see if the difference between ?y and ?x is
greater than three.

  Patterns on LHS of rule             Fact in the fact-list
Fires?

(defrule .....

    (foo ?x)    (foo 6)    Y

    (bar ?y)    (bar 9)

    (test (> (- ?y ?x) 3))

    =>  .....



The next example checks to see if there is a positive slope between two
points on a line.



 Patterns on LHS of rule             Fact in the fact-list
Fires?

(defrule .....

    (point ?a ?x1 ?y1)    (point 1 4.00 7.00)    Y

    (point ?b&~?a ?x2 ?y2)    (point 2 5.00 9.00)

    (test (< 0 (/ (- ?y2 ?y1)

                       (- ?x2 ?x1))))

    =>  .....



All defined functions may be used as predicates, although it is usually
meaningful only for the comparison functions.



Examples/multiple patterns:

  Patterns on LHS of rule             Fact in the fact-list
Fires?

(defrule .....

    (foo1 ?y)    (foo1 3)    Y

    (foo2 ?x&:(> ?x ?y))    (foo2 5)

    =>  .....



(defrule .....

    (foo1 ?y)    (foo1 9)    N

    (foo2 ?x&:(> ?x ?y))    (foo2 5)

    =>  .....



(defrule .....

    (foo1 ?y)    (foo1 4)    Y

    (foo2 ?x&:(= ?y ?x))    (foo2 4)

    =>  .....



(defrule .....

    (foo1 ?y)    (foo1 bar)    N

    (foo2 ?x&:(= ?x ?y))    (foo2 5)                    (this is an error!)

    =>  .....





(defrule .....

    (foo1 ?y)    (foo1 "4")    N

    (foo2 ?x&:(= ?y ?x))    (foo2 4)                       (also an error!)

    =>  .....



These last two errors could be handled better as follows:



  Patterns on LHS of rule             Fact in the fact-list
Fires?

(defrule .....

    (foo1 ?y&:(numberp ?y))    (foo1 bar)    N

    (foo2 ?x&:(= ?x ?y))    (foo2 5)                         (not an error)

    =>  .....



or



(defrule .....

    (foo1 ?y)    (foo1 bar)    N

    (foo2 ?x&:(eq ?x ?y))    (foo2 5)                         (not an error)

    =>  .....





3.7  Logical Pattern Blocks

The LHS of CLIPS rules are made up of a series of patterns that represent
the conditions that must be satisfied in order for the rule to be placed on
the agenda. Unless otherwise noted, CLIPS assumes that all rules have an
implicit and surrounding the patterns on the LHS. This means that all
conditions on the LHS must be met before the rule can be activated. There is
no need to explicitly define an implicit and condition. However, it is
possible to change this default and define other combinations of conditions
which would cause a rule to fire. This is done with logical pattern
blocks, which allow patterns to be combined using inclusive or, and
explicit and logic. The entire logic block is treated as a single condition on
the LHS and must be satisfied along with all other conditions before the rule
can fire. Logical blocks may be mixed with other logical blocks in any order
and patterns within the logical block may use field constraints. As with all
CLIPS features, the blocks are marked by opening and closing parentheses.



3.7.1  Inclusive or

The or logical block allows any one of several patterns to trigger a rule
firing. If any of the patterns inside the or block exist, the constraint is
satisfied. If all other LHS conditions are true, the rule will be activated.
Any number of patterns may be within an or block. The exact same effect
could be accomplished by writing multiple rules with similar left and right
hand sides.

Syntax:



    (defrule <name>

        [(<<additional patterns>>)]

        (or    (<<pattern 1>>)

                  %

                  %

            (<<pattern n>>))

        [(<<additional patterns>>)]

        =>

        (<<actions>>))



If more than one of the patterns in the or block can be met, the rule will
fire for each possible combination of conditions.



Example:



    (defrule system-fault

        (error-status unknown)

        (or    (temp high)

            (valve broken)

            (pump off))

        =>

        (printout "The system has a fault." crlf))



Note, the above example could be written as three separate rules:



    (defrule system-fault

        (error-status unknown)

        (pump off)

        =>

        (printout "The system has a fault." crlf))



     (defrule system-fault

        (error-status unknown)

        (valve broken)

        =>

        (printout "The system has a fault." crlf))



    (defrule system-fault

        (error-status unknown)

        (temp high)

        =>

        (printout "The system has a fault." crlf))

 3.7.2  Explicit and

An explicit and is provided to allow the mixing of and and or conditions.
This allows logical combinations of patterns within an or block. The
condition will be satisfied when all the patterns inside the explicit and
block are satisfied (plus any additional patterns). Any number of patterns
may be placed in an and block. Any number of ands may be within an or
block.



Syntax:



    (defrule <name>

        [(<<additional patterns>>)]

        (or    (and    (<<pattern 1>>)

                       %

                      %

                (<<pattern n>>))

            (<<other patterns>>))

        [(<<additional patterns>>)]

        =>

        (<<actions>>))



Example:



    (defrule system-flow

        (error-status confirmed)

        (or    (and    (temp high)

                (valve closed))

            (and    (temp low)

                (valve open)))

        =>

        (printout "The system is having a flow problem." crlf))





3.8  Pattern negation- not

Sometimes, the lack of information is meaningful, i.e. you wish to fire a
rule if a fact does not exist in the fact-list. The not function provides this
capability. As with logic blocks, any number of normal patterns may also be
on the LHS of the rule, and field constraints may be used within the negated
pattern.



Syntax:



    (defrule <name>

        (<<pattern 1>>)

        (not    (<<pattern 2>>))

        [(<<additional patterns>>)]

        =>

        (<<actions>>))



Only one pattern may be negated at a time. Multiple patterns may be negated
by using multiple not statements. And and or logic blocks may not be
placed inside a not pattern, although a not may be placed inside an and or
or. Care must be taken when combining not with or and and blocks; the
results aren't always obvious! The same is true for variable bindings within
a negated pattern. Variables that are previously bound may be used freely
inside a negated pattern. However, variables bound for the first time within
a negated pattern can only be used in that pattern. Since negated facts are
treated specially by CLIPS, users should always perform a reset after
creating or loading rules which include negated patterns.



Example:



    (defrule high-flow-rate

        (temp high)

        (valve open)

        (not    (error-status confirmed))

        =>

        (printout "Recommend closing of valve due to high temp" crlf))



    (defrule check-valve

        (check-status ?valve)

        (not    (valve-broken ?valve))

        =>

        (printout "Device " ?valve " is OK" crlf))



    (defrule double-pattern

        (foo bar)

        (not (foo bar ?x ?x))

        =>

        (printout "No foo bar mumble mumble patterns!" crlf ))



Negating a NOT is illegal, i.e.  (not (not (<<pattern>>))) is not allowed.





3.9  Pattern Bindings

Certain RHS actions, such as retract, can operate on an entire fact. To
signify which fact they are to act upon, a variable can be bound to an entire
fact, as follows:

Syntax:



    ?<var-name><-(<<fields>>)



The left arrow, "<-", is a required part of the syntax.



Example:



    (defrule dummy

        (foo 1)

        ?fact<-(dummy pattern)

        =>

        (retract ?fact))



Section 4: RHS Syntax - Actions



4.1  Assert

Assert allows you to add a fact to the fact-list. Only one fact may be
asserted in each assert statement. However, multiple asserts may be placed
on the RHS of a rule.



Syntax:



    (assert    (<<pattern>>))



The fact asserted may contain bound variables, calls to defined functions,
(see section 4.6), and literals. If an identical copy of the fact already exists
in the fact-list, the fact will not be added.



Example:



    (assert    (foo bar))    ; assert a simple fact



    (defrule close-valve

        (temp ?sensor high)

        (valve ?v open)

        (not    (error-status confirmed))

        =>

        (assert  (Set ?v close))    ;assert a fact with variables

        (printout "Close valve due to high temp" crlf))





4.2  Retract

Retract allows you to remove facts from the fact-list. The fact (or facts)
must have been bound on the LHS as described in section 3.9. Multiple facts
may be retracted with a single retract statement. The retraction of a fact
also removes all rules from the agenda that depended upon that fact for
activation.



Syntax:



    (retract    ?<fact1>[ . . . ?<factN>])



Example:



    (retract ?f1 ?f2 ?f3)



    (defrule change-valve-status

        ?f1<-(valve ?v open)

        ?f2<-(Set ?v close)

        =>

        (retract ?f1 ?f2)

        (assert  (valve ?v close)))





4.3  Printout

Printout allows simple output to the standard output device (usually the
screen). It will evaluate variable bindings and print the value of a variable
in the output string. Any number of variables or strings may be sent for
printout.



Syntax:



    (printout <item> ... <item> [crlf])



Where <item> is a string delimited by double quotes ("), or a bound variable
The word crlf will force a carriage return/newline and may be placed
anywhere in the printout string.



Example:



    (defrule change-valve-status

        ?f1<-(valve ?v open)

        ?f2<-(Set ?v close)

        =>

        (retract ?f1 ?f2)

        (assert  (valve ?v close))

        (printout "The valve " ?v " has been closed" crlf))





4.4  Bind

Occasionally it is important to create new variables or modify the value of
previously bound variables on the RHS of a rule. The bind function provides
this capability for all defined functions (see section 4.6) which return a
value suitable for binding.



Syntax:



    (bind ?<var-name> (<defined-function>))



Where <var-name> must be a variable name (it may have been previously
bound), and valid <defined-functions> will be discussed in section 4.6.



Example:



    (bind ?input (read))



    (bind ?value (+ ?x ?y))





4.5  Pattern Expansion

Sometimes it is preferable to expand a pattern within an assertion. This
can be done with the equals (=) operator. The equals operator allows you to
call a defined function (see section 4.6) inside an assert. The value is
incorporated directly into the pattern at the position the function was
called.



Syntax:



    (assert ([<<fields>>] =(<defined-function> <<args...>>) [<<fields>>])



This is exactly the same as binding a variable to the return from a defined
function using the bind function and then placing the variable inside the
assert.



Example:



    (assert (foo bar =(+ ?x ?y)))



    (defrule user-close-valve

        (goal close valve)

        (input-from user)

        =>

        (printout "Which valve should be closed? ")

        (assert (close-valve =(read))))





4.6  Defined functions

A number of CLIPS actions, such as bind or assert, allow calls to a defined
function. These functions can be defined by the user or provided by CLIPS.
User functions must be defined according to the method described in section
5.0 and variables may be passed to these functions. The function must return
either a pointer to a single string or a floating point number. All defined
functions use the prefix notation, so the arguments always appear after the
function name. Appendix A gives a complete list of defined functions. In
addition to the defined functions used with test, there are functions which
are usually used only on the RHS. These are:



   function    Capability

    read    read input from the keyboard

    gensym    create a random (string) word





4.6.1  read

The read function allows a user to input information for a single field. All
the standard field rules (e.g. multiple words must be embedded within
quotes) apply.



Example:



    (bind ?input (read))



    (assert (new fact =(read) input))





4.6.2  gensym

The gensym function returns a special, sequenced word, typically stored as
a single field. This is primarily for tagging patterns which need a unique
identifier but the user doesn't care what the identifier is. Multiple calls to
gensym are guaranteed to return different identifiers, however, they could
conflict with user defined fields. The gensym returns strings of the form:



genX



where X is a number. The first call to gensym returns gen1, all subsequent
calls increment the number. If users plan to use the gensym feature, they
should avoid creating facts which include a user defined field of this form.



Example:



    (assert (new-id  =(gensym) flag1 7))



which, on the first call, generates a fact of the form:



    (new-id gen1 flag1 7.00)





4.6.3  Functions to operate on Multi-field variables

A number of functions to operate on multi-field variables ($? variables)
will be provided in future releases of CLIPS as defined functions.



Examples using Arithmetic Defined Functions:

A number of the defined functions provide computational capability. They
should only be used on numeric arguments. CLIPS does not check the validity
of the numeric operation, so the user is responsible for preventing error.



    (bind ?var (/ ?x ?y))    ;means ?var = ?x / ?y



    (bind ?var (* ?x ?y))    ;means ?var = ?x * ?y



    (bind ?var (** ?x ?y))    ;means ?var = ?x^?y



    (bind ?var (+ ?x ?y))    ;means ?var = ?x + ?y



    (bind ?var (- ?x ?y))    ;means ?var = ?x - ?y



The examples all use the bind function, but arithmetic function calls can be
used anywhere a defined function is valid.





4.7  Call

The defined functions discussed in Section 4.6 are usually called for their
return value. Effect functions are called for effect only. The call function
allows this capability from the RHS of a rule. Effect functions should be
written in C and must follow the conventions described in Section 5.0.
Arguments may be passed to the functions within the limitations described
in that section.



Syntax:



    (call (<function-name> [<<args...>>]))



Functions called in this manner must be called for effect only. The return
value will not be captured.



Example:



     (defrule display-valve-system

        (valve ?v1 open)

        (valve ?v2&~v1 closed)

        =>

        (call (display-valves ?v1 ?v2)))



CLIPS provides one pre-defined effect function, called setgen.





4.7.1  setgen

The setgen function allows the user to set the starting number used by
gensym (see section 4.6.2).



Syntax:



    (call (setgen <num>))



where <num> must be a positive integer value. All subsequent calls to
gensym will return a sequnced word with the numeric portion of the word
starting at <num>.



Example:



    (call (setgen 32))    ; calls to gensym will return
                    ;   gen32, gen 33, etc.





4.8  If...then...else

Under certain circumstances, it is preferable to take actions based on
parameter testing on the RHS of a rule instead of writing two rules. CLIPS
provides an if...then...else structure to allow this kind of operation.



Syntax:



    (if (<defined-function> <<args...>>)

     then

        (<<action 1>>)

            %

        (<<action n>>)

    [else

        (<<action 1>>)

            %

        (<<action n>>)])



Any number of allowable RHS actions may be used inside the then or else
section, including another if...then...else structure. The else portion is
optional. All defined functions are available for use in this structure and are
used as they are in test. Variables used in the comparison must have been
previously bound.



Example:



    (defrule closed-valves

        (temp high)

        (valve ?v closed)

        =>

        (if (= ?v 6)

         then

            (printout "The special valve " ?v " is closed!" crlf)

            (assert (some special operation))

         else

            (printout "Valve " ?v " is normally closed" crlf)))





4.9  While

The while structure is provided to allow simple looping on the RHS of a
rule. Its use is similar to that of if...then...else:



Syntax:



    (while (<defined-function> [<<args...>>])

        (<<action 1>>)

            %

        (<<action n>>))



Again, all defined functions are available for use in while. Any number of
allowable RHS actions may be placed inside the while block, including
if...then...else or additional while structures.



Example:



    (defrule open-valves

        (valves-open-through ?v)

        =>

        (while (> ?v 0)

            (printout "Valve " ?v " is open" crlf)

            (bind ?v (- ?v 1))))





Section 5: Integrating CLIPS with External Functions



A user can define external functions for use on both the LHS and the RHS of
rules. If a defined function is to be used as a predicate, it must return a
floating point number. All other defined functions must return either a
string or a floating point. Effect functions are called merely for effect
and their return value is not of concern. Both defined functions and
effect functions are described to CLIPS in the same way. Since C is the
only external language currently supported, all of the examples are in C.





5.1  Declaring User Defined External Functions to CLIPS

A function called usrfuncs must be included inside the user's source code.
This function should call the define_function routine for every function
the user wants CLIPS to know about. The user's source code is then compiled
and linked with CLIPS.



A sample usrfuncs declaration follows:



usrfuncs()

   {

    define_function("fun",'s',fun);

    define_function("dummy",'i',my_dummy);

    /* Additional define function statements could go here. */

   }



The first argument to define_function is the CLIPS name, a string
representation of the  name that will be used inside CLIPS rules. The second
argument is the return type where 'i' = integer, 'f' = float, 'c' = character,
and
's' = pointer to character.  The third argument is a pointer to the actual
function, the compiled function name. The string representation (first
argument) need not be the same as the actual function name (third
argument).



User defined functions are searched before system functions. If the user
defines a CLIPS name which is the same as one of the defined functions
already provided, the user function will be executed in its place. Appendix A
contains a list of the defined functions provided by CLIPS.





5.2  Passing variables from CLIPS to External Functions

Although arguments are listed directly following a function name inside
CLIPS rules, CLIPS will call the function without any arguments. Instead,
the parameters are stored in internal CLIPS arrays and can be accessed by
calling the functions:



    int num_args();

    char *rstring(<arg>);

    float  rfloat(<arg>);



A call to num_args() will return an integer telling how many arguments the
function was called with. A call to rstring() returns a character pointer, and
rfloat() returns a floating point number. The parameters have to be
requested by the called function one at a time. This is done by specifying the
parameter position number as the <arg> to rstring() or rfloat().



Example:



(assert (foo bar =(fun ?x "wow" 18.9))



The function fun() would look something like this:



#include "clips.h"    /* this declaration should appear on     */

        /* top of each of your "C" source files. */



char *fun()

   {

    char *arg1;

    char *arg2;       /* pointers to characters, arrays */

    float arg3;        /* floating point argument.          */

    int num_passed;



    num_passed = num_args();    /*  find out how many args where passed */

     %

    %

    arg1 = rstring(1);     /* ask for the first argument */

    arg2 = rstring(2);     /* and for the second one.      */

    arg3 = rfloat(3);     /* and the third is a float      */

    %

    %

    return("sample text");    /* returns a string */

   }



Note that rfloat() is called with a 3 for the third parameter, even though it
is the first floating point number accessed. Also, fun() should be defined in
usrfuncs().



5.3  Passing data from an External Function to CLIPS

An external function can assert a new fact into the CLIPS fact-list.  This is
done by specifying a global C function declaration:



FACT *assert();



To assert a fact from the user function, simply call assert():



assert("string");



where "string" is a single string made up of floating point numbers and
words. The return value is variable of type FACT, which can not be used in
any meaningful way, as of yet. Future functions may be able to use this
information.



Examples:



   assert("99 is a number");

   assert("Hello there");

   assert("10 plus two is 12");



To construct a string based on variable data, use sprintf:



char string[50];

sprintf(string,"valve %f %s",number, char_pointer);

assert(string);



5.4  Extended Function Libraries for CLIPS

The method used by CLIPS to incorporate user defined functions allows the
creation of whole libraries of external functions; making CLIPS highly
extensible. An example of such an extended package is included with the
CLIPS source. This example adds a number of math and trigonometric
functions to CLIPS for use as defined functions. Users who wish to create
other extended packages for CLIPS should follow the style shown in the
math package. Documentation should be included demonstrating how to use
the functions and also how to install them.



Section 6: Using CLIPS



CLIPS expert systems may be executed in two ways; interactively using a
simple, line type interface, or as embedded expert systems in which the
user provides a main program and controls execution of the expert system
as part of a sequential program.



6.1  Interactive Interface Commands

CLIPS provides a simple, interactive, line type interface for high
portability. The standard usage is: Create or edit rules using any standard
text editor and save the file(s) as a text file. Exit the editor and execute
CLIPS. Load rule file(s) into CLIPS. The interface provides commands for
viewing the current state of the system, tracing execution, adding or
removing information, or clearing CLIPS.  Following is a list of all the
available CLIPS interface commands:



CLIPS Environment Commands

(reset)    Resets the database. Removes all activations from the
agenda and all facts from the database, and asserts all
facts listed in deffacts statements into the database.



(clear)    Removes all rules and deffacts from the environment.
Removes all activations from the agenda and all facts
from the database.



(run [<run-limit>])    Starts execution of the rules.  If <run-limit> is
specified, execution will cease after <run-limit> rule
firings or when the agenda contains no rule
activations, otherwise execution will cease when the
agenda contains no rule activations.

    Example: (run 3)



(load <file-name>)    Loads the rules stored in the file specified by
<file-name> into the environment.

    Example:  (load "rules.txt")



(save <file-name>)    Saves all of the rules in the current environment into
the file specified by <file-name>.

    Example:  (save "rules.txt")





CLIPS System Status Commands

(facts)    Displays all facts stored in the fact-list.



(rules)    Displays the names of all rules stored in the database.



(agenda)    Displays all activations on the agenda.



(pprule <rule>)    Displays the text of the rule named <rule>.

    Example:  (pprule bogus-name)



CLIPS Debugging Commands

(watch <item>)    If <item> is facts, all fact assertions and retractions
will be displayed.  If <item> is rules, all rule firings
will be displayed.  If <item> is activations, all rule
activations and deactivations will be displayed.

    Example:  (watch rules)



(unwatch <item>)    Deactivates the watch command for <item>.

    Example:  (unwatch facts)



Additional CLIPS Commands

(assert <fact>)    Asserts <fact> into the database.

    Example:  (assert (this is a fact))



(retract <fact#>)    Retracts the fact number <fact#> from the database.

    Example:  (retract 1)



(excise <rule>)    Remove the rule named <rule> from the system without
changing anything system state.



(undeffacts <name>)    Reverse the affect of a deffacts statement. All facts
listed in the deffacts construct named <name> will no
longer be put into the initial fact-list after a reset.



Defrule and deffacts blocks, as defined in Section 2, may also be entered at
top level of the interactive interface.





6.2    Embedded CLIPS Commands

CLIPS can be embedded within other programs. In fact, it is relatively
simple. To embed CLIPS, add this include statement to your main program
file:



#include <clips.h>



(This will have to be tailored so that the compiler on your system can find
the CLIPS include file.) Your main program must initialize CLIPS by calling
the function init_clips() sometime prior to loading rules. Also,
usrfuncs() must be defined if CLIPS calls any external functions. Compile
and link all your code with all CLIPS files EXCEPT the CLIPS main.o.



Within your program, several functions are available to set up and control
CLIPS:





init_clips()    Initializes the CLIPS system. Must be called prior to
any other CLIPS function call. No meaningful return
value.



run(<run_limit>)    Fires <run_limit> number of rules, which should be an
integer. If <run_limit> is minus one (-1), then rules
will fire until the agenda is empty. Returns an  integer
value: the number of rules that were fired.



clear_clips()    Clears the CLIPS environment. No meaningful return
value. See clear in section 6.1.



reset_clips()    Resets the CLIPS environment. No meaningful return
value. See reset in section 6.1.



load_rules(<file>)    Loads a set of rules into the CLIPS database. Returns
an integer value. If positive, value is the number of
constructs (defrules and deffacts) loaded. If negative,
then an error was encountered during the load process.
If an error is encountered, load_rules will still
attempt to read the entire file.



assert(<pattern>)    Asserts a fact into the CLIPS fact-list. <pattern> must
be a pointer to a string, as discussed in section 5.3. It
returns a pointer to a FACT structure, which is not
very meaningful externally.



Appendix A: Defined Functions Provided by CLIPS



The following table lists all the defined functions provided by CLIPS along
with examples of their use.



Symbol    Function      Use    Means
                              Logical

       !         not (inverse)    logical       -

        &&        and     logical        -

        ||        or     logical        -



                           Comparison

       =         equal (numeric)    (test (= ?x ?y))    ?x = ?y

    eq    equal (all)    (test (eq ?x ?y))    ?x eq ?y

        !=        not equal     (test (!= ?x ?y))    ?x - ?y

        >=        greater than or equal     (test (>= ?x ?y))    ?x >= ?y

        >         greater than     (test (> ?x ?y))    ?x > ?y

        <=        less than or equal     (test (<= ?x ?y))    ?x <= ?y

        <         less than     (test (< ?x ?y))    ?x < ?y



                         Arithmetic

        /         division     (test (/ ?x ?y))    ?x / ?y

        *         multiplication     (test (* ?x ?y))    ?x * ?y

        **        exponentiation     (test (** ?x ?y))    ?x^?y

        +         addition     (test (+ ?x ?y))    ?x + ?y

        -         subtraction     (test (- ?x ?y))    ?x - ?y



                          Predicate

    Function           Use    Means

    (numberp <arg>)    (foo ?x&:(numberp ?x))    Is the value a number?

    (stringp <arg>)    (foo ?x&:(stringp ?x))    Is the value a string?

    (evenp <arg>)    (foo ?x&:(evenp ?x))    Is the value an even number?

    (oddp <arg>)    (foo ?x&:(oddp ?x))    Is the value an odd number?





=   is for comparison between numbers

eq is for any kind of comparison

Appendix B: Installing CLIPS



CLIPS was designed for portability. To this date, CLIPS has been installed on
over half a dozen kinds of computers with only minor modifications to the
source code. In many cases, no modifications were required. It should run on
any system which supports a full Kernighan and Ritchie C compiler. The beta
release of the source code is available from the Mission Planning and
Analysis Division's Artificial Intelligence Section until August 1986. All
future releases will be available through COSMIC. Only the source code files
are provided. Installing the executable version is up to the user. This section
describes a step by step plan of how to do so in a fairly generic manner.



1)    Load the source code onto your system

    The following C source files are necessary to set up the CLIPS system:



        clips.c    main.c    npsr.c

        usrint.c    parser.c    sysdep.c

        structdef.h    constdef.h    clips.h



2)    Modify all include statements

    Any include statements in each of the ".c" files, of the form:



    #include "constdef.h"

      #include "structdef.h"

    #include "clips.h"



    may have to be changed to match the way your compiler searches for
include files.



3)    Compile all of the ".c" files to object code

    The ".h" files are include file used by the other files and do not need to be
compiled.



4)    Create the interactive CLIPS executable element

    To create the interactive CLIPS executable, link together all the object
files. This executable will provide the interactive interface defined in
section 6.1. If user defined functions are needed, compile the source code
for those functions and modify the usrfuncs definition in main.c to
reflect your functions. Link your object files with the rest of the CLIPS
files and the modified main file to create an interactive CLIPS with
external user functions.





5)    (optional) Create an embedded CLIPS executable element

    To create an embedded CLIPS, remove the object file "main.o" from the
link list and instead link with your own main function. Be sure to follow
the guidelines discussed in section 6.2 for embedded CLIPS applications.



6)    Test the executable version

    The executable version of CLIPS can be tested as follows: execute CLIPS
in the interactive mode, load the MAB.CLP file, reset and run. The monkey
should eat the banannas if CLIPS is working properly.



The sysdep.c source file contains some potentially system dependent code.
Functions are provided, for example, to allow for timing. The default
settings within sysdep.c are settings which should run on any computer.  You
may wish to change sysdep.c to customize it for a specific computer.
Eventually, stub functions may be included in this file to support features
like windowed interfaces, mouse support, or other fancy, machine dependent
features.



Special Installation notes

CLIPS was designed for portability and strictly follows the K&R definition
of the language. The one exception to this is in variable and function names.
To improve code readability, we have used fairly lengthy (more than 8
characters) variable names. Every compiler we have used supports this.
However, some compilers need a special option turned on during compilation.
If your compiler does not default to long variable namnes (at least 14
characters) then that option needs to be turned on during compilation.



Another potentially important note. Some microcomputer compilers support
either large or small memory compilation. CLIPS should always use the
large memory option.



The memory allocation functions are included in the sysdep.c file because
experience has shown that this is an area which may benefit from
customization. Some compilers provide lower level memory allocation than
malloc. Changing the malloc and free calls in sysdep.c to those specific
for your system may provide significant performance benefits.



Any undocumented features (bugs) should be brought to the attention of



      Gary Riley or Chris Culbert

      NASA/Johnson Space Center

      Mission Planning & Analysis Division

      Artificial Intelligence Section - FM72

      Houston, Texas   77058

Appendix C: Performance Notes



CLIPS is a rule language based on the Rete algorithm. The Rete algorithm
was specifically designed to provide very efficient pattern matching. CLIPS
has attempted to implement this algorithm in a manner which combines
efficient performance with powerful features. When used properly, CLIPS
can provide very reasonable performance, especially on powerful computers.
However, to use CLIPS properly requires some understanding of how the
pattern matcher works.



Prior to beginning execution, each rule is loaded into the system and a
network of all the patterns which appear on the LHS of any rule is
constructed. As facts are asserted into the fact-list, the facts are filtered
through the pattern network. If the form of the pattern (number of fields and
literal fields) matches any of the patterns in the network, the rule(s) with
that pattern are partially instantiated. When facts exist which match all the
patterns on the LHS of the rule, then variable bindings (if any) are
considered. They are considered from the top to the bottom, i.e. the first
pattern on the LHS of a rule is considered, then the second, and so on. If the
field values for all patterns are consistent with the constraints applied to
the variables, then the rule(s) are activated and placed on the agenda.



This is a very simplistic description of what occurs in CLIPS, but it gives
the basic idea. A number of important considerations come out of this. Basic
pattern matching is done by filtering through the pattern network. The time
involved in doing this is fairly constant. The slow portion comes from
comparing variable bindings across patterns. Therefore, the single most
important performance factor is the ordering of patterns on the LHS of the
rule. Unfortunately, there are no hard and fast methods which will always
order the patterns properly. At best, there seem to be three "quasi" methods
for ordering the patterns:



1)    Most specific to most general. The more wildcards or unbound variables
there are in a pattern, the lower it should go. If the rule firing can be
controlled by a single pattern, place that pattern first. This technique is
often used to provide control structure in an expert system, i.e. some
kind of "phase" fact. Putting this kind of pattern first will guarantee that
the rest of the rule will not be considered until that pattern exists. This
is most effective if the single pattern is a literal pattern. If multiple
patterns with variable bindings control rule firing, then arrange the
patterns so that the most important variables are bound first and then
compared as soon as possible to the other pattern constraints.



2)    Patterns with the lowest number of occurrences in the fact-list should
go near the top. A large number of patterns of a particular form in the
fact-list cause can cause numerous partial instantiations of a rule which
have to be "weeded" out by comparing the variable bindings, a slower
operation.



3)    Volatile patterns (ones that are retracted and asserted continuously)
should go last, particularly if the rest of the patterns are mostly
independent. Every time a fact is asserted, it must be filtered through
the network. If it causes a partial rule instantiation, the variable
bindings must then be considered. By putting volatile patterns last, the
variable bindings will only be checked if all the rest of the patterns
already exist.



These rules are not independent and commonly conflict with each other. At
best they provide some rough guidelines. Since all system have these
characteristics in different proportions, it is not evident at a glance what
the most efficient manner of ordering patterns for a given system is. The
best approach is to develop the rules without considering ordering. When the
reasoning is fairly well verified, then experiment with the patterns until
the optimum configuration is found.



Another performance issue is the use of multi-field variables and wildcards
($?). Although they provide a powerful capability, they must be used very
carefully. Since they can bind to zero or more fields, they can cause
multiple instantiations of a single rule. In particular, the use of multiple
multi-field variables in one pattern can cause a very large number of
instantiations (see example, section 3.3).



Some final notes on performance: Our experience suggests that you should
keep the expert system "lean and mean". Don't use the fact-list as a
database for storage of extraneous information. Store and pattern match
only on that information necessary for reasoning. Keep the pattern matching
to a minimum and be as specific as possible. Lots of short, simple rules
perform better than long, complex rules.







Appendix D: Glossary



This section defines some of the terminology used throughout this manual.



activation

    A rule is activated if all it's conditions are satisfied and it is ready to
fire. An activated rule is placed on the agenda.



agenda

    The agenda is a list of all the rules that are presently ready to fire. It
is sorted by salience values. When a rule is activated, it is placed in
front of all the rules that have salience values less than or equal to
its own. The rule at the front of the agenda is the next rule that will
fire.



defined function

    A special class of external function, defined by the user or provided by
CLIPS. These functions are called for their return value and must
return a valid CLIPS data type (floating point number or string
pointer).



effect function

    A special class of external function, defined by the user of provided by
CLIPS. These functions are called for side effect only. They are called
from the RHS using call.



external function

    A function defined by the user or provided by CLIPS and called from
within CLIPS rules. One of two types, defined functions or effect
functions.



fact

    A set of words (strings or numbers) separated by spaces. Facts can
have any number of fields and can be in any order. Facts are the data
which the expert system reasons about. Facts represent the current
state of the world.



field

    A single word in a fact. Must be either a string or a number.



fire

    A rule is said to fire if all it's conditions are satisfied and the actions
are executed.

Appendix E: Glossary (cont'd)



instantiated

    The pattern or variable has matched successfully against a fact or
field.



LHS

    Left Hand Side: The logical pattern structure that must be satisfied in
order for the RHS's actions to be performed.



pattern

    A fact. (see fact)



RHS

    Right Hand Side: The actions to be performed when a rule's LHS is
satisfied.



rule

    A collection of patterns and actions. When all patterns are satisfied,
the actions will be taken. Rules are the basic unit of knowledge in
CLIPS.



salience

    A priority number given to a rule.  When multiple rules are ready for
firing, they are fired in order of priority. The default salience is zero
(0).