Knowledge providers

struct TmeAxiomProvider

This structure acts as an axiom provider for the reasoner.

The TmeAxiomProvider interface must be implemented in order to provide axioms to the reasoner instance. This allows the inference services implemented in the Core to be reusable regardless of how axioms are stored or parsed.

Implementation of this interface must come in the form of function pointers provided to the tme_axiom_provider_alloc() function. Please refer to its documentation for further info.

See

TmeReasoner

Public Functions

TmeAxiomProvider *tme_axiom_provider_alloc(void *axiom_source, TmeVocabulary (*get_vocabulary)(void *axiom_source), Vector_TmeEntityPtr *(*get_atomic_concepts)(void *axiom_source), TmeSemDesc *(*get_concept_description)(void *axiom_source, TmeEntityPtr concept, TmeSubsumers *subsumers), Vector_TmeEntityPtr *(*get_atomic_individuals)(void *axiom_source), TmeSemDesc *(*get_individual_description)(void *axiom_source, TmeEntityPtr individual), void (*axiom_source_free)(void *axiom_source))

Allocates a new axiom provider.

Unless otherwise stated, the data structures returned by the functions implementing the axiom provider interface must respect the following rules:

• They must not be NULL.

• They must be dynamically allocated.

• They must never be directly freed.

Return

Axiom provider instance.

Parameters

• axiom_source: Context for the subsequent handlers.

• get_vocabulary: Implements tme_axiom_provider_get_vocabulary().

• get_atomic_concepts: Implements tme_axiom_provider_get_concepts().

• get_concept_description: Implements tme_axiom_provider_get_concept_description().

• get_atomic_individuals: Implements tme_axiom_provider_get_individuals().

• get_individual_description: Implements tme_axiom_provider_get_individual_description().

• axiom_source_free: Called as part of tme_axiom_provider_free().

void tme_axiom_provider_free(TmeAxiomProvider *provider)

Deallocates the axiom provider.

Parameters

• provider: Axiom provider to deallocate.

TmeVocabulary tme_axiom_provider_get_vocabulary(TmeAxiomProvider const *provider)

Retrieves the vocabulary.

Return

Vocabulary.

Parameters

• provider: Axiom provider instance.

Vector_TmeEntityPtr *tme_axiom_provider_get_concepts(TmeAxiomProvider const *provider)

Retrieves all the concepts in the TBox.

This function must return all the concepts present in the TBox. The reasoner instance iterates over them, calling tme_axiom_provider_get_concept_description() for each concept, in order to populate its data structures.

Return

All the concepts in the TBox.

Parameters

• provider: Axiom provider instance.

TmeSemDesc *tme_axiom_provider_get_concept_description(TmeAxiomProvider const *provider, TmeEntityPtr concept, TmeSubsumers *subsumers)

Retrieves the semantic description of the specified concept.

The returned description must be the intersection of subsumers and equivalents. It is not necessary to intersect subsumers recursively: direct subsumers are enough.

Furthermore, it is essential to populate the subsumers structure as follows:

• Named equivalents must be marked as such via tme_subsumers_add_named_equivalence().

• Named subsumers must be marked as such via tme_subsumers_add_told(). Also in this case, direct subsumers are enough.

• As a special case, subsumers of the bottom concept are actually equivalent to it, so they must be marked via tme_subsumers_add_named_equivalence().

• The presence of an equivalence with a class expression must be marked by calling tme_subsumers_mark_equivalence_with_expression().

Return

Semantic description of the specified concept.

Parameters

• provider: Axiom provider instance.

• concept: Concept whose description should be retrieved.

• [out] subsumers: Subsumers of the specified concept.

Vector_TmeEntityPtr *tme_axiom_provider_get_individuals(TmeAxiomProvider const *provider)

Retrieves all the individuals in the ABox.

This function must return all the individuals present in the ABox. The reasoner instance iterates over them, calling tme_axiom_provider_get_individual_description() for each individual, in order to populate its data structures.

Return

All the individuals in the ABox.

Parameters

• provider: Axiom provider instance.

TmeSemDesc *tme_axiom_provider_get_individual_description(TmeAxiomProvider const *provider, TmeEntityPtr individual)

Retrieves the semantic description of the specified individual.

The returned description must be the intersection of the types associated with the individual. It is not necessary to intersect types recursively: “leaf” types are enough.

Return

Semantic description of the specified individual.

Parameters

• provider: Axiom provider instance.

• individual: Individual whose description should be retrieved.

struct TmeStringProvider

This structure acts as a string provider for the reasoner.

The TmeStringProvider interface must be implemented in order to map entity identifiers to their human-readable representations (usually IRIs).

Implementation of this interface must come in the form of function pointers provided to the tme_string_provider_alloc() function. Please refer to its documentation for further info.

See

TmeLogger

Model

TmeString tme_string_for_entity_iri(TmeStringProvider const *provider, TmeEntityPtr entity_ptr)

Returns the IRI associated with the specified entity.

Return

String representation.

Parameters

• provider: String provider instance.

• entity_ptr: Entity identifier.

TmeString tme_string_for_entity(TmeStringProvider const *provider, TmeEntityPtr entity_ptr)

Returns a readable representation of the specified entity.

Return

String representation.

Parameters

• provider: String provider instance.

• entity_ptr: Entity identifier.

TmeString tme_string_for_negated_entity(TmeStringProvider const *provider, TmeEntityPtr entity_ptr)

Returns a readable representation of the specified negated entity.

Return

String representation.

Parameters

• provider: String provider instance.

• entity_ptr: Entity identifier.

TmeString tme_string_for_card_role(TmeStringProvider const *provider, TmeCardinalityRole role)

Returns a readable representation of the specified cardinality restriction.

Return

String representation.

Parameters

• provider: String provider instance.

• role: Cardinality restriction.

TmeString tme_string_for_gt_role(TmeStringProvider const *provider, TmeCardinalityRole role)

Returns a readable representation of the specified minimum cardinality restriction.

Return

String representation.

Parameters

• provider: String provider instance.

• role: Cardinality restriction.

TmeString tme_string_for_lt_role(TmeStringProvider const *provider, TmeCardinalityRole role)

Returns a readable representation of the specified maximum cardinality restriction.

Return

String representation.

Parameters

• provider: String provider instance.

• role: Cardinality restriction.

TmeString tme_string_for_uv_role(TmeStringProvider const *provider, TmeUniversalRole role)

Returns a readable representation of the specified value restriction.

Return

String representation.

Parameters

• provider: String provider instance.

• role: Value restriction.

TmeString tme_string_for_sem_desc(TmeStringProvider const *provider, TmeSemDesc const *desc)

Returns a readable representation of the specified semantic description.

Return

String representation.

Parameters

• provider: String provider instance.

• desc: Semantic description.

TmeString tme_string_for_abduction(TmeStringProvider const *provider, TmeAbduction abduction)

Returns a readable representation of the specified abduction result.

Return

String representation.

Parameters

• provider: String provider instance.

• abduction: Abduction result.

TmeString tme_string_for_bonus(TmeStringProvider const *provider, TmeBonus bonus)

Returns a readable representation of the specified bonus result.

Return

String representation.

Parameters

• provider: String provider instance.

• bonus: Bonus result.

TmeString tme_string_for_contraction(TmeStringProvider const *provider, TmeContraction contraction)

Returns a readable representation of the specified contraction result.

Return

String representation.

Parameters

• provider: String provider instance.

• contraction: Contraction result.

TmeString tme_string_for_composition(TmeStringProvider const *provider, TmeComposition composition)

Returns a readable representation of the specified covering result.

Return

String representation.

Parameters

• provider: String provider instance.

• composition: Covering result.

Misc

TmeString tme_string_for_reasoner_metadata(void)

Returns a formatted, multi-line description of the reasoner (name, version, vendor, etc.).

Return

Reasoner description.

TmeString tme_string_from_nanos(uint64_t nanos, TmeTimeUnit unit)

Returns a readable representation of the specified time interval in nanoseconds.

Return

String representation.

Parameters

• nanos: Time interval in nanoseconds.

• unit: Desired time unit.

void tme_string_sort_entities(TmeStringProvider *provider, Vector_TmeEntityPtr *entities)

Sorts the specified entities by their human-readable string representation.

Parameters

• provider: String provider instance.

• entities: Entities to sort.

Public Functions

TmeStringProvider *tme_string_provider_alloc(void *context, char const *(*get_string)(void *context, TmeEntityPtr entity_ptr, bool *should_free, size_t *length), char const *(*get_short_string)(void *context, TmeEntityPtr entity_ptr, bool *should_free, size_t *length), void (*context_free)(void *context))

Allocates a new string provider.

Strings returned by the functions implementing this interface don’t need to be dynamically allocated. However, it is important that the should_free out parameter is correctly populated.

Return

String provider instance.

Parameters

• context: Context for the subsequent handlers.

• get_string: Implements tme_string_provider_get_string().

• get_short_string: Implements tme_string_provider_get_short_string().

• context_free: Called as part of tme_string_provider_free().

void tme_string_provider_free(TmeStringProvider *provider)

Deallocates the string provider.

Parameters

• provider: String provider to deallocate.

char const *tme_string_provider_get_string(TmeStringProvider const *provider, TmeEntityPtr entity_ptr, bool *should_free, size_t *length)

Returns the string associated with the specified entity identifier.

Return

IRI associated with the entity identifier.

Parameters

• provider: String provider instance.

• entity_ptr: Entity identifier.

• [out] should_free: True if the string should be freed by the caller, false otherwise.

• [out] length: Length of the returned string (excluding the null terminator).

char const *tme_string_provider_get_short_string(TmeStringProvider const *provider, TmeEntityPtr entity_ptr, bool *should_free, size_t *length)

Returns the short string associated with the specified entity identifier.

The returned string is mainly used for debugging or pretty-printing purposes, and it has no uniqueness requirements (e.g. it can be the fragment of the IRI).

Return

Short string associated with the entity identifier.

Parameters

• provider: String provider instance.

• entity_ptr: Entity identifier.

• [out] should_free: True if the string should be freed by the caller, false otherwise.

• [out] length: Length of the returned string (excluding the null terminator).

void *tme_string_provider_get_context(TmeStringProvider const *provider)

Returns the context passed to the string provider during its allocation.

Return

String provider context.

Parameters

• provider: String provider instance.

struct TmeSubsumers

Models told subsumption and equivalence relations.

A subsumer is said to be “told” when the subsumption relation is explicitly present in the TBox (e.g. if it’s not inferred). A “named” or “terminological” equivalence is an equivalence with a named concept (rather than a concept expression).

See

TmeAxiomProvider

Public Functions

void tme_subsumers_add_named_equivalence(TmeSubsumers *subsumers, TmeEntityPtr concept)

Marks the specified concept as a named equivalence.

Parameters

• subsumers: Subsumers instance.

• concept: Concept to mark as a named equivalence.

void tme_subsumers_add_told(TmeSubsumers *subsumers, TmeEntityPtr concept)

Marks the specified concept as a told subsumer.

Parameters

• subsumers: Subsumers instance.

• concept: Concept to mark as a told subsumer.

void tme_subsumers_add_told_aided(TmeSubsumers *subsumers, TmeEntityPtr concept, UHash_TmeEntityTable *cache)

Marks the specified concept as a told subsumer, using an associative cache to speed up uniqueness checks.

Note

If cache is NULL, it falls back to regular tme_subsumers_add_told.

Parameters

• subsumers: Subsumers instance.

• concept: Concept to mark as a told subsumer.

• cache: Cache for uniqueness checks.

void tme_subsumers_mark_equivalence_with_expression(TmeSubsumers *subsumers)

Marks the presence of an equivalence relation with a concept expression.

Parameters

• subsumers: Subsumers instance.

void tme_subsumers_populate(TmeSubsumers *subsumers, Vector_TmeEntityPtr *told, Vector_TmeEntityPtr *equivalents, bool equivalence_with_expression)

Allows populating the subsumers data structure in a single function call.

Note

Vectors passed to this function are directly assigned to the internal data structures, so you must not deallocate them.

Parameters

• subsumers: Subsumers instance.

• told: Told subsumers.

• equivalents: Named equivalents.

• equivalence_with_expression: Marks the presence of an equivalence relation with a concept expression.