PluginAtom Class Reference

Interface class for external Atoms. More...

#include <include/dlvhex2/PluginInterface.h>

Inherited by ComfortPluginAtom, FunctionComposeAtom, FunctionDecomposeAtom, FunctionDecomposeGeneralAtom, FunctionInterprete, GetArityAtom, IsFunctionTermAtom, TestAppendAtom, TestASPQueryAtom, TestConcatAllAtom, TestConcatAtom, TestCycleAtom, TestDisjAtom, TestDLSimulatorAtom, TestEqualAtom, TestFirstAtom, TestHashAtom, TestIdAtom, TestIdcAtom, TestIdpAtom, TestLessThanAtom, TestListConcatAtom, TestListDomainAtom, TestListLengthAtom, TestListMergeAtom, TestListSplitAtom, TestListSplitHalfAtom, TestMoveAtom, TestNegAtom, TestNonmon2Atom, TestNonmonAtom, TestPlugin::ProductionRequirementsAtom, TestPlugin::SumNonZeroAtom, TestPlugin::TestGen2Atom, TestPlugin::TestIsEmpty, TestPlugin::TestNumberOfBalls, TestPlugin::TestNumberOfBallsGE, TestPlugin::TestNumberOfBallsSE, TestPlugin::TestSetUnionAtom, TestPushAtom, TestReachableAtom, TestSetMinusNogoodBasedLearningAtom, TestSetMinusNonComfortAtom, TestSetMinusNongroundNogoodBasedLearningAtom, TestSetMinusPartialAtom, TestSetMinusRuleBasedLearningAtom, TestSmallerThanAtom, TestStrlenAtom, TestSubstrAtom, TestTransitiveClosureAtom, TestTrueMultiInpAtom, TestTrueMultiInpAtom2, and TestZeroArityAtom.

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 ()
	Destructor.
int	getInputArity () const
	Get input arity.
int	getOutputArity () const
	Get output arity.
bool	checkInputArity (unsigned arity) const
	Checks the input arity of the external atom against the specified arity.
bool	checkOutputArity (const ExtSourceProperties &prop, unsigned arity) const
	Checks whether the output arity of the external atom is compatible with the specified arity (also under consideration of prop.hasVariableOutputArity()).
virtual void	setupProperties (const ExternalAtom &eatom)
	Can be used to customize the generic properties of an external source for a particular external atom.
virtual void	guardSupportSet (bool &keep, Nogood &ng, const ID eaReplacement)
	Decides for a support set instance whether to keep or drop it.
bool	retrieveFacade (const Query &query, Answer &answer, NogoodContainerPtr nogoods, bool useCache)
	Single interface to answer an external query.
virtual bool	retrieveCached (const Query &query, Answer &answer, NogoodContainerPtr nogoods)
	Retrieve answer object according to a query by using the cache if possible.
virtual void	retrieve (const Query &query, Answer &answer, NogoodContainerPtr nogoods)
	Retrieve answer to a query (external computation happens here).
virtual void	retrieve (const Query &query, Answer &answer)
	Retrieve answer to a query (external computation happens here).
virtual void	learnSupportSets (const Query &query, NogoodContainerPtr nogoods)
	Is called for learning support sets.
virtual void	generalizeNogood (Nogood ng, ProgramCtx *ctx, NogoodContainerPtr nogoods)
	Tries to generalize learned nogoods to nonground nogoods.
virtual std::vector< Query >	splitQuery (const Query &query, 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.
const std::vector< InputType > &	getInputTypes () const
	Return vector of input types.
virtual bool	providesCustomExternalAtomEvaluationHeuristicsFactory () const
	Returns if this external atom provides a custom model generator factory.
virtual ExternalAtomEvaluationHeuristicsFactoryPtr	getCustomExternalAtomEvaluationHeuristicsFactory () const
	Must create a model generator factory for the component described by ci.
const ExtSourceProperties &	getExtSourceProperties () const
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).
PredicateMaskPtr	getReplacements ()
	Returns a mask of all positive replacement atoms which are currently in the registry and match with this PluginAtom.
void	resetCache ()
	Erase all elements from queryAnswerNogoodCache.
Protected Types
typedef boost::unordered_map < const Query, std::pair < Answer, SimpleNogoodContainerPtr > >	QueryAnswerNogoodCache
	Type used for associating an Answer and a NogoodContainer to a Query.
typedef boost::unordered_map < const Query, SimpleNogoodContainerPtr >	QueryNogoodCache
	Type used for associating a container of learned nogoods to a Query.
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
	ID of the predicate name, ID_FAIL if no registry is set.
bool	allmonotonic
	Whether the function is monotonic in all parameters (this will automatically declare all predicate input parameters as monotonic, see PluginAtom::prop).
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
	Number of output arguments.
QueryAnswerNogoodCache	queryAnswerNogoodCache
	Associates an Answer and a NogoodContainer to a Query.
boost::mutex	cacheMutex
	Mutex for accessing PluginAtom::queryAnswerNogoodCache.
PredicateMaskPtr	replacements
	Mask of all positive replacement atoms of this external atom.
std::vector< Tuple >	otuples
	Output tuples generated so far (used for learning for functional sources).
RegistryPtr	registry
	Registry associated with this atom.
Private Member Functions
	PluginAtom (const PluginAtom &pa)
	Copy-constructor of the plugin atom.
const PluginAtom &	operator= (const PluginAtom &pa)
	Assignment operator.

---

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:

   addInputPredicate();
   addInputPredicate();
   addInputConstant();

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. There are two overloaded versions:

   virtual void
   retrieve(const Query& query, Answer& answer)
   {

and

   virtual void
   retrieve(const Query& query, Answer& answer, NogoodContainerPtr nogoods)
   {

retrieve() always takes a query object as input and returns the result tuples in an answer object. The second version also takes a pointer to a NogoodContainer which can be used for learning additional user-defined nogoods (see NogoodContainer and ExternalLearningHelper). Note that this pointer can be NULL as external sources are sometimes evaluated without the need to learn something. However, whenever it is not NULL, the external source is free to add customized nogoods in order to prune the search space. If both methods are overridden, the second one takes precedence over the first one.

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.

If an external atom specifies that it provides partial answers (see ExtSourceProperties::providesPartialAnswer), it further must add all tuples which can become true if currently unassigned input atoms are defined using

 answer.getUnknown().push_back(tuple) 

. As this might be the case for infinitely many tuples, the (finite) set of relevant ones can be retrieved from the output atoms in the set

 replacements 

of all positive replacement atoms stemming from this external atom.

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 699 of file PluginInterface.h.

---

Member Typedef Documentation

typedef boost::unordered_map<const Query, std::pair<Answer, SimpleNogoodContainerPtr> > PluginAtom::QueryAnswerNogoodCache [protected]

Type used for associating an Answer and a NogoodContainer to a Query.

Definition at line 1313 of file PluginInterface.h.

typedef boost::unordered_map<const Query, SimpleNogoodContainerPtr> PluginAtom::QueryNogoodCache [protected]

Type used for associating a container of learned nogoods to a Query.

Definition at line 1315 of file PluginInterface.h.

---

Member Enumeration Documentation

enum PluginAtom::InputType

Type of input parameter.

Three types of input parameters can be specified: PREDICATE, CONSTANT, and TUPLE.

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	An input argument of type PREDICATE means that the atom needs those facts of the interpretation whose predicate match the value of this argument.
CONSTANT	An input argument of type CONSTANT means that only its value is relevent to the external atom, regardless of the interpretation.
TUPLE	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.

Definition at line 914 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:

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,

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

Definition at line 949 of file PluginInterface.h.

virtual PluginAtom::~PluginAtom

(

)

[inline, virtual]

Destructor.

Definition at line 996 of file PluginInterface.h.

PluginAtom::PluginAtom

(

const PluginAtom &

pa

)

[inline, private]

Copy-constructor of the plugin atom.

Parameters:

pa	Other plugin atom to copy.

Definition at line 1339 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 154 of file PluginInterface.cpp.

References CONSTANT, inputType, and TUPLE.

Referenced by FunctionDecomposeAtom::FunctionDecomposeAtom(), FunctionDecomposeGeneralAtom::FunctionDecomposeGeneralAtom(), FunctionInterprete::FunctionInterprete(), GetArityAtom::GetArityAtom(), IsFunctionTermAtom::IsFunctionTermAtom(), TestAppendAtom::TestAppendAtom(), TestASPQueryAtom::TestASPQueryAtom(), TestCycleAtom::TestCycleAtom(), TestDLSimulatorAtom::TestDLSimulatorAtom(), TestFirstAtom::TestFirstAtom(), TestPlugin::TestGen2Atom::TestGen2Atom(), TestIdcAtom::TestIdcAtom(), TestListLengthAtom::TestListLengthAtom(), TestListMergeAtom::TestListMergeAtom(), TestListSplitAtom::TestListSplitAtom(), TestListSplitHalfAtom::TestListSplitHalfAtom(), TestMinusOneAtom::TestMinusOneAtom(), TestMoveAtom::TestMoveAtom(), TestNegAtom::TestNegAtom(), TestPlugin::TestNumberOfBalls::TestNumberOfBalls(), TestPlugin::TestNumberOfBallsGE::TestNumberOfBallsGE(), TestPlugin::TestNumberOfBallsSE::TestNumberOfBallsSE(), TestPushAtom::TestPushAtom(), TestReachableAtom::TestReachableAtom(), TestSmallerThanAtom::TestSmallerThanAtom(), TestStrlenAtom::TestStrlenAtom(), TestSubstrAtom::TestSubstrAtom(), TestTrueMultiInpAtom::TestTrueMultiInpAtom(), and TestTrueMultiInpAtom2::TestTrueMultiInpAtom2().

void PluginAtom::addInputPredicate

(

bool

nameIsRelevant = false

)

[protected]

Adds an input parameter of type PREDICATE.

Parameters:

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 138 of file PluginInterface.cpp.

References allmonotonic, inputType, ExtSourceProperties::monotonicInputPredicates, PREDICATE, ExtSourceProperties::predicateParameterNameIndependence, prop, and TUPLE.

Referenced by TestPlugin::ProductionRequirementsAtom::ProductionRequirementsAtom(), TestPlugin::SumNonZeroAtom::SumNonZeroAtom(), TestAAtom::TestAAtom(), TestAppendAtom::TestAppendAtom(), TestASPQueryAtom::TestASPQueryAtom(), TestBAtom::TestBAtom(), TestCAtom::TestCAtom(), TestConcatAllAtom::TestConcatAllAtom(), TestCycleAtom::TestCycleAtom(), TestDisjAtom::TestDisjAtom(), TestDLSimulatorAtom::TestDLSimulatorAtom(), TestEqualAtom::TestEqualAtom(), TestEvenAtom::TestEvenAtom(), TestPlugin::TestGen2Atom::TestGen2Atom(), TestHashAtom::TestHashAtom(), TestIdAtom::TestIdAtom(), TestIdpAtom::TestIdpAtom(), TestPlugin::TestIsEmpty::TestIsEmpty(), TestLessThanAtom::TestLessThanAtom(), TestMoveAtom::TestMoveAtom(), TestNegAtom::TestNegAtom(), TestNonmon2Atom::TestNonmon2Atom(), TestNonmonAtom::TestNonmonAtom(), TestPlugin::TestNumberOfBalls::TestNumberOfBalls(), TestPlugin::TestNumberOfBallsGE::TestNumberOfBallsGE(), TestPlugin::TestNumberOfBallsSE::TestNumberOfBallsSE(), TestOddAtom::TestOddAtom(), TestReachableAtom::TestReachableAtom(), TestSetMinusAtom::TestSetMinusAtom(), TestSetMinusNogoodBasedLearningAtom::TestSetMinusNogoodBasedLearningAtom(), TestSetMinusNonComfortAtom::TestSetMinusNonComfortAtom(), TestSetMinusNongroundNogoodBasedLearningAtom::TestSetMinusNongroundNogoodBasedLearningAtom(), TestSetMinusPartialAtom::TestSetMinusPartialAtom(), TestSetMinusRuleBasedLearningAtom::TestSetMinusRuleBasedLearningAtom(), TestPlugin::TestSetUnionAtom::TestSetUnionAtom(), and TestTransitiveClosureAtom::TestTransitiveClosureAtom().

void PluginAtom::addInputTuple

(

)

[protected]

Adds an input parameter of type TUPLE.

Only use in constructor!

Definition at line 166 of file PluginInterface.cpp.

References inputType, and TUPLE.

Referenced by FunctionComposeAtom::FunctionComposeAtom(), FunctionInterprete::FunctionInterprete(), TestConcatAtom::TestConcatAtom(), TestListConcatAtom::TestListConcatAtom(), and TestListDomainAtom::TestListDomainAtom().

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 if arity matches and false otherwise.

Definition at line 187 of file PluginInterface.cpp.

References inputType, and TUPLE.

Referenced by DependencyGraph::createExternalPredicateInputDependencies(), and DependencyGraph::createNodesAndIntraRuleDependenciesForBody().

bool PluginAtom::checkOutputArity	(	const ExtSourceProperties &	prop,
		unsigned	arity
	)		const

Checks whether the output arity of the external atom is compatible with the specified arity (also under consideration of prop.hasVariableOutputArity()).

Returns:

True if the check is passed and false otherwise.

Definition at line 208 of file PluginInterface.cpp.

References ExtSourceProperties::hasVariableOutputArity(), and outputSize.

Referenced by 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.

Parameters:

ng	A learned nogood with some external atom auxiliary over this external predicate.
ctx	Program context.
nogoods	The nogood container where related nogoods shall be added.

Definition at line 560 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.

virtual ExternalAtomEvaluationHeuristicsFactoryPtr PluginAtom::getCustomExternalAtomEvaluationHeuristicsFactory

(

)

const [inline, virtual]

Must create a model generator factory for the component described by ci.

Needs to be implemented only if PluginAtom::providesCustomExternalAtomEvaluationHeuristicsFactory return true;

Returns:

True if this plugin provides a custom heuristics for external atom evaluations, false otherwise.

Reimplemented in TestSetMinusAtom.

Definition at line 1210 of file PluginInterface.h.

Referenced by GenuineGuessAndCheckModelGenerator::initializeHeuristics().

const ExtSourceProperties& PluginAtom::getExtSourceProperties

(

)

const [inline]

Returns:

External source properties associated with this plugin atom (applies to all external atoms of this kind, unless they override the properties).

Definition at line 1216 of file PluginInterface.h.

int PluginAtom::getInputArity

(

)

const

Get input arity.

Returns:

int Input arity, where a tuple parameter is counted once.

Definition at line 173 of file PluginInterface.cpp.

References inputType.

PluginAtom::InputType PluginAtom::getInputType

(

unsigned

index

)

const

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

Returns:

Type of input parameter with index index

Definition at line 644 of file PluginInterface.cpp.

References inputType, and TUPLE.

Referenced by ComponentGraph::calculatePredicatesOfComponent(), ComponentGraph::calculateStratificationInfo(), AnnotatedGroundProgram::computeAdditionalDependencies(), ComponentGraph::computeCollapsedComponentInfos(), BaseModelGenerator::computeExtensionOfDomainPredicates(), ComponentGraph::computeRecursiveAggregatesInComponent(), DependencyGraph::createAuxiliaryRuleIfRequired(), LiberalSafetyChecker::createDependencyGraph(), DependencyGraph::createExternalPredicateInputDependencies(), LiberalSafetyChecker::createPreconditionsAndLocationIndices(), generalizeNogood(), ExternalAtomMask::matchOutputAtom(), DLVHEX_NAMESPACE_BEGIN::FinitenessChecker::run(), 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.

Returns:

Vector of input types

Definition at line 1195 of file PluginInterface.h.

Referenced by ExtSourceProperties::isAntimonotonic(), and ExtSourceProperties::isMonotonic().

int PluginAtom::getOutputArity

(

)

const

Get output arity.

Returns:

int Output arity.

Definition at line 180 of file PluginInterface.cpp.

References outputSize.

const std::string& PluginAtom::getPredicate

(

)

const [inline]

Get predicate name (as specified in constructor).

Should not be overridden.

Returns:

Predicate name specified in the constructor (without leading &)

Definition at line 1274 of file PluginInterface.h.

Referenced by DependencyGraph::createExternalPredicateInputDependencies(), ExternalAtom::print(), and BaseModelGenerator::verifyEAtomAnswerTuple().

ID PluginAtom::getPredicateID

(

)

const [inline]

Get ID of the predicate name.

Should not be overridden.

Returns:

ID of the predicate name specified in the constructor or ID_FAIL if no registry is set.

Definition at line 1264 of file PluginInterface.h.

Referenced by BaseModelGeneratorFactory::convertRuleBody(), BaseModelGenerator::evaluateExternalAtom(), generalizeNogood(), and BaseModelGenerator::learnSupportSetsForExternalAtom().

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.

Returns:

Pointer to the registry used by this plugin.

Definition at line 1254 of file PluginInterface.h.

Referenced by TestCautiousQueryAtom::answerQuery(), TestBraveQueryAtom::answerQuery(), FunctionInterprete::containsPlaceholder(), ExternalAtomMask::matchOutputAtom(), ExternalAtom::print(), FunctionComposeAtom::retrieve(), FunctionDecomposeAtom::retrieve(), IsFunctionTermAtom::retrieve(), GetArityAtom::retrieve(), FunctionDecomposeGeneralAtom::retrieve(), FunctionInterprete::retrieve(), ComfortPluginAtom::retrieve(), TestSetMinusNonComfortAtom::retrieve(), TestSetMinusPartialAtom::retrieve(), TestSetMinusNogoodBasedLearningAtom::retrieve(), TestSetMinusNongroundNogoodBasedLearningAtom::retrieve(), TestSetMinusRuleBasedLearningAtom::retrieve(), TestNonmonAtom::retrieve(), TestNonmon2Atom::retrieve(), TestIdAtom::retrieve(), TestIdpAtom::retrieve(), TestNegAtom::retrieve(), TestLessThanAtom::retrieve(), TestEqualAtom::retrieve(), TestTransitiveClosureAtom::retrieve(), TestCycleAtom::retrieve(), TestAppendAtom::retrieve(), TestDisjAtom::retrieve(), TestHashAtom::retrieve(), TestReachableAtom::retrieve(), TestDLSimulatorAtom::retrieve(), TestPlugin::TestSetUnionAtom::retrieve(), TestPlugin::TestGen2Atom::retrieve(), TestPlugin::SumNonZeroAtom::retrieve(), TestPlugin::ProductionRequirementsAtom::retrieve(), TestASPQueryAtom::retrieveOrLearnSupportSets(), ExternalAtomMask::updateMask(), ExternalAtom::updatePredicateInputMask(), and BaseModelGenerator::VerifyExternalAtomCB::VerifyExternalAtomCB().

PredicateMaskPtr PluginAtom::getReplacements

(

)

[inline]

Returns a mask of all positive replacement atoms which are currently in the registry and match with this PluginAtom.

Definition at line 1278 of file PluginInterface.h.

virtual void PluginAtom::guardSupportSet	(	bool &	keep,
		Nogood &	ng,
		const ID	eaReplacement
	)		[inline, virtual]

Decides for a support set instance whether to keep or drop it.

Decides for a ground support set if it should be kept (in possibly modified form) or rejected. This allows for checking the satisfaction of guard literals in the nogood, which depend on the external source.

Parameters:

keep	Must be set to true if ng should be kept.
ng	The ground nogood, for which the method calls must decide if it should be kept. If keep is true, then ng might be modified such that the resulting nogood is a subset of the original one. If keep is false, then ng must be unchanged.
eaReplacement	The ID of the external atom replacement in ng (just for user convenience)

Definition at line 1060 of file PluginInterface.h.

References Nogood::isGround().

void PluginAtom::learnSupportSets	(	const Query &	query,
		NogoodContainerPtr	nogoods
	)		[virtual]

Is called for learning support sets.

Needs to be implemented if PluginAtom::prop declares that the external source provides support sets.

This function implements the learning of support sets from external atoms. The learned support sets should be added to .

Parameters:

query	Input to the external source.
nogoods	Support sets learned from the external source.

Reimplemented in TestASPQueryAtom.

Definition at line 443 of file PluginInterface.cpp.

References prop, and ExtSourceProperties::providesSupportSets().

Referenced by BaseModelGenerator::learnSupportSetsForExternalAtom().

const PluginAtom& PluginAtom::operator=

(

const PluginAtom &

pa

)

[inline, private]

Assignment operator.

Parameters:

pa	Other plugin atom to assign.

Returns:

Reference to this object.

Definition at line 1346 of file PluginInterface.h.

virtual bool PluginAtom::providesCustomExternalAtomEvaluationHeuristicsFactory

(

)

const [inline, virtual]

Returns if this external atom provides a custom model generator factory.

Returns:

True if this plugin provides a custom heuristics for external atom evaluations, false otherwise.

Reimplemented in TestSetMinusAtom.

Definition at line 1203 of file PluginInterface.h.

Referenced by GenuineGuessAndCheckModelGenerator::initializeHeuristics().

void PluginAtom::resetCache

(

)

[inline]

Erase all elements from queryAnswerNogoodCache.

Definition at line 1283 of file PluginInterface.h.

void PluginAtom::retrieve	(	const Query &	query,
		Answer &	answer,
		NogoodContainerPtr	nogoods
	)		[virtual]

Retrieve answer to a query (external computation happens here).

This function implements the external atom computation with customized learning functions.

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

See also documentation of Query and Answer classes.

If both retrieve(const Query& query, Answer& answer) and retrieve(const Query& query, Answer& answer, NogoodContainerPtr nogoods) are overridden, the latter takes over precedence.

Parameters:

query	Input to the external source.
answer	Output of the external source.
nogoods	Here, nogoods learned from the external source can be added to prune the search space; see Nogood, NogoodContainer and ExternalLearningHelper.

Reimplemented in TestPlugin::TestSetUnionAtom, TestASPQueryAtom, TestSetMinusRuleBasedLearningAtom, TestSetMinusNongroundNogoodBasedLearningAtom, and TestSetMinusNogoodBasedLearningAtom.

Definition at line 430 of file PluginInterface.cpp.

References DBGLOG.

Referenced by retrieveCached(), and retrieveFacade().

void PluginAtom::retrieve	(	const Query &	query,
		Answer &	answer
	)		[virtual]

Retrieve answer to a query (external computation happens here).

This function implements the external atom computation without customized learning functions.

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

See also documentation of Query and Answer classes.

If both retrieve(const Query& query, Answer& answer) and retrieve(const Query& query, Answer& answer, NogoodContainerPtr nogoods) are overridden, the latter takes over precedence.

Parameters:

query	Input to the external source.
answer	Output of the external source.

Reimplemented in TestPlugin::ProductionRequirementsAtom, TestPlugin::SumNonZeroAtom, TestPlugin::TestNumberOfBallsGE, TestPlugin::TestNumberOfBallsSE, TestPlugin::TestNumberOfBalls, TestPlugin::TestIsEmpty, TestPlugin::TestGen2Atom, TestPlugin::TestSetUnionAtom, TestASPQueryAtom, TestDLSimulatorAtom, TestReachableAtom, TestTrueMultiInpAtom2, TestTrueMultiInpAtom, TestHashAtom, TestDisjAtom, TestAppendAtom, TestCycleAtom, TestTransitiveClosureAtom, TestEqualAtom, TestLessThanAtom, TestNegAtom, TestIdcAtom, TestIdpAtom, TestIdAtom, TestNonmon2Atom, TestNonmonAtom, TestSetMinusPartialAtom, TestSetMinusNonComfortAtom, TestStrlenAtom, TestMoveAtom, TestPushAtom, TestFirstAtom, TestSmallerThanAtom, TestSubstrAtom, ComfortPluginAtom, TestListMergeAtom, TestListSplitHalfAtom, TestListSplitAtom, TestListLengthAtom, FunctionInterprete, TestListConcatAtom, FunctionDecomposeGeneralAtom, TestListDomainAtom, GetArityAtom, IsFunctionTermAtom, FunctionDecomposeAtom, TestConcatAllAtom, FunctionComposeAtom, TestConcatAtom, and TestZeroArityAtom.

Definition at line 437 of file PluginInterface.cpp.

References DBGLOG.

bool PluginAtom::retrieveCached	(	const Query &	query,
		Answer &	answer,
		NogoodContainerPtr	nogoods
	)		[virtual]

Retrieve answer object according to a query by using the cache if possible.

This function implements the query cache, if enabled, and will rarely need to be overridden. If the query cannot be answered from the cache, it will be forwarded to the PluginAtom::retrieve method.

Parameters:

query	Input to the external source.
answer	Output of the external source.
nogoods	Here, nogoods learned from the external source can be added to prune the search space; see Nogood, NogoodContainer and ExternalLearningHelper.

Returns:

True if the query was answered from cache and false otherwise.

Todo:

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

Definition at line 307 of file PluginInterface.cpp.

References PluginAtom::Query::assign(), cacheMutex, PluginAtom::Query::ctx, DBGLOG, DLVHEX_BENCHMARK_REGISTER_AND_SCOPE, DLVHEX_BENCHMARK_REGISTER_AND_START, DLVHEX_BENCHMARK_STOP, queryAnswerNogoodCache, ProgramCtx::registry(), retrieve(), and PluginAtom::Answer::use().

Referenced by retrieveFacade().

bool PluginAtom::retrieveFacade	(	const Query &	query,
		Answer &	answer,
		NogoodContainerPtr	nogoods,
		bool	useCache
	)

Single interface to answer an external query.

Will delegate the call to the other retrieve functions depending on the settings.

The function performs the following operations. 1. It splits the query into atomic queries using PluginAtom::splitQuery. 2. It answers the atomic queries by calling either PluginAtom::retrieveCached or PluginAtom::retrieve, depending on the settings. 3. It applies default learning methods to the result (e.g. learning from IO behavior, monotonicity, functionality, etc.).

This method must not be overridden.

Parameters:

query	Input to the external source.
answer	Output of the external source.
nogoods	Here, nogoods learned from the external source can be added to prune the search space; see Nogood, NogoodContainer and ExternalLearningHelper.
useCache	True to use the cache (if possible), false to answer the query directly.

Returns:

True if the query was answered from cache and false otherwise.

Definition at line 255 of file PluginInterface.cpp.

References ProgramCtx::config, PluginAtom::Query::ctx, DBGLOG, DLVHEX_BENCHMARK_REGISTER_AND_SCOPE, PluginAtom::Query::eatomID, PluginAtom::Answer::get(), Configuration::getOption(), PluginAtom::Answer::getUnknown(), ID_FAIL(), ExtSourceProperties::isFunctional(), ExternalLearningHelper::learnFromFunctionality(), ExternalLearningHelper::learnFromInputOutputBehavior(), ExternalLearningHelper::learnFromNegativeAtoms(), otuples, prop, registry, replacements, retrieve(), retrieveCached(), and splitQuery().

Referenced by BaseModelGenerator::evaluateExternalAtomQuery().

void PluginAtom::setOutputArity

(

unsigned

arity

)

[protected]

Specifies the output arity of the external Atom.

Only use in constructor!

Use prop.setVariableOutputArity(true) to define an external atom with variable output arity.

Parameters:

arity

The desired output arity >= 0.

Definition at line 201 of file PluginInterface.cpp.

References outputSize.

Referenced by FunctionComposeAtom::FunctionComposeAtom(), FunctionDecomposeAtom::FunctionDecomposeAtom(), FunctionDecomposeGeneralAtom::FunctionDecomposeGeneralAtom(), FunctionInterprete::FunctionInterprete(), GetArityAtom::GetArityAtom(), IsFunctionTermAtom::IsFunctionTermAtom(), TestPlugin::ProductionRequirementsAtom::ProductionRequirementsAtom(), TestPlugin::SumNonZeroAtom::SumNonZeroAtom(), TestAAtom::TestAAtom(), TestAppendAtom::TestAppendAtom(), TestASPQueryAtom::TestASPQueryAtom(), TestBAtom::TestBAtom(), TestCAtom::TestCAtom(), TestConcatAllAtom::TestConcatAllAtom(), TestConcatAtom::TestConcatAtom(), TestCycleAtom::TestCycleAtom(), TestDisjAtom::TestDisjAtom(), TestDLSimulatorAtom::TestDLSimulatorAtom(), TestEqualAtom::TestEqualAtom(), TestEvenAtom::TestEvenAtom(), TestFirstAtom::TestFirstAtom(), TestPlugin::TestGen2Atom::TestGen2Atom(), TestHashAtom::TestHashAtom(), TestIdAtom::TestIdAtom(), TestIdcAtom::TestIdcAtom(), TestIdpAtom::TestIdpAtom(), TestPlugin::TestIsEmpty::TestIsEmpty(), TestLessThanAtom::TestLessThanAtom(), TestListConcatAtom::TestListConcatAtom(), TestListDomainAtom::TestListDomainAtom(), TestListLengthAtom::TestListLengthAtom(), TestListMergeAtom::TestListMergeAtom(), TestListSplitAtom::TestListSplitAtom(), TestListSplitHalfAtom::TestListSplitHalfAtom(), TestMinusOneAtom::TestMinusOneAtom(), TestMoveAtom::TestMoveAtom(), TestNegAtom::TestNegAtom(), TestNonmon2Atom::TestNonmon2Atom(), TestNonmonAtom::TestNonmonAtom(), TestPlugin::TestNumberOfBalls::TestNumberOfBalls(), TestPlugin::TestNumberOfBallsGE::TestNumberOfBallsGE(), TestPlugin::TestNumberOfBallsSE::TestNumberOfBallsSE(), TestOddAtom::TestOddAtom(), TestPushAtom::TestPushAtom(), TestReachableAtom::TestReachableAtom(), TestSetMinusAtom::TestSetMinusAtom(), TestSetMinusNogoodBasedLearningAtom::TestSetMinusNogoodBasedLearningAtom(), TestSetMinusNonComfortAtom::TestSetMinusNonComfortAtom(), TestSetMinusNongroundNogoodBasedLearningAtom::TestSetMinusNongroundNogoodBasedLearningAtom(), TestSetMinusPartialAtom::TestSetMinusPartialAtom(), TestSetMinusRuleBasedLearningAtom::TestSetMinusRuleBasedLearningAtom(), TestPlugin::TestSetUnionAtom::TestSetUnionAtom(), TestSmallerThanAtom::TestSmallerThanAtom(), TestStrlenAtom::TestStrlenAtom(), TestSubstrAtom::TestSubstrAtom(), TestTransitiveClosureAtom::TestTransitiveClosureAtom(), TestTrueMultiInpAtom::TestTrueMultiInpAtom(), TestTrueMultiInpAtom2::TestTrueMultiInpAtom2(), 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.

Parameters:

reg	Pointer to the registry to set.

Definition at line 655 of file PluginInterface.cpp.

References ID_FAIL(), ID::MAINKIND_TERM, predicate, predicateID, registry, replacements, and ID::SUBKIND_TERM_CONSTANT.

virtual void PluginAtom::setupProperties

(

const ExternalAtom &

eatom

)

[inline, virtual]

Can be used to customize the generic properties of an external source for a particular external atom.

The function is called once for each external atom in order to finalize the initialization of its properties. While the properties in class PluginAtom apply to all external atoms of the type, this method can modify the properties for selected external atoms. It may inspect the input list and set additional external atom properties, which do not hold in general but only for a certain usage of the external source.

Example: Let

 {.txt}&sql[r1, ..., rn, query](X1, ..., Xm)

be an SQL-query processor over relations r1, ..., rn. Then &sql is in general not monotonic, but if query is a simple selection of all tuples, then it becomes monotonic.

When this method is called, eatom.prop already contains the properties derived from the plugin and specified directly in the HEX-program (using syntax <...>). This method may modify them or add additional properties.

Parameters:

eatom

Reference to the external atom whose properties are to be initialized.

Definition at line 1047 of file PluginInterface.h.

std::vector< PluginAtom::Query > PluginAtom::splitQuery	(	const Query &	query,
		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. By default, queries will be split according to the linearity properties defined in (if an external source does not have such properties, then the query is passed as is to one of the retrieve methods). By overriding the method, customized decomposition strategies may be implemented.

Parameters:

query	The original query to split up.
prop	External source properties.

Returns:

A set of subqueries to be sent to one of the retrieve methods.

Definition at line 449 of file PluginInterface.cpp.

References ID::address, ProgramCtx::config, PluginAtom::Query::ctx, DBGLOG, PluginAtom::Query::eatomID, getInputType(), Configuration::getOption(), ExternalAtom::getPredicateInputMask(), ID_FAIL(), PluginAtom::Query::interpretation, ExtSourceProperties::isLinearOnAtomLevel(), ExtSourceProperties::isLinearOnTupleLevel(), ID::MAINKIND_ATOM, PREDICATE, PluginAtom::Query::predicateInputMask, ProgramCtx::registry(), ID::SUBKIND_ATOM_ORDINARYG, and Atom::tuple.

Referenced by retrieveFacade().

---

Field Documentation

bool PluginAtom::allmonotonic [protected]

Whether the function is monotonic in all parameters (this will automatically declare all predicate input parameters as monotonic, see PluginAtom::prop).

Definition at line 1300 of file PluginInterface.h.

Referenced by addInputPredicate().

boost::mutex PluginAtom::cacheMutex [protected]

Mutex for accessing PluginAtom::queryAnswerNogoodCache.

Definition at line 1319 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 1306 of file PluginInterface.h.

Referenced by addInputConstant(), addInputPredicate(), addInputTuple(), checkInputArity(), generalizeNogood(), getInputArity(), and getInputType().

std::vector<Tuple> PluginAtom::otuples [protected]

Output tuples generated so far (used for learning for functional sources).

Definition at line 1325 of file PluginInterface.h.

Referenced by retrieveFacade().

unsigned PluginAtom::outputSize [protected]

Number of output arguments.

Definition at line 1309 of file PluginInterface.h.

Referenced by checkOutputArity(), getOutputArity(), and setOutputArity().

std::string PluginAtom::predicate [protected]

Definition at line 1294 of file PluginInterface.h.

Referenced by setRegistry().

ID PluginAtom::predicateID [protected]

ID of the predicate name, ID_FAIL if no registry is set.

Definition at line 1297 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 1303 of file PluginInterface.h.

Referenced by addInputPredicate(), FunctionComposeAtom::FunctionComposeAtom(), FunctionDecomposeAtom::FunctionDecomposeAtom(), FunctionDecomposeGeneralAtom::FunctionDecomposeGeneralAtom(), generalizeNogood(), GetArityAtom::GetArityAtom(), IsFunctionTermAtom::IsFunctionTermAtom(), learnSupportSets(), TestPlugin::ProductionRequirementsAtom::ProductionRequirementsAtom(), retrieveFacade(), TestAppendAtom::TestAppendAtom(), TestASPQueryAtom::TestASPQueryAtom(), TestConcatAllAtom::TestConcatAllAtom(), TestConcatAtom::TestConcatAtom(), TestCycleAtom::TestCycleAtom(), TestEqualAtom::TestEqualAtom(), TestFirstAtom::TestFirstAtom(), TestIdpAtom::TestIdpAtom(), TestLessThanAtom::TestLessThanAtom(), TestListConcatAtom::TestListConcatAtom(), TestListDomainAtom::TestListDomainAtom(), TestListLengthAtom::TestListLengthAtom(), TestListMergeAtom::TestListMergeAtom(), TestListSplitAtom::TestListSplitAtom(), TestListSplitHalfAtom::TestListSplitHalfAtom(), TestMoveAtom::TestMoveAtom(), TestNonmonAtom::TestNonmonAtom(), TestPlugin::TestNumberOfBalls::TestNumberOfBalls(), TestPlugin::TestNumberOfBallsGE::TestNumberOfBallsGE(), TestPlugin::TestNumberOfBallsSE::TestNumberOfBallsSE(), TestPushAtom::TestPushAtom(), TestReachableAtom::TestReachableAtom(), TestSetMinusAtom::TestSetMinusAtom(), TestSetMinusNonComfortAtom::TestSetMinusNonComfortAtom(), TestSetMinusNongroundNogoodBasedLearningAtom::TestSetMinusNongroundNogoodBasedLearningAtom(), TestSetMinusPartialAtom::TestSetMinusPartialAtom(), TestSmallerThanAtom::TestSmallerThanAtom(), TestStrlenAtom::TestStrlenAtom(), TestSubstrAtom::TestSubstrAtom(), and TestTransitiveClosureAtom::TestTransitiveClosureAtom().

QueryAnswerNogoodCache PluginAtom::queryAnswerNogoodCache [protected]

Associates an Answer and a NogoodContainer to a Query.

Definition at line 1317 of file PluginInterface.h.

Referenced by retrieveCached().

RegistryPtr PluginAtom::registry [protected]

Registry associated with this atom.

This association cannot be done by the plugin itself, it is done by the PluginContainer loading or receiving the plugin.

Definition at line 1332 of file PluginInterface.h.

Referenced by TestConcatAtom::retrieve(), FunctionComposeAtom::retrieve(), TestConcatAllAtom::retrieve(), FunctionDecomposeAtom::retrieve(), IsFunctionTermAtom::retrieve(), GetArityAtom::retrieve(), TestListDomainAtom::retrieve(), FunctionDecomposeGeneralAtom::retrieve(), TestListConcatAtom::retrieve(), FunctionInterprete::retrieve(), TestListLengthAtom::retrieve(), TestListSplitAtom::retrieve(), TestListSplitHalfAtom::retrieve(), TestListMergeAtom::retrieve(), TestSubstrAtom::retrieve(), TestSmallerThanAtom::retrieve(), TestFirstAtom::retrieve(), TestPushAtom::retrieve(), TestMoveAtom::retrieve(), TestStrlenAtom::retrieve(), TestPlugin::SumNonZeroAtom::retrieve(), TestPlugin::ProductionRequirementsAtom::retrieve(), retrieveFacade(), and setRegistry().

PredicateMaskPtr PluginAtom::replacements [protected]

Mask of all positive replacement atoms of this external atom.

Definition at line 1322 of file PluginInterface.h.

Referenced by retrieveFacade(), and setRegistry().

---

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

• include/dlvhex2/PluginInterface.h
• src/PluginInterface.cpp