dlvhex  2.1.0
PluginAtom Class Reference

Interface class for external Atoms. More...

#include <include/dlvhex2/PluginInterface.h>

Inheritance diagram for PluginAtom:
Collaboration diagram for PluginAtom:

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< QuerysplitQuery (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 ExtSourcePropertiesgetExtSourceProperties () 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< InputTypeinputType
 Type of each input argument (only last may be TUPLE).
unsigned outputSize
QueryAnswerCache queryAnswerCache
QueryNogoodCache queryNogoodCache
boost::mutex cacheMutex
std::vector< Tupleotuples
 output tuples generated so far (used for learning for
RegistryPtr registry
 Registry associated with this atom.

Private Member Functions

 PluginAtom (const PluginAtom &pa)
const PluginAtomoperator= (const PluginAtom &pa)

Detailed Description

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.


Member Typedef Documentation

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.


Member Enumeration Documentation

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.

Enumerator:
PREDICATE 
CONSTANT 
TUPLE 

Definition at line 825 of file PluginInterface.h.


Constructor & Destructor Documentation

PluginAtom::PluginAtom ( const std::string &  predicate,
bool  monotonic 
) [inline, protected]

Constructor.

Call this constructor when creating custom external atoms.

Parameters:
predicateThe 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,

  • you may define inputs using PluginAtom::addInput..., and
  • you must call setOutputArity().

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.


Member Function Documentation

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

Returns:
true iff arity matches.

Definition at line 151 of file PluginInterface.cpp.

References inputType, and TUPLE.

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.

Return monotonicity of atom.

Returns:
general monotonicity Should not be overridden.
external source properties associated with this plugin atom

Definition at line 991 of file PluginInterface.h.

Referenced by ExternalAtom::getExtSourceProperties().

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

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:

  • they must contain the same number of terms as pattern
  • constants in pattern must match constants in answer tuples
  • variables in pattern must be replaced by constants in answer tuples

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

Todo:
: efficiency could be increased for certain programs by considering pattern relationships as indicated above

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]
Todo:
: efficiency could be increased for certain programs by considering pattern relationships as indicated above

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


Field Documentation

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

Definition at line 1064 of file PluginInterface.h.

Referenced by setRegistry().

Definition at line 1082 of file PluginInterface.h.

Referenced by retrieveCached().

Definition at line 1083 of file PluginInterface.h.

Referenced by retrieveCached().

Registry associated with this atom.

Definition at line 1096 of file PluginInterface.h.

Referenced by TestConcatAtom::retrieve(), and setRegistry().


The documentation for this class was generated from the following files: