================================
Documentation of pyontology.py
================================

.. contents::
.. sectnum::

Prerequisites
==============

The Ontology reasoner uses the following python packages:

    Logilab constraint solver: logilab.org
    The RDFlib package: rdflib.net
    The PyParsing package: 

Usage
======

To read an ontology into the reasoner, the Ontology class has to be
instantiated. When instantiated the ontology cna be read by supplying the
ontology file to the "add_file" method. To convert the ontology into a
constraint satisfaction problem, the "attach_fd" method should be called::

    O = Ontology()
    O.add_file(<filename>)
    O.attach_fd()

Now consistency can be checked by calling the "consistency" method.

A SPARQL query can be answered by calling the "sparql" method with a query
string. If the query string is not valid, a ParserException will be raised. If
the query leads to an inconsinstent problem a ConsistencyFailure exceptionis
raised::

    O.consistency()
    query = """
        PREFIX ns: <http://example.org/ns#>
        SELECT ?x
        WHERE {
                ?x ns:p 123 . 
              }"""
    res = O.sparql(query)

The return value of the sparql method is a list of dictionaries, one dictionary
for each solution to the query. The dictionary maps query variables to values. 

Introduction
=============


The fundamental concepts of OWL (Web Ontology Language) are:

Classes
-------

Classes are defined in the following ways:

    1. a class identifier (a URI reference) (ie. (?, owl:type, owl:Classes) triples)
    2. an exhaustive enumeration of individuals that together form the instances of a class
    3. a property restriction
    4. the intersection of two or more class descriptions (intersectionOf predicate)
    5. the union of two or more class descriptions (unionOf predicate)
    6. the complement of a class description (complementOf predicate)
    
In case 2 the class is final, ie there can be no more or no less members than the enumeration gives.

Properties
-----------

Properties can be of the types owl:ObjectProperty, owl:DatatypeProperty,
owl:FunctionalProperty, owl: InverseFunctionalProperty, owl:SymmetricProperty.

Properties can have restrictions on them, either value restrictions,
cardinality restrictions or global restrictions in the form of domain and range
restrictions. 


Individuals
-----------

Individuals are instances of classes. Individuals are created either with  a owl:type predicate with object being userdefined class, by a owl:type, owl:Thing triple or by a triple with a userdefined property as predicate. Individuals has to be able to been compared. The comparison can return true, false or unknown. Individuals are equal if it has the same names, or there has been a owl:sameAs triple relating the two Individuals. Two Individuals compare unequal (return false) if there has been a owl:differentFrom (or a Alldifferent) triple.


Implementation
===============

The Ontology is read from a file (either in RDF-XML or N3 format) into a RDFLIB
Graph. The triples of the Graph are considered individually by calling the
methods on the Ontology class. 

Since the ordering of triples is random the final processing has to be
postponed until all triples have been considered. 

When all triples have been processed the semantics of the Ontology will be
contained in the objects in self.variables. In order to complete the conversion
from the OWL ontology to a constraint problem the finish method of the objects
needs to be called.

The result of considering all the triples is a constraint problem. A constraint
problem cosists of variables domains an constraints. The variables of the OWL
constraint problem are the names of the userdefined classses and userdefined
properties. Each variable has a domain which hold the individuals. The
constraints makes relations between variables. By setting the domain of each
variables, which have an empty domain (meaningthat it have no explicit
individuals) to the domain of everything (owl:Thing or owl:Property for
properties) the constraints can narrow the domain to the subset that satisfies
the constraints imposed on this class.

The domains of properties contain tuples of individual and value, so the triple
(Peter, hasParent, Mary) will put the tuple (Peter, Mary) into the domain of
the property hasParent.

Some special variables and domains are created to enable to infer facts on
Ontologies that have no individuals. 

Class hierarchy
-----------------

The class hierarchy for OWL DL ontologies is:

Classes that contains individuals::

                        ClassDomain
                        /         \
                    ThingDomain    PropertyDomain
                
There some special instances of these classes. Owl_Thing contains all
indivuals, "owl_Class" contains all classes, "rdf_Property" contains all
Properties,"owl_Restriction" contains all restriction classes.

Type
------

A "rdf:type" triple links a Urirefence to either There can be more than one
triple, for a subject, containing the predicate "rdf:Type".  These type
declarations need to checked and possibly merged. If a class is final (ie.
defined be enumerationg its instances) we cannot add more instances the the
class. If we meet a typedeclaration foran individual we shall check if it is
part off the existing definition. If we meet a typedeclaration for a class, we
need to merge the class extension of the new definition with the old
definition.

Restrictions
------------

Restrictions are anonymous classes that define restrictions on properties. The
individuals that satisfies The restriction are the Individuals that shall be in
the domain of this anonymous class. 
 
Cardinality restrictions
------------------------

Cardinality restrictions have two implications. The can be used to assert the
restrictions on individuals, to check that an individual of class fulfills the
restriction, and to check the schema of a class is consistent.  That is to
check for example that a certain class is not defined to have a maxCardinality
lower than a minCardinality for a certain property.

maxCardinality
--------------

The result of a maxCardinality restriction is all the individuals that have at
most the number of values for the property as stated in the object of the
triple. 

This is achieved by adding a constraint that will use the "getValuesPrKey"
method of the property domain and remove the individuals that do not satisfy
the constraint from the domain of the restriction. The constraint is
implementedby the class CardinalityConstraint, which takes a property class, a
restriction name, a val and a comparison string (can be '<','>' or '=').

To check for the consistency in absence of individuals, a special variable is
created with the domain of range(val + 1). This is the domain of possible
values for the cardinality.

As the name of the property might not be known when the triple containing the
cardinality restriction is being processed the actual addition of the domains
and constraint is being deferred to the finish method of the restriction class.

hasValue
--------

The hasvalue restriction defines the set of individuals which have the value
for the property concerned.

subClassOf
----------

The subClassOf triple states that the set of individuals of the subject class
shall be a subset of the setof individuals of the object class. 

When a triple with predicate "subClassOf" is considered, we add the object to
the bases attribute of the subjecct class. When the finish method is called the
domains and constraints of the subject class will be augmented with those of
the object class.

equivalentClass
----------------

The equivalentClass states that the subject class and object class contain the
same elements.

The implementation of these semantics has to consider different situations.

    1. The two classes are final. In this case the classes cannot be
       narrowed by the semantics of equivalentClass. We have to prove that the
       two classes have the same members. So we check the number of members in
       the two classes. 

    2. If the number of elements differ the only way that the two classes
       can be equivalent is if all members are the same. 

    3. If the numbers of elements are equal we try to prove equality between
       the individuals of the classes
 

The Ontology class
-------------------

ClassDomain.finish()
+++++++++++++++++++++

    1. Evaluate the uninitialised constraints of the class.
        
    2. Loop through the bases list and for each class:
       call finish()
       instantiate the constraints found in the baseclasses
       remove BNodes from the domain store
    
