Basic PowerLoom® Commands

    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")

|MDL|/PL-KERNEL-KB/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")

|MDL|/PL-KERNEL-KB/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"))

|MDL|/PL-KERNEL-KB/PL-USER/BASICS

;; 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")

|MDL|/PL-KERNEL-KB/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)

|l|(:EMIT-THINKING-DOTS :JUST-IN-TIME-INFERENCE)

;; `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)

: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-TESTING-EXAMPLE:
  Add a query and score pair to the master list of 
ADD-TRAINING-EXAMPLE:
  Add a query and score pair to the master list of 
ALL-FACTS-OF:
  Return a cons list of all definite (TRUE or FALSE) propositions
  that reference the instance `instanceRef'.
ALL-FACTS-OF-N:
  This is a generalization of `all-facts-of' (which see).
ALL-SENTENCES-OF:
  Return a list of sentences describing facts about 'instanceRef'.
ASK:
  Perform inference to determine whether the proposition specified in
  `proposition&options' is true.
ASK-PARTIAL:
  Similar to `ask' (which see), but return the highest partial match score
  for the supplied proposition instead of a truth value.
ASSERT:
  Assert the truth of `proposition'.  Return the asserted proposition object.
ASSERT-FROM-QUERY:
  Evaluate `query', instantiate the query proposition for each generated
  solution and assert the resulting propositions.
ASSERT-RULE:
  Set the truth value of the rule named 'ruleName' to 
  TRUE.
CALL-ALL-FACTS-OF:
  Return a list of all definite (TRUE or FALSE) propositions
  that reference the instance `instanceRef'.
CC:
  Change the current context to the one named `name'.
CLASSIFY-INSTANCES:
  Classify instances visible in `module'.
CLASSIFY-RELATIONS:
  Classify named relations visible in `module'.
CLEAR-INSTANCES:
  Destroy all instances belonging to module `name' or any of its children.
CLEAR-MODULE:
  Destroy all objects belonging to module `name' or any of its children.
CONCEIVE:
  Guess whether 'formula' represents a term or a sentence/proposition.
CONCEIVE-TERM:
  `tree' is a term expression (a string or an s-expression),
  or is a class reference (a symbol or surrogate).
COPYRIGHT:
  Print detailed PowerLoom copyright information.
CREATE:
  Create a logic object with name 'name' and return it.
CURRENT-INFERENCE-LEVEL:
  Return the current inference level that is active in the
  current query, the current module, or, otherwise, globally.
DEFCONCEPT:
  Define (or redefine) a concept.
DEFFUNCTION:
  Define (or redefine) a logic function.
DEFINSTANCE:
  Define (or redefine) a logic instance (`definstance' is an alias
  for `defobject' which see).
DEFMODULE:
  Define (or redefine) a module named `name'.
DEFOBJECT:
  Define (or redefine) a logic instance.
DEFPROPOSITION:
  Define (or redefine) a named proposition.
DEFRELATION:
  Define (or redefine) a logic relation.
DEFRULE:
  Define (or redefine) a named rule (`defrule' is an alias
  for `defproposition' which see).
DELETE-RULES:
  Delete the list of rules associated with `relation'.
DEMO:
  Read logic commands from a file, echo them verbatimly to standard output,
  and evaluate them just as if they had been typed in interactively.
DENY:
  Assert the falsity of `proposition'.
DESTROY:
  Find an object or proposition as specified by `objectSpec', and destroy all
  propositions and indices that reference it.
FIND-INSTANCE:
  Return the nearest instance with name 'instanceRef'
  visible from the current module.
FIND-RULE:
  Search for a rule named 'ruleName'.
GET-RULES:
  Return the list of rules associated with `relation'.
HELP:
  Describe specific commands, or print a list of available commands.
IN-DIALECT:
  Change the current logic dialect to `dialect'.
IN-MODULE:
  Change the current module to the module named `name'.
LIST-FEATURES:
  Return a list containing two lists, a list of currently enabled PowerLoom
  features, and a list of all available PowerLoom features.
LIST-UNCLASSIFIED-INSTANCES:
  Collect all instances in `module' (or in any module if `module'
LIST-UNCLASSIFIED-RELATIONS:
  Collect all named description in `module' (or in any module if `module'
LIST-UNDEFINED-RELATIONS:
  Return a list of as yet undefined concepts and relations in `module'.
LOAD:
  Read logic commands from `file' and evaluate them.
PRESUME:
  Presume the default truth of `proposition'.
PRINT-FEATURES:
  Print the currently enabled and available PowerLoom environment features.
PRINT-RULES:
  Print the list of rules associated with `relation'.
PROCESS-DEFINITIONS:
  Finish processing all definitions and assertions that have
  been evaluated/loaded since that last call to 'process-definitions'.
PROPAGATE-CONSTRAINTS:
  Trigger constraint propagation over all propositions of module `name'.
REPROPAGATE-CONSTRAINTS:
  Force non-incremental constraint propagation over all propositions of
  module `name'.
RESET-FEATURES:
  Reset the PowerLoom environment features to their default settings.
RETRACT:
  Retract the truth of `proposition'.
RETRACT-FACTS-OF:
  Retract all definite (TRUE or FALSE) propositions
  that reference the instance `instanceRef'.
RETRACT-FROM-QUERY:
  Evaluate `query' which has to be a strict or partial retrieval
RETRACT-RULE:
  If it is currently TRUE, set the truth value 
RETRIEVE:
  Retrieve elements of a relation (tuples) that satisfy a proposition.
RETRIEVE-PARTIAL:
  Partial-match version of `retrieve' (which see) that generates scored
  partial solutions based on the current partial match strategy.
RUN-FORWARD-RULES:
  Run forward inference rules in module 'moduleRef'.
RUN-POWERLOOM-TESTS:
  Run the PowerLoom test suite.
SAVE-ALL-NEURAL-NETWORKS:
  Save all neural networks to `file' (if `file' is non-NULL).
SAVE-MODULE:
  Save all definitions and assertions of module `name' to `file'.
SET-ERROR-PRINT-CYCLE:
  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 `.
SET-FEATURE:
  Enable the PowerLoom environment feature(s) named by `features'.
SET-INFERENCE-LEVEL:
  Set the inference level of `module' to the level specified
  by 'levelKeyword'.
SET-NUM-NEIGHBORS:
  Sets the number of nearest neighbors to predict from.
SET-NUM-TRAINING-PER-CASE:
  Sets the number of training examples for each case in the training set.
SET-SAVE-NETWORK-CYCLE:
  Set number of cycles between which networks are saved to the
  file established by the last call to `save-all-neural-networks'.
UNASSERT:
  Retract the truth or falsity of `proposition'.
UNSET-FEATURE:
  Disable the PowerLoom environment feature(s) named by `features'.
WHY:
  Print an explanation for the result of the most recent query.

Undocumented Commands:

ADD-CASE:
ADD-TABOO-OPERATORS:
ADD-TRAINING-EXAMPLE-IN-MODULE:
APPROXIMATE:
ASSERT-INDUCED-RULES:
BOTTOM-UP-RULE-INDUCTION:
CHECK-MASTER-NETWORK-LIST:
CLEAR-ALL-NEURAL-NETWORKS:
CLEAR-CASES:
CLEAR-SLOT-FROM-CLASS:
CLEAR-TRAINING-EXAMPLES:
DEFNETWORK:
DELETE-ALL-NEURAL-NETWORKS:
EVALUATE-RULE-INDUCTION:
FINALIZE-CASES:
GET-RULE:
GNP:
GUESS:
INDUCE-DECISION-RULES:
INDUCE-DECISION-TREE:
INDUCE-INFERENCE-RULES:
LOAD-NEURAL-NETWORK-FILE:
MULTIPLE-NETWORK-TRAINING-RUNS:
PRINT-FACTS:
SAVE-NEURAL-NETWORK:
SAVE-TRAINING-EXAMPLES:
SET-CASE-SOLUTION-COMBINATION:
SET-CLOSED-WORLD-TRAINING-EXAMPLES:
SET-ERROR-CUTOFF:
SET-GREEDY-NETWORK-PRUNING:
SET-LEARNING-RATE:
SET-MAXIMUM-SCORE-CUTOFF:
SET-MINIMUM-SCORE-CUTOFF:
SET-MOMENTUM-TERM:
SET-NEURAL-NETWORK-TRAINING-METHOD:
SET-PARTIAL-MATCH-MODE:
SET-PRINT-CASE-DISTANCES:
SET-RECURSIVE-DECISION-NODES:
SET-RULE-COMBINATION:
SET-RULE-INDUCTION-STRATEGY:
SET-SIGNATURE-RULES:
SET-SIGNATURE-STRATEGY:
SET-STRUCTURE-DEPTH:
SET-TRACE-NEURAL-NETWORK-TRAINING:
SET-TRAIN-CACHED-NEURAL-NETWORKS:
SET-WEIGHT-RANGE:
STRUCTURED-NEURAL-NETWORK-REGRESSION:
SWAP-IN-NETWORK-FILE:
SWAP-IN-NEW-NETWORKS:
TEST-CASE-BASED-REASONER:
TEST-CASE-MATCHER:
TEST-DOMAIN-THEORY:
TEST-NEURAL-NETWORK:
TEST-OVER-TRAINING-EXAMPLES:
THINGIFY-UNTYPED-INSTANCES:
TOP-DOWN-RULE-INDUCTION:
TRAIN-AND-TEST-CASE-MATCHER:
TRAIN-AND-TEST-NEURAL-NETWORK:
TRAIN-CASE-MATCHER:
TRAIN-NEURAL-NETWORK:
TRANSLATE-LEARNING:
WHYNOT:

;; 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.")

|c|PERSON

;; `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))

|P|(PERSON FRED)

|= (assert (Person Joe))

|P|(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.")

|r|LIKES

;; 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.")

|r|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))

|P|(LIKES JOE FRED)

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

|= (assert (happy Fred))

|P|(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...
TRUE

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

|= (ask (happy Joe))

UNKNOWN

;; 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)))

|P|(NOT (HAPPY JOE))

;; Now the query will return FALSE:

|= (ask (happy Joe))

FALSE

;; `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.")

|f|AGE

;; 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))

TRUE

;; 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))

|P?|(= (AGE FRED) (AGE FRED))

;; 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)

(|P|(PERSON FRED) |P|(LIKES JOE FRED) |P|(HAPPY FRED) |P|(= (AGE FRED) 42))

;; `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'.

|=