From 52bba67e640fb1e30817fd1114a54e1d38ad5a74 Mon Sep 17 00:00:00 2001 From: Federico Igne Date: Wed, 18 May 2022 15:05:44 +0100 Subject: docs: update README.md --- README.md | 130 +++++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 100 insertions(+), 30 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 663b6cb..13fe729 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,117 @@ -PAGOdA -====== + +

-PAGOdA is a conjunctive query answering engine for OWL 2 ontologies. +

· ACQuA ·

+

+A hybrid architecture for conjunctive query answering overover OWL 2 DL. +
+Read the thesis +· +Read the journal paper +· +Report bug +

+ + Release badge + + + Issues badge + + + + + + License badge + + + DOI badge + +

-Project dependencies/requirements -================================= +

-- This software has been developed for Linux -- JavaSE 8 -- Maven +## About +ACQuA is a hybrid query answering framework that combines black-box services to provide a CQ answering service for OWL. +Specifically, it combines scalable CQ answering services for tractable languages with a CQ answering service for a more expressive language approaching the full OWL 2. +If the query can be fully answered by one of the tractable services, then that service is used. +Otherwise the tractable services are used to compute lower and upper bound approximations, taking the union of the lower bounds and the intersection of the upper bounds. +If the bounds don’t coincide, then the “gap” answers are checked using the “full” service. -Building and packaging -====================== +This reference implementation combines [RSAComb], [PAGOdA], and [HermiT], but these tools can be potentially subtituted or augmented with more capable ones to improve the overall performance of the system. -This is a Maven project, hence Maven should be used for building and packaging. -* Compile `mvn compile` -* Create jars `mvn package`; -you will get a jar without dependencies *target/pagoda-x.y.z.jar* and a runnable jar with dependencies *target/pagoda-x.y.z-jar-with-dependencies.jar*. -* Execute tests `mvn test -DskipTests=false`; +> ACQuA is still in its preliminary stage of development and might contain bugs. +## Preliminaries -Configuring the engine -====================== +RSAComb uses a recent version of [RDFox] under the hood to offload part of the computation. -The engine provides a standard configuration, but it is most likely that is not suitable for your purposes. -You should provide your own configuration in a file called `pagoda.properties` including it in the classpath. -Such a file should resemble the file `src/resources/_default_pagoda.properties`. +In order to run ACQuA you need to have [RDFox](https://www.oxfordsemantic.tech/product) available in your system, along with *a valid license*. +RDFox is proprietary software and as such we are not able to distribute it along with our code. +This software has been developed and tested with RDFox v5.5 +### Installing RDFox -Executing -========= +We refer to the [official documentation](https://docs.oxfordsemantic.tech/getting-started.html#getting-started) for a step-by-step guide on how to setup RDFox on your personal machine. +In particular, you will need to know the path to the RDFox Java API (usually called `JRDFox.jar`) that comes with the distribution. -Once you have the runnable jar, you can make the system answer queries through the command line interface. +Alternatively, run the following commands (on a Linux x86 machine) from the root of the project to install RDFox locally. +Download links for other versions, operating systems, and architectures can be found [here](https://www.oxfordsemantic.tech/downloads). -Run `java -jar pagoda-x.y.z-jar-with-dependencies.jar` for getting a list of the mandatory arguments and optional parameters. +```{.bash} +mkdir -p lib && pushd lib +wget https://rdfox-distribution.s3.eu-west-2.amazonaws.com/release/v5.5/RDFox-linux-x86_64-5.5.zip +unzip RDFox-linux-x86_64-5.2.1.zip +ln -s RDFox-linux-x86_64-5.2.1.zip/lib/JRDFox.jar +popd +``` -Run `java -cp pagoda-x.y.z-jar-with-dependencies.jar:/pagoda.properties arg [arg]...` for executing the engine with a custom configuration. +### Providing an RDFox license -Using it as a library -===================== +The [documentation](https://docs.oxfordsemantic.tech/features-and-requirements.html#license-key), describes several ways to provide the license to RDFox. -The API is offered by the class `QueryReasoner`, however we provide a more handy wrapper, that is the class `Pagoda`. -Thanks to such a wrapper, you can build an instance of `Pagoda` by specifying different parameters and after that you will get -a runnable `Pagoda` object. +One easy way is to put your license key in a file `RDFox.lic` in `$HOME/.RDFox/`, with adequate read permissions for the user executing the program. + + +## Using the software + +`TODO` + +### Running tests + +`TODO` + +``` +mvn compile +mvn package +java -cp ... uk.ac.ox.cs.acqua.Acqua [OPTIONs] +``` + +## References + +[1] Horridge, Matthew and Bechhofer, Sean. + *The OWL API: A Java API for OWL Ontologies*. + Semantic Web Journal 2(1), Special Issue on Semantic Web Tools and Systems, pp. 11-21, 2011. + +## Acknowledgements + +- OWLAPI [[2]](#references) +- [RDFox](https://www.oxfordsemantic.tech/product) +- [PAGOdA]() + +## Credits + +- Federico Igne +- Stefano Germano +- Ian Horrocks (*Scientific Supervisor*) + +From the [Knowledge Representation and Reasoning research group](https://www.cs.ox.ac.uk/isg/krr/) in the [Department of Computer Science](https://www.cs.ox.ac.uk/) of the [University of Oxford](https://www.ox.ac.uk/). + +## License + +This project is licensed under the [Apache License 2.0](LICENSE). + +## TODOs + +- [ ] Better integration between ACQuA, RDFox and PAGOdA configuration parameters. -- cgit v1.2.3