diff --git a/docs/source/api_ref.md b/docs/source/api_ref.md index 6fb951f..c5c69e8 100644 --- a/docs/source/api_ref.md +++ b/docs/source/api_ref.md @@ -81,18 +81,7 @@ This document is for developers and/or advanced users of OSP-core, it contains a ## Utilities ```eval_rst -.. autoclass:: osp.core.utils.cuds2dot.Cuds2dot - :members: - -.. automodule:: osp.core.utils.general - :members: - -.. automodule:: osp.core.utils.pretty_print - :members: - -.. automodule:: osp.core.utils.simple_search - :members: - -.. automodule:: osp.core.utils.wrapper_development - :members: +.. automodule:: osp.core.utils + :imported-members: + :members: ``` \ No newline at end of file diff --git a/docs/source/fundamentals.md b/docs/source/fundamentals.md index 743826e..6d8fb40 100644 --- a/docs/source/fundamentals.md +++ b/docs/source/fundamentals.md @@ -139,7 +139,7 @@ CUDS, or Common Universal Data Structure, is the ontology compliant data format - **CUDS is an ontology individual**: each CUDS object is an instantiation of a class in the ontology. If we assume a food ontology that describes classes like pizza or pasta, a CUDS object could represent one specific pizza or pasta dish, that exists in the real world. Similar to ontology individuals, CUDS objects can be related with other individuals/CUDS by relations defined in the ontology. Like a _pizza_ that 'hasPart' _tomato sauce_ -- **CUDS is API**: To allow users to interact with the ontology individuals and their data, CUDS provide a CRUD API. +- **CUDS is API**: To allow users to interact with the ontology individuals and their data, CUDS provides a CRUD API. - **CUDS is a container**: Depending on the relationship connecting two CUDS objects, a certain instance can be seen as a container of other instances. We call a relationship that express containment an 'active relationship'. In the pizza example, 'hasPart' would be an 'active relationship'. If one would like to share the pizza CUDS object with others, one would like to share also the tomato sauce. diff --git a/docs/source/index.md b/docs/source/index.md index 68c2045..392fb97 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -81,6 +81,7 @@ SimPhoNy is an ontology-based [open-source](./license.md) Python framework that jupyter/sessions_and_vars.ipynb utils.md jupyter/multiple_wrappers.ipynb + jupyter/import_export.ipynb jupyter/simlammps.ipynb jupyter/quantum_espresso.ipynb diff --git a/docs/source/jupyter/import_export.ipynb b/docs/source/jupyter/import_export.ipynb new file mode 100644 index 0000000..f9795e7 --- /dev/null +++ b/docs/source/jupyter/import_export.ipynb @@ -0,0 +1,319 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "boxed-professional", + "metadata": {}, + "source": [ + "# Tutorial: Import and export" + ] + }, + { + "cell_type": "markdown", + "id": "operational-honey", + "metadata": {}, + "source": [ + "
\n", + " \n", + "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/simphony/docs/master?filepath=docs%2Fsource%2Fjupyter%2Fimport_export.ipynb \"Click to run the tutorial yourself!\")\n", + " \n", + "
\n", + "\n", + "In this tutorial we will be covering the import and export capabilities of OSP-core. The utility functions that provide these functionalities are `import_cuds` and `export_cuds`, respectively." + ] + }, + { + "cell_type": "markdown", + "id": "qualified-works", + "metadata": {}, + "source": [ + "
\n", + "
Tip
\n", + " \n", + "The full API specifictions of the import and export functions can be found in the\n", + "[utilities API reference page](../api_ref.html#osp.core.utils.export_cuds).\n", + " \n", + "
\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "driving-injury", + "metadata": {}, + "source": [ + "For our running example, we'll be using the *city ontology* that was already introduces in the [cuds API tutorial](./cuds_api.html). First, make sure the city ontology is installed. If not, run the following command:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "dying-accreditation", + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "INFO 2021-05-31 10:55:51,839 [osp.core.ontology.installation]: Will install the following namespaces: ['city']\n", + "INFO 2021-05-31 10:55:51,879 [osp.core.ontology.yml.yml_parser]: Parsing YAML ontology file c:\\users\\yoav\\anaconda3\\envs\\osp\\lib\\site-packages\\osp\\core\\ontology\\docs\\city.ontology.yml\n", + "INFO 2021-05-31 10:55:51,995 [osp.core.ontology.yml.yml_parser]: You can now use `from osp.core.namespaces import city`.\n", + "INFO 2021-05-31 10:55:51,996 [osp.core.ontology.parser]: Loaded 7396 ontology triples in total\n", + "INFO 2021-05-31 10:55:52,437 [osp.core.ontology.installation]: Installation successful\n" + ] + } + ], + "source": [ + "!pico install city" + ] + }, + { + "cell_type": "markdown", + "id": "lonely-listening", + "metadata": {}, + "source": [ + "Next we create a few CUDS objects:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "considered-leonard", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from osp.core.namespaces import city\n", + "\n", + "c = city.City(name=\"Freiburg\", coordinates=[47, 7])\n", + "p1 = city.Citizen(name=\"Peter\")\n", + "p2 = city.Citizen(name=\"Anne\")\n", + "c.add(p1, rel=city.hasInhabitant)\n", + "c.add(p2, rel=city.hasInhabitant)" + ] + }, + { + "cell_type": "markdown", + "id": "worth-province", + "metadata": {}, + "source": [ + "Now we can use the `export_cuds` methods to export the data into a file:" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "monthly-anxiety", + "metadata": {}, + "outputs": [], + "source": [ + "from osp.core.utils import export_cuds\n", + "\n", + "export_cuds(c, file='./data.ttl', format='turtle')" + ] + }, + { + "cell_type": "markdown", + "id": "determined-nursing", + "metadata": {}, + "source": [ + "This will create the file `data.ttl` with the following content:" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "outstanding-wound", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "@prefix city: .\n", + "@prefix cuba: .\n", + "@prefix rdf: .\n", + "@prefix xsd: .\n", + "\n", + "cuba:_serialization rdf:first \"47398674-720b-4765-9047-b5351ed175c0\" .\n", + "\n", + " a city:Citizen ;\n", + " city:INVERSE_OF_hasInhabitant ;\n", + " city:age 25 ;\n", + " city:name \"Peter\" .\n", + "\n", + " a city:Citizen ;\n", + " city:INVERSE_OF_hasInhabitant ;\n", + " city:age 25 ;\n", + " city:name \"Anne\" .\n", + "\n", + " a city:City ;\n", + " city:coordinates \"[47, 7]\"^^ ;\n", + " city:hasInhabitant ,\n", + " ;\n", + " city:name \"Freiburg\" .\n", + "\n" + ] + } + ], + "source": [ + "from sys import platform\n", + "\n", + "if platform == 'win32':\n", + " !more data.ttl\n", + "else:\n", + " !cat data.ttl" + ] + }, + { + "cell_type": "markdown", + "id": "offshore-cotton", + "metadata": {}, + "source": [ + "You can change the format by entering a different value for the parameter `format`. The supported formats are “xml”, “n3”, “turtle”, “nt”, “pretty-xml”, “trix”, “trig” and “nquads”." + ] + }, + { + "cell_type": "markdown", + "id": "derived-advancement", + "metadata": {}, + "source": [ + "To import data, we can use the `import` method. Let's assume we wish to import data into an SQLite session. The following code will help us to achieve our aim:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "stable-session", + "metadata": {}, + "outputs": [], + "source": [ + "from osp.wrappers.sqlite import SqliteSession\n", + "from osp.core.utils import import_cuds\n", + "\n", + "with SqliteSession(\"test.db\") as session:\n", + " wrapper = city.CityWrapper(session=session)\n", + " c = import_cuds('./data.ttl')\n", + " wrapper.add(c)\n", + " session.commit()" + ] + }, + { + "cell_type": "markdown", + "id": "higher-short", + "metadata": {}, + "source": [ + "Now we can verify the data was indeed imported:" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "suspended-albert", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "- Cuds object:\n", + " uid: 03015cb9-f88c-4ab1-9df9-bb52743b99de\n", + " type: city.CityWrapper\n", + " superclasses: city.CityWrapper, cuba.Entity, cuba.Wrapper\n", + " description: \n", + " To Be Determined\n", + "\n", + " |_Relationship city.hasPart:\n", + " - city.City cuds object named :\n", + " . uid: 72595bc4-1b68-46a3-97e9-8f3de2650f2c\n", + " . coordinates: [47 7]\n", + " . |_Relationship city.hasInhabitant:\n", + " . - city.Citizen cuds object named :\n", + " . . uid: 92a00459-0927-438c-a305-a26512ac7f03\n", + " . . age: 25\n", + " . - city.Citizen cuds object named :\n", + " . uid: 27d1e83b-4ee9-4f4f-adb5-0b01a3cc2c1b\n", + " . age: 25\n", + " - city.City cuds object named :\n", + " . uid: 47398674-720b-4765-9047-b5351ed175c0\n", + " . coordinates: [47 7]\n", + " . |_Relationship city.hasInhabitant:\n", + " . - city.Citizen cuds object named :\n", + " . . uid: 98f8ac8c-713d-4406-bc36-e0152f9e2ea3\n", + " . . age: 25\n", + " . - city.Citizen cuds object named :\n", + " . uid: 8a90e2b3-7cca-4103-9eba-aab55e5903b1\n", + " . age: 25\n", + " - city.City cuds object named :\n", + " uid: d886f8ce-1326-40f5-a98b-c4c893b8c085\n", + " coordinates: [47 7]\n", + " |_Relationship city.hasInhabitant:\n", + " - city.Citizen cuds object named :\n", + " . uid: 2b5d0a3f-81a5-4746-aab9-40adcb65e71f\n", + " . age: 25\n", + " - city.Citizen cuds object named :\n", + " uid: 766b320a-7e9a-43ec-a696-96b4f9ee494d\n", + " age: 25\n" + ] + } + ], + "source": [ + "from osp.core.utils import pretty_print\n", + "\n", + "with SqliteSession(\"test.db\") as session:\n", + " wrapper = city.CityWrapper(session=session)\n", + " pretty_print(wrapper) " + ] + }, + { + "cell_type": "markdown", + "id": "virgin-river", + "metadata": {}, + "source": [ + "
\n", + "
Notes
\n", + " \n", + "1. The format is automatically inferred from the file extension. To specify it explicitly, you can add the `format` parameter, like so: `import_cuds('./data.ttl', format='turtle')`.\n", + "1. The `session` parameter is optional and inferred automatically from the context that created by the `with` statement (see the [tutorial on multiple wrappers](./multiple_wrappers.html) for more information). You can specify the session explicitly like so: `import_cuds('./data.ttl', session=session)`.\n", + " \n", + "
" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3.7.4 64-bit", + "language": "python", + "name": "python37464bit7e5bfc198a4544d1be12f13215aed90d" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.5" + }, + "metadata": { + "interpreter": { + "hash": "301cd6007de04cbbf15bca26f0bc1cb48004d089278091d760363de622bdd0c8" + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/jupyter/ontology_interface.ipynb b/docs/source/jupyter/ontology_interface.ipynb index 9529d98..8344f62 100644 --- a/docs/source/jupyter/ontology_interface.ipynb +++ b/docs/source/jupyter/ontology_interface.ipynb @@ -201,6 +201,28 @@ "- When the keyword `reference_by_label` is set to `False` (disabled) or not set, the dot notation is a shorthand for fetching by suffix instead. This keyword is **disabled** in the `city` namespace." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To get a list of all the entities available within a namespace, run `list(namespace)`." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "
\n", + "
\n", + "
Tip
\n", + " \n", + "The dot notation supports IPython autocompletion. For example, when working on a Jupyter notebook, once the namespace has been imported, it is possible to get suggestions for the entity names by writing `namespace.` and pressing TAB.\n", + "\n", + "
\n", + "
\n", + "" + ] + }, { "cell_type": "markdown", "metadata": {}, diff --git a/docs/source/links.md b/docs/source/links.md index 76ac9b7..2f76edc 100644 --- a/docs/source/links.md +++ b/docs/source/links.md @@ -48,7 +48,8 @@ The following table describes the compatibilities between of SimPhoNy docs and O ============= ========== SimPhoNy docs OSP-core ============= ========== - 2.4.x 3.5.2-beta + 2.4.1 3.5.3.1-beta + 2.4.0 3.5.2-beta 2.3.x 3.4.0-beta 2.2.x 3.3.5-beta 2.1.x 3.3.0-beta diff --git a/docs/source/ontologies_included.md b/docs/source/ontologies_included.md index 3474e0d..a9d337d 100644 --- a/docs/source/ontologies_included.md +++ b/docs/source/ontologies_included.md @@ -13,7 +13,6 @@ ontology. We used [Ontology2Dot](utils.md#ontology2dot) for that: ![ontology2dot sample image](./_static/img/ontology2dot.png) -eval_rst To use the city ontology you have to install it using the tool [Pico](utils.md#pico-installs-cuds-ontologies): ```sh diff --git a/docs/source/ontology_intro.md b/docs/source/ontology_intro.md index 5957b20..fe6a55d 100644 --- a/docs/source/ontology_intro.md +++ b/docs/source/ontology_intro.md @@ -10,4 +10,4 @@ the representational primitives include information about their meaning and constraints on their logically consistent application. (Source: ) -TODO extend \ No newline at end of file +[//]: # (TODO Extend) diff --git a/docs/source/overview.md b/docs/source/overview.md index 10f4691..5dca740 100644 --- a/docs/source/overview.md +++ b/docs/source/overview.md @@ -61,7 +61,7 @@ At this point, the results could be fetched again and for example, visualized wi Exactly in the same way that the data can be moved between a database and a simulation engine using their respective wrappers, it can also be moved between simulation engines. -This functionality facilitates the coupling and linking between such simulation engines. For example, in the domain of materials science, a certain engine might be useful for representing structures made up of atomistic particles (molecular dynamics), while another software tool could be focussed on representing bodies of fluids (fluid dynamics). As SimPhoNy can enable communication between the two tools, they could both be run and synced simultaneously to create more complex scenarios. +This functionality facilitates the coupling and linking between such simulation engines. For example, in the domain of materials science, a certain engine might be useful for representing structures made up of atomistic particles (molecular dynamics), while another software tool could be focussed on representing bodies of fluids (fluid dynamics). As SimPhoNy can enable communication between the two tools, they could both be run and synced simultaneously to create more complex scenarios, such as a multi-scale simulation.
@@ -83,7 +83,9 @@ In order achieve that, it would be necessary to translate the input and output f
-_Coupling of two simulation engines, one that handles free traffic and another that exclusively handles traffic lights._ +_Coupling of two simulation engines, one that handles fluid dynamics +(macroscopic behavior) and another that takes care of molecular dynamics +(microscopic behavior)._
diff --git a/docs/source/owl.md b/docs/source/owl.md index 8faf366..1dbe581 100644 --- a/docs/source/owl.md +++ b/docs/source/owl.md @@ -44,9 +44,10 @@ functionality of [Protégé](https://protege.stanford.edu/). **format**: File format of the ontology file to be parsed. We support all the formats that [RDFLib](https://rdflib.readthedocs.io/en/stable/plugin_parsers.html) supports: -XML (`xml`, default), RDF/XML (`rdf+xml`), N3 (`n3`), NTriples (`nt`), -N-Quads (`nquads`), Turtle (`turtle`), TriX (`trix`), -RDFa (`rdfa`, `rdfa1.0`, `rdfa1.1`) and Microdata (`mdata`). +XML (`xml`, `application/rdf+xml`, default), Turtle (`turtle`, `ttl`, +`text/turtle`), N3 (`n3`,`text/n3`), NTriples (`nt`, `nt11`, +`application/n-triples`), N-Quads (`nquads`, `application/n-quads`), +TriX (`trix`, `application/trix`) and TriG (`trig`, `application/trig`). **reference_by_label** (default False): Whether the label should be used or the IRI suffix to reference entity from within OSP-core. In case of EMMO it is true, because IRI suffixes are not diff --git a/packageinfo.py b/packageinfo.py index 3c6c186..163873d 100644 --- a/packageinfo.py +++ b/packageinfo.py @@ -1,2 +1,2 @@ NAME = "simphony_docs" -VERSION = "2.4.0" +VERSION = "2.4.1" diff --git a/requirements.txt b/requirements.txt index 285a2ad..1196407 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,3 +9,4 @@ ipython==7.22.0 jupyter==1.0.0 sphinx-autobuild==2021.3.14 sphinx-panels==0.5.2 +jinja2==2.11.2