[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter lists all available PowerLoom commands alphabetically.
Each command is documented with its name, a (possibly empty) list of
parameters specified as (<name> <type>)
pairs, its return
type, and its category (Command). Almost all of the commands implicitly
quote their arguments, meaning that when calling them, you don't need
to add any quotation yourself. For example, the command
all-facts-of
is defined as follows:
- Command: all-facts-of ((instanceRef NAME)) : (CONS OF PROPOSITION)
- Return a cons list of all definite (TRUE or FALSE) propositions that reference the instance instanceRef.
The all-facts-of
command has one parameter called
instanceRef of type NAME, and returns a STELLA
LIST containing zero or more objects of type
PROPOSITION as its result. The type NAME subsumes the
types SYMBOL, SURROGATE, STRING, and KEYWORD.
Unless you are in a case-sensitive module, the following four commands
are equivalent:
(all-facts-of Merryweather) (all-facts-of :MERRYWEATHER) (all-facts-of "merryweather") (all-facts-of @MerryWeather) |
Commands can also have &rest
parameters (similar to Lisp
functions). These are either used to allow a variable number of
arguments, or to handle optional arguments, since STELLA does not
directly support optional arguments.
Here is a list of important parameter types used in the command specifications below:
Merryweather
, a keyword
(similar to a Lisp keyword) such as :KIF
, or a STELLA surrogate
which is a symbol starting with an at-sign, e.g., @CONS
. STELLA
surrogates are used as names for objects of arbitrary types.
(happy Fred)
is a parse tree, and so are its components
happy
and Fred
.
Here is the list of all available PowerLoom commands:
run-forward-rules
).
ask
will spend most of its effort to determine whether the proposition
is true and only a little effort via shallow inference strategies to
determine whether it is false. To find out whether a proposition is
false with full inference effort ask
its negation.
KIF example: (ask (happy Fred))
will return TRUE if Fred was indeed
found to be happy. Note, that for this query to run, the logic
constant Fred
and the relation happy
must already be defined (see
assert
). Use (set/unset-feature goal-trace)
to en/disable goal
tracing of the inference engine.
The ask
command supports two options, declared with the keywords
:TIMEOUT
and :DONT-OPTIMIZE
. The argument to :TIMEOUT
is an
integer or floating point time limit, specified in seconds. For
example, the command (ask (nervous Fred) :timeout 2.0)
will cease
inference after two seconds if a proof has not been found by then.
The argument to :DONT-OPTIMIZE?
is the constant TRUE, which tells
PowerLoom not to optimize the query before evaluating it.
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
.
(assert-from-query <query-command> [:relation <relation-name>] [:pattern <description-term>] [:module <module-name>]) |
<query-command> has to be a strict or partial retrieval command. If a :relation option is supplied, <relation-name> is used as the relation of the resulting propositions. In this case the bindings of each solution will become arguments to the specified relation in the order of querys output variables (the arities have to match). The :pattern option is a generalization of this mechanism that specifies an arbitrary proposition pattern to be instantiated by the query's solution. In this case <description-term> has to be a SETOFALL or KAPPA expression whose IO-variables will be bound in sequence to the bindings of a query solution to generate the resulting proposition. Finally, if a :module option is specified, the assertions will be generated in that module. Note that for this to work the relations referenced in the query proposition or pattern have to be visible in the module. Also, instances will not be copied to the target module, therefore, the resulting propositions might reference external out-of-module objects in case they are not visible there. Here are some examples:
(assert-from-query (retrieve all (foo ?x ?y))) (assert-from-query (retrieve all (?y ?x) (exists ?z (and (foo ?x ?z) (foo ?z ?y)))) :relation bar :module other) (assert-from-query (retrieve all (and (relation ?x) (symmetric ?x))) :pattern (kappa (?pred) (forall (?x ?y) (=> (holds ?pred ?x ?y) (holds ?pred ?y ?x)))))) |
retract-rule
).
cc
is a no-op if the
context reference cannot be successfully evaluated.
Conceptually, the classifier operates by comparing each concept or relation
with all other concepts/relations, searching for a proof that a
subsumption relation exists between each pair. Whenever a new subsumption
relation is discovered, the classifier adds an implication
link between
members of the pair, thereby augmenting the structure of the
concept or relation hierarchy. The implemented classification algorithm is
relatively efficient -- it works hard at limiting the number of concepts
or relations that need to be checked for possible subsumption
relationships.
Conceptually, the classifier operates by comparing each instance
with all concepts in the hierarchy, searching for a
proof for each pairing indicating that the instance belongs to the concept.
Whenever a new is-a
relation is discovered, the classifier
adds an is-a
link between the instance and the concept, thereby
recording an additional fact about the instance. The implemented
classification algorithm is relatively efficient -- it works hard
at limiting the number of concepts or relations that need to
be checked for possible is-a relationships.
happy
must already
be defined (see assert
). If the logic constant Fred
has not yet been
created, it is automatically created as a side-effect of calling conceive
.
(defconcept <conceptconst> [(<var> <parent>*)] [:documentation <string>] [:<= <sentence>] | [:=> <sentence>] | [:<<= <sentence>] | [:=>> <sentence>] | [:<=> <sentence>] | [:<=>> <sentence>] | [:<<=> <sentence>] | [:<<=>> <sentence>] | [:axioms {<sentence> | (<sentence>+)}] | <keyword-option>*) |
Declaration of a concept variable <var>
is optional, unless any
implication (arrow) options are supplied that need to reference it. A
possibly empty list of concept names following <var>
is taken as the list
of parents of <conceptconst>
. Alternatively, parents can be specified
via the :=>
option. If no parents are specified, the parent of
<conceptconst>
is taken to be THING. <keyword-option>
represents a
keyword followed by a value that states an assertion about <conceptconst>
.
See defrelation
for a description of <keyword-option>
s.
(deffunction <funconst> (<vardecl>+) [:-> <vardecl>] [:documentation <string>] [:<= <sentence>] | [:=> <sentence>] | [:<<= <sentence>] | [:=>> <sentence>] | [:<=> <sentence>] | [:<=>> <sentence>] | [:<<=> <sentence>] | [:<<=>> <sentence>] | [:axioms {<sentence> | (<sentence>+)}] [<keyword-option>*]) |
Function parameters can be typed or untyped. If the :->
option is
supplied, it specifies the output variable of the function. Otherwise,
the last variable in the parameter list is used as the output variable.
See defrelation
for a description of <keyword-option>
s.
definstance
is an alias
for defobject
which see).
(defmodule <module-name> [:documentation <docstring>] [:includes {<module-name> | (<module-name>*)}] [:uses {<module-name> | (<module-name>*)}] [:lisp-package <package-name-string>] [:java-package <package-specification-string>] [:cpp-namespace <namespace-name-string>] [:java-catchall-class [:api? {TRUE | FALSE}] [:case-sensitive? {TRUE | FALSE}] [:shadow (<symbol>*)] [:java-catchall-class <class-name-string>] [<other-options>*]) |
name can be a string or a symbol.
Modules include objects from other modules via two separate mechanisms:
(1) they inherit from their parents specified via the :includes
option
and/or a fully qualified module name, and (2) they inherit from used
modules specified via the :uses
option. The main difference between
the two mechanisms is that inheritance from parents is transitive, while
uses-links are only followed one level deep. I.e., a module A that uses
B will see all objects of B (and any of B's parents) but not see anything
from modules used by B. Another difference is that only objects declared
as public can be inherited via uses-links (this is not yet enforced).
Note that - contrary to Lisp - there are separate name spaces for classes,
functions, and variables. For example, a module could inherit the class
CONS
from the STELLA
module, but shadow the function of the same name.
The above discussion of :includes
and :uses
semantics keyed on the
inheritance/visibility of symbols. The PowerLoom system makes another
very important distinction: If a module A
is inherited directly or
indirectly via :includes
specification(s) by a submodule B
, then all
definitions and facts asserted in A
are visible in B
. This is not the
cases for :uses
; the :uses
options does not impact inheritance of
propositions at all.
The list of modules specified in the
:includes
option plus (if supplied) the parent in the path used for
name become the new module's parents. If no :uses
option was
supplied, the new module will use the STELLA
module by default,
otherwise, it will use the set of specified modules.
If :case-sensitive?
is supplied as TRUE, symbols in the module will be
interned case-sensitively, otherwise (the default), they will be
converted to uppercase before they get interned. Modules can shadow
definitions of functions and classes inherited from parents or used
modules. Shadowing is done automatically, but generates a warning unless
the shadowed type or function name is listed in the :shadow
option of
the module definition .
Examples:
(defmodule "PL-KERNEL/PL-USER" :uses ("LOGIC" "STELLA") :package "PL-USER") (defmodule PL-USER/GENEALOGY) |
The remaining options are relevant only for modules that contain STELLA code. Modules used only to contain knowledge base definitions and assertions have no use for them:
The keywords :lisp-package
, :java-package
, and :cpp-package
specify
the name of a native package or name space in which symbols of the module
should be allocated when they get translated into one of Lisp, Java, or
C++. By default, Lisp symbols are allocated in the STELLA
package, and
C++ names are translated without any prefixes. The rules that the STELLA
translator uses to attach translated Java objects to classes and packages
are somewhat complex. Use :java-package option to specify a list of
package names (separated by periods) that prefix the Java object in this
module. Use :java-catchall-class to specify the name of the Java class to
contain all global & special variables, parameter-less functions and functions
defined on arguments that are not classes in the current module.
The default value will be the name of the module.
When set to TRUE, the :api? option tells the PowerLoom User Manual
generator that all functions defined in this module should be included in
the API section. Additionally, the Java translator makes all API
functions synchronized
.
(defobject <constant> [:documentation <string>] [<keyword-option>*]) |
<keyword-option>
represents a keyword followed by a value
that states an assertion about <constant>. See defrelation
for a
description of <keyword-option>
s.
defobject
provides a sugar-coated way to assert a collection of facts
about a logic constant, but otherwise adds nothing in terms of functionality.
(defproposition <name> <sentence> [:documentation <string>] [:forward-only? {true | false}] [:backward-only? {true | false}] [:dont-optimize? {true | false}] [:confidence-level {:strict | :default}] [<keyword-option>*]) |
<sentence> can be any sentence that is legal as a top-level assertion. <name> can be a string or symbol and will be bound to the asserted proposition represented by <sentence>. After this definition every occurrence of <name> will be replaced by the associated proposition.
The options :forward-only? and :backward-only? can be used to tell the
inference engine to only use the rule in forward or backward direction
(this can also be achieved by using the <<=
or =>>
implication
arrows). :dont-optimize? tells the inference engine to not rearrange
the order of clauses in the antecedent of a rule and instead evaluate
them in their original order. :confidence-level can be used to mark a
proposition as default only.
<keyword-option>
represents a keyword followed by a value
that states an assertion about the proposition <name>. See defrelation
for a description of <keyword-option>
s.
(defrelation <relconst> (<vardecl>+) [:documentation <string>] [:<= <sentence>] | [:=> <sentence>] | [:<<= <sentence>] | [:=>> <sentence>] | [:<=> <sentence>] | [:<=>> <sentence>] | [:<<=> <sentence>] | [:<<=>> <sentence>] | [:axioms {<sentence> | (<sentence>+)}] [<keyword-option>*]) |
Relation parameters can be typed or untyped.
<keyword-option>
represents a keyword followed by a value that states an
assertion about <relconst>
. For example, including the option :foo bar
states that the proposition (foo <relconst> bar)
is true. :foo (bar fum)
states that both (foo <relconst> bar)
and (foo <relconst> fum)
are true.
:foo true
states that (foo <relconst>)
is true, :foo false
states that
(not (foo <relconst>))
is true.
defrule
is an alias
for defproposition
which see).
c
at the pause prompt.
Typing ?
at the pause prompt prints a list of available commands.
happy
must already be defined
(see assert
).
in-module
declaration that specifies
the module within which all remaining commands are to be evaluated
The remaining commands are evaluated one-by-one, applying the function
evaluate
to each of them.
happy
must already be defined (see assert
).
process-definitions
.
PowerLoom defers complete processing of definitions to make it easier
to support cyclic definitions. Following finalization of definitions,
this call performs semantic validation of any assertions evaluated since
the last call to process-definitions
. PowerLoom calls this function
internally before each query; the primary reason to call it explicitly
is to force the production of any diagnostic information that results from
the processing and validation.
propagate-constraints
.
happy
must already
be defined. If the constant Fred
has not yet been created, it is
automatically created as a side-effect of calling retract
.
assert-from-query
for
available command options.
assert-rule
to
observe the effects of querying with or without a particular (named) rule
being asserted within the current context. The proposition having the name
ruleName may be any arbitrary proposition, although we expect that it is
probably a material implication.
(retrieve [<integer> | all] [[{<vardecl> | (<vardecl>+)}] <proposition>]) |
The variables and proposition are similar to an exists
sentence or
kappa
term without the explicit quantifier. If variables are declared,
they must match the free variables referenced by <proposition>. Otherwise,
the free variables referenced in <proposition> will be used as the query
variables. If <proposition> is omitted, the most recently asked query
will be continued.
A solution is a set of bindings for the listed variables for which
<proposition> is true. The optional first argument controls how many
solutions should be generated before control is returned. The keyword
all
indicates that all solutions should be generated. By default,
retrieve
returns after it has found one new solution or if it cannot
find any more solutions.
retrieve
returns an iterator which saves all the necessary state of
a query and stores all generated solutions. When used interactively,
the returned iterator will print out with the set of solutions collected
so far. Calling retrieve
without any arguments (or only with the first
argument) will generate one (or more) solutions to the most recently
asked query.
KIF examples:
(retrieve (?x Person) (happy ?x)) |
will try to find the next happy person and store it in the returned query iterator.
(retrieve 10 (?x Person) (happy ?x)) |
will try to find 10 happy people.
(retrieve 10) |
will try to find the next 10 happy people.
(retrieve all (?x Person) (happy ?x)) |
will find all happy people.
(retrieve all (?x Person)) |
will find all people.
(retrieve (?x Person) (or (happy ?x) (parent-of Fred ?x))) |
will try to find a person that is happy or has Fred as a parent.
(retrieve (or (happy ?x) (parent-of Fred ?x))) |
will do the same in a more concise syntax by omitting the query variable declaration.
(retrieve ((?x Person) (?y Person)) (parent-of ?x ?y)) |
will try to find the next pair of parent/child.
(retrieve all (?x Person) (exists (?y Person) (parent-of ?x ?y))) |
will generate the set of all parents. Note, that for these queries to run,
the class Person
, the relations happy
and parent-of
, and the logic
constant Fred
must already be defined (see assert
).
Use (set/unset-feature trace-subgoals)
to en/disable goal tracing of the
inference engine.
set-feature
without any
arguments can be used to display the currently enabled features.
The following features are supported:
just-in-time-inference
: Enables interleaving of forward chaining inference
within backward chaining queries.
iterative-deepening
: Tells the query processor to use iterative deepening
instead of a depth-first search to find answers. This is less efficient
but necessary for some kinds of highly recursive queries.
trace-subgoals
: Enables the generation of subgoaling trace information during
backchaining inference.
trace-solutions
: Prints newly found solutions during retrieval right when they
are generated as opposed to when the query terminates.
trace-classifier
: Tells the classifier to describe the inferences it draws.
justifications
: Enables the generation of justifications during inference,
which is a prerequiste for the generation of explanations with (why)
.
emit-thinking-dots
: Tells PowerLoom to annotate its inference progress by
outputting characters indicating the completion of individual reasoning steps.
By default, the features emit-thinking-dots
and just-in-time-inference
are enabled, and the others are disabled.
unset-feature
without any
arguments can be used to display the currently enabled features.
See set-feature
for a description of supported features.
why
prints an explanation of the top level
query proposition down to a maximum depth of 3. (why all)
prints
an explanation to unlimited depth. Alternatively, a particular depth
can be specified, for example, (why 5)
explains down to a depth of 5.
A proof step that was not explained explicitly (e.g., due to a depth
cutoff) can be explained by supplying the label of the step as the
first argument to why
, for example, (why 1.2.3 5)
prints an explanation
starting at 1.2.3 down to a depth of 5 (which is counted relative to the
depth of the starting point). The keywords brief
and verbose
can be
used to select a particular explanation style. In brief mode, explicitly
asserted propositions are not further explained and indicated with a
!
assertion marker. Additionally, relatively uninteresting proof steps
such as AND-introductions are skipped. This explanation style option is
sticky and will affect future calls to why
until it gets changed again.
The various options can be combined in any way, for example,
(why 1.2.3 brief 3)
explains starting from step 1.2.3 down to a depth
of 3 in brief explanation mode.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |