|
dlvhex
2.1.0
|
Interface class for external Atoms. More...
#include <include/dlvhex2/PluginInterface.h>


Data Structures | |
| struct | Answer |
| Output of an external atom call. More... | |
| struct | Query |
| Query class which provides the input of an external atom call. More... | |
Public Types | |
| enum | InputType { PREDICATE, CONSTANT, TUPLE } |
| Type of input parameter. More... | |
Public Member Functions | |
| virtual | ~PluginAtom () |
| bool | checkInputArity (unsigned arity) const |
| Checks the input arity of the external atom against the specified arity. | |
| bool | checkOutputArity (unsigned arity) const |
| Checks whether the output arity of the external atom is compatible with the specified arity. | |
| virtual void | retrieveCached (const Query &, Answer &) |
| Retrieve answer object according to a query (cached). | |
| virtual void | retrieveCached (const Query &, Answer &, NogoodContainerPtr nogoods) |
| virtual void | retrieve (const Query &, Answer &)=0 |
| Retrieve answer to a query (external computation happens here). | |
| virtual void | retrieve (const Query &, Answer &, NogoodContainerPtr nogoods) |
| virtual void | generalizeNogood (Nogood ng, ProgramCtx *ctx, NogoodContainerPtr nogoods) |
| Tries to generalize learned nogoods to nonground nogoods. | |
| virtual std::vector< Query > | splitQuery (const Query &q, const ExtSourceProperties &prop) |
| Splits a non-atomic query up into a set of atomic queries, such that the result of the composed query corresponds to the union of the results to the atomic queries. | |
| InputType | getInputType (unsigned index) const |
| Returns the type of the input argument specified by position (starting with 0). | |
| const std::vector< InputType > & | getInputTypes () const |
| Return vector of input types. | |
| const ExtSourceProperties & | getExtSourceProperties () const |
| Return monotonicity of atom. | |
| virtual void | setRegistry (RegistryPtr reg) |
| Associate plugin atom with registry pointer. | |
| RegistryPtr | getRegistry () const |
| Get Registry associcated with atom. | |
| ID | getPredicateID () const |
| Get ID of the predicate name. | |
| const std::string & | getPredicate () const |
| Get predicate name (as specified in constructor). | |
| void | resetCache () |
| Erase all elements from queryAnswerCache and queryNogoodCache. | |
Protected Types | |
| typedef boost::unordered_map < const Query, Answer > | QueryAnswerCache |
| typedef boost::unordered_map < const Query, SimpleNogoodContainerPtr > | QueryNogoodCache |
Protected Member Functions | |
| PluginAtom (const std::string &predicate, bool monotonic) | |
| Constructor. | |
| void | addInputPredicate (bool nameIsRelevant=false) |
| Adds an input parameter of type PREDICATE. | |
| void | addInputConstant () |
| Adds an input parameter of type CONSTANT. | |
| void | addInputTuple () |
| Adds an input parameter of type TUPLE. | |
| void | setOutputArity (unsigned arity) |
| Specifies the output arity of the external Atom. | |
Protected Attributes | |
| std::string | predicate |
| ID | predicateID |
| ExtSourceProperties | prop |
| general properties of the external source (may be overridden on atom-level) | |
| std::vector< InputType > | inputType |
| Type of each input argument (only last may be TUPLE). | |
| unsigned | outputSize |
| QueryAnswerCache | queryAnswerCache |
| QueryNogoodCache | queryNogoodCache |
| boost::mutex | cacheMutex |
| std::vector< Tuple > | otuples |
| output tuples generated so far (used for learning for | |
| RegistryPtr | registry |
| Registry associated with this atom. | |
Private Member Functions | |
| PluginAtom (const PluginAtom &pa) | |
| const PluginAtom & | operator= (const PluginAtom &pa) |
Interface class for external Atoms.
An external atom is represented by a subclassed PluginAtom. The actual evaluation function of the atom is realized in the PluginAtom::retrieve() method. In the constructor, the user must specify monotonicity, the types of input terms and the output arity of the atom.
See also ComfortPluginInterface.
First, we have to subclass PluginAtom to create our own RDFatom class:
class RDFatom: public PluginAtom {
The constructor of RDFatom will be used to define some properties of the atom:
public: RDFatom(): PluginAtom("rdf", true) { addInputPredicate(); setOutputArity(3); }
We first specify predicate "&rdf" and monotonicity (it is monotonic). Then we specify the number and types of input parameters. The RDF-atom as we used it above, has a single input parameter, which is the name of the predicate to hold the URIs. In this case, we just need a single call to PluginAtom::addInputPredicate(). Another possibility would have been to define the single input term as a constant, which represents the URI directly (which means, that then there can only be one URI). In this case, the input interpretation would be irrelevant, since we don't need the extension of any predicate. To define a constant input parameter, we use PluginAtom::addInputConstant().
If we wanted to have, say, two input parameters which will represent predicate names and a third one which will be a constant, we would put this sequence of calls in the constructor:
The call setOutputArity(3) ensures that occurences of this atom with other than three output terms will cause an error at parsing time.
The only member function of the atom class that needs to be defined is retrieve:
virtual void retrieve(const Query& query, Answer& answer) {
retrieve() always takes a query object as input and returns the result tuples in an answer object.
By definition the same query should return the same result, this is used by the method retrieveCached() which has the effect that retrieve() is never called twice for the same query (if you do not disable the cache via --nocache).
In the implementation of retrieve, query.input contains the input tuple, query.pattern contains the tuple of constants and variables an output tuple should unify with, and query.interpretation is an interpretation containing all relevant bits of predicate inputs.
query.input and query.pattern store Term IDs, you resolve such IDs via the table Registry::terms, except for integers which are directly encoded in the ID::address member and are detected using ID::isInteger().
Note that each constant has a unique ID in the Registry, therefore obtaining const Term& from Registry::terms might not be necessary in all cases, it might be sufficient to compare the ID without looking at the actual (printable) content of the symbol.
if( query.input[0].isInteger() ) { std::cerr << "got integer << query.input[0].address << std::endl; } else { const Term& t = registry->terms.getByID(query.input[0]); std::cerr << "got term << t << std::endl; }
You obtain all ground atoms in the interpretation by iterating over its bits, or by testing individual bits.
Interpretation::TrueBitIterator it, it_end; for(boost::tie(it, it_end) = query.interpretation.trueBits(); it != it_end; ++it) { const OrdinaryAtom& gatom = registry->ogatoms.getByAddress(*it); std::cerr << "got atom in interpretation: " << gatom << std::endl; }
Note that each ground atom has a unique ID in the Registry, therefore obtaining const OrdinaryAtom& from Registry::ogatoms might not be necessary in all cases, it might be sufficient to compare the ID without looking at the actual (printable) content of the symbol.
For more information about accessing interpretation and IDs, please refer to the documentation and header files of the classes ID, Registry, Term, Atom, Interpretation, ...
At this point, the plugin author will implement the actual function of the external atom, either within this class or by calling other functions.
Throwing exceptions will abort the model building process and display the exception.
Answer tuples of data type Tuple which is std::vector<ID>, are added to the answer object as follows:
Tuple tuple; answer.get().push_back(tuple);
IDs put into tuple must either be integer IDs or Term IDs that have been registered in table Registry::terms.
So far, we described the implementation of a specific external atom. In order to integrate one or more atoms in the interface framework, the plugin author needs to subclass PluginInterface and register all external atoms in PluginInterface::createAtoms (see documentation of PluginInterface).
Definition at line 635 of file PluginInterface.h.
typedef boost::unordered_map<const Query, Answer> PluginAtom::QueryAnswerCache [protected] |
Definition at line 1080 of file PluginInterface.h.
typedef boost::unordered_map<const Query, SimpleNogoodContainerPtr> PluginAtom::QueryNogoodCache [protected] |
Definition at line 1081 of file PluginInterface.h.
Type of input parameter.
Three types of input parameters can be specified: PREDICATE, CONSTANT, and TUPLE.
* An input argument of type PREDICATE means that the atom needs those facts of the interpretation whose predicate match the value of this argument. * An input argument of type CONSTANT means that only its value is relevent to the external atom, regardless of the interpretation. * An input argument of type TUPLE may be specified as last input type only, it means that an unspecified number of CONSTANT values may be specified after other inputs.
Specifying the input parameters' types is necessary for reducing the interpretation that will be passed to the external atom as well as improving the dependency information used by the internal evaluation strategies of dlvhex.
Definition at line 825 of file PluginInterface.h.
| PluginAtom::PluginAtom | ( | const std::string & | predicate, |
| bool | monotonic | ||
| ) | [inline, protected] |
Constructor.
Call this constructor when creating custom external atoms.
| predicate | The name of the external atom as it appears in the HEX program must be specified here. As it is useful to have a tight connection of each PluginAtom with its name, every plugin atom can have only one name. monotonic This boolean indicates whether the atom is monotonic or not. Specifying false is always allowed, but might degrade evaluation performance in cases where a fixed point calculation could be used instead of guess and check model building. |
Within the derived constructor,
Definition at line 848 of file PluginInterface.h.
| virtual PluginAtom::~PluginAtom | ( | ) | [inline, virtual] |
Definition at line 895 of file PluginInterface.h.
| PluginAtom::PluginAtom | ( | const PluginAtom & | pa | ) | [inline, private] |
Definition at line 1099 of file PluginInterface.h.
| void PluginAtom::addInputConstant | ( | ) | [protected] |
Adds an input parameter of type CONSTANT.
Only use in constructor!
Definition at line 132 of file PluginInterface.cpp.
References CONSTANT, inputType, and TUPLE.
Referenced by TestAppendAtom::TestAppendAtom(), TestCycleAtom::TestCycleAtom(), TestMinusOneAtom::TestMinusOneAtom(), and TestNegAtom::TestNegAtom().
| void PluginAtom::addInputPredicate | ( | bool | nameIsRelevant = false | ) | [protected] |
Adds an input parameter of type PREDICATE.
| nameIsRelevant | If true, the name of the predicate parameter might influence the result, otherwise only its extension is relevant. Only use in constructor! |
Definition at line 118 of file PluginInterface.cpp.
References inputType, PREDICATE, ExtSourceProperties::predicateParameterNameIndependence, prop, and TUPLE.
Referenced by TestAAtom::TestAAtom(), TestAppendAtom::TestAppendAtom(), TestBAtom::TestBAtom(), TestCAtom::TestCAtom(), TestCycleAtom::TestCycleAtom(), TestDisjAtom::TestDisjAtom(), TestEqualAtom::TestEqualAtom(), TestEvenAtom::TestEvenAtom(), TestIdAtom::TestIdAtom(), TestLessThanAtom::TestLessThanAtom(), TestNegAtom::TestNegAtom(), TestNonmon2Atom::TestNonmon2Atom(), TestNonmonAtom::TestNonmonAtom(), TestOddAtom::TestOddAtom(), TestSetMinusAtom::TestSetMinusAtom(), TestSetMinusNogoodBasedLearningAtom::TestSetMinusNogoodBasedLearningAtom(), TestSetMinusRuleBasedLearningAtom::TestSetMinusRuleBasedLearningAtom(), and TestTransitiveClosureAtom::TestTransitiveClosureAtom().
| void PluginAtom::addInputTuple | ( | ) | [protected] |
Adds an input parameter of type TUPLE.
Only use in constructor!
Definition at line 144 of file PluginInterface.cpp.
References inputType, and TUPLE.
Referenced by TestConcatAtom::TestConcatAtom().
| bool PluginAtom::checkInputArity | ( | unsigned | arity | ) | const |
Checks the input arity of the external atom against the specified arity.
The input arity follows from the number of specified predicates and might be variable.
Definition at line 151 of file PluginInterface.cpp.
References inputType, and TUPLE.
Referenced by DependencyGraphFull::createExternalConstantInputDependencies(), DependencyGraphFull::createExternalPredicateInputDependencies(), DependencyGraph::createExternalPredicateInputDependencies(), and DependencyGraph::createNodesAndIntraRuleDependenciesForBody().
| bool PluginAtom::checkOutputArity | ( | unsigned | arity | ) | const |
Checks whether the output arity of the external atom is compatible with the specified arity.
Definition at line 174 of file PluginInterface.cpp.
References outputSize.
Referenced by DependencyGraphFull::createExternalConstantInputDependencies(), DependencyGraphFull::createExternalPredicateInputDependencies(), DependencyGraph::createExternalPredicateInputDependencies(), and DependencyGraph::createNodesAndIntraRuleDependenciesForBody().
| void PluginAtom::generalizeNogood | ( | Nogood | ng, |
| ProgramCtx * | ctx, | ||
| NogoodContainerPtr | nogoods | ||
| ) | [virtual] |
Tries to generalize learned nogoods to nonground nogoods.
Should only be overridden by experienced users.
@param ng A learned nogood with some external atom auxiliary over this external predicate @param ctx Program context @param nogoods The nogood container where related nogoods shall be added
Definition at line 444 of file PluginInterface.cpp.
References ID::address, ID::ALL_ONES, NogoodContainer::createLiteral(), DBGLOG, getInputType(), getPredicateID(), Nogood::getStringRepresentation(), ID_FAIL(), inputType, Nogood::insert(), Nogood::isGround(), ExtSourceProperties::isIndependentOfPredicateParameterName(), ID::isNaf(), Atom::kind, PREDICATE, prop, ProgramCtx::registry(), ID::SUBKIND_ATOM_ORDINARYN, ID::SUBKIND_MASK, and Atom::tuple.
| const ExtSourceProperties& PluginAtom::getExtSourceProperties | ( | ) | const [inline] |
Return monotonicity of atom.
Definition at line 991 of file PluginInterface.h.
Referenced by ExternalAtom::getExtSourceProperties().
| PluginAtom::InputType PluginAtom::getInputType | ( | unsigned | index | ) | const |
Returns the type of the input argument specified by position (starting with 0).
Returns TUPLE for TUPLE input arguments (variably many). Returns the type of the input argument specified by position.
Should not be overridden.
Indexing starts with 0. Returns TUPLE for TUPLE input arguments (variably many).
Definition at line 524 of file PluginInterface.cpp.
References inputType, and TUPLE.
Referenced by ComponentGraph::calculateStratificationInfo(), FLPModelGeneratorBase::computeExtensionOfDomainPredicates(), ComponentGraph::computeRecursiveAggregatesInComponent(), DependencyGraph::createAuxiliaryRuleIfRequired(), DependencyGraphFull::createExternalConstantInputDependencies(), DependencyGraphFull::createExternalPredicateInputDependencies(), DependencyGraph::createExternalPredicateInputDependencies(), generalizeNogood(), ExternalAtomMask::matchOutputAtom(), ExternalAtomMask::setEAtom(), and splitQuery().
| const std::vector<InputType>& PluginAtom::getInputTypes | ( | ) | const [inline] |
Return vector of input types.
Should not be overridden.
TUPLE may be returned as last type.
Definition at line 974 of file PluginInterface.h.
Referenced by ExtSourceProperties::isAntimonotonic(), and ExtSourceProperties::isMonotonic().
| const std::string& PluginAtom::getPredicate | ( | ) | const [inline] |
Get predicate name (as specified in constructor).
Should not be overridden.
Definition at line 1042 of file PluginInterface.h.
Referenced by DependencyGraph::createExternalPredicateInputDependencies().
| ID PluginAtom::getPredicateID | ( | ) | const [inline] |
Get ID of the predicate name.
Should not be overridden.
Returns ID_FAIL if no registry is set.
Definition at line 1034 of file PluginInterface.h.
Referenced by BaseModelGeneratorFactory::convertRuleBody(), BaseModelGenerator::evaluateExternalAtom(), and generalizeNogood().
| RegistryPtr PluginAtom::getRegistry | ( | ) | const [inline] |
Get Registry associcated with atom.
Should not be overridden.
As PluginAtom internally stores IDs, it has to be associated with a fixed Registry for its lifetime. Create several instantiations if you need the same atom in several registries.
Definition at line 1024 of file PluginInterface.h.
Referenced by ExternalAtomMask::matchOutputAtom(), TestSetMinusNogoodBasedLearningAtom::retrieve(), TestSetMinusRuleBasedLearningAtom::retrieve(), ComfortPluginAtom::retrieve(), TestNonmonAtom::retrieve(), TestNonmon2Atom::retrieve(), TestIdAtom::retrieve(), TestNegAtom::retrieve(), TestLessThanAtom::retrieve(), TestEqualAtom::retrieve(), TestTransitiveClosureAtom::retrieve(), TestCycleAtom::retrieve(), TestAppendAtom::retrieve(), TestDisjAtom::retrieve(), ExternalAtomMask::setEAtom(), ExternalAtomMask::updateMask(), ExternalAtom::updatePredicateInputMask(), and FLPModelGeneratorBase::VerifyExternalAtomCB::VerifyExternalAtomCB().
| const PluginAtom& PluginAtom::operator= | ( | const PluginAtom & | pa | ) | [inline, private] |
Definition at line 1100 of file PluginInterface.h.
| void PluginAtom::resetCache | ( | ) | [inline] |
Erase all elements from queryAnswerCache and queryNogoodCache.
Definition at line 1048 of file PluginInterface.h.
| virtual void PluginAtom::retrieve | ( | const Query & | , |
| Answer & | |||
| ) | [pure virtual] |
Retrieve answer to a query (external computation happens here).
This function implements the external atom computation. See also documentation of Query and Answer classes.
Answer tuples must conform to the content of the pattern tuple in Query:
Implemented in TestDisjAtom, TestAppendAtom, TestCycleAtom, TestTransitiveClosureAtom, TestEqualAtom, TestLessThanAtom, TestNegAtom, TestIdAtom, TestNonmon2Atom, TestNonmonAtom, ComfortPluginAtom, TestSetMinusRuleBasedLearningAtom, TestSetMinusNogoodBasedLearningAtom, TestConcatAtom, and TestZeroArityAtom.
Referenced by BaseModelGenerator::evaluateExternalAtom(), retrieve(), and retrieveCached().
| void PluginAtom::retrieve | ( | const Query & | query, |
| Answer & | answer, | ||
| NogoodContainerPtr | nogoods | ||
| ) | [virtual] |
Reimplemented in TestSetMinusRuleBasedLearningAtom, and TestSetMinusNogoodBasedLearningAtom.
Definition at line 318 of file PluginInterface.cpp.
References DBGLOG, PluginAtom::Query::eatom, PluginAtom::Answer::get(), ExternalAtom::getExtSourceProperties(), ExternalLearningHelper::learnFromFunctionality(), ExternalLearningHelper::learnFromInputOutputBehavior(), ExternalLearningHelper::learnFromNegativeAtoms(), otuples, prop, retrieve(), and splitQuery().
| void PluginAtom::retrieveCached | ( | const Query & | query, |
| Answer & | answer | ||
| ) | [virtual] |
Retrieve answer object according to a query (cached).
This function implements the query cache, if enabled, and will rarely need to be overridden.
Definition at line 180 of file PluginInterface.cpp.
References cacheMutex, DLVHEX_BENCHMARK_REGISTER_AND_SCOPE, PluginAtom::Answer::hasBeenUsed(), PluginAtom::Query::input, PluginAtom::Query::interpretation, LOG, PluginAtom::Query::pattern, Printer::printmany(), queryAnswerCache, retrieve(), and PluginAtom::Answer::use().
Referenced by BaseModelGenerator::evaluateExternalAtom().
| void PluginAtom::retrieveCached | ( | const Query & | query, |
| Answer & | answer, | ||
| NogoodContainerPtr | nogoods | ||
| ) | [virtual] |
Definition at line 251 of file PluginInterface.cpp.
References cacheMutex, DBGLOG, DLVHEX_BENCHMARK_REGISTER_AND_SCOPE, PluginAtom::Answer::hasBeenUsed(), queryAnswerCache, queryNogoodCache, retrieve(), and PluginAtom::Answer::use().
| void PluginAtom::setOutputArity | ( | unsigned | arity | ) | [protected] |
Specifies the output arity of the external Atom.
Only use in constructor!
This arity always has to be fixed, i.e., there are no variable-output-arity external atoms.
Definition at line 167 of file PluginInterface.cpp.
References outputSize.
Referenced by TestAAtom::TestAAtom(), TestAppendAtom::TestAppendAtom(), TestBAtom::TestBAtom(), TestCAtom::TestCAtom(), TestConcatAtom::TestConcatAtom(), TestCycleAtom::TestCycleAtom(), TestDisjAtom::TestDisjAtom(), TestEqualAtom::TestEqualAtom(), TestEvenAtom::TestEvenAtom(), TestIdAtom::TestIdAtom(), TestLessThanAtom::TestLessThanAtom(), TestMinusOneAtom::TestMinusOneAtom(), TestNegAtom::TestNegAtom(), TestNonmon2Atom::TestNonmon2Atom(), TestNonmonAtom::TestNonmonAtom(), TestOddAtom::TestOddAtom(), TestSetMinusAtom::TestSetMinusAtom(), TestSetMinusNogoodBasedLearningAtom::TestSetMinusNogoodBasedLearningAtom(), TestSetMinusRuleBasedLearningAtom::TestSetMinusRuleBasedLearningAtom(), TestTransitiveClosureAtom::TestTransitiveClosureAtom(), and TestZeroArityAtom::TestZeroArityAtom().
| void PluginAtom::setRegistry | ( | RegistryPtr | reg | ) | [virtual] |
Associate plugin atom with registry pointer.
Should not be overridden.
This implicitly calculates the predicate ID. If overridden, the original method must be called.
As PluginAtom internally stores IDs, it has to be associated with a fixed Registry for its lifetime. Create several instantiations if you need the same atom in several registries.
PluginContainer calls this method automatically when loading a plugin and its atoms.
Definition at line 535 of file PluginInterface.cpp.
References ID_FAIL(), ID::MAINKIND_TERM, predicate, predicateID, registry, and ID::SUBKIND_TERM_CONSTANT.
| std::vector< PluginAtom::Query > PluginAtom::splitQuery | ( | const Query & | q, |
| const ExtSourceProperties & | prop | ||
| ) | [virtual] |
Splits a non-atomic query up into a set of atomic queries, such that the result of the composed query corresponds to the union of the results to the atomic queries.
Should only be overridden by experienced users. @param q A query @param prop External source properties @return std::vector<Query> A set of subqueries
Definition at line 338 of file PluginInterface.cpp.
References ID::address, ProgramCtx::config, PluginAtom::Query::ctx, DBGLOG, PluginAtom::Query::eatom, getInputType(), Configuration::getOption(), ExternalAtom::getPredicateInputMask(), PluginAtom::Query::interpretation, ExtSourceProperties::isLinearOnAtomLevel(), ExtSourceProperties::isLinearOnTupleLevel(), ID::MAINKIND_ATOM, PREDICATE, PluginAtom::Query::predicateInputMask, ID::SUBKIND_ATOM_ORDINARYG, and Atom::tuple.
Referenced by retrieve().
boost::mutex PluginAtom::cacheMutex [protected] |
Definition at line 1084 of file PluginInterface.h.
Referenced by retrieveCached().
std::vector<InputType> PluginAtom::inputType [protected] |
Type of each input argument (only last may be TUPLE).
Definition at line 1074 of file PluginInterface.h.
Referenced by addInputConstant(), addInputPredicate(), addInputTuple(), checkInputArity(), generalizeNogood(), and getInputType().
std::vector<Tuple> PluginAtom::otuples [protected] |
output tuples generated so far (used for learning for
Definition at line 1088 of file PluginInterface.h.
Referenced by retrieve().
unsigned PluginAtom::outputSize [protected] |
Definition at line 1077 of file PluginInterface.h.
Referenced by checkOutputArity(), and setOutputArity().
std::string PluginAtom::predicate [protected] |
Definition at line 1061 of file PluginInterface.h.
Referenced by setRegistry().
ID PluginAtom::predicateID [protected] |
Definition at line 1064 of file PluginInterface.h.
Referenced by setRegistry().
ExtSourceProperties PluginAtom::prop [protected] |
general properties of the external source (may be overridden on atom-level)
Definition at line 1070 of file PluginInterface.h.
Referenced by addInputPredicate(), generalizeNogood(), retrieve(), TestAppendAtom::TestAppendAtom(), TestConcatAtom::TestConcatAtom(), TestCycleAtom::TestCycleAtom(), TestEqualAtom::TestEqualAtom(), TestLessThanAtom::TestLessThanAtom(), and TestTransitiveClosureAtom::TestTransitiveClosureAtom().
QueryAnswerCache PluginAtom::queryAnswerCache [protected] |
Definition at line 1082 of file PluginInterface.h.
Referenced by retrieveCached().
QueryNogoodCache PluginAtom::queryNogoodCache [protected] |
Definition at line 1083 of file PluginInterface.h.
Referenced by retrieveCached().
RegistryPtr PluginAtom::registry [protected] |
Registry associated with this atom.
Definition at line 1096 of file PluginInterface.h.
Referenced by TestConcatAtom::retrieve(), and setRegistry().