[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Commands

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:

Here is the list of all available PowerLoom commands:

Command: add-load-path ((path STRING)) : (CONS OF STRING-WRAPPER)

Append the directories listed in the |-separated path to the end of the STELLA load path. Return the resulting load path.

N-Command: all-facts-of ((instanceRef OBJECT)) : (CONS OF PROPOSITION)

Return a cons list of all definite (TRUE or FALSE) propositions that reference the instance instanceRef. This includes propositions asserted to be true by default, but it does not include propositions that are found to be TRUE only by running the query engine. Facts inferred to be TRUE by the forward chainer will be included. Hence, the returned list of facts may be longer in a context where the forward chainer has been run then in one where it has not (see run-forward-rules). instanceRef can be a regular name such as fred as well as a function term such as (father fred).

N-Command: ask (&rest (proposition&options PARSE-TREE)) : TRUTH-VALUE

Perform inference to determine whether the proposition specified in proposition&options is true. Return the truth-value found. 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 the following options: :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. If the :DONT-OPTIMIZE? is given as TRUE, it tells PowerLoom to not optimize the order of clauses in the query before evaluating it. This is useful for cases where a specific evaluation order of the clauses is required (or the optimizer doesn’t do the right thing). If :THREE-VALUED? is given as TRUE, PowerLoom will try to prove the negation of the query with full effort in case the given query returned UNKNOWN. By default, PowerLoom uses full effort to prove the query as stated and only a little opportunistic effort to see whether it is actually false.

N-Command: assert ((proposition PARSE-TREE)) : 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.

N-Command: assert-from-query ((query CONS) &rest (options OBJECT)) : (CONS OF PROPOSITION)

Evaluate query, instantiate the query proposition for each generated solution and assert the resulting propositions. The accepted syntax is as follows:

 
 (assert-from-query <query-command>
                    [:relation <relation-name>]
                    [:pattern <description-term>]
                    [:module <module-name>]
                    [:record-justifications? TRUE|FALSE]
                    [:result :list|:none|:print|:summary|:stats])

<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. If :record-justifications? is TRUE, justifications will be recorded for the query and the resulting justifications will be linked to the asserted propositions. :result can be used to control what should be returned or printed, the default is :list which is the list of asserted propositions. 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))))))
N-Command: assert-rule ((ruleName NAME)) : PROPOSITION

Set the truth value of the rule named ruleName to TRUE. The proposition having the name ruleName may be any arbitrary proposition, although we expect that it is probably a material implication. (See retract-rule).

N-Command: cc (&rest (name NAME)) : CONTEXT

Change the current context to the one named name. Return the value of the new current context. If no name is supplied, return the pre-existing value of the current context. cc is a no-op if the context reference cannot be successfully evaluated.

N-Command: classify-relations (&rest (options OBJECT)) :

Classify relations visible in the module defined by the :module option (which defaults to the current module). If :module was explicitly specified as NULL, classify relations in all modules. If :local? is specified as TRUE only classify relations that belong to the specified module but not any modules it inherits. For backwards compatibility, this command also supports the old <module> <local?> arguments specified without keywords.

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.

N-Command: classify-instances (&rest (options OBJECT)) :

Classify instances visible in the module defined by the :module option (which defaults to the current module). If :module was explicitly specified as NULL, classify instances in all modules. If :local? is specified as TRUE only classify instances that belong to the specified module but not any modules it inherits. For backwards compatibility, this command also supports the old <module> <local?> arguments specified without keywords.

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.

Command: clear-caches () :

Clear all query and memoization caches.

N-Command: clear-instances (&rest (name NAME)) :

Destroy all instances belonging to module name or any of its children. Leave meta-objects, e.g., concepts and relations, alone. If no name is supplied, the current module will be cleared after confirming with the user.

N-Command: clear-module (&rest (name NAME)) :

Destroy all objects belonging to module name or any of its children. If no name is supplied, the current module will be cleared after confirming with the user. Important modules such as STELLA are protected against accidental clearing.

N-Command: conceive ((formula PARSE-TREE)) : OBJECT

Guess whether formula represents a term or a sentence/proposition. If we are not sure, assume its a proposition. If it is a term, return its internal representation. If a proposition, construct a proposition for formula without asserting its truth value. Return the conceived proposition object. KIF example: "(conceive (happy Fred))" builds the proposition expressing that Fred is happy without explictly asserting or denying it. Note, that for this to succeed, the relation 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.

Command: copyright () :

Print detailed PowerLoom copyright information.

N-Command: defconcept (&rest (args PARSE-TREE)) : NAMED-DESCRIPTION

Define (or redefine) a concept. The accepted syntax is:

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

N-Command: deffunction (&rest (args PARSE-TREE)) : NAMED-DESCRIPTION

Define (or redefine) a logic function. The accepted syntax is:

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

N-Command: definstance (&rest (args PARSE-TREE)) : LOGIC-OBJECT

Define (or redefine) a logic instance (definstance is an alias for defobject which see).

N-Command: defmodule ((name NAME) &rest (options OBJECT)) :

Define (or redefine) a module named name. The accepted syntax is:

 
  (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. That means that any reference from inside a case-sensitive module to a non-case-sensitive module will have to use uppercase names for symbols in the non-case-sensitive module. The standard system modules are all NOT case sensitive.

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.

N-Command: defobject (&rest (args PARSE-TREE)) : LOGIC-OBJECT

Define (or redefine) a logic instance. The accepted syntax is:

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

N-Command: defproposition (&rest (args PARSE-TREE)) : PROPOSITION

Define (or redefine) a named proposition. The accepted syntax is:

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

N-Command: defrelation (&rest (args PARSE-TREE)) : NAMED-DESCRIPTION

Define (or redefine) a logic relation. The accepted syntax is:

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

N-Command: defrule (&rest (args PARSE-TREE)) : PROPOSITION

Define (or redefine) a named rule (defrule is an alias for defproposition which see).

N-Command: delete-rules ((relation NAME)) :

Delete the list of rules associated with relation. This function is included mainly for debugging purposes, when a user wants to verify the behavior of different sets of rules.

Command: demo (&rest (fileandpause OBJECT)) :

Read logic commands from a file, echo them verbatimly to standard output, and evaluate them just as if they had been typed in interactively. When called with no arguments, present a menu of example demos, otherwise, use the first argument as the name of the file to demo. Pause for user confirmation after each expression has been read but before it is evaluated. Pausing can be turned off by suppling FALSE as the optional second argument, or by typing c at the pause prompt. Typing ? at the pause prompt prints a list of available commands.

N-Command: deny ((proposition PARSE-TREE)) : OBJECT

Assert the falsity of proposition. Return the asserted proposition object. KIF example: "(deny (happy Fred))" asserts that Fred is not happy, which could have been done equivalently by "(assert (not (happy Fred)))". Note, that for this to succeed, the relation happy must already be defined (see assert).

N-Command: describe ((name OBJECT) &rest (mode OBJECT)) :

Print a description of an object in :verbose, :terse, or :source modes.

N-Command: destroy ((objectSpec PARSE-TREE)) : OBJECT

Find an object or proposition as specified by objectSpec, and destroy all propositions and indices that reference it. objectSpec must be a name or a parse tree that evaluates to a proposition. Return the deleted object, or NULL if no matching object was found.

Command: drop-load-path ((path STRING)) : (CONS OF STRING-WRAPPER)

Remove the directories listed in the |-separated path from the PowerLoom load path.

Command: get-load-path () : (CONS OF STRING-WRAPPER)

Return the current STELLA load path.

N-Command: get-rules ((relation NAME)) : (CONS OF PROPOSITION)

Return the list of rules associated with relation.

N-Command: help (&rest (commands SYMBOL)) :

Describe specific commands, or print a list of available commands.

N-Command: in-module ((name NAME)) : MODULE

Change the current module to the module named name.

N-Command: list-inconsistent-propositions (&rest (options OBJECT)) : (CONS OF PROPOSITION)

Return a list of all currently known inconsistent proposition in the module defined by the :module option (which defaults to the current module). If :local? is specified as TRUE only look in the specified module but not any modules it inherits. Note, that this simply reports propositions that have been assigned an inconsistent truth value so far (e.g., in clash exceptions), it will not try to detect any new or all inconsistencies in a module.

Command: list-modules ((kb-only? BOOLEAN)) : (CONS OF MODULE)

Returns a cons of all modules defined in PowerLoom. If kb-only? is true, then any modules which are code only or just namespaces are not returned.

N-Command: list-unclassified-instances (&rest (options OBJECT)) : (CONS OF LOGIC-OBJECT)

Collect all instances in the module defined by the :module option (which defaults to the current module) that were not (or will not be) classified due to their lack of non-inferable/primitive type assertions. If :module was explicitly specified as NULL, look in all currently defined modules. If :local? is specified as TRUE only look in the specified module but not any modules it inherits. For backwards compatibility, this command also supports the old <module> <local?> arguments specified without keywords.

N-Command: list-unclassified-relations (&rest (options OBJECT)) : (CONS OF NAMED-DESCRIPTION)

Collect all named description in the module defined by the :module option (which defaults to the current module) that were not (or will not be) classified due to their lack of non-inferable/primitive ancestor relations. If :module was explicitly specified as NULL, look in all currently defined modules. If :local? is specified as TRUE only look in the specified module but not any modules it inherits. For backwards compatibility, this command also supports the old <module> <local?> arguments specified without keywords.

N-Command: list-undefined-relations (&rest (options OBJECT)) : (CONS OF NAMED-DESCRIPTION)

Return a list of as yet undefined concepts and relations in the module defined by the :module option (which defaults to the current module). These relations were defined by the system, since they were referenced but have not yet been defined by the user. If :local? is specified as TRUE only look in the specified module but not any modules it inherits. For backwards compatibility, this command also supports the old <module> <local?> arguments specified without keywords.

Command: load ((file STRING) &rest (options OBJECT)) :

Read logic commands from file and evaluate them. By default, this will check for each asserted proposition whether an equivalent proposition already exists and, if so, not assert the duplicate. These duplicate checks are somewhat expensive though and can be skipped by setting the option :check-duplicates? to false. This can save time when loading large KBs where it is known that no duplicate assertions exist in a file.

Also, by setting the :module option, the module in which the file contents will be loaded will be set. This will only affect files that do NOT have an in-module declaration as part of the file. If this is not set, and no in-module declaration is in the file, the file will be loaded into the current module.

The option :assertion-module can be used to have assertions and definitional axioms be asserted in a different module than the top-level module where definitions are evaluated. This is useful in some cases where vocabulary definitions and their associated axioms and assertions need to be separate for inference or efficiency reasons. The assertion module can be given as a name in case it is defined in the loaded file. Obviously, it needs to be a child of the top-level module where vocabulary definitions are created.

Loading is done in two passes: in the first pass all definitional commands such as defmodule, defconcept, etc. are evaluated but not yet finalized, that is, their definitional axioms are parsed but not yet asserted. In the second pass all definitional commands are finalized and then all commands in the file are executed in order (which will be no-ops for the definitions already processed). This scheme tries to maintain some order independence for the commands in the file, since relation definitions need to be performed before they can be used in assertions. At any point process-definitions can be called to finalize all unfinalized definitions queued up so far. Future versions might also support a :one-pass? option for added efficiency.

Command: load-file ((file STRING)) :

Read STELLA commands from file and evaluate them. The file should begin with an 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.

Command: pop-load-path () : STRING

Remove the first element from the STELLA load path and return the removed element.

N-Command: presume ((proposition PARSE-TREE)) : OBJECT

Presume the default truth of proposition. Return the presumed proposition object. KIF example: "(presume (happy Fred))" states that Fred is most probably happy. Note, that for this to succeed, the relation happy must already be defined (see assert).

Command: print-features () :

Print the currently enabled and available PowerLoom environment features.

N-Command: print-rules ((relation OBJECT)) :

Print the list of true rules associated with relation.

Command: process-definitions () :

Finish processing all definitions and assertions that have been evaluated/loaded since that last call to 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.

N-Command: propagate-constraints (&rest (name NAME)) :

OBSOLETE: use run-forward-rules instead.

Command: push-load-path ((path STRING)) : (CONS OF STRING-WRAPPER)

Add the directories listed in the |-separated path to the front of the STELLA load path. Return the resulting load path.

N-Command: repropagate-constraints (&rest (name NAME)) :

OBSOLETE: use run-forward-rules instead.

Command: reset-features () : (LIST OF KEYWORD)

Reset the PowerLoom environment features to their default settings.

Command: reset-powerloom () :

Reset PowerLoom to its initial state. CAUTION: This will destroy all loaded knowledge bases and might break other loaded STELLA systems if they do reference PowerLoom symbols in their code.

N-Command: retract ((proposition PARSE-TREE)) : OBJECT

Retract the truth of proposition. Return the retracted proposition object. KIF example: "(retract (happy Fred))" retracts that Fred is 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 retract.

N-Command: retract-facts-of ((instanceRef OBJECT)) :

Retract all definite (TRUE or FALSE) propositions that reference the instance instanceRef.

N-Command: retract-from-query ((query CONS) &rest (options OBJECT)) : (CONS OF PROPOSITION)

Evaluate query which has to be a strict or partial retrieval command, instantiate the query proposition for each generated solution and retract the resulting propositions. See assert-from-query for available command options.

N-Command: retract-rule ((ruleName NAME)) : PROPOSITION

If it is currently TRUE, set the truth value of the rule named ruleName to UNKNOWN This command may be used alternately with 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.

N-Command: retrieve (&rest (query PARSE-TREE)) : QUERY-ITERATOR

Retrieve elements of a relation (tuples) that satisfy a proposition. The accepted syntax is:

 
  (retrieve [<integer> | all]
            [[{<vardecl> | (<vardecl>+)}]
             <proposition>
             [<option-keyword> <option-value>]])

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.

retrieve supports the following options: :TIMEOUT Time limit on query effort in seconds. :MAXIMUM-DEPTH Inference depth cutoff in goal depth. :INFERENCE-LEVEL Level of inference to use. The values in order of effort and power are ASSERTION, SHALLOW, SUBSUMPTION, BACKTRACKING, NORMAL and REFUTATION. Default is NORMAL. :FOUR-VALUED? Will attempt to disprove values and find conflicts. :ITERATIVE-DEEPENING? Controls whether the search strategy will use depth-first or breadth-first search. :DONT-OPTIMIZE? Option to disable re-arrangement of clauses by the query optimizer. If TRUE, then use the order of clauses as given in the query. :SORT-BY one of SCORE, VALUES, VALUES-DESCENDING, VALUES-ASCENDING. SCORE is only meaningful for partial match mode. The value sorting is done by values in order in the tuple. Default is ascending. :MATCH-MODE Allows choice of matching mode. One of STRICT, INCREMENTAL, NEURAL-NETWORK, or other plug-in partial-match mode. The default is STRICT. :MINIMUM-SCORE The minimum score to return. Only useful in partial match mode. :MAXIMUM-UNKNOWNS The maximum number of unknown values to allow. Only useful for whynot matching.

KIF examples:

 
  (retrieve (happy ?x))

will try to find one happy entity and store it in the returned query iterator.

 
  (retrieve 10 (happy ?x))

will try to find 10 happy entities.

 
  (retrieve 10)

will try to find the next 10 happy entities..

 
  (retrieve all (happy ?x))

will find all happy entities.

 
  (retrieve all (?x Person) (happy ?x))

will to find all happy people. Here we used the optional retrieve variable syntax to restrict the acceptable solutions. The above is equivalent to the following query:

 
  (retrieve all (and (Person ?x) (happy ?x)))

Similarly,

 
  (retrieve all (?x Person))
  (retrieve all (Person ?x))
  (retrieve all ?x (Person ?x))

will find all people. Note that in the first case we only specify a query variable and its type but omit the logic sentence which defaults to TRUE. This somewhat impoverished looking query can be paraphrased as "retrieve all ?x of type Person such that TRUE."

 
  (retrieve ?x (or (happy ?x) (parent-of Fred ?x)))

will try to find a person that is happy or has Fred as a parent.

 
  (retrieve (?y ?x) (parent-of ?x ?y))

will try to find the one pair of parent/child and return it in the order of child/parent.

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

Command: save-module (&rest (options OBJECT)) :

Save all definitions and assertions of the specified :module (which defaults to the current module) to a file or persistent store. If :file is specified, the KB is saved to that file. If no :file is specified but the specified :module is associated with a persistent store, the KB will saved to that store, otherwise, an error will be signalled. The specifics on how a save operation will proceed for a persistent store depends on the particular type of store (see respective documentation). For backwards compatibility, this command also supports the old <module> <file> arguments specified without keywords.

N-Command: set-feature (&rest (features NAME)) : (LIST OF KEYWORD)

Enable the PowerLoom environment feature(s) named by features. Return the list of enabled features. Calling 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.

Command: set-load-path ((path STRING)) : (CONS OF STRING-WRAPPER)

Set the STELLA load path to the |-separated directories listed in path. Return the resulting load path.

N-Command: time-command ((command CONS)) : OBJECT

Execute command, measure and report its CPU and elapsed time needed for its execution, and then return its result.

N-Command: unset-feature (&rest (features NAME)) : (LIST OF KEYWORD)

Disable the PowerLoom environment feature(s) named by features. Return the list of enabled features. Calling unset-feature without any arguments can be used to display the currently enabled features. See set-feature for a description of supported features.

N-Command: why (&rest (args OBJECT)) :

Print an explanation for the result of the most recent query. Without any arguments, 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] [ ? ]

This document was generated by Hans Chalupsky on January 6, 2023 using texi2html 1.82.