Basic PowerLoom® Commands

This example explains some fundamental PowerLoom commands and concepts that will be referred to throughout the various examples. It is probably the best starting point to learn how to use PowerLoom.

    Welcome to PowerLoom 3.0.1.beta

Copyright (C) USC Information Sciences Institute, 1997-2003.
PowerLoom is a registered trademark of the University of Southern California.
PowerLoom comes with ABSOLUTELY NO WARRANTY!
Type `(copyright)' for detailed copyright information.
Type `(help)' for a list of available commands.
Type `(demo)' for a list of example applications.
Type `bye', `exit', `halt', `quit', or `stop', to exit.

|= (demo 1)

Now reading from `PL:sources;logic;demos;basics.ste'.
Type `?' at the pause prompt for a list of available commands.

;;; -*- Mode: Lisp; Package: STELLA; Syntax: COMMON-LISP; Base: 10 -*-

;;; Version: basics.ste,v 1.12 2003/04/01 01:12:10 hans Exp

;;; The Basics: simple definition, assertion, retrieval, and retraction.
;;; ====================================================================

;;; This demo file explains some fundamental PowerLoom commands and
;;; concepts that will be referred to throughout the various example
;;; demos.  It introduces name spaces, commands to define concepts and
;;; relations in these name spaces, assertion and retraction as well
;;; as basic query commands to inspect the content of a knowledge base.
;;; This file is probably the best starting point to learn how to use
;;; PowerLoom.  The best way to view this file is by calling `(demo)'
;;; and selecting it from the menu of example demos.

;; The `in-package' declaration is optional and will be ignored by PowerLoom.
;; Its main purpose is to tell your Emacs-to-Lisp interface what package to
;; use for this file (in case it cannot derive the same information from the
;; mode line).

|= (in-package "STELLA")
------ pause ------c

;; Modules provide name spaces for concepts, functions, relations,
;; regular instances, etc.  They also provide assertion spaces for
;; logical assertions.  Modules are organized hierarchically.  Each
;; module has a possibly empty set of parent or "included" modules,
;; and a possibly empty set of "used" modules.  The only difference
;; (currently) between "included" and "used" modules is that use-links
;; are only followed one level deep (this allows circular dependencies
;; where two modules can use each other).  Each module can see all the
;; names, their associated objects and assertions of all its parent
;; and used modules as well as of all of their parents, etc.  A module
;; can also shadow inherited names and provide its own definitions for
;; them.

;; The default module for PowerLoom users is called `PL-USER'.  Each
;; demo file uses its own module to avoid interference with other
;; demos (all demo modules are organized as siblings which have
;; `PL-USER' as their common parent module).  Similar to a Lisp
;; package, a module has to be defined with `defmodule' first before
;; it can be used.

;; Below we define the module `BASICS' as a child of `PL-USER'.
;; Module names use a syntax similar to Unix pathnames to express
;; parent/child relationships.  The name `/PL-KERNEL/PL-USER/BASICS'
;; identifies the module `BASICS' whose parent is `PL-USER' whose
;; parent in turn is PL-KERNEL.  For modules with a single parent it
;; suffices to use the qualified name to identify the parent of the
;; new module:

|= (defmodule "/PL-KERNEL/PL-USER/BASICS")


;; The command above returned the generated module object as its
;; result value.  Such objects are usually printed with a prefix that
;; indicates the object's type followed by the name or some other
;; description of the object.  For modules the prefix is `|MDL|'
;; which is folled by the name of the module.

;; Modules remember their definition options, and redefinitions with
;; the same set of options are treated as no-ops.  Thus, the definition
;; below simply returns the previously created module:

|= (defmodule "/PL-KERNEL/PL-USER/BASICS")


;; An alternative method for specifying parents is to use the
;; `:includes' keyword (for multiple parents this is the only way to
;; do so).  Below we redefine the `BASICS' module in this way:

|= (defmodule "BASICS"
  :includes ("PL-USER"))


;; If a module name is unique in the current set of modules, it can be
;; used by itself to identify a module instead of having to use a
;; fully qualified pathname.  This is the reason why above we could
;; simply write `PL-USER' to identify the parent module of the
;; `BASICS' module.  Similarly, we could have used the following
;; relative pathname to define the module:

|= (defmodule "PL-USER/BASICS")


;; Every PowerLoom file has to have exactly one `in-module'
;; declaration.  All unqualified definitions and references (i.e.,
;; those with names not qualified by a module pathname) will be
;; processed with respect to that module.  The only command permitted
;; before an `in-module' declaration is `defmodule'.

|= (in-module "BASICS")

;; First, we clear the module to remove any information accumulated
;; from any previous runs.  The `clear-module' command eliminates
;; all locally defined names, their associated objects and any assertions
;; made about them:

|= (clear-module "BASICS")

;; We reset the PowerLoom features to their default settings to avoid
;; interference with features set by the user or by other demos:

|= (reset-features)


;; `in-dialect' declares the logic dialect assumed for the parsing of
;; logical expressions.  There can be multiple `in-dialect'
;; specifications in a file.  The default logic dialect is `KIF'.

|= (in-dialect KIF)


;; `help' provides a simple on-line command documentation facility.
;; For example, the following invocation provides help about the
;; `assert' command:

|= (help assert)

ASSERT ((proposition OBJECT)):
  Assert the truth of `proposition'.  Return the asserted proposition object.
  KIF example:  "(assert (happy Fred))" asserts that Fred is indeed happy.
  Note that for this assertion to succeed, the relation `happy' must already
  be defined.  If the constant `Fred' has not yet been created, it is
  automatically created as a side-effect of calling `assert'.

;; Calling `help' without any arguments lists all available commands
;; with a short description of each.  In Lisp, one can also get
;; information about a command by looking up its documentation string,
;; e.g., with the help of an Emacs-to-Lisp interface.

|= (help)

The following commands are available (type `(help +)'
to get command-specific documentation):

  Add a query and score pair to the master list of 
  Add a query and score pair to the master list of 
  Return a cons list of all definite (TRUE or FALSE) propositions
  that reference the instance `instanceRef'.
  This is a generalization of `all-facts-of' (which see).
  Return a list of sentences describing facts about 'instanceRef'.
  Perform inference to determine whether the proposition specified in
  `proposition&options' is true.
  Similar to `ask' (which see), but return the highest partial match score
  for the supplied proposition instead of a truth value.
  Assert the truth of `proposition'.  Return the asserted proposition object.
  Evaluate `query', instantiate the query proposition for each generated
  solution and assert the resulting propositions.
  Set the truth value of the rule named 'ruleName' to 
  Return a list of all definite (TRUE or FALSE) propositions
  that reference the instance `instanceRef'.
  Change the current context to the one named `name'.
  Classify instances visible in `module'.
  Classify named relations visible in `module'.
  Destroy all instances belonging to module `name' or any of its children.
  Destroy all objects belonging to module `name' or any of its children.
  Guess whether 'formula' represents a term or a sentence/proposition.
  `tree' is a term expression (a string or an s-expression),
  or is a class reference (a symbol or surrogate).
  Print detailed PowerLoom copyright information.
  Create a logic object with name 'name' and return it.
  Return the current inference level that is active in the
  current query, the current module, or, otherwise, globally.
  Define (or redefine) a concept.
  Define (or redefine) a logic function.
  Define (or redefine) a logic instance (`definstance' is an alias
  for `defobject' which see).
  Define (or redefine) a module named `name'.
  Define (or redefine) a logic instance.
  Define (or redefine) a named proposition.
  Define (or redefine) a logic relation.
  Define (or redefine) a named rule (`defrule' is an alias
  for `defproposition' which see).
  Delete the list of rules associated with `relation'.
  Read logic commands from a file, echo them verbatimly to standard output,
  and evaluate them just as if they had been typed in interactively.
  Assert the falsity of `proposition'.
  Find an object or proposition as specified by `objectSpec', and destroy all
  propositions and indices that reference it.
  Return the nearest instance with name 'instanceRef'
  visible from the current module.
  Search for a rule named 'ruleName'.
  Return the list of rules associated with `relation'.
  Describe specific commands, or print a list of available commands.
  Change the current logic dialect to `dialect'.
  Change the current module to the module named `name'.
  Return a list containing two lists, a list of currently enabled PowerLoom
  features, and a list of all available PowerLoom features.
  Collect all instances in `module' (or in any module if `module'
  Collect all named description in `module' (or in any module if `module'
  Return a list of as yet undefined concepts and relations in `module'.
  Read logic commands from `file' and evaluate them.
  Presume the default truth of `proposition'.
  Print the currently enabled and available PowerLoom environment features.
  Print the list of rules associated with `relation'.
  Finish processing all definitions and assertions that have
  been evaluated/loaded since that last call to 'process-definitions'.
  Trigger constraint propagation over all propositions of module `name'.
  Force non-incremental constraint propagation over all propositions of
  module `name'.
  Reset the PowerLoom environment features to their default settings.
  Retract the truth of `proposition'.
  Retract all definite (TRUE or FALSE) propositions
  that reference the instance `instanceRef'.
  Evaluate `query' which has to be a strict or partial retrieval
  If it is currently TRUE, set the truth value 
  Retrieve elements of a relation (tuples) that satisfy a proposition.
  Partial-match version of `retrieve' (which see) that generates scored
  partial solutions based on the current partial match strategy.
  Run forward inference rules in module 'moduleRef'.
  Run the PowerLoom test suite.
  Save all neural networks to `file' (if `file' is non-NULL).
  Save all definitions and assertions of module `name' to `file'.
  Set number of cycles between which error rates are saved to
  the file established by the last call to `save-all-neural-networks' appended
  with extension `.
  Enable the PowerLoom environment feature(s) named by `features'.
  Set the inference level of `module' to the level specified
  by 'levelKeyword'.
  Sets the number of nearest neighbors to predict from.
  Sets the number of training examples for each case in the training set.
  Set number of cycles between which networks are saved to the
  file established by the last call to `save-all-neural-networks'.
  Retract the truth or falsity of `proposition'.
  Disable the PowerLoom environment feature(s) named by `features'.
  Print an explanation for the result of the most recent query.

Undocumented Commands:


;; PowerLoom uses a first-order logic based on KIF as its primary
;; representation and reasoning substrate.  KIF is the "Knowledge
;; Interchange Format" - see
;;     M.R. Genesereth, "Knowledge interchange format." In J. Allen,
;;     R. Fikes, and E. Sandewall, editors, Proceedings of the 2nd
;;     International Conference on Principles of Knowledge Representation
;;     and Reasoning, pages 599-600, Morgan Kaufmann Publishers, 1991.

;; PowerLoom also has various extensions beyond standard first-order
;; logic such as type-level and limited second-order reasoning,
;; selective closed-world reasoning, as well as some features such as
;; a description classifier that are usually only found in description
;; logics.

;; With PowerLoom domains are modeled in terms of objects of different
;; types and the relations that hold between them.  Additionally,
;; rules such as "every parent has at least one child" can be used to
;; express the semantic structure of the domain.  Such rules can in
;; turn be exploited by the inference engine to derive various logical
;; conclusions.

;; Object types can be defined with the `defconcept' command.
;; Concepts are defined with an optional variable list containing one
;; variable.  Variables in PowerLoom all start with a question mark
;; (?)  character.  That variable can be typed with another parent
;; concept name, in which case the concept will be a subconcept of
;; that parent.  Additional options are introduced by keyword/value
;; pairs defining various things such as documentation, axioms etc.
;; All keywords begin with a colon (:) character.  For example, the
;; definition below defines the `Person' concept.  Once a concept has
;; been defined, we can define instances or members such as `Fred'.
;; Note that we will often use the terms `concept', `type' or `class'
;; interchangably to mean the same thing.

;; Similar to many other PowerLoom commands, `defconcept' returns the
;; generated concept object which is printed with a `|c|' prefix
;; followed by its name:

|= (defconcept Person (?p)
  :documentation "The class of human beings.")


;; `assert' asserts the truth of a proposition.  The two assertions
;; below state that `Fred' and `Joe' are instances of the concept
;; `Person'.  Such type assertions also serve the purpose of
;; introducing new individuals.  For example, since the constants
;; `Fred' and `Joe' have not been mentioned before, two new logic
;; objects with type `Person' will be created.  Subsequent references
;; to `Fred' and `Joe' will be about these two logic objects.

;; `assert' returns the proposition objects it created which are
;; printed with a `|P|' prefix followed by a description of the
;; proposition in the current logic dialect (KIF):

|= (assert (Person Fred))


|= (assert (Person Joe))


;; PowerLoom relations are used to express relationships between
;; objects, to specify properties of objects, their attributes, etc.
;; Relations allow multiple values, whereas functions allow only
;; single values.

;; Relations are defined with PowerLoom's `defrelation' command.  For
;; example, below we define the unary relation `happy' and the binary
;; relation `likes' (higher arity relations are also possible).  Each
;; element in the argument list following the relation name represents
;; one of the relation argments (or a "role").  The number of such
;; arguments determines the relation's arity.

;; Such an argument can be specified either by a simple untyped KIF
;; variable, or, as done below, using the KIF convention of a variable
;; (denoted by a leading question mark) followed by a type indicating
;; the domain of the particular argument.  (Variables become more
;; useful when a definition is supplied.  Definitions are covered in
;; another demo.)  For example, in the `likes' definition we indicate
;; that both arguments are of type `Person'.  Relation definitions
;; return the defined relation object which is printed with an `|r|'
;; prefix followed by the relation name:

|= (defrelation likes ((?p1 Person) (?p2 Person))
  :documentation "True if ?p1 likes ?p2.")


;; The relation `happy' is a unary relation.  Unary relations are
;; similar to concepts, but are normally used to model more transient
;; properties -- thus `Person' is a concept whereas `happy' is a unary
;; relation.  Unary relations can also be thought of as boolean
;; properties of instances.  They are either present or not.

|= (defrelation happy ((?p Person))
  :documentation "True if ?p is happy.")


;; Note that concepts and unary relations are logically equivalent and
;; have the same representation power.  However, they are treated and
;; indexed differently by PowerLoom using the following heuristics:
;; concepts are assumed to model the relatively few, fundamental
;; types of an object that will persist throughout (most of) the
;; lifetime of an object.  Unary relations or properties such as
;; `happy', on the other hand, might change often and every object
;; might have a potentially large number associated with it.

;; Once a relation has been defined, we can assert specific instances
;; of the relation.  For example, to assert that Joe likes Fred's we
;; can use the following assertion:

|= (assert (likes Joe Fred))


;; To assert that Fred is happy we can do this:

|= (assert (happy Fred))


;; Once a PowerLoom knowledge base (KB) has been populated with some
;; assertions we can use its query mechanism to access the content of
;; the KB.  There are two principle ways of querying the KB:
;;    (1) Asking true/false questions with the `ask' command.
;;    (2) Retrieving instances that satisfy a particular predicate
;;        with `retrieve'.
;; `ask' takes a fully ground logical sentence as an argument and
;; tries to determine its truth value relative to the current state of
;; the KB.  For example, we can ask whether Fred is happy with the
;; following query:

|= (ask (happy Fred))

Processing check-types agenda...

;; Let's try to ask the same for Joe:

|= (ask (happy Joe))


;; The previous query returns UNKNOWN, since PowerLoom doesn't know if
;; Joe is happy or not.  Nothing was asserted about Joe's happiness,
;; and there are also no rules that would let us infer the answer.
;; Unlike some other systems, if PowerLoom doesn't know a fact, it
;; does not automatically conclude the fact is false.  This behavior
;; is known as an "open world assumption", i.e., PowerLoom (by default)
;; does not assume to have a complete model of the world or
;; domain that is modeled.  (This is different from the closed world
;; assumption commonly made by deductive databases or Prolog).

;; The results of queries are NOT boolean values, since there are more
;; than just TRUE or FALSE as possible outputs.
;; Instead the return value is of type TRUTH-VALUE, with printing routines
;; setup to print TRUE, FALSE, UNKNOWN, etc.  For use in programs, there are
;; routines in the interface to test for these values.

;; Let us explicitly assert that Joe is not happy:

|= (assert (not (happy Joe)))


;; Now the query will return FALSE:

|= (ask (happy Joe))


;; `retrieve' can be used to retrieve instances or tuples of instances
;; for which a particular predicate is true.  `retrieve' takes a
;; logical sentence with one or more free variables as an argument and
;; tries to retrieve bindings for these variables for which the
;; sentence is true in the KB.  We use the KIF question-mark syntax to
;; indicate the retrieval variables.  An optional first argument
;; indicates how many solutions should be generated.  The special
;; symbol `all' indicates that we want all solutions.  For example,
;; the list of all people can be retrieved with the following query:

|= (retrieve all (Person ?x))

There are 2 solutions:
  #1: ?X=JOE
  #2: ?X=FRED

;; Note, that the bindings found for the variable `?x' above are actual
;; logic objects.  The default interactive print routine for query
;; results is to show the explicit variable bindings on each line.
;; The binding for `?x' prints as the name of the object, but the
;; value is the actual object itself.

;; Let us retrieve who Joe likes:

|= (retrieve all (likes Joe ?x))

There is 1 solution:
  #1: ?X=FRED

;; `retrieve' can also take the list of retrieval variables as an
;; optional argument.  In this case, it is important that they match
;; the free variables in the query sentence.  This is useful if one
;; wants to order the retrieval variables in a different way than they
;; occur in the query sentence.  For example:

|= (retrieve all (?y ?x) (likes ?x ?y))

There is 1 solution:
  #1: ?Y=FRED, ?X=JOE

;; Retrieval variables can also be optionally typed, for example:

|= (retrieve all ((?y Person) (?x Person)) (likes ?x ?y))

There is 1 solution:
  #1: ?Y=FRED, ?X=JOE

;; The previous query is equivalent to the following (note that in
;; this case the `Person' restrictions are redundant, since they
;; simply mirror the domain restrictions of the `likes' relation):

|= (retrieve all (and (Person ?y)
                   (Person ?x)
                   (likes ?x ?y)))

There is 1 solution:
  #1: ?Y=FRED, ?X=JOE

;; If no argument is supplied for the number of desired solutions,
;; only one solution is retrieved.  For example:

|= (retrieve (Person ?x))

There is 1 solution so far:
  #1: ?X=JOE

;; The previous query is equivalent to this one:

|= (retrieve 1 (Person ?x))

There is 1 solution so far:
  #1: ?X=JOE

;; Retrieving a limited number of solutions or just one at a time is
;; useful if that is all that's needed, or if generating all solutions
;; would take a very long time due to a large search space.  Since
;; logical inference can be expensive, PowerLoom generates solutions
;; lazily on demand and does not precompute the full answer set unless
;; the user asked for all solutions.  This is different from standard
;; database API's where a query usually returns a full result set that
;; can then be iterated over.

;; `retrieve' returns a query iterator (or enumerator) object that
;; encodes all necessary state to continue the query and generate
;; additional solutions.  The query results you see are generated by a
;; special print function that displays the set of solutions
;; accumulated so far in the query iterator.  The iterator generated
;; by the most recent query is stored in an internal variable.
;; Subsequent solutions to that query can then be generated by calling
;; `retrieve' without any arguments (or by only supplying a number of
;; desired new solutions).  For example:

|= (retrieve)

There are 2 solutions so far:
  #1: ?X=JOE
  #2: ?X=FRED

;; Since we have already found all solutions to this query, the next
;; call to `retrieve' cannot generate any new ones.  This is indicated
;; by a slightly different message that shows that PowerLoom cannot
;; generate any additional solutions:

|= (retrieve 1)

There are 2 solutions:
  #1: ?X=JOE
  #2: ?X=FRED

;; PowerLoom relations defined by `defrelation' are by default
;; multi-valued.  For example, there might be multiple people that Joe
;; likes which could be modeled via multiple `(likes Joe ...)'
;; assertions.  Often it is also useful to model something as a
;; single-valued relation where for each set of input arguments there
;; is at most one possible value.  Examples are somebody's biological
;; mother, attributes such as somebody's current age or height, etc.
;; One way to do this in PowerLoom is to define such a relation as a
;; function via the `deffunction' command.  `deffunction' is similar
;; to `defrelation' with the exception of the functional output
;; argument which is separated from the remaining arguments via the
;; :-> keyword.  Functions can be defined using the specialized syntax
;; shown below, or by using a form like defrelation.  If not using the
;; specialized form with the result arrow (:->), then the last
;; variable is the range.  For example, to define an `age' function we
;; can do the following (`Integer' is a built-in concept defined in
;; PowerLoom's kernel KB):

|= (deffunction age ((?p Person)) :-> (?a Integer)
  :documentation "?a is ?p's age in years.")


;; The following idiom can be used to assert a function value:

|= (assert (= (age Fred) 35))

|P|(= (AGE FRED) 35)

;; The assertion language for functions also allows one to use the
;; syntax for relations as well.  The previous assertion could also
;; have been specified as

|= (assert (age Fred 35))

|P|(= (AGE FRED) 35)

;; Asserting the same value again has no additional effect on PowerLoom.
;; either form creates the same internal representation through a process
;; called `normalization'.

;; Now we can use `ask' to see whether Fred has a particular age:

|= (ask (= (age Fred) 35))


;; Or we can use `retrieve' to find out what Fred's age is:

|= (retrieve (= (age Fred) ?x))

There is 1 solution so far:
  #1: ?X=35

;; On Fred's next birthday, we might want to retract his previous age
;; with help of the `retract' command:

|= (retract (= (age Fred) 35))


;; Now we can only retrieve the skolem constant representing the term
;; `Fred's age', however, since it does not have a value associated
;; with it the query iterator reports no solutions:

|= (retrieve (= (age Fred) ?x))

No solutions.

;; Let's make Fred one year older:

|= (assert (= (age Fred) 36))

|P|(= (AGE FRED) 36)

|= (retrieve (= (age Fred) ?x))

There is 1 solution so far:
  #1: ?X=36

;; Note, that for single-valued functions such as `age' PowerLoom supports
;; "clipping", i.e., we can change a value by simply asserting a new
;; value without performing a retraction first.  The following assertion
;; will replace Fred's current age with a new value:

|= (assert (= (age Fred) 42))

|P|(= (AGE FRED) 42)

|= (retrieve (= (age Fred) ?x))

There is 1 solution so far:
  #1: ?X=42

;; The command `all-facts-of' can be used to lookup all propositions
;; asserted about a logic constant with a particular name:

|= (all-facts-of Fred)


;; `retract-facts-of' can be used to retract all assertions about
;; a particular logic constant:

|= (retract-facts-of Fred)

|= (all-facts-of Fred)



Finished demo `PL:sources;logic;demos;basics.ste'.


Information Sciences Institute PowerLoom Home Page
PowerLoom is a registered trademark of the University of Southern California.
Last modified: May 27, 2006