From 1bcd594eadd26395d68f28862425c2bf20fc47bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Manuel=20Dom=C3=ADnguez?= <43052541+kysrpex@users.noreply.github.com> Date: Thu, 7 Apr 2022 10:52:54 +0200 Subject: [PATCH 1/9] Update compatibility table for release 2.5.1 (`dev`) (#203) * Update compatibility table for release 2.5.0 * Update compatibility table for release 2.5.1 --- docs/source/links.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/links.md b/docs/source/links.md index d1cfbd4..3b11541 100644 --- a/docs/source/links.md +++ b/docs/source/links.md @@ -57,6 +57,8 @@ The following table describes the compatibilities between of SimPhoNy docs and O ============= ========== SimPhoNy docs OSP-core ============= ========== + 2.5.1 3.8.0 + 2.5.0 3.8.0 2.4.5 3.7.0 2.4.4 3.5.8-beta 2.4.3 3.5.5-beta From 46ab4a808f51cd6e8b3a577629c47d2250e00433 Mon Sep 17 00:00:00 2001 From: Pablo de Andres <9430234+pablo-de-andres@users.noreply.github.com> Date: Tue, 12 Apr 2022 09:40:00 +0200 Subject: [PATCH 2/9] Change theme and update dependencies' versions (#207) * Change theme and update dependencies' versions * Update version of python and actions in CI --- .github/workflows/ci.yml | 8 +++---- docs/source/_static/custom.css | 16 +++++++++++++ docs/source/conf.py | 43 +++++++++++++++++----------------- requirements.txt | 20 ++++++++-------- 4 files changed, 51 insertions(+), 36 deletions(-) create mode 100644 docs/source/_static/custom.css diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9114698..ed328aa 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,11 +8,11 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - name: Set up Python 3.7 - uses: actions/setup-python@v2 + - uses: actions/checkout@v3 + - name: Set up Python 3.10 + uses: actions/setup-python@v3 with: - python-version: 3.7 + python-version: "3.10" - name: Install OS dependencies run: | sudo apt-get update diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..654bc5f --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,16 @@ +.caption-text, +h1, +h2, +h3, +h4 { + color: #6580A1 !important; +} + +.btn-outline-primary { + border-color: #6580A1 !important; +} + +.btn-outline-primary:hover { + background-color: #6580A1 !important; + color: azure !important; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index 2845650..8f790da 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,21 +1,12 @@ -# -- Path setup -------------------------------------------------------------- +"""Configuration file for the Sphinx documentation builder.""" -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -# -- Project information ----------------------------------------------------- +# Project information project = 'SimPhoNy' # Version is given in setuptools -copyright = ('2021, Materials Data Science and ' - 'Informatics Team at Fraunhofer IWM') -author = 'Materials Data Science and Informatics team at Fraunhofer IWM' +copyright = '2022, Materials Informatics team at Fraunhofer IWM' +author = 'Materials Informatics team at Fraunhofer IWM' -# -- General configuration --------------------------------------------------- +# General configuration extensions = [ 'myst_parser', # markdown source support 'sphinx.ext.autodoc', # API ref @@ -35,20 +26,28 @@ plantuml = 'java -jar lib/plantuml.jar' plantuml_output_format = 'svg_img' -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['**.ipynb_checkpoints'] -# -- Options for HTML output ------------------------------------------------- - -html_theme = 'sphinx_rtd_theme' +# HTML output +html_theme = 'sphinx_book_theme' html_favicon = '_static/img/simphony_favicon.png' -html_logo = '_static/img/simphony_logo_light.png' +html_logo = '_static/img/simphony_logo_dark.png' +html_theme_options = { + "github_url": "https://github.com/simphony/docs", + "repository_url": "https://github.com/simphony/docs", + "use_repository_button": True, + "repository_branch": "main", + "path_to_docs": "docs", + "logo_only": True, + "show_navbar_depth": 2, +} + + html_static_path = ['_static'] +html_css_files = ["custom.css"] -# -- Options for LaTeX output ------------------------------------------------- +# LaTeX output latex_documents = [('index', 'SimPhoNy_docs.tex', 'SimPhoNy documentation', diff --git a/requirements.txt b/requirements.txt index ac74d52..ef654e2 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,13 +1,13 @@ git+https://github.com/simphony/osp-core.git#egg=osp-core -sphinx==3.5.3 -myst-parser==0.15.2 -sphinx_rtd_theme==0.5.2 -sphinxcontrib-plantuml==0.20.1 -nbsphinx==0.8.2 -sphinx-copybutton==0.3.1 -ipython==7.31.1 +ipython==8.1.1 +jinja2==3.0.3 jupyter==1.0.0 +markupsafe==2.1.1 +myst-parser==0.17.0 +nbsphinx==0.8.8 +sphinx==4.4.0 sphinx-autobuild==2021.3.14 -sphinx-panels==0.5.2 -jinja2==2.11.3 -markupsafe==2.0.1 +sphinx_book_theme==0.2.0 +sphinxcontrib-plantuml==0.23 +sphinx-copybutton==0.5.0 +sphinx-panels==0.6.0 From 2799b19dbefdae1827ccd34f1867419b13f4f472 Mon Sep 17 00:00:00 2001 From: Pablo de Andres <9430234+pablo-de-andres@users.noreply.github.com> Date: Tue, 5 Jul 2022 17:04:32 +0200 Subject: [PATCH 3/9] Add pre commit hooks (#208) * add configuration file * Initial file formatting by pre-commit * Tackle review from kysrpex * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * autofix for pretty-format-json Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .dockerignore | 2 +- .github/issue-branch.yml | 6 +- .github/workflows/ci.yml | 35 +- .gitignore | 2 +- .pre-commit-config.yaml | 32 + README.md | 23 +- docs/source/_static/custom.css | 6 +- docs/source/_static/img/branch_workflow.svg | 2 +- docs/source/_static/img/mergedlinkeddata.svg | 2 +- docs/source/_static/img/trafficsim.svg | 1474 ++++++++--------- docs/source/_static/img/wrappers.svg | 2 +- docs/source/_static/img/wrappers_coupled.svg | 2 +- docs/source/api_ref.md | 19 +- docs/source/conf.py | 65 +- docs/source/contact.md | 3 +- docs/source/contribute.md | 157 +- docs/source/detailed_design.md | 688 ++++---- docs/source/fundamentals.md | 311 ++-- docs/source/general_architecture.md | 180 +- docs/source/index.md | 10 +- docs/source/installation.md | 23 +- docs/source/json_schema/serialized_cuds.json | 180 +- docs/source/jupyter/cuds_api.ipynb | 2 +- docs/source/jupyter/multiple_wrappers.ipynb | 2 +- docs/source/jupyter/ontology_interface.ipynb | 2 +- docs/source/jupyter/quantum_espresso.ipynb | 2 +- docs/source/jupyter/sessions_and_vars.ipynb | 2 +- docs/source/jupyter/simlammps.ipynb | 2 +- docs/source/jupyter/wrapper_development.ipynb | 2 +- docs/source/license.md | 1 + docs/source/links.md | 29 +- docs/source/ontologies_included.md | 117 +- docs/source/ontology_intro.md | 4 +- docs/source/overview.md | 27 +- docs/source/utils.md | 98 +- docs/source/working_with_ontologies.md | 127 +- docs/source/wrapper_development.md | 290 ++-- 37 files changed, 2075 insertions(+), 1856 deletions(-) create mode 100644 .pre-commit-config.yaml diff --git a/.dockerignore b/.dockerignore index 608b1d4..e524d79 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,2 +1,2 @@ .vscode/ -build/ \ No newline at end of file +build/ diff --git a/.github/issue-branch.yml b/.github/issue-branch.yml index 12915a8..f721400 100644 --- a/.github/issue-branch.yml +++ b/.github/issue-branch.yml @@ -1,11 +1,11 @@ mode: chatops -branchName: '${issue.number}-${issue.title}' +branchName: "${issue.number}-${issue.title}" autoCloseIssue: true branches: - - label: '*' + - label: "*" name: dev -openDraftPR: true \ No newline at end of file +openDraftPR: true diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ed328aa..a03ae84 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,24 +4,23 @@ on: pull_request jobs: build: - runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - name: Set up Python 3.10 - uses: actions/setup-python@v3 - with: - python-version: "3.10" - - name: Install OS dependencies - run: | - sudo apt-get update - sudo apt-get install pandoc latexmk - sudo apt-get install texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra - - name: Install python dependencies - run: | - python -m pip install --upgrade pip - pip install wheel - pip install -r requirements.txt - - name: Build docs - run: sphinx-build docs/source docs/build/html + - uses: actions/checkout@v3 + - name: Set up Python 3.10 + uses: actions/setup-python@v3 + with: + python-version: "3.10" + - name: Install OS dependencies + run: | + sudo apt-get update + sudo apt-get install pandoc latexmk + sudo apt-get install texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra + - name: Install python dependencies + run: | + python -m pip install --upgrade pip + pip install wheel + pip install -r requirements.txt + - name: Build docs + run: sphinx-build docs/source docs/build/html diff --git a/.gitignore b/.gitignore index 608b1d4..e524d79 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ .vscode/ -build/ \ No newline at end of file +build/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..a2834a1 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,32 @@ +--- +ci: + autoupdate_branch: "dev" + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.2.0 + hooks: + - id: check-json + - id: pretty-format-json + args: ["--autofix", "--no-sort-keys"] + - id: check-yaml + - id: end-of-file-fixer + - id: trailing-whitespace + + - repo: https://github.com/pre-commit/mirrors-prettier + rev: v2.6.2 + hooks: + - id: prettier + files: \.(js|ts|jsx|tsx|css|less|html|markdown|md|yaml|yml)$ + + - repo: https://github.com/psf/black + rev: 22.6.0 + hooks: + - id: black + args: [--line-length, "79"] + + - repo: https://github.com/pycqa/isort + rev: 5.10.1 + hooks: + - id: isort + args: [--profile, black, --filter-files, --line-length, "79"] diff --git a/README.md b/README.md index 110a72a..ae59c0c 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,67 @@ ## Build Status -**latest** - [![Documentation latest](https://readthedocs.org/projects/simphony/badge/?version=latest)](https://simphony.readthedocs.io/en/latest/?badge=latest) + +**latest** - [![Documentation latest](https://readthedocs.org/projects/simphony/badge/?version=latest)](https://simphony.readthedocs.io/en/latest/?badge=latest) **dev** - [![Documentation dev](https://readthedocs.org/projects/simphony/badge/?version=dev)](https://simphony.readthedocs.io/en/latest/?badge=dev) # SimPhoNy docs + To access the documentation, please visit: [https://simphony.readthedocs.io](https://simphony.readthedocs.io). If you find any error or problem with the documentation, please [create an issue](https://github.com/simphony/docs/issues). ## Local Rendering + ### HTML + A server will start, generate the docs and listen for changes in the source files. This can be done by using docker or installing the development environment directly on the you machine. Next are installation guides for Docker and Linux OS. #### Docker + First, build the Docker image by running the following command: + ```shell $ docker build -f local_build.Dockerfile -t simphony-docs . ``` Then, start the program by running: + ```shell $ docker run --rm -v $PWD:/app -p 8000:8000 simphony-docs ``` #### Linux + At an OS level (these commands work on Linux Debian): + ```shell $ sudo apt install pandoc graphviz default-jre $ sudo apt-get install texlive-latex-recommended \ texlive-latex-extra \ texlive-fonts-recommended \ - latexmk + latexmk ``` + The python dependencies: + ```shell $ pip install -r requirements.txt ``` Now you can start the server and render the docs: + ``` $ sphinx-autobuild docs/source docs/build/html ``` -The documentation will be available on [`http://127.0.0.1:8000`](http://127.0.0.1:8000). +The documentation will be available on [`http://127.0.0.1:8000`](http://127.0.0.1:8000). ### PDF (LaTeX) + To generate a PDF of the documentation, simply run (from the root project folder): + ```sh make -C docs latexpdf ``` -The generated PDF can be found under docs/build/latex/SymPhoNy_docs.pdf \ No newline at end of file + +The generated PDF can be found under docs/build/latex/SymPhoNy_docs.pdf diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css index 654bc5f..6137013 100644 --- a/docs/source/_static/custom.css +++ b/docs/source/_static/custom.css @@ -3,14 +3,14 @@ h1, h2, h3, h4 { - color: #6580A1 !important; + color: #6580a1 !important; } .btn-outline-primary { - border-color: #6580A1 !important; + border-color: #6580a1 !important; } .btn-outline-primary:hover { - background-color: #6580A1 !important; + background-color: #6580a1 !important; color: azure !important; } diff --git a/docs/source/_static/img/branch_workflow.svg b/docs/source/_static/img/branch_workflow.svg index df7ed10..ccc1692 100644 --- a/docs/source/_static/img/branch_workflow.svg +++ b/docs/source/_static/img/branch_workflow.svg @@ -1,3 +1,3 @@ -
Merge to dev from issue branches using a Squash commit
Merge to dev from...
Merge from hotfix branches both to master and dev, using a Squash commit
Merge from hotfix...
Merge to master from dev using a Merge commit
Merge to master f...
master
master
xyz-hotfix
xyz-hotfix
dev
dev
xyz-issue
xyz-issueViewer does not support full SVG 1.1 \ No newline at end of file +
Merge to dev from issue branches using a Squash commit
Merge to dev from...
Merge from hotfix branches both to master and dev, using a Squash commit
Merge from hotfix...
Merge to master from dev using a Merge commit
Merge to master f...
master
master
xyz-hotfix
xyz-hotfix
dev
dev
xyz-issue
xyz-issueViewer does not support full SVG 1.1 diff --git a/docs/source/_static/img/mergedlinkeddata.svg b/docs/source/_static/img/mergedlinkeddata.svg index bddd379..c148fb9 100644 --- a/docs/source/_static/img/mergedlinkeddata.svg +++ b/docs/source/_static/img/mergedlinkeddata.svg @@ -1,3 +1,3 @@ -
Old city
Old city
Port district
Port distri...
Wang
Wang
Anne
Anne
Klaus
Klaus
Fabrizio
Fabrizio
livesIn
livesIn
livesIn
livesIn
livesIn
livesIn
livesIn
livesIn
hasWorkingHours
hasWorkingHours
08:30-14:00
08:30-14:00
09:00-12:00
09:00-12:00
08:30-14:00
08:30-14:00
08:00-13:00
08:00-13:00
hasWorkingHours
hasWorkingHours
hasWorkingHours
hasWorkingHours
hasWorkingHours
hasWorkingHours
St. NIcholas St.
St. NIcholas St.
Old market St.
Old market St.
adjacent
adjacent
Riverside St.
River...
Campus
Campus
adjacent
adjacent
adjacent
adjacent
adjacent
adjacent
adjacent
adjacent
hasLength
hasLength
3 km
3 km
hasLanes
hasLanes
3
3
hasSpeedLimit
hasSpeedLimit
50 kmh⁻¹
50 kmh⁻¹
hasLength
hasLength
5 km
5 km
hasLanes
hasLanes
2
2
hasSpeedLimit
hasSpeedLimit
80 kmh⁻¹
80 kmh⁻¹
2 km
2 km
1
1
30 kmh⁻¹
30 kmh⁻¹
hasLength
hasLength
hasSpeedLimit
hasSpeedLimit
hasLanes
hasLanes
adjacent
adjacent
Data from traffic authority
Data from traffic authority
Data from a city guide
Data from a city guide
Data from the university registry
Data from the university registryViewer does not support full SVG 1.1 \ No newline at end of file +
Old city
Old city
Port district
Port distri...
Wang
Wang
Anne
Anne
Klaus
Klaus
Fabrizio
Fabrizio
livesIn
livesIn
livesIn
livesIn
livesIn
livesIn
livesIn
livesIn
hasWorkingHours
hasWorkingHours
08:30-14:00
08:30-14:00
09:00-12:00
09:00-12:00
08:30-14:00
08:30-14:00
08:00-13:00
08:00-13:00
hasWorkingHours
hasWorkingHours
hasWorkingHours
hasWorkingHours
hasWorkingHours
hasWorkingHours
St. NIcholas St.
St. NIcholas St.
Old market St.
Old market St.
adjacent
adjacent
Riverside St.
River...
Campus
Campus
adjacent
adjacent
adjacent
adjacent
adjacent
adjacent
adjacent
adjacent
hasLength
hasLength
3 km
3 km
hasLanes
hasLanes
3
3
hasSpeedLimit
hasSpeedLimit
50 kmh⁻¹
50 kmh⁻¹
hasLength
hasLength
5 km
5 km
hasLanes
hasLanes
2
2
hasSpeedLimit
hasSpeedLimit
80 kmh⁻¹
80 kmh⁻¹
2 km
2 km
1
1
30 kmh⁻¹
30 kmh⁻¹
hasLength
hasLength
hasSpeedLimit
hasSpeedLimit
hasLanes
hasLanes
adjacent
adjacent
Data from traffic authority
Data from traffic authority
Data from a city guide
Data from a city guide
Data from the university registry
Data from the university registryViewer does not support full SVG 1.1 diff --git a/docs/source/_static/img/trafficsim.svg b/docs/source/_static/img/trafficsim.svg index deef2bf..2403b29 100644 --- a/docs/source/_static/img/trafficsim.svg +++ b/docs/source/_static/img/trafficsim.svg @@ -21,19 +21,19 @@ - - @@ -41,8 +41,8 @@ z - @@ -53,32 +53,32 @@ L 0 3.5 - - @@ -98,28 +98,28 @@ z - @@ -139,23 +139,23 @@ z - @@ -175,34 +175,34 @@ z - @@ -222,43 +222,43 @@ z - @@ -278,18 +278,18 @@ z - @@ -303,309 +303,309 @@ z - - - - - - - - - - - - - - @@ -651,8 +651,8 @@ z - @@ -679,29 +679,29 @@ L -3.5 0 - @@ -738,14 +738,14 @@ z - @@ -776,100 +776,100 @@ z - - - - - @@ -892,137 +892,137 @@ z - - - - - - - - @@ -1055,21 +1055,21 @@ z - - @@ -1077,86 +1077,86 @@ L 76.36 39.018438 - - - - @@ -1177,8 +1177,8 @@ z - @@ -1186,17 +1186,17 @@ L 76.36 53.696562 - @@ -1219,8 +1219,8 @@ z - diff --git a/docs/source/_static/img/wrappers.svg b/docs/source/_static/img/wrappers.svg index 1aeaebd..043ad88 100644 --- a/docs/source/_static/img/wrappers.svg +++ b/docs/source/_static/img/wrappers.svg @@ -1,3 +1,3 @@ -
Simulation engine wrapper
Simulation...
SQLite Database
SQLite Database
Traffic simulation engine
Traffic simulation engine
SQLite Wrapper
SQLite Wrap...
Transfer ontology
individuals (data)
Transfer ontology...
SQLite Database
SQLite Database
SQLite Wrapper
SQLite Wrap...
Transfer results back
Tran...
Simulation engine wrapper
Simulation...
Traffic simulation engine (finished)
Traffic simulation engine (finished)
Run simulation
Run simula...Viewer does not support full SVG 1.1 \ No newline at end of file +
Simulation engine wrapper
Simulation...
SQLite Database
SQLite Database
Traffic simulation engine
Traffic simulation engine
SQLite Wrapper
SQLite Wrap...
Transfer ontology
individuals (data)
Transfer ontology...
SQLite Database
SQLite Database
SQLite Wrapper
SQLite Wrap...
Transfer results back
Tran...
Simulation engine wrapper
Simulation...
Traffic simulation engine (finished)
Traffic simulation engine (finished)
Run simulation
Run simula...Viewer does not support full SVG 1.1 diff --git a/docs/source/_static/img/wrappers_coupled.svg b/docs/source/_static/img/wrappers_coupled.svg index ea77b03..ce66d03 100644 --- a/docs/source/_static/img/wrappers_coupled.svg +++ b/docs/source/_static/img/wrappers_coupled.svg @@ -1,3 +1,3 @@ -
Simulation engine wrapper
Simulation...
SQLite Database
SQLite Database
Molecular dynamics engine
Molecular dynamics engine
SQLite Wrapper
SQLite Wrap...
Transfer ontology individuals (data)
Transfer ontology individuals (data)
SQLite Database
SQLite Database
SQLite Wrapper
SQLite Wrap...
Transfer results back
Transfer results back
Simulation engine wrapper
Simulation...
Fluid dynamics engine
Fluid dynamics engine
Run some simulation steps,
transfer data
Run some simulation steps,...
Run some simulation steps, transfer data
Run some simulation steps, transfer dataViewer does not support full SVG 1.1 \ No newline at end of file +
Simulation engine wrapper
Simulation...
SQLite Database
SQLite Database
Molecular dynamics engine
Molecular dynamics engine
SQLite Wrapper
SQLite Wrap...
Transfer ontology individuals (data)
Transfer ontology individuals (data)
SQLite Database
SQLite Database
SQLite Wrapper
SQLite Wrap...
Transfer results back
Transfer results back
Simulation engine wrapper
Simulation...
Fluid dynamics engine
Fluid dynamics engine
Run some simulation steps,
transfer data
Run some simulation steps,...
Run some simulation steps, transfer data
Run some simulation steps, transfer dataViewer does not support full SVG 1.1 diff --git a/docs/source/api_ref.md b/docs/source/api_ref.md index 03caa91..f14ee41 100644 --- a/docs/source/api_ref.md +++ b/docs/source/api_ref.md @@ -4,9 +4,11 @@

API Reference

``` + This document is for developers and/or advanced users of OSP-core, it contains all API details. ## CUDS + ```{eval-rst} .. autoclass:: osp.core.cuds.Cuds :members: @@ -14,38 +16,40 @@ This document is for developers and/or advanced users of OSP-core, it contains a ``` ## Ontology interface + ```{eval-rst} .. autoclass:: osp.core.ontology.namespace.OntologyNamespace :members: :special-members: __getattr__, __getitem__, __contains__, __iter__, __eq__ :show-inheritance: - + .. autoclass:: osp.core.ontology.entity.OntologyEntity :members: :show-inheritance: - + .. autoclass:: osp.core.ontology.oclass.OntologyClass :members: :show-inheritance: - + .. autoclass:: osp.core.ontology.oclass_restriction.Restriction :members: :show-inheritance: - + .. autoclass:: osp.core.ontology.oclass_composition.Composition :members: :show-inheritance: - + .. autoclass:: osp.core.ontology.relationship.OntologyRelationship :members: :show-inheritance: - + .. autoclass:: osp.core.ontology.attribute.OntologyAttribute :members: :show-inheritance: ``` ## Sessions + ```{eval-rst} .. autoclass:: osp.core.session.session.Session :members: @@ -73,6 +77,7 @@ This document is for developers and/or advanced users of OSP-core, it contains a ``` ## Registry + ```{eval-rst} .. autoclass:: osp.core.session.registry.Registry :members: @@ -80,6 +85,7 @@ This document is for developers and/or advanced users of OSP-core, it contains a ``` ## Utilities + ```{eval-rst} .. automodule:: osp.core.utils :imported-members: @@ -87,6 +93,7 @@ This document is for developers and/or advanced users of OSP-core, it contains a ``` ### pico + ```{eval-rst} .. automodule:: osp.core.pico :members: install, uninstall, packages, namespaces diff --git a/docs/source/conf.py b/docs/source/conf.py index 8f790da..c65da8a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,37 +1,37 @@ """Configuration file for the Sphinx documentation builder.""" # Project information -project = 'SimPhoNy' +project = "SimPhoNy" # Version is given in setuptools -copyright = '2022, Materials Informatics team at Fraunhofer IWM' -author = 'Materials Informatics team at Fraunhofer IWM' +copyright = "2022, Materials Informatics team at Fraunhofer IWM" +author = "Materials Informatics team at Fraunhofer IWM" # General configuration extensions = [ - 'myst_parser', # markdown source support - 'sphinx.ext.autodoc', # API ref - 'sphinx.ext.napoleon', # API ref Google and NumPy style - 'sphinx.ext.viewcode', # API link to source - 'sphinx.ext.graphviz', # Graphviz - 'sphinxcontrib.plantuml', # PlantUml - 'sphinx_copybutton', # Copy button for codeblocks - 'nbsphinx', # Jupyter - 'IPython.sphinxext.ipython_console_highlighting', # nb syntax highlight - 'sphinx.ext.autosectionlabel', # Auto-generate section labels. - 'sphinx_panels' # Create panels in a grid layout or as drop-downs + "myst_parser", # markdown source support + "sphinx.ext.autodoc", # API ref + "sphinx.ext.napoleon", # API ref Google and NumPy style + "sphinx.ext.viewcode", # API link to source + "sphinx.ext.graphviz", # Graphviz + "sphinxcontrib.plantuml", # PlantUml + "sphinx_copybutton", # Copy button for codeblocks + "nbsphinx", # Jupyter + "IPython.sphinxext.ipython_console_highlighting", # nb syntax highlight + "sphinx.ext.autosectionlabel", # Auto-generate section labels. + "sphinx_panels", # Create panels in a grid layout or as drop-downs ] -master_doc = 'index' +master_doc = "index" -plantuml = 'java -jar lib/plantuml.jar' -plantuml_output_format = 'svg_img' +plantuml = "java -jar lib/plantuml.jar" +plantuml_output_format = "svg_img" -exclude_patterns = ['**.ipynb_checkpoints'] +exclude_patterns = ["**.ipynb_checkpoints"] # HTML output -html_theme = 'sphinx_book_theme' -html_favicon = '_static/img/simphony_favicon.png' -html_logo = '_static/img/simphony_logo_dark.png' +html_theme = "sphinx_book_theme" +html_favicon = "_static/img/simphony_favicon.png" +html_logo = "_static/img/simphony_logo_dark.png" html_theme_options = { "github_url": "https://github.com/simphony/docs", "repository_url": "https://github.com/simphony/docs", @@ -43,19 +43,22 @@ } -html_static_path = ['_static'] +html_static_path = ["_static"] html_css_files = ["custom.css"] # LaTeX output -latex_documents = [('index', - 'SimPhoNy_docs.tex', - 'SimPhoNy documentation', - ('Materials Data Science and ' - 'Informatics team at Fraunhofer IWM'), - "manual", - "false",)] -latex_logo = '_static/img/simphony_logo_dark.png' -latex_elements = {'figure_align': 'H'} +latex_documents = [ + ( + "index", + "SimPhoNy_docs.tex", + "SimPhoNy documentation", + ("Materials Data Science and " "Informatics team at Fraunhofer IWM"), + "manual", + "false", + ) +] +latex_logo = "_static/img/simphony_logo_dark.png" +latex_elements = {"figure_align": "H"} nbsphinx_allow_errors = True diff --git a/docs/source/contact.md b/docs/source/contact.md index 8f51a83..9096c59 100644 --- a/docs/source/contact.md +++ b/docs/source/contact.md @@ -1,8 +1,9 @@ # Contact + If you see something wrong, missing, or in need of clarification, you can directly create an issue in [here](https://github.com/simphony/docs/issues). Any other questions, issues or comments can be directed to [Pablo de Andrés](mailto:pablo.de.andres@iwm.fraunhofer.de), -[José Manuel Domínguez](mailto:jose.manuel.dominguez@iwm.fraunhofer.de) and +[José Manuel Domínguez](mailto:jose.manuel.dominguez@iwm.fraunhofer.de) and [Yoav Nahshon](mailto:yoav.nahshon@iwm.fraunhofer.de) from the Materials Data Science and Informatics Team, Fraunhofer IWM. diff --git a/docs/source/contribute.md b/docs/source/contribute.md index af31c46..b05de17 100644 --- a/docs/source/contribute.md +++ b/docs/source/contribute.md @@ -1,38 +1,46 @@ # Contribute + This section aims to explain how we develop and organise, in order to help those that want to contribute to SimPhoNy. ## Background + ### Tools + The following are some of the technologies and concepts we use regularly. It might be useful to become familiar with them: - - Version control: [Git](https://git-scm.com/), - [GitHub](https://github.com/about) and - [GitLab](https://about.gitlab.com/) - - [Unittest](https://docs.python.org/3/library/unittest.html) - - Continuous integration - - Python virtual environments/[conda](https://docs.conda.io) - - [Docker](https://www.docker.com/resources/what-container/) - - Benchmarks + +- Version control: [Git](https://git-scm.com/), + [GitHub](https://github.com/about) and + [GitLab](https://about.gitlab.com/) +- [Unittest](https://docs.python.org/3/library/unittest.html) +- Continuous integration +- Python virtual environments/[conda](https://docs.conda.io) +- [Docker](https://www.docker.com/resources/what-container/) +- Benchmarks ### Code Organisation + There are 3 main categories of repos: - - [_OSP-core_](https://github.com/simphony/osp-core) contains the nucleus of - SimPhoNy, the base on which the wrappers build. - - Each _wrapper_ will be in its own repository on GitHub or GitLab, - mimicking - [wrapper_development](https://github.com/simphony/wrapper-development). - - [_docs_](https://github.com/simphony/docs) - holds the source for this documentation. + +- [_OSP-core_](https://github.com/simphony/osp-core) contains the nucleus of + SimPhoNy, the base on which the wrappers build. +- Each _wrapper_ will be in its own repository on GitHub or GitLab, + mimicking + [wrapper_development](https://github.com/simphony/wrapper-development). +- [_docs_](https://github.com/simphony/docs) + holds the source for this documentation. There are also 4 types of branches: - - `master/main` contains all the releases, and should always be stable. - - `dev` holds the code for the newest release that is being developed. - - `issue branch` is where an specific issue is being solved. - - `hotfix branch` is where a critical software bug detected on the stable - release (more on this later) is being solved. + +- `master/main` contains all the releases, and should always be stable. +- `dev` holds the code for the newest release that is being developed. +- `issue branch` is where an specific issue is being solved. +- `hotfix branch` is where a critical software bug detected on the stable + release (more on this later) is being solved. All wrappers and OSP-core are part of a common directory structure: + - _`osp/`_: contains all the SimPhoNy source code. - _`core/`_: OSP-core source code. - _`wrappers/`_: wrappers source code. @@ -41,37 +49,40 @@ All wrappers and OSP-core are part of a common directory structure: - _`examples/`_: simple examples of how to use a certain feature. ## Developing workflow -- Every new feature or bug is defined in an issue and labelled accordingly. - If there is something that is missing or needs improving, - make an issue in the appropriate project. + +- Every new feature or bug is defined in an issue and labelled accordingly. + If there is something that is missing or needs improving, + make an issue in the appropriate project. - Generally, the issues are fixed by creating a new `issue branch` from the - `dev` branch, committing to that branch and making a new Pull/Merge + `dev` branch, committing to that branch and making a new Pull/Merge Request when done. An owner of the project should be tagged for review. They will review and merge the PR if the fix is correct, deleting the - `issue branch` afterwards. The changes should be clearly explained in the + `issue branch` afterwards. The changes should be clearly explained in the issue/Pull Request. + ```{warning} - If the issue is a critical software bug detected in the stable release, a - `hotfix branch` should be created from the `master/main` branch - instead. - - After committing to such branch, a new Pull/Merge request (targeting - `dev`) should be created. If the fix is correct, the project owner - will merge the PR to `dev`, additionally merge the - `hotfix branch` to `master/main`, and then delete the + If the issue is a critical software bug detected in the stable release, a + `hotfix branch` should be created from the `master/main` branch + instead. + + After committing to such branch, a new Pull/Merge request (targeting + `dev`) should be created. If the fix is correct, the project owner + will merge the PR to `dev`, additionally merge the + `hotfix branch` to `master/main`, and then delete the `hotfix branch`. ``` -- Once the features for a release have been reached, `dev` will be merged to - `master/main`. Every new commit in the `master/main` branch generally - corresponds to a new release, which is labelled with a - [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) matching its - version number. An exception to this rule may apply, for example when - several critical hotfixes are applied in a row, as it would then be - better to just to publish a single release afterwards. In regard to - version numbering, we adhere to the + +- Once the features for a release have been reached, `dev` will be merged to + `master/main`. Every new commit in the `master/main` branch generally + corresponds to a new release, which is labelled with a + [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) matching its + version number. An exception to this rule may apply, for example when + several critical hotfixes are applied in a row, as it would then be + better to just to publish a single release afterwards. In regard to + version numbering, we adhere to the [_Semantic versioning_](https://semver.org/) rules. -In the next image it can be seen how the branches usually look during this +In the next image it can be seen how the branches usually look during this workflow, and the different commits used to synchronise them:
@@ -81,75 +92,84 @@ workflow, and the different commits used to synchronise them:
## Coding + ### Documenting -- All code must be properly documented with meaningful comments. -- For readability, we now follow the + +- All code must be properly documented with meaningful comments. +- For readability, we now follow the [Google docstring format](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings). -- If some behaviour is very complex, in-line comments can be used. +- If some behaviour is very complex, in-line comments can be used. However, proper naming and clear operations are always preferred. ### Code style + - Code should follow [PEP8 code style conventions](https://peps.python.org/pep-0008/). -- All Python code should be validated by the - [Flake8](https://github.com/pycqa/flake8) tool. The validation is also +- All Python code should be validated by the + [Flake8](https://github.com/pycqa/flake8) tool. The validation is also enforced on the repository by the - [continuous integration](contribute.md#continuous-integration). Click + [continuous integration](contribute.md#continuous-integration). Click [here](https://github.com/simphony/osp-core/blob/master/.github/workflows/ci.yml#L12) to see the specific options with which Flake8 is launched. - All Python code should be reformatted with - [black](https://github.com/psf/black) and - [isort](https://github.com/PyCQA/isort). The use of said tools is + [black](https://github.com/psf/black) and + [isort](https://github.com/PyCQA/isort). The use of said tools is enforced by the [continuous integration](contribute.md#continuous-integration). Therefore, we strongly recommend that you use the [configuration file](https://github.com/simphony/osp-core/blob/master/.pre-commit-config.yaml) bundled with the repository to [install](https://pre-commit.com/#installation) the - [pre-commit framework](https://pre-commit.com/), that automates the task + [pre-commit framework](https://pre-commit.com/), that automates the task using git pre-commit hooks. - A few [other style conventions](https://github.com/simphony/osp-core/blob/master/.pre-commit-config.yaml) are also enforced by the continuous integration through - [pre-commit](https://pre-commit.com/) (such as empty lines at the end of - text files). If you decide not to use it, the CI will let you know what + [pre-commit](https://pre-commit.com/) (such as empty lines at the end of + text files). If you decide not to use it, the CI will let you know what to correct. ### Testing + - All complex functionality must be tested. -- If some implementation can not be checked through unittest, it should be +- If some implementation can not be checked through unittest, it should be at least manually run in different systems to assure an expected behaviour. ### Continuous Integration + - We currently run the CI through Github Actions/GitLab CI. -- Code style conventions are enforced through the use of Flake8, black, isort, - and various - [pre-commit](https://pre-commit.com/) +- Code style conventions are enforced through the use of Flake8, black, isort, + and various + [pre-commit](https://pre-commit.com/) [hooks](https://github.com/simphony/osp-core/blob/master/.pre-commit-config.yaml). -- Tests are automatically run for all pull requests. -- For the OSP-core code, benchmarks are run after every merge to `dev`. +- Tests are automatically run for all pull requests. +- For the OSP-core code, benchmarks are run after every merge to `dev`. Benchmark results are available - [here](https://simphony.github.io/osp-core/dev/bench/index.html). The CI - will report a failure when a benchmark is 50% slower than in the previous - run, in addition to automatically commenting on the commit. + [here](https://simphony.github.io/osp-core/dev/bench/index.html). The CI + will report a failure when a benchmark is 50% slower than in the previous + run, in addition to automatically commenting on the commit. ### Naming conventions -- Use `cuds_object` as the argument name of your methods (not `entity`, + +- Use `cuds_object` as the argument name of your methods (not `entity`, `cuds`, `cuds_instance`...). -- The official spelling is `OSP-core` (as opposed to _osp core_, _OSP-Core_ +- The official spelling is `OSP-core` (as opposed to _osp core_, _OSP-Core_ or similar). ## Contribute to OSP-core + If you are not a member of the -[SimPhoNy organisation](https://github.com/simphony), rather than creating -a branch from `dev`, you will have to fork the repository and create the +[SimPhoNy organisation](https://github.com/simphony), rather than creating +a branch from `dev`, you will have to fork the repository and create the Pull Request. ## Contribute to wrapper development + For a sample wrapper, visit the [wrapper_development](https://github.com/simphony/wrapper-development) repo. README files should include: + - Information regarding the purpose of the wrapper and the backend used. - A compatibility matrix with OSP-core. - Installation instructions. @@ -157,7 +177,8 @@ README files should include: - Any other necessary information for users and other developers. ## Contribute to the docs -If you have any suggestion for this documentation, whether it is something -that needs more explanation, is inaccurate or simply a note on anything + +If you have any suggestion for this documentation, whether it is something +that needs more explanation, is inaccurate or simply a note on anything that could be improved, you can open an issue [here](https://github.com/simphony/docs/issues), and we will look into it!. diff --git a/docs/source/detailed_design.md b/docs/source/detailed_design.md index e80f9f2..50d6799 100644 --- a/docs/source/detailed_design.md +++ b/docs/source/detailed_design.md @@ -1,4 +1,5 @@ # Detailed design + Here we will give an in-depth view of the design of the 3 layers. For a more general overview, go to [getting started](./getting_started.md#general-architecture). @@ -108,7 +109,7 @@ For a more general overview, go to [getting started](./getting_started.md#genera List updated List removed SyntacticLayer syntactic - -- + -- } } @@ -141,12 +142,14 @@ For a more general overview, go to [getting started](./getting_started.md#genera ``` ## Semantic layer + The semantic layer is the representation of the classes of the ontology in a programming language. When the user installs an ontology through `pico`, all ontology concepts are saved in a graph in `~/.osp_ontologies`. The procedure is as follows: + - The `OntologyInstallationManager` receives a list of yml files with ontologies to install. - It instantiates a `Parser`. - The parser goes through the ontologies and creates an `OntologyClass` per entity. @@ -161,19 +164,23 @@ The graph is read, and an instance of the [Cuds](#cuds) class with the ontology Through the Cuds they realise the [Cuds API](#cuds-api) which enables the user to work with them in a generic, simple way. ### Cuds + _Location:_ `osp.core.cuds` -It is the base class for all instances. +It is the base class for all instances. Besides whatever might have been defined in the ontology, they all have 3 basic attributes: - - uid: instance of `uuid.UUID`, it serves to uniquely identify an instance. - - session: this is the link to the interoperability layer. - By default all objects are in the `CoreSession`, unless they are in a wrapper. - - oclass: indicates the ontology class they originate from. + +- uid: instance of `uuid.UUID`, it serves to uniquely identify an instance. +- session: this is the link to the interoperability layer. + By default all objects are in the `CoreSession`, unless they are in a wrapper. +- oclass: indicates the ontology class they originate from. #### Cuds structure + Each cuds object contains the uids and oclass of the directly related entities, as well as the relationship that connects them. The actual related objects are kept in the [registry](#registry). + ``` a_cuds_object := { Relation1: {uid1: oclass, uid2: oclass}, @@ -188,11 +195,13 @@ The actual related objects are kept in the [registry](#registry). ``` #### Cuds API + The governing idea behind the API design was to simplify as much as possible the usage. This CRUD API is defined by 6 methods: ##### Create + ```python from osp.core.namespaces import some_namespace @@ -202,70 +211,17 @@ cuds_obj = some_namespace.OntologyClass() ``` ##### Add - ```python - # These will also add the opposed relationship to the new contained cuds object - cuds_obj.add(*other_cuds, rel=relationship) - cuds_obj.add(yet_another_cuds) # Uses default relationship from ontology - ``` - - The flow of information for the call of the `add` method would be: - ```{uml} - :caption: add method call - :align: center - - skinparam { - Shadowing false - BackgroundColor transparent - sequenceBoxBackgroundColor #9FC6DE - sequenceBoxBorderColor black - ActorBackgroundColor transparent - ActorBorderColor #179c7d - ParticipantBackgroundColor #E3E3E3 - ParticipantBorderColor black - DatabaseBackgroundColor transparent - DatabaseBorderColor #179c7d - SequenceLifeLineBorderColor #179c7d - ArrowColor #179c7d - } - actor user - box "Semantic Layer" - participant "cuds" as cuds - end box - - box "Interoperability Layer" - participant "session" as sess - end box - - box "Syntactic Layer" - participant "engine" as eng - end box - - database "backend" as back - - user -> cuds: add - cuds <- sess: load - cuds -> sess: store - ``` - As you can see, the information is sent to the next layer, but not all the way to the backend. - This will be propagated when the user calls `session.run()` or `session.commit`. - The registry is checked for a pre-existing object, in case something that is already there is being added. +```python +# These will also add the opposed relationship to the new contained cuds object +cuds_obj.add(*other_cuds, rel=relationship) +cuds_obj.add(yet_another_cuds) # Uses default relationship from ontology +``` +The flow of information for the call of the `add` method would be: -##### Get - ```python - # Returns a list, unless only one uid was given - cuds_obj.get() # All the contained cuds objects - cuds_obj.get(rel=relationship) # Entities under that relationship - cuds_obj.get(*uids) # Searches elements for the uids - cuds_obj.get(*uids, rel=relationship) # Faster, filters by relationship - cuds_obj.get(oclass=ontology_class) # Elements of that class - cuds_obj.get(rel=relationship, oclass=ontology_class) # Filters by rel and oclass - ``` - In this case, the calls carried out by the `get` method are as follows: - - ```{uml} - :caption: get method call +```{uml} + :caption: add method call :align: center skinparam { @@ -286,7 +242,7 @@ cuds_obj = some_namespace.OntologyClass() actor user box "Semantic Layer" participant "cuds" as cuds - end box + end box box "Interoperability Layer" participant "session" as sess @@ -298,175 +254,240 @@ cuds_obj = some_namespace.OntologyClass() database "backend" as back - user -> cuds: get - cuds -> sess: load - - == Object not in registry == - sess -> eng: _load_from_backend - eng -> back: - back --> eng: - eng --> sess: - == Object in registry == - sess --> cuds: object - cuds --> user: object - ``` - Now the backend is contacted to make sure the user receives the latest - available version of the objects being queried. - This is done through `_load_from_backend()`. + user -> cuds: add + cuds <- sess: load + cuds -> sess: store +``` -##### Update - ```python - # Objects to update must exist already - cuds_obj.update(*cuds_objs) - ``` - - A simple `update` call triggers the following behaviour: - ```{uml} - :caption: update method call - :align: center +As you can see, the information is sent to the next layer, but not all the way to the backend. +This will be propagated when the user calls `session.run()` or `session.commit`. +The registry is checked for a pre-existing object, in case something that is already there is being added. - skinparam { - Shadowing false - BackgroundColor transparent - sequenceBoxBackgroundColor #9FC6DE - sequenceBoxBorderColor black - ActorBackgroundColor transparent - ActorBorderColor #179c7d - ParticipantBackgroundColor #E3E3E3 - ParticipantBorderColor black - DatabaseBackgroundColor transparent - DatabaseBorderColor #179c7d - SequenceLifeLineBorderColor #179c7d - ArrowColor #179c7d - } +##### Get - actor user - box "Semantic Layer" - participant "cuds" as cuds - end box +```python +# Returns a list, unless only one uid was given +cuds_obj.get() # All the contained cuds objects +cuds_obj.get(rel=relationship) # Entities under that relationship +cuds_obj.get(*uids) # Searches elements for the uids +cuds_obj.get(*uids, rel=relationship) # Faster, filters by relationship +cuds_obj.get(oclass=ontology_class) # Elements of that class +cuds_obj.get(rel=relationship, oclass=ontology_class) # Filters by rel and oclass +``` - box "Interoperability Layer" - participant "session" as sess - end box +In this case, the calls carried out by the `get` method are as follows: - box "Syntactic Layer" - participant "engine" as eng - end box +```{uml} +:caption: get method call +:align: center + +skinparam { +Shadowing false +BackgroundColor transparent +sequenceBoxBackgroundColor #9FC6DE +sequenceBoxBorderColor black +ActorBackgroundColor transparent +ActorBorderColor #179c7d +ParticipantBackgroundColor #E3E3E3 +ParticipantBorderColor black +DatabaseBackgroundColor transparent +DatabaseBorderColor #179c7d +SequenceLifeLineBorderColor #179c7d +ArrowColor #179c7d +} + +actor user +box "Semantic Layer" + participant "cuds" as cuds +end box + +box "Interoperability Layer" + participant "session" as sess +end box + +box "Syntactic Layer" + participant "engine" as eng +end box + +database "backend" as back + +user -> cuds: get +cuds -> sess: load + +== Object not in registry == +sess -> eng: _load_from_backend +eng -> back: +back --> eng: +eng --> sess: +== Object in registry == +sess --> cuds: object +cuds --> user: object +``` - database "backend" as back +Now the backend is contacted to make sure the user receives the latest +available version of the objects being queried. +This is done through `_load_from_backend()`. - user -> cuds: update - cuds <- sess: load() - cuds -> sess: store() - ``` - You can see the calls are very much the same as with the `add` method. - The difference is that the `update` requires the object to be there previously. - And so the object is first loaded from the registry, then updated and stored. +##### Update +```python +# Objects to update must exist already +cuds_obj.update(*cuds_objs) +``` -##### Remove - ```python - # These will trigger the update in the opposed relationship of the erased element - cuds_obj.remove() # Remove all - cuds_obj.remove(*uids/cuds_objs) # Remove objects with the given uids - cuds_obj.remove(*uids/cuds_objs, rel=relationship) # Faster, filters by relationship - cuds_obj.remove(rel=relationship) # Delete all elements under a relationship - cuds_obj.remove(oclass=ontology_class) # Delete all elements of a certain class - cuds_obj.remove(rel=relationship, oclass=ontology_class) # Delete filtering by rel and oclass - ``` - - The sequence for a simple `remove` is: - ```{uml} - :caption: remove method call - :align: center +A simple `update` call triggers the following behaviour: - skinparam { - Shadowing false - BackgroundColor transparent - sequenceBoxBackgroundColor #9FC6DE - sequenceBoxBorderColor black - ActorBackgroundColor transparent - ActorBorderColor #179c7d - ParticipantBackgroundColor #E3E3E3 - ParticipantBorderColor black - DatabaseBackgroundColor transparent - DatabaseBorderColor #179c7d - SequenceLifeLineBorderColor #179c7d - ArrowColor #179c7d - } +```{uml} +:caption: update method call +:align: center + +skinparam { +Shadowing false +BackgroundColor transparent +sequenceBoxBackgroundColor #9FC6DE +sequenceBoxBorderColor black +ActorBackgroundColor transparent +ActorBorderColor #179c7d +ParticipantBackgroundColor #E3E3E3 +ParticipantBorderColor black +DatabaseBackgroundColor transparent +DatabaseBorderColor #179c7d +SequenceLifeLineBorderColor #179c7d +ArrowColor #179c7d +} + +actor user +box "Semantic Layer" + participant "cuds" as cuds +end box + +box "Interoperability Layer" + participant "session" as sess +end box + +box "Syntactic Layer" + participant "engine" as eng +end box + +database "backend" as back + +user -> cuds: update +cuds <- sess: load() +cuds -> sess: store() +``` - actor user - box "Semantic Layer" - participant "cuds" as cuds - end box +You can see the calls are very much the same as with the `add` method. +The difference is that the `update` requires the object to be there previously. +And so the object is first loaded from the registry, then updated and stored. - box "Interoperability Layer" - participant "session" as sess - end box +##### Remove - box "Syntactic Layer" - participant "engine" as eng - end box +```python +# These will trigger the update in the opposed relationship of the erased element +cuds_obj.remove() # Remove all +cuds_obj.remove(*uids/cuds_objs) # Remove objects with the given uids +cuds_obj.remove(*uids/cuds_objs, rel=relationship) # Faster, filters by relationship +cuds_obj.remove(rel=relationship) # Delete all elements under a relationship +cuds_obj.remove(oclass=ontology_class) # Delete all elements of a certain class +cuds_obj.remove(rel=relationship, oclass=ontology_class) # Delete filtering by rel and oclass +``` - database "backend" as back +The sequence for a simple `remove` is: - user -> cuds: remove - cuds <- sess: load() - cuds -> cuds: remove_rel() - ``` - Here the registry is accessed to fetch the neighbours of the removed object - and delete their links (relationships) to it. +```{uml} +:caption: remove method call +:align: center + +skinparam { +Shadowing false +BackgroundColor transparent +sequenceBoxBackgroundColor #9FC6DE +sequenceBoxBorderColor black +ActorBackgroundColor transparent +ActorBorderColor #179c7d +ParticipantBackgroundColor #E3E3E3 +ParticipantBorderColor black +DatabaseBackgroundColor transparent +DatabaseBorderColor #179c7d +SequenceLifeLineBorderColor #179c7d +ArrowColor #179c7d +} + +actor user +box "Semantic Layer" + participant "cuds" as cuds +end box + +box "Interoperability Layer" + participant "session" as sess +end box + +box "Syntactic Layer" + participant "engine" as eng +end box + +database "backend" as back + +user -> cuds: remove +cuds <- sess: load() +cuds -> cuds: remove_rel() +``` +Here the registry is accessed to fetch the neighbours of the removed object +and delete their links (relationships) to it. ##### Iterate - ```python - cuds_obj.iter() # Iterates through all - cuds_obj.iter(oclass=ontology_class) # Iterates filtering by the ontology class - cuds_obj.iter(rel=relationship) # Iterates filtering by the relationship - ``` - - The general behaviour of the `iter` is: - ```{uml} - :caption: iter method call - :align: center - skinparam { - Shadowing false - BackgroundColor transparent - sequenceBoxBackgroundColor #9FC6DE - sequenceBoxBorderColor black - ActorBackgroundColor transparent - ActorBorderColor #179c7d - ParticipantBackgroundColor #E3E3E3 - ParticipantBorderColor black - DatabaseBackgroundColor transparent - DatabaseBorderColor #179c7d - SequenceLifeLineBorderColor #179c7d - ArrowColor #179c7d - } - - actor user - box "Semantic Layer" - participant "cuds" as cuds - end box +```python +cuds_obj.iter() # Iterates through all +cuds_obj.iter(oclass=ontology_class) # Iterates filtering by the ontology class +cuds_obj.iter(rel=relationship) # Iterates filtering by the relationship +``` - box "Interoperability Layer" - participant "session" as sess - end box +The general behaviour of the `iter` is: - box "Syntactic Layer" - participant "engine" as eng - end box +```{uml} +:caption: iter method call +:align: center + +skinparam { +Shadowing false +BackgroundColor transparent +sequenceBoxBackgroundColor #9FC6DE +sequenceBoxBorderColor black +ActorBackgroundColor transparent +ActorBorderColor #179c7d +ParticipantBackgroundColor #E3E3E3 +ParticipantBorderColor black +DatabaseBackgroundColor transparent +DatabaseBorderColor #179c7d +SequenceLifeLineBorderColor #179c7d +ArrowColor #179c7d +} + +actor user +box "Semantic Layer" + participant "cuds" as cuds +end box + +box "Interoperability Layer" + participant "session" as sess +end box + +box "Syntactic Layer" + participant "engine" as eng +end box + +database "backend" as back + +user -> cuds: iterate +cuds <- sess: load() +cuds -> user: yield(object) +``` - database "backend" as back +First the uids of all the objects to be iterated are gathered, +and then they are yielded like a generator - user -> cuds: iterate - cuds <- sess: load() - cuds -> user: yield(object) - ``` - First the uids of all the objects to be iterated are gathered, - and then they are yielded like a generator - ```{hint} There is also an `is_a` method for checking oclass inheritance. ``` @@ -475,10 +496,14 @@ cuds_obj = some_namespace.OntologyClass() Be aware that the sequence diagrams shown represent simple use cases, and more complex scenarios are also possible (e.g. adding an object with children). ``` + ## Interoperability layer + The interoperability layer takes care of the connection and translation between the semantic and syntactic parts. It also contains the storage of all the objects that share a session. + ### Registry + _Location:_ `osp.core.session.registry` This flat datastructure stores all the objects in the same workspace (session) by their uid. @@ -487,6 +512,7 @@ It is accessed through the session, and invisible to the user. It also has functionality for pruning, resetting, or filtering its elements. ### Session + _Location:_ `osp.core.session` The main purpose of session objects is to propagate the changes introduced by the user (and stored in the registry) @@ -496,121 +522,121 @@ The backend is accessed via the Syntactic layer, through the `_engine` property. To simplify and group functionality, we built an inheritance scheme: - ```{uml} - :caption: Session inheritance scheme - :align: center +```{uml} +:caption: Session inheritance scheme +:align: center - skinparam { - Shadowing false - BackgroundColor transparent - ClassBackgroundColor #E3E3E3 - ClassBorderColor black - PackageBorderColor black - PackageBackgroundColor #9FC6DE - ArrowColor #179c7d +skinparam { + Shadowing false + BackgroundColor transparent + ClassBackgroundColor #E3E3E3 + ClassBorderColor black + PackageBorderColor black + PackageBackgroundColor #9FC6DE + ArrowColor #179c7d +} + +rectangle "OSP-core" as OSP { + abstract class Session { + Registry : registry + -- + store(cuds_object) : Cuds + load(*uids) : Iterator + prune(rel) : void + {abstract}_notify_delete(cuds_object) + {abstract}_notify_update(cuds_object) + {abstract}_notify_read(cuds_object) } - rectangle "OSP-core" as OSP { - abstract class Session { - Registry : registry - -- - store(cuds_object) : Cuds - load(*uids) : Iterator - prune(rel) : void - {abstract}_notify_delete(cuds_object) - {abstract}_notify_update(cuds_object) - {abstract}_notify_read(cuds_object) - } - - class CoreSession implements Session { - -- - load(*uids) : Iterator - } + class CoreSession implements Session { + -- + load(*uids) : Iterator + } - abstract class WrapperSession extends Session { - SyntacticLayer: _engine - Set : _expired - Dict : _added - Dict : _updated - Dict : _deleted - -- - expire(*cuds_or_uids) : void - expire_all() : void() - refresh(*cuds_or_uids) : void - _apply_added() : void - _apply_updated() : void - _apply_deleted() : void - _notify_delete(cuds_object) : void - _notify_update(cuds_object) : void - _notify_read(cuds_object) : void - _reset_buffers(changed_by) : bool - _check_cardinalities() : void - {abstract}_load_from_backend(uids) : void - } + abstract class WrapperSession extends Session { + SyntacticLayer: _engine + Set : _expired + Dict : _added + Dict : _updated + Dict : _deleted + -- + expire(*cuds_or_uids) : void + expire_all() : void() + refresh(*cuds_or_uids) : void + _apply_added() : void + _apply_updated() : void + _apply_deleted() : void + _notify_delete(cuds_object) : void + _notify_update(cuds_object) : void + _notify_read(cuds_object) : void + _reset_buffers(changed_by) : bool + _check_cardinalities() : void + {abstract}_load_from_backend(uids) : void + } - class TransportSession implements WrapperSession { - CommunicationEngineServer : com_facility - Session : session_cls - dict : session_objs - -- - startListening() : void - handle_disconnect(user) : void - handle_request(command, data, user) : str - } + class TransportSession implements WrapperSession { + CommunicationEngineServer : com_facility + Session : session_cls + dict : session_objs + -- + startListening() : void + handle_disconnect(user) : void + handle_request(command, data, user) : str + } - abstract class DbWrapperSession extends WrapperSession { - -- - commit() : void - load_by_cuba_key(cuba_key, update_registry) : Iterator - store(cuds_object) : void - {abstract}_initialize() : void - {abstract}_load_first_level : void - {abstract}_init_transaction : void - {abstract}_rollback_transaction : void - {abstract}close : void - {abstract}_load_by_cuba(uids, update_registry): Cuds - } + abstract class DbWrapperSession extends WrapperSession { + -- + commit() : void + load_by_cuba_key(cuba_key, update_registry) : Iterator + store(cuds_object) : void + {abstract}_initialize() : void + {abstract}_load_first_level : void + {abstract}_init_transaction : void + {abstract}_rollback_transaction : void + {abstract}close : void + {abstract}_load_by_cuba(uids, update_registry): Cuds + } - abstract class SqlWrapperSession extends DbWrapperSession { - -- - _apply_added() : void - _apply_updated() : void - _apply_deleted() : void - _load_from_backend() : Iterator - _apply_deleted() : void - load_first_level : void - _load_by_cuba : void - {abstract}_db_create(...) - {abstract}_db_select(...) - {abstract}_db_insert(...) - {abstract}_db_update(...) - {abstract}_db_delete(...) - } + abstract class SqlWrapperSession extends DbWrapperSession { + -- + _apply_added() : void + _apply_updated() : void + _apply_deleted() : void + _load_from_backend() : Iterator + _apply_deleted() : void + load_first_level : void + _load_by_cuba : void + {abstract}_db_create(...) + {abstract}_db_select(...) + {abstract}_db_insert(...) + {abstract}_db_update(...) + {abstract}_db_delete(...) + } - abstract class SimWrapperSession extends WrapperSession { - bool : _ran - -- - run() - {abstract}_run(root_cuds) - {abstract}_update_cuds_after_run(root_cuds) - } + abstract class SimWrapperSession extends WrapperSession { + bool : _ran + -- + run() + {abstract}_run(root_cuds) + {abstract}_update_cuds_after_run(root_cuds) } +} - rectangle "Sqlite wrapper" as sqlite { - class SqliteWrapperSession implements SqlWrapperSession { - } +rectangle "Sqlite wrapper" as sqlite { + class SqliteWrapperSession implements SqlWrapperSession { } +} - rectangle "SqlAlchemy wrapper" as sqlalchemy { - class SqlAlchemyWrapperSession implements SqlWrapperSession { - } +rectangle "SqlAlchemy wrapper" as sqlalchemy { + class SqlAlchemyWrapperSession implements SqlWrapperSession { } +} - rectangle "Simlammps" as simlammps { - class SimlammpsSession implements SimWrapperSession { - } +rectangle "Simlammps" as simlammps { + class SimlammpsSession implements SimWrapperSession { } - ``` +} +``` ```{note} This is a reduced version and does not represent the entirety of the contained functions. @@ -622,7 +648,7 @@ and has no backend. It just accesses the registry to manage the operations made All wrappers will share `WrapperSession` as an ancestor. This will define which methods have to be implemented and `_engine` as the access point to a backend. -`SimWrapperSession` and `DbWrapperSession` further specify the behaviour of wrappers, defining the methods that +`SimWrapperSession` and `DbWrapperSession` further specify the behaviour of wrappers, defining the methods that trigger an action on the backend (`run` and `commit`, respectively). ```{note} @@ -633,44 +659,48 @@ trigger an action on the backend (`run` and `commit`, respectively). ``` #### Buffers + Session classes under `WrapperSession` share 3 types of buffers, namely `added`, `updated` and `deleted`. -The previous buffers are repeated twice, first for the user and then for the engine, +The previous buffers are repeated twice, first for the user and then for the engine, so the number of buffers is actually 6. As we have seen in the previous section, not all API calls trigger a change all the way to the backend. -In fact, most of them do not. This is done to limit the traffic in the slower sections +In fact, most of them do not. This is done to limit the traffic in the slower sections (networking or communicating with the engine). -On the other hand, the user should be able to access the latest version of the data +On the other hand, the user should be able to access the latest version of the data (meaning the changes they might have just done), and the wrapper should know what changes have taken place since the last sync with the backend software (`commit` or `run`). In order to achieve these, the changes done by the user directly modify the semantic layer and are flagged in the buffers as changes to be propagated -Users or wrapper developers do not have to worry about updating this buffers, OSP-core handles them +Users or wrapper developers do not have to worry about updating this buffers, OSP-core handles them (both filling them up and emptying them). However, these structures will be used in the different `_apply_` methods when developing a wrapper (see [this](./wrapper_development.md#coding) section of wrapper development). #### Load from Backend -Similar to how the `_apply_` methods are used to send information to the engine, + +Similar to how the `_apply_` methods are used to send information to the engine, `_load_from_backend` has the purpose of updating the semantic layer with the latest information from the backend. You can see in the [`get` sequence diagram](#id3) that when the information has potentially changed in the backend (i.e the simulation has run, or a database has more data) -the `get` has to fetch the latest version. -To achieve this, OSP-core calls `_load_from_backend` with the list of desired uids, +the `get` has to fetch the latest version. +To achieve this, OSP-core calls `_load_from_backend` with the list of desired uids, and the wrapper wrapper will update the objects in the registry with the relevant information and `yield` them. ### Networking + _Location:_ `osp.core.session.transport` You may have noticed in the [session inheritance scheme](#id2) that there is `TransportSession` implementing the `WrapperSession`. This session class is the way to connect to engines that are located in other machines through web sockets. The behaviour is as follows: + - The user instantiates a `TransportSessionClient` and provides the session class of the remote server, the hostname and the port. - The `TransportSessionClient` will connect to a `TransportSessionServer` @@ -685,24 +715,28 @@ The behaviour is as follows: The chosen implementation hides most of the work from the users and wrapper developers. The only difference between a local wrapper and a remote one is the line where the wrapper session is instantiated, from: + ```python sess = SomeWrapperSession(parameter_a, parameter_b) wrapper = AWrapperInstance(session=sess) ``` + to: + ```python # Once the server is properly setup sess = TransportSessionClient(SomeWrapperSession, host, port, parameter_a, parameter_b) wrapper = AWrapperInstance(session=sess) ``` + ## Syntactic layer -This layer is in direct communication with the backend. -It has no ontological knowledge and must just provide a simple interface for the interoperability layer to interact with the wrapped application. -This means it may have to be a binding if the application is in a different language. +This layer is in direct communication with the backend. +It has no ontological knowledge and must just provide a simple interface for the interoperability layer to interact with the wrapped application. + +This means it may have to be a binding if the application is in a different language. It could also be a file generator/parser for backends that only allow file i/o. -In other cases, (e.g. LAMMPS with PyLammps) it is provided by the backend itself, and requires no implementation. +In other cases, (e.g. LAMMPS with PyLammps) it is provided by the backend itself, and requires no implementation. Since the syntactic layer will greatly depend on the specific backend, no standardisation is provided there. - diff --git a/docs/source/fundamentals.md b/docs/source/fundamentals.md index 2d7951e..eff539c 100644 --- a/docs/source/fundamentals.md +++ b/docs/source/fundamentals.md @@ -1,8 +1,11 @@ # Fundamental concepts + In this section we will present some of the main concepts behind SimPhoNy. ## General notions + ### Degrees of interoperability + There is a multitude of tools and programs out there, all with their own formats and protocols. Every time a user wants to use one of these tools, they must familiarise themselves with the software. @@ -12,131 +15,138 @@ take care of the conversion on their own. Based on how tools communicate with other tools, we can define 3 levels: #### Compatibility - ```{uml} - :align: center - :caption: Compatibility - skinparam { - linetype ortho - Shadowing false - BackgroundColor transparent - RectangleBackgroundColor #E3E3E3 - RectangleBorderColor black - ArrowColor #179c7d - } - - rectangle A - rectangle B - rectangle C - rectangle D - - A <-> B - A <-[hidden]- C - C <-> D - ``` +```{uml} + :align: center + :caption: Compatibility + + skinparam { + linetype ortho + Shadowing false + BackgroundColor transparent + RectangleBackgroundColor #E3E3E3 + RectangleBorderColor black + ArrowColor #179c7d + } + + rectangle A + rectangle B + rectangle C + rectangle D + + A <-> B + A <-[hidden]- C + C <-> D +``` - When we say two tools are compatible, they are able to communicate with each other - in a one to one basis. - This means the tools must either use the same format, or be able to convert to the format of the other. +When we say two tools are compatible, they are able to communicate with each other +in a one to one basis. +This means the tools must either use the same format, or be able to convert to the format of the other. - If we compare this to speaking languages, you could say `A` and `B`, or `C` and `D` speak the same language. - However, `A` has no way to talk with `C` or `D`, for example. +If we compare this to speaking languages, you could say `A` and `B`, or `C` and `D` speak the same language. +However, `A` has no way to talk with `C` or `D`, for example. #### De Facto Standard - ```{uml} - :align: center - :caption: De Facto Standard - skinparam { - Shadowing false - BackgroundColor transparent - RectangleBackgroundColor #E3E3E3 - RectangleBorderColor black - ArrowColor #179c7d - } - - rectangle A - rectangle B - rectangle C - rectangle D - - A <--> B - A <-> C - C <-[hidden]- D - B <-[hidden]- D - A <-> D - ``` +```{uml} + :align: center + :caption: De Facto Standard + + skinparam { + Shadowing false + BackgroundColor transparent + RectangleBackgroundColor #E3E3E3 + RectangleBorderColor black + ArrowColor #179c7d + } + + rectangle A + rectangle B + rectangle C + rectangle D + + A <--> B + A <-> C + C <-[hidden]- D + B <-[hidden]- D + A <-> D +``` - In this case, the level of operability is higher. - All tools know how to communicate with a tool whose format has become a de facto standard. +In this case, the level of operability is higher. +All tools know how to communicate with a tool whose format has become a de facto standard. - To continue with our language simile, `A` would be a translator that speaks the languages of `B`, `C` and `D`. - If `B` wants to talk to `C`, they must first relay the message to `A`, - and `A` will convert it to a format that `C` understands. +To continue with our language simile, `A` would be a translator that speaks the languages of `B`, `C` and `D`. +If `B` wants to talk to `C`, they must first relay the message to `A`, +and `A` will convert it to a format that `C` understands. #### Interoperability - ```{uml} - :align: center - :caption: Interoperability - skinparam { - linetype ortho - Shadowing false - BackgroundColor transparent - RectangleBackgroundColor #E3E3E3 - RectangleBorderColor black - UsecaseBackgroundColor transparent - UsecaseBorderColor #55A5D9 - ArrowColor #179c7d - } - - usecase x as "open standard" - rectangle A - rectangle B - rectangle C - rectangle D - A <-down-> x - B <-right-> x - C <-left-> x - D <-up-> x - ``` - The highest level of operability is interoperability. - Here there is no need for all tools to go through the De Facto standard, - because there is a format that is known by all of them and enables all components to communicate among themselves. +```{uml} + :align: center + :caption: Interoperability + + skinparam { + linetype ortho + Shadowing false + BackgroundColor transparent + RectangleBackgroundColor #E3E3E3 + RectangleBorderColor black + UsecaseBackgroundColor transparent + UsecaseBorderColor #55A5D9 + ArrowColor #179c7d + } + + usecase x as "open standard" + rectangle A + rectangle B + rectangle C + rectangle D + A <-down-> x + B <-right-> x + C <-left-> x + D <-up-> x +``` - This final stage could be compared to all parties using an instant translator that can convert - text from one language into any other. +The highest level of operability is interoperability. +Here there is no need for all tools to go through the De Facto standard, +because there is a format that is known by all of them and enables all components to communicate among themselves. +This final stage could be compared to all parties using an instant translator that can convert +text from one language into any other. Interoperability between software tools is one of the most important objectives of the SimPhoNy framework. + ### Semantic vs. syntactic - We can interpret a word as a specific sequence of characters without caring about the meaning itself. - This way, a simulation engine parsing an input file will know that the integer written after the keyword - `step` will be used to set the number of iterations the execution loop will run. - It does nothing else, and could as easily use the sequence `ppp`. - However, for a person, the word `step` will be a sign representing a specific concept. - It could be the number of rounds in a simulation, but also the consecutive instructions in an algorithm, the - different levels in a stair or the motion a person makes when walking. - Based on the domain, a person can also list other relevant concepts and relationships - (e.g. when thinking of a stair, the `material` or the `width`). +We can interpret a word as a specific sequence of characters without caring about the meaning itself. +This way, a simulation engine parsing an input file will know that the integer written after the keyword +`step` will be used to set the number of iterations the execution loop will run. +It does nothing else, and could as easily use the sequence `ppp`. - Being able to know the semantic meaning of an instance, and hence its connection to other concepts, - is one of the principles of SimPhoNy. For achieving this goal, ontologies play a major role. +However, for a person, the word `step` will be a sign representing a specific concept. +It could be the number of rounds in a simulation, but also the consecutive instructions in an algorithm, the +different levels in a stair or the motion a person makes when walking. +Based on the domain, a person can also list other relevant concepts and relationships +(e.g. when thinking of a stair, the `material` or the `width`). + +Being able to know the semantic meaning of an instance, and hence its connection to other concepts, +is one of the principles of SimPhoNy. For achieving this goal, ontologies play a major role. ### Ontology + ```{important} An ontology is a formal specification of a shared conceptualization. [[Borst, 1997]](https://research.utwente.nl/en/publications/construction-of-engineering-ontologies-for-knowledge-sharing-and-) ``` Let's look at the individual components of this definition, starting from the end. - - _Conceptualization_, an ontology will work on the ideas and relationships in an area of interest. - - _Shared_, the ideas and concepts are perceived and agreed by multiple people. - - _Specification_, it will define and describe them in detail, following some predetermined rules and format. - - _Formal_, meaning it will follow a machine readable syntax. -In a simpler way, an ontology can be seen as the definition of concepts relevant to a given domain, +- _Conceptualization_, an ontology will work on the ideas and relationships in an area of interest. +- _Shared_, the ideas and concepts are perceived and agreed by multiple people. +- _Specification_, it will define and describe them in detail, following some predetermined rules and format. +- _Formal_, meaning it will follow a machine readable syntax. + +In a simpler way, an ontology can be seen as the definition of concepts relevant to a given domain, as well as the relationships between them, in a way that a machine can interpret it. For a deeper, more detailed analysis of the definition, refer to [[Guarino, 2009]](http://dx.doi.org/10.1007/978-3-540-92673-3_0). @@ -145,20 +155,23 @@ Ontologies are more elaborated than taxonomies in that they can include multiple (not just parent-child) between complex concepts in big domains. #### EMMO + The Elementary Multiperspective Material Ontology ([EMMO](https://github.com/emmo-repo/EMMO), previously the European Materials Modelling Ontology) is an ontology developed by the European Materials Modelling Council ([EMMC](https://emmc.info/)). EMMO's goal is to define a representational system universal for scientists in the field of materials modelling to enable interoperability. -It has been designed from the bottom up, starting with the concepts of different domains and application fields -and generalising into a middle and top level layers, and it is currently being further +It has been designed from the bottom up, starting with the concepts of different domains and application fields +and generalising into a middle and top level layers, and it is currently being further developed in multiple projects of the European Union. -SimPhoNy is being developed with the intention of being compatible with EMMO, and an easy installation of the +SimPhoNy is being developed with the intention of being compatible with EMMO, and an easy installation of the ontology is available (further explained [here](./ontologies_included.md#working-with-emmo)). There is also [documentation](https://ontology.pages.fraunhofer.de/documentation/latest/) available for developing an EMMO compliant ontology (requires login). ### CUDS + CUDS, or Common Universal Data Structure, is the ontology compliant data format of OSP-core: + - **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_ @@ -169,28 +182,33 @@ CUDS, or Common Universal Data Structure, is the ontology compliant data format - **CUDS is RDF**: Internally a CUDS object is only an interface to an RDF-based triple store that contains the data of all CUDS objects. - **CUDS is a node in a graph**: : CUDS being individuals in an RDF graph implies that each CUDS object can also be seen as a node in a graph. This does not conflict with the container perspective, instead we see it as to different views on the data. + ## Technologies and frameworks + ### RDF + [RDF](https://www.w3.org/RDF/) (Resource Description Framework) is a formal language for describing structured information used in the Semantic Web. Its first specification was published in 1999 and extended in 2004. Knowledge is represented in directed graphs where the nodes are either ontological classes, -instances of those classes or literals and the edges the relationships connecting them. +instances of those classes or literals and the edges the relationships connecting them. The graph is serialised in the form of triples of the form "subject-predicate-object" + - _Subject_: The IRI of the entity the triple refers to. - Blank nodes have no IRI, but they are outside of the scope of this thesis. + Blank nodes have no IRI, but they are outside of the scope of this thesis. - _Predicate_: IRI of the relationship from subject to object. - _Object_: Literal or IRI of an entity The following is an example of an RDF triple. This example will also be used to show the different serialisation formats of RDF. For the IRIs, `dbpedia`'s namespace was used. + ```{uml} :align: center :caption: RDF triple sample skinparam { - linetype ortho + linetype ortho Shadowing false BackgroundColor transparent UsecaseBorderColor black @@ -204,13 +222,15 @@ For the IRIs, `dbpedia`'s namespace was used. ``` The most used formats for storing RDF data are: + - [XML](https://www.w3.org/2001/sw/RDFCore/TR/WD-rdf-syntax-grammar-20030117/): Historically the most common format given the amount of libraries for handling it. - It was released hand in hand with the RDF specification. - Unfortunately, XML is best used with tree-like structures rather than graphs, - which also makes it harder for humans to read. + It was released hand in hand with the RDF specification. + Unfortunately, XML is best used with tree-like structures rather than graphs, + which also makes it harder for humans to read. + + The example triple in XML is: - The example triple in XML is: ```xml @@ -223,10 +243,11 @@ The most used formats for storing RDF data are: ``` - [N3](https://www.w3.org/TeamSubmission/n3/): Notation3 is designed with human readability as a motivator. - The RDF triples are written one per line, with the possibility to define common prefixes - and other directives for simplicity. - - The previous example in N3 would be: + The RDF triples are written one per line, with the possibility to define common prefixes + and other directives for simplicity. + + The previous example in N3 would be: + ```turtle @prefix dbo: . @prefix dbr: . @@ -234,62 +255,70 @@ The most used formats for storing RDF data are: ``` - [Turtle](https://www.w3.org/TR/turtle/): Based on N3, it strips some of its syntax, making it easier to parse - for machines. - The recurring example would be exactly the same in Turtle as in N3. + for machines. + The recurring example would be exactly the same in Turtle as in N3. - [N-Triples](https://www.w3.org/TR/n-triples/): N-Triples are even simpler, without any of the syntactic sugar from N3 or Turtle. - The triples are written one per line without prefixes. This makes it a very easy format to parse - but complex to maintain/read by a human. + The triples are written one per line without prefixes. This makes it a very easy format to parse + but complex to maintain/read by a human. + + The following representation should be in one line (it has been split for readability) - The following representation should be in one line (it has been split for readability) ```xml . ``` - + - [JSON-LD](https://www.w3.org/TR/json-ld/): uses the commonly accepted web data scheme for serialising RDF triples. - Easier than XML for humans, JSON has standard libraries in practically all programming languages. + Easier than XML for humans, JSON has standard libraries in practically all programming languages. + + The example in JSON is: - The example in JSON is: ```json - {"@id": "http://dbpedia.org/resource/The_Lord_of_the_Rings", - "http://dbpedia.org/property/author": - [{"@id": "http://dbpedia.org/resource/J._R._R._Tolkien"}] - } + { + "@id": "http://dbpedia.org/resource/The_Lord_of_the_Rings", + "http://dbpedia.org/property/author": [ + { "@id": "http://dbpedia.org/resource/J._R._R._Tolkien" } + ] + } ``` -SimPhoNy supports all the previous formats (plus a simpler custom YAML) as inputs in the ontology installation. + + SimPhoNy supports all the previous formats (plus a simpler custom YAML) as inputs in the ontology installation. #### SPARQL + [SPARQL](https://www.w3.org/TR/sparql11-overview/) (recursively SPARQL Protocol and RDF Query Language) is the most common query language for RDF. Queries are graph patterns (similar to the triples of Turtle) with variables for the parts of the pattern that make up the result. Variables start with the identifier `?` and represent concrete values that will be matched in the query process. -They can appear in multiple locations in the patterns and those present in the +They can appear in multiple locations in the patterns and those present in the `SELECT` clause will be returned as the query result. The query for the author of _The Lord of the Rings_ from our sample triples in SPARQL is: - ```sparql - PREFIX dbo: - PREFIX dbr: - SELECT ?person WHERE { - dbr:The_Lord_of_the_Rings dbo:author ?person . - } - ``` + +```sparql + PREFIX dbo: + PREFIX dbr: + SELECT ?person WHERE { + dbr:The_Lord_of_the_Rings dbo:author ?person . + } +``` The SPARQL query language offers multiple types of result sets and clauses, most of which won't be used for this Master's thesis. One which should be mentioned is the `FILTER` keyword. This will limit the result to those that evaluate `true` to the expression inside the brackets. For instance (omitting the prefix declaration for simplicity): - ```sparql - SELECT ?character WHERE { - ?character dbp:affiliation dbr:The_Lord_of_the_Rings . - ?character dbo:age ?age . - FILTER(?age >= 100) - } - ``` -The previous query would return the characters from the book series with an age higher or equal to 100. +```sparql + SELECT ?character WHERE { + ?character dbp:affiliation dbr:The_Lord_of_the_Rings . + ?character dbo:age ?age . + FILTER(?age >= 100) + } +``` + +The previous query would return the characters from the book series with an age higher or equal to 100. (Note that while the query is correct, the result is empty, as such information is not stored on DBpedia). For a very interesting and comprehensive introduction into RDF and SPARQL, see [[Hitzler, 2009]](http://dx.doi.org/10.1201/9781420090512). diff --git a/docs/source/general_architecture.md b/docs/source/general_architecture.md index d3163fe..0aba67f 100644 --- a/docs/source/general_architecture.md +++ b/docs/source/general_architecture.md @@ -1,4 +1,5 @@ # General architecture + The following architecture has the aim to cover and support the goals presented in the [overview section](overview.md). ```{uml} @@ -6,7 +7,7 @@ The following architecture has the aim to cover and support the goals presented :caption: Interoperability concept skinparam { - linetype ortho + linetype ortho Shadowing false BackgroundColor transparent UsecaseBackgroundColor #E3E3E3 @@ -21,7 +22,7 @@ The following architecture has the aim to cover and support the goals presented ranksep 10 } - + actor user rectangle SimPhoNy { usecase "OSP-core" as osp @@ -50,8 +51,8 @@ The following architecture has the aim to cover and support the goals presented As you can see, OSP-core provides the standard data format and API, and the wrappers take care of mapping that format to and from the backend specific syntax and API. -In order to simplify and generalise the usage as much as possible, the backend -specific and syntactic knowledge should be abstracted to ontology concepts +In order to simplify and generalise the usage as much as possible, the backend +specific and syntactic knowledge should be abstracted to ontology concepts that encompass all third party tools. For that, a 3 layer schema is used: @@ -61,7 +62,7 @@ For that, a 3 layer schema is used: :align: center skinparam { - linetype ortho + linetype ortho Shadowing false BackgroundColor transparent RectangleBackgroundColor #E3E3E3 @@ -75,25 +76,25 @@ For that, a 3 layer schema is used: ArrowColor #179c7d ranksep 10 } - + skinparam rectangle<> { BorderColor Transparent BackgroundColor transparent stereotypeFontColor transparent } Actor user - + rectangle "semantic layer" as sem { } rectangle "interoperability layer" as intop { } - rectangle "syntactic layer" as syn { + rectangle "syntactic layer" as syn { } - + database backend - + rectangle gen<>[ Ontology aware, generic\t ] @@ -114,23 +115,24 @@ For that, a 3 layer schema is used: backend -[hidden]-> spe ``` -- The *Semantic layer* are the classes generated from the ontology with the CUDS API. -- The *Interoperability layer* maps the changes in the semantic layer to calls in the syntactic layer. -- The *Syntactic layer* provides access to the backend. +- The _Semantic layer_ are the classes generated from the ontology with the CUDS API. +- The _Interoperability layer_ maps the changes in the semantic layer to calls in the syntactic layer. +- The _Syntactic layer_ provides access to the backend. The closer to the user, the closer to the ontology concepts. The abstraction is replaced by specificity when you move towards the backend. For example, the City, Street or Neighborhood classes from the demonstrative [City Ontology](ontologies_included.md#the-city-ontology) included in OSP-core, as well as the individuals that can be instantiated using them, would be part of the semantic layer. Any wrapper (e.g. the included [SQLite wrapper](https://github.com/simphony/osp-core/tree/master/osp/wrappers/sqlite)), would be part of the interoperability layer. Finally, following the SQLite example, the [sqlite3 library](https://docs.python.org/3/library/sqlite3.html) from python would be part of the syntactic layer. - For a full explanation on the architecture and design, go to [detailed design](detailed_design.md). ## OSP-core + [OSP-core](https://github.com/simphony/osp-core) is the main component of the SimPhoNy framework. It is independent of any backend and provides the basic ontology based data structures for the seamless exchange of data between wrappers. ### Ontology file + OSP-core requires an ontology file to create the appropriate CUDS classes. Said ontology must be either in a YAML format as defined by [our specification](working_with_ontologies.md#osp-core-yaml-ontology-format) @@ -140,82 +142,84 @@ or [one of the supported owl ontologies](working_with_ontologies.md#owl-ontologi YAML Ontology sample The following is an excerpt from the `city.ontology.yml` in osp-core. - ```yaml - --- - version: "0.0.3" - - namespace: "city" - - ontology: - - encloses: - subclass_of: - - cuba.activeRelationship - inverse: city.isEnclosedBy - - isEnclosedBy: - subclass_of: - - cuba.passiveRelationship - inverse: city.encloses - - hasInhabitant: - subclass_of: - - city.encloses - - ################ - - CityWrapper: - subclass_of: - - cuba.Wrapper - - city.hasPart: - range: city.City - cardinality: 1+ - exclusive: false - - ################ - - City: - subclass_of: - - city.PopulatedPlace - - city.hasPart: - range: city.Neighborhood - cardinality: many - exclusive: true - - city.isPartOf: - range: city.CityWrapper - cardinality: 0-1 - exclusive: true - - city.hasMajor: - range: city.Citizen - cardinality: 0-1 - exclusive: true - - Building: - subclass_of: - - city.ArchitecturalStructure - - city.hasPart: - range: city.Address - cardinality: 1 - exclusive: false - - city.hasPart: - range: city.Floor - cardinality: many - exclusive: false - - city.isPartOf: - range: city.Street - cardinality: 1 - exclusive: true - - Citizen: - subclass_of: - - city.Person - ``` +```yaml + --- + version: "0.0.3" + + namespace: "city" + + ontology: + + encloses: + subclass_of: + - cuba.activeRelationship + inverse: city.isEnclosedBy + + isEnclosedBy: + subclass_of: + - cuba.passiveRelationship + inverse: city.encloses + + hasInhabitant: + subclass_of: + - city.encloses + + ################ + + CityWrapper: + subclass_of: + - cuba.Wrapper + - city.hasPart: + range: city.City + cardinality: 1+ + exclusive: false + + ################ + + City: + subclass_of: + - city.PopulatedPlace + - city.hasPart: + range: city.Neighborhood + cardinality: many + exclusive: true + - city.isPartOf: + range: city.CityWrapper + cardinality: 0-1 + exclusive: true + - city.hasMajor: + range: city.Citizen + cardinality: 0-1 + exclusive: true + + Building: + subclass_of: + - city.ArchitecturalStructure + - city.hasPart: + range: city.Address + cardinality: 1 + exclusive: false + - city.hasPart: + range: city.Floor + cardinality: many + exclusive: false + - city.isPartOf: + range: city.Street + cardinality: 1 + exclusive: true + + Citizen: + subclass_of: + - city.Person +``` + OSP-core can be used with EMMO (Elementary Multiperspective Material Ontology) out of the box. See more [here](ontologies_included.md). ### Python classes + Upon installation of OSP-core, each ontology class (except from attributes and relationships) becomes a python class. Since each ontology has a namespace, it can be used to import the classes and create cuds objects: @@ -228,17 +232,19 @@ other_entity = another_namespace.SomeOtherEntity() ``` ### Sessions -The [sessions](./detailed_design.md#session) are the interoperability classes that connect to where the data is stored. + +The [sessions](./detailed_design.md#session) are the interoperability classes that connect to where the data is stored. [In the case of wrappers](./wrapper_development.md#coding), they take care of keeping consistency between the backends (e.g. databases) and the internal registry. The `CoreSession` is the default one used when instantiating a new object in your workspace. When you add an object to a wrapper, a copy of the object is created in the registry belonging to the session of the wrapper. ## Wrappers -Like we have mentioned in previous sections, wrappers allow the user to interact + +Like we have mentioned in previous sections, wrappers allow the user to interact through the cuds API with different backends. Since each backend is different, for more detailed documentation of each wrapper we suggest going through the different available [repositories](https://gitlab.cc-asp.fraunhofer.de/simphony/wrappers/). -For more technical information regarding wrappers, particularly for wrapper developers, +For more technical information regarding wrappers, particularly for wrapper developers, we recommend visiting [wrapper development](wrapper_development.md). diff --git a/docs/source/index.md b/docs/source/index.md index 88b613e..386567b 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -24,16 +24,16 @@ SimPhoNy is an ontology-based [open-source](./license.md) Python framework that :classes: btn-outline-primary stretched-link --- - + **Working with Ontologies** Ontology overview, included ontologies, YAML ontologies and ontology querying ```{link-button} ontology_intro.html - :text: To the ontology guides + :text: To the ontology guides :classes: btn-outline-primary stretched-link --- - + **Wrapper Development** A deep dive into the wrapper mechanism for developing new wrappers @@ -42,7 +42,7 @@ SimPhoNy is an ontology-based [open-source](./license.md) Python framework that :text: To the wrapper development guides :classes: btn-outline-primary stretched-link --- - + **API Reference** Python API of CUDS, the *Session* classes, and other utilities @@ -50,7 +50,7 @@ SimPhoNy is an ontology-based [open-source](./license.md) Python framework that ```{link-button} api_ref.html :text: To the API reference :classes: btn-outline-primary stretched-link - + --- **Additional Information** diff --git a/docs/source/installation.md b/docs/source/installation.md index bf7c663..3db3e5e 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -1,20 +1,20 @@ # Installation -For the installation and usage of the framework Python 3.6 or higher is +For the installation and usage of the framework Python 3.6 or higher is needed. OSP-core is available on PyPI, so it can be installed using `pip`: ```shell ~/test$ pip install osp-core ``` -However, we *highly* encourage the use of a [virtual environment](https://docs.python.org/3/tutorial/venv.html) +However, we _highly_ encourage the use of a [virtual environment](https://docs.python.org/3/tutorial/venv.html) or a [conda](https://docs.conda.io/en/latest/) environment. ```shell -# virtual environment +# virtual environment ~/test$ python3 -m venv SimPhoNy ~/test$ source SimPhoNy/bin/activate -(SimPhoNy) ~/test$ +(SimPhoNy) ~/test$ ``` ```shell @@ -23,8 +23,8 @@ or a [conda](https://docs.conda.io/en/latest/) environment. ~/test$ conda activate ``` -Unfortunately, OSP-core is not available on the Anaconda Repository, so -in both cases, after setting up the environment, it must be installed with +Unfortunately, OSP-core is not available on the Anaconda Repository, so +in both cases, after setting up the environment, it must be installed with `pip install osp-core`. After installing OSP-core, you can install your ontology namespaces. @@ -39,15 +39,18 @@ python -m osp.core.pico install ``` ## Wrapper installation -Wrappers are currently not available on PyPI, so they must be installed + +Wrappers are currently not available on PyPI, so they must be installed from source. First, the repository is cloned: ```shell git clone https://github.com/simphony/.git cd some-wrapper ``` + ### Local wrapper installation -With OSP-core installed, if the wrapper has its own ontology, it *must* be installed: + +With OSP-core installed, if the wrapper has its own ontology, it _must_ be installed: ```shell pico install @@ -67,6 +70,7 @@ python3 setup.py install ``` ### Wrapper Docker image + Some wrappers also provided a [Dockerfile](https://docs.docker.com/engine/reference/builder/) for an automatic installation in a container. Simply run the `docker_install.sh` script. There is no need to install OSP-core either. @@ -75,10 +79,9 @@ Simply run the `docker_install.sh` script. There is no need to install OSP-core ./docker_install.sh ``` - ## Installing OSP-core from source -If you are a developer or an advanced user, you might be interested in +If you are a developer or an advanced user, you might be interested in installing OSP-core from source. To do so, first the repository must be cloned: diff --git a/docs/source/json_schema/serialized_cuds.json b/docs/source/json_schema/serialized_cuds.json index e18f669..80f8ac6 100644 --- a/docs/source/json_schema/serialized_cuds.json +++ b/docs/source/json_schema/serialized_cuds.json @@ -1,96 +1,43 @@ - { - "cuds_array": { - "title": "Array of flat CUDS objects", - "description": "This schema shows how the method `osp.core.utils.serialize()`\n\nwill serialize a CUDS object to JSON. The result is a flat list,\n\nwhere ich element references its neighbors by UUID.", - "type": "array", - "items": { - "$ref": "#/definitions/cuds" - } - }, - "definitions": { - "cuds": { - "title": "Flat CUDS object", - "description": "A representation of a single non-hierarchical CUDS object", - "type": "object", - "$$target": "#/definitions/cuds", - "properties": { - "uid": { - "$ref": "#/definitions/uuid" - }, - "oclass": { - "$ref": "#/definitions/entity" - }, - "attributes": { - "$ref": "#/definitions/attributes" - }, - "relationships": { - "$ref": "#/definitions/relationships" - } +{ + "cuds_array": { + "title": "Array of flat CUDS objects", + "description": "This schema shows how the method `osp.core.utils.serialize()`\n\nwill serialize a CUDS object to JSON. The result is a flat list,\n\nwhere ich element references its neighbors by UUID.", + "type": "array", + "items": { + "$ref": "#/definitions/cuds" + } + }, + "definitions": { + "cuds": { + "title": "Flat CUDS object", + "description": "A representation of a single non-hierarchical CUDS object", + "type": "object", + "$$target": "#/definitions/cuds", + "properties": { + "uid": { + "$ref": "#/definitions/uuid" }, - "required": [ - "uid", - "oclass" - ], - "example": { - "uid": "0ed73819-a095-423f-a444-e7e21e600957", - "oclass": "onto.WaterMolecule", - "attributes": { - "onto.velocity": 7 - }, - "relationships": { - "onto.hasPart": { - "b22fc8f5-2fdf-40f1-955c-96d6e2c278d8": "onto.Oxygen", - "ee901cdc-307e-4ca7-837e-074ba14996d6": "onto.Hydrogen", - "1e8f75f6-29d5-450f-a991-fc0dc2890075": "onto.Hydrogen" - } - } - } - }, - "entity": { - "title": "Name of an ontology entity", - "type": "string", - "description": "An ontology entity", - "format": "oclass", - "example": "onto.SimulationCuds", - "$$target": "#/definitions/entity", - "pattern": "([a-zA-Z])([a-zA-Z]|[0-9]|_)*\\.([a-zA-Z])([a-zA-Z]|[0-9]|_)*" - }, - "uuid": { - "title": "Universal unique identifier", - "type": "string", - "format": "uuid", - "description": "The unique identifier of a CUDS", - "example": "9053ed01-b301-473d-b59d-c184d4e772a1", - "$$target": "#/definitions/uuid" - }, - "attributes": { - "title": "Attributes of the CUDS objects", - "description": "**The key is a `entity`:** A mapping from the **ontology attribute** to its **values**", - "type": "object", - "additionalProperties": true, - "$$target": "#/definitions/attributes", - "example": { - "onto.Foo": 42, - "onto.Bar": [ - 1, - 2, - 3 - ] + "oclass": { + "$ref": "#/definitions/entity" + }, + "attributes": { + "$ref": "#/definitions/attributes" + }, + "relationships": { + "$ref": "#/definitions/relationships" } }, - "relationships": { - "title": "Relationships of the CUDS objects", - "type": "object", - "$$target": "#/definitions/relationships", - "description": "**The key is a `entity`:** A mapping from the **ontology relationship** to the related cuds objects' **UUIDs and ontology classes**.", - "additionalProperties": { - "type": "object", - "description": "**The key is a `uuid`:** A mapping from the **uuid** to the **ontology class** of the related cuds objects", - "additionalProperties": { - "$ref": "#/definitions/entity" - } + "required": [ + "uid", + "oclass" + ], + "example": { + "uid": "0ed73819-a095-423f-a444-e7e21e600957", + "oclass": "onto.WaterMolecule", + "attributes": { + "onto.velocity": 7 }, - "example": { + "relationships": { "onto.hasPart": { "b22fc8f5-2fdf-40f1-955c-96d6e2c278d8": "onto.Oxygen", "ee901cdc-307e-4ca7-837e-074ba14996d6": "onto.Hydrogen", @@ -98,5 +45,58 @@ } } } + }, + "entity": { + "title": "Name of an ontology entity", + "type": "string", + "description": "An ontology entity", + "format": "oclass", + "example": "onto.SimulationCuds", + "$$target": "#/definitions/entity", + "pattern": "([a-zA-Z])([a-zA-Z]|[0-9]|_)*\\.([a-zA-Z])([a-zA-Z]|[0-9]|_)*" + }, + "uuid": { + "title": "Universal unique identifier", + "type": "string", + "format": "uuid", + "description": "The unique identifier of a CUDS", + "example": "9053ed01-b301-473d-b59d-c184d4e772a1", + "$$target": "#/definitions/uuid" + }, + "attributes": { + "title": "Attributes of the CUDS objects", + "description": "**The key is a `entity`:** A mapping from the **ontology attribute** to its **values**", + "type": "object", + "additionalProperties": true, + "$$target": "#/definitions/attributes", + "example": { + "onto.Foo": 42, + "onto.Bar": [ + 1, + 2, + 3 + ] + } + }, + "relationships": { + "title": "Relationships of the CUDS objects", + "type": "object", + "$$target": "#/definitions/relationships", + "description": "**The key is a `entity`:** A mapping from the **ontology relationship** to the related cuds objects' **UUIDs and ontology classes**.", + "additionalProperties": { + "type": "object", + "description": "**The key is a `uuid`:** A mapping from the **uuid** to the **ontology class** of the related cuds objects", + "additionalProperties": { + "$ref": "#/definitions/entity" + } + }, + "example": { + "onto.hasPart": { + "b22fc8f5-2fdf-40f1-955c-96d6e2c278d8": "onto.Oxygen", + "ee901cdc-307e-4ca7-837e-074ba14996d6": "onto.Hydrogen", + "1e8f75f6-29d5-450f-a991-fc0dc2890075": "onto.Hydrogen" + } + } } - } \ No newline at end of file + } +} diff --git a/docs/source/jupyter/cuds_api.ipynb b/docs/source/jupyter/cuds_api.ipynb index 7133b13..d972b39 100644 --- a/docs/source/jupyter/cuds_api.ipynb +++ b/docs/source/jupyter/cuds_api.ipynb @@ -614,4 +614,4 @@ "metadata": {}, "nbformat": 4, "nbformat_minor": 4 -} \ No newline at end of file +} diff --git a/docs/source/jupyter/multiple_wrappers.ipynb b/docs/source/jupyter/multiple_wrappers.ipynb index 40ae201..5cbb576 100644 --- a/docs/source/jupyter/multiple_wrappers.ipynb +++ b/docs/source/jupyter/multiple_wrappers.ipynb @@ -356,4 +356,4 @@ "metadata": {}, "nbformat": 4, "nbformat_minor": 2 -} \ No newline at end of file +} diff --git a/docs/source/jupyter/ontology_interface.ipynb b/docs/source/jupyter/ontology_interface.ipynb index f691158..456b0f4 100644 --- a/docs/source/jupyter/ontology_interface.ipynb +++ b/docs/source/jupyter/ontology_interface.ipynb @@ -946,4 +946,4 @@ }, "nbformat": 4, "nbformat_minor": 4 -} \ No newline at end of file +} diff --git a/docs/source/jupyter/quantum_espresso.ipynb b/docs/source/jupyter/quantum_espresso.ipynb index 52b3269..9e522a2 100644 --- a/docs/source/jupyter/quantum_espresso.ipynb +++ b/docs/source/jupyter/quantum_espresso.ipynb @@ -444,4 +444,4 @@ "metadata": {}, "nbformat": 4, "nbformat_minor": 2 -} \ No newline at end of file +} diff --git a/docs/source/jupyter/sessions_and_vars.ipynb b/docs/source/jupyter/sessions_and_vars.ipynb index ce4ee97..f7dbc4c 100644 --- a/docs/source/jupyter/sessions_and_vars.ipynb +++ b/docs/source/jupyter/sessions_and_vars.ipynb @@ -189,4 +189,4 @@ "metadata": {}, "nbformat": 4, "nbformat_minor": 2 -} \ No newline at end of file +} diff --git a/docs/source/jupyter/simlammps.ipynb b/docs/source/jupyter/simlammps.ipynb index 70441b8..053c656 100644 --- a/docs/source/jupyter/simlammps.ipynb +++ b/docs/source/jupyter/simlammps.ipynb @@ -299,4 +299,4 @@ "metadata": {}, "nbformat": 4, "nbformat_minor": 2 -} \ No newline at end of file +} diff --git a/docs/source/jupyter/wrapper_development.ipynb b/docs/source/jupyter/wrapper_development.ipynb index e9fc51a..e1c5a60 100644 --- a/docs/source/jupyter/wrapper_development.ipynb +++ b/docs/source/jupyter/wrapper_development.ipynb @@ -413,4 +413,4 @@ "metadata": {}, "nbformat": 4, "nbformat_minor": 2 -} \ No newline at end of file +} diff --git a/docs/source/license.md b/docs/source/license.md index 466549e..6ecbf5d 100644 --- a/docs/source/license.md +++ b/docs/source/license.md @@ -1,4 +1,5 @@ # License + Copyright © 2021 Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. acting on behalf of its Fraunhofer IWM. Contact: Pablo de Andrés, José Manuel Domínguez, Yoav Nahshon. BSD 3-Clause License diff --git a/docs/source/links.md b/docs/source/links.md index 3b11541..0fa64a6 100644 --- a/docs/source/links.md +++ b/docs/source/links.md @@ -1,7 +1,9 @@ # Related links + Here are links to other projects relevant for this documentation. SimPhoNy: + - [GitLab's SimPhoNy group](https://gitlab.cc-asp.fraunhofer.de/simphony) - [GitHub's SimPhoNy group](https://github.com/simphony) - [OSP-core](https://github.com/simphony/osp-core) @@ -9,11 +11,13 @@ SimPhoNy: - [wrapper development](https://github.com/simphony/wrapper-development) Technologies used: + - [Docker](https://www.docker.com/), used for the CI and engines - [Sphinx](https://www.sphinx-doc.org/), used for the documentation - [PlantUML](https://plantuml.com/), used for the diagrams # Acknowledgements + SimPhoNy OSP-core and wrappers development is supported by the following Grants: ```{eval-rst} @@ -33,19 +37,20 @@ OntoTRANS Horizon 2020 H2020-NMBP-TO-IND-2019 862136 ============= ============ =============================== ================== ``` -Some of the explanations and background provided have been adapted from Pablo de Andres' +Some of the explanations and background provided have been adapted from Pablo de Andres' master thesis on "Natural Language Search on an ontology-based data structure". -The OSP-core Python package originates from the European Project -[SimPhoNy](https://www.simphony-project.eu/) (Project Nr. 604005). -We would like to acknowledge and thank our project partners, especially -[Enthought, Inc](https://www.enthought.com/), -[Centre Internacional de Mètodes Numèrics a l'Enginyeria (CIMNE)](https://cimne.com/) -and the [University of Jyväskylä](https://www.jyu.fi/en), for their important -contributions to some of the core concepts of OSP-core, which were originally +The OSP-core Python package originates from the European Project +[SimPhoNy](https://www.simphony-project.eu/) (Project Nr. 604005). +We would like to acknowledge and thank our project partners, especially +[Enthought, Inc](https://www.enthought.com/), +[Centre Internacional de Mètodes Numèrics a l'Enginyeria (CIMNE)](https://cimne.com/) +and the [University of Jyväskylä](https://www.jyu.fi/en), for their important +contributions to some of the core concepts of OSP-core, which were originally demonstrated under the project https://github.com/simphony/simphony-common. # Compatibility table + The following table describes the compatibilities between of SimPhoNy docs and OSP-core. ```{eval-rst} @@ -55,11 +60,11 @@ The following table describes the compatibilities between of SimPhoNy docs and O :widths: auto ============= ========== - SimPhoNy docs OSP-core + SimPhoNy docs OSP-core ============= ========== - 2.5.1 3.8.0 - 2.5.0 3.8.0 - 2.4.5 3.7.0 + 2.5.1 3.8.0 + 2.5.0 3.8.0 + 2.4.5 3.7.0 2.4.4 3.5.8-beta 2.4.3 3.5.5-beta 2.4.2 3.5.4-beta diff --git a/docs/source/ontologies_included.md b/docs/source/ontologies_included.md index 4961328..5b40f58 100644 --- a/docs/source/ontologies_included.md +++ b/docs/source/ontologies_included.md @@ -1,21 +1,21 @@ # Included ontologies As described on the [working with ontologies](../working_with_ontologies.md) -section, to use an ontology you first have to install it, and to do so +section, to use an ontology you first have to install it, and to do so usually you have either to define a `yml` -[configuration file](working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies) -(for OWL ontologies and RDFS vocabularies) or provide the ontology in the -[OSP-core YAML ontology format](working_with_ontologies.md#osp-core-yaml-ontology-format). +[configuration file](working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies) +(for OWL ontologies and RDFS vocabularies) or provide the ontology in the +[OSP-core YAML ontology format](working_with_ontologies.md#osp-core-yaml-ontology-format). -However, in order to make using ontologies easier, we bundle a few of these -files with OSP-core to enable rapid installation of common, -well-known ontologies. Do not hesitate to [contact us](contact.md) if you want +However, in order to make using ontologies easier, we bundle a few of these +files with OSP-core to enable rapid installation of common, +well-known ontologies. Do not hesitate to [contact us](contact.md) if you want your ontology to be shipped with SimPhoNy. -The included ontologies, together with their domains of application, are +The included ontologies, together with their domains of application, are listed below. -- [Elementary Multiperspective Material Ontology (EMMO)](ontologies_included.html#elementary-multiperspective-material-ontology-emmo) +- [Elementary Multiperspective Material Ontology (EMMO)](ontologies_included.html#elementary-multiperspective-material-ontology-emmo) \- Applied sciences - [Dublin Core Metadata Initiative (DCMI)](ontologies_included.html#dublin-core-metadata-initiative-dcmi) \- Metadata description @@ -30,31 +30,31 @@ listed below. The ontologies can be installed providing the right _[package identifier](working_with_ontologies.md#keywords)_ to -[pico](utils.md#pico-installs-cuds-ontologies). You can find such -package identifier and additional information on each ontology by clicking on +[pico](utils.md#pico-installs-cuds-ontologies). You can find such +package identifier and additional information on each ontology by clicking on the links from the list above. -## Elementary Multiperspective Material Ontology (EMMO) +## Elementary Multiperspective Material Ontology (EMMO) ```{eval-rst} .. epigraph:: - EMMO is a multidisciplinary effort to develop a standard representational - framework (the ontology) for applied sciences. It is based on physics, - analytical philosophy and information and communication technologies. It - has been instigated by materials science to provide a framework for - knowledge capture that is consistent with scientific principles and - methodologies. It is released under a Creative Commons - `CC BY 4.0 `_ + EMMO is a multidisciplinary effort to develop a standard representational + framework (the ontology) for applied sciences. It is based on physics, + analytical philosophy and information and communication technologies. It + has been instigated by materials science to provide a framework for + knowledge capture that is consistent with scientific principles and + methodologies. It is released under a Creative Commons + `CC BY 4.0 `_ license. - -- `About EMMO section `_, - from the + -- `About EMMO section `_, + from the `official EMMO GitHub repository `_ ``` For a short introduction on this ontology, see the [fundamentals](fundamentals.md#emmo) -section. To install the [EMMO ontology](https://emmo-repo.github.io/), use +section. To install the [EMMO ontology](https://emmo-repo.github.io/), use ```sh pico install emmo @@ -78,32 +78,32 @@ and then just start creating cuds objects ```{eval-rst} .. epigraph:: - The Dublin Core™ Metadata Initiative, or "DCMI", is an organization - supporting innovation in metadata design and best practices across the - metadata ecology. DCMI works openly, and it supported by a + The Dublin Core™ Metadata Initiative, or "DCMI", is an organization + supporting innovation in metadata design and best practices across the + metadata ecology. DCMI works openly, and it supported by a `paid-membership model `_. -- `About DCMI `_ ``` -The Dublin Core™ Metadata Initiative has published, among others, the +The Dublin Core™ Metadata Initiative has published, among others, the [DCMI Metadata Terms](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/) -specification, which establishes a set of core metadata terms enabling +specification, which establishes a set of core metadata terms enabling cross-domain description of resources on the web. ```{eval-rst} .. epigraph:: - Included are the fifteen terms of the Dublin Core™ Metadata Element Set - (also known as "the Dublin Core") plus several dozen properties, classes, - datatypes, and vocabulary encoding schemes. [...] These terms are intended - to be used in combination with metadata terms from other, compatible + Included are the fifteen terms of the Dublin Core™ Metadata Element Set + (also known as "the Dublin Core") plus several dozen properties, classes, + datatypes, and vocabulary encoding schemes. [...] These terms are intended + to be used in combination with metadata terms from other, compatible vocabularies in the context of application profiles. -- `DCMI Metadata Terms `_ ``` -To install the `dcmitype` and `dcterms` RDFS vocabularies from the [Dublin +To install the `dcmitype` and `dcterms` RDFS vocabularies from the [Dublin Core Metadata Initiative (DCMI)](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/), use ```sh @@ -120,17 +120,17 @@ be detected. ```{eval-rst} .. epigraph:: - DCAT is an RDF vocabulary designed to facilitate interoperability + DCAT is an RDF vocabulary designed to facilitate interoperability between data catalogs published on the Web. [...] DCAT enables a publisher to describe datasets and data services in a catalog - using a standard model and vocabulary that facilitates the consumption and - aggregation of metadata from multiple catalogs. This can increase the + using a standard model and vocabulary that facilitates the consumption and + aggregation of metadata from multiple catalogs. This can increase the discoverability of datasets and data services. It also makes it possible to - have a decentralized approach to publishing data catalogs and makes - federated search for datasets across catalogs in multiple sites possible - using the same query mechanism and structure. Aggregated DCAT metadata + have a decentralized approach to publishing data catalogs and makes + federated search for datasets across catalogs in multiple sites possible + using the same query mechanism and structure. Aggregated DCAT metadata can serve as a manifest file as part of the digital preservation process. -- `Data Catalog Vocabulary (DCAT) - Version 2 `_ @@ -147,17 +147,17 @@ pico install dcat2 ```{eval-rst} .. epigraph:: - FOAF is a project devoted to linking people and information using the Web. - Regardless of whether information is in people's heads, in physical or - digital documents, or in the form of factual data, it can be linked. - FOAF integrates three kinds of network: social networks of human - collaboration, friendship and association; representational networks that - describe a simplified view of a cartoon universe in factual terms, and - information networks that use Web-based linking to share independently - published descriptions of this inter-connected world. FOAF does not - compete with socially-oriented Web sites; rather it provides an approach - in which different sites can tell different parts of the larger story, - and by which users can retain some control over their information in a + FOAF is a project devoted to linking people and information using the Web. + Regardless of whether information is in people's heads, in physical or + digital documents, or in the form of factual data, it can be linked. + FOAF integrates three kinds of network: social networks of human + collaboration, friendship and association; representational networks that + describe a simplified view of a cartoon universe in factual terms, and + information networks that use Web-based linking to share independently + published descriptions of this inter-connected world. FOAF does not + compete with socially-oriented Web sites; rather it provides an approach + in which different sites can tell different parts of the larger story, + and by which users can retain some control over their information in a non-proprietary format. -- `FOAF Vocabulary Specification `_ @@ -174,14 +174,14 @@ pico install foaf ```{eval-rst} .. epigraph:: - The PROV Ontology (PROV-O) expresses the PROV Data Model - [`PROV-DM `_] + The PROV Ontology (PROV-O) expresses the PROV Data Model + [`PROV-DM `_] using the OWL2 Web Ontology Language (OWL2) [`OWL2-OVERVIEW `_]. It provides a set of classes, properties, and restrictions that can be used - to represent and interchange provenance information generated in different - systems and under different contexts. It can also be specialized to create - new classes and properties to model provenance information for different + to represent and interchange provenance information generated in different + systems and under different contexts. It can also be specialized to create + new classes and properties to model provenance information for different applications and domains. -- `PROV-O: The PROV Ontology `_ @@ -195,10 +195,10 @@ pico install prov ## The City ontology -The City ontology is a -[simple, example ontology](ontology_intro.html#an-example-the-city-ontology) -included with OSP-core. It provides a collection of concepts to describe -people and buildings in a city, and is aimed at demonstrating the usage of +The City ontology is a +[simple, example ontology](ontology_intro.html#an-example-the-city-ontology) +included with OSP-core. It provides a collection of concepts to describe +people and buildings in a city, and is aimed at demonstrating the usage of SimPhoNy OSP-core. To install the @@ -207,4 +207,3 @@ To install the ```sh pico install city ``` - diff --git a/docs/source/ontology_intro.md b/docs/source/ontology_intro.md index d7f0765..dd3f494 100644 --- a/docs/source/ontology_intro.md +++ b/docs/source/ontology_intro.md @@ -10,11 +10,11 @@ the representational primitives include information about their meaning and constraints on their logically consistent application. (Source: ) -[//]: # (TODO Extend) +[//]: # "TODO Extend" ## An example: the City ontology -OSP-core ships with one simple example ontology, called `city`. +OSP-core ships with one simple example ontology, called `city`. You can use it to play around and get familiar with OSP-core. We will also use it a lot in this documentation as an example. diff --git a/docs/source/overview.md b/docs/source/overview.md index 5dca740..e6e6b6d 100644 --- a/docs/source/overview.md +++ b/docs/source/overview.md @@ -2,16 +2,13 @@ SimPhoNy is an ontology-based framework aimed at enabling interoperability between different simulation and data management tools, with a focus on materials science. - - ## What can SimPhoNy be used for? ### Manipulate ontology-based linked data, a format well suited for [FAIR data principles](https://en.wikipedia.org/wiki/FAIR_data) - [Linked data](https://en.wikipedia.org/wiki/Linked_data) is a format for structured data that facilitates the interoperability among different data sources. In particular, the data is structured as a directed graph, consistent of nodes and labeled arcs. With SimPhoNy, you can not only manipulate this linked data, **but also transform existing non-linked data into linked data**. -To better understand the idea of linked data, take a quick glance at the toy example below. It shows data about a city from three different data sources: the city's traffic authority, a map from a city guide, and the university registry. As some of the concepts are present in multiple datasets, the linked data representation naturally joins all of them into a single one. +To better understand the idea of linked data, take a quick glance at the toy example below. It shows data about a city from three different data sources: the city's traffic authority, a map from a city guide, and the university registry. As some of the concepts are present in multiple datasets, the linked data representation naturally joins all of them into a single one.
@@ -25,7 +22,7 @@ _Linked data about a city from three different sources: the city's traffic autho
-Although the example above shows just plain linked data, in SimPhoNy, the linked data is enhanced with [ontologies](https://en.wikipedia.org/wiki/Ontology_(information_science)), which give **meaning** to the data. Specifically, SimPhoNy works with ontologies based on the [Web Ontology Language](https://en.wikipedia.org/wiki/Web_Ontology_Language), making the data compatible with the [Semantic Web](https://en.wikipedia.org/wiki/Semantic_Web). +Although the example above shows just plain linked data, in SimPhoNy, the linked data is enhanced with [ontologies](), which give **meaning** to the data. Specifically, SimPhoNy works with ontologies based on the [Web Ontology Language](https://en.wikipedia.org/wiki/Web_Ontology_Language), making the data compatible with the [Semantic Web](https://en.wikipedia.org/wiki/Semantic_Web). ### Fetch data from a database, run a simulation and immediately store the results @@ -59,7 +56,7 @@ At this point, the results could be fetched again and for example, visualized wi ### Couple simulation engines easily -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. +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, such as a multi-scale simulation. @@ -83,8 +80,8 @@ In order achieve that, it would be necessary to translate the input and output f
-_Coupling of two simulation engines, one that handles fluid dynamics -(macroscopic behavior) and another that takes care of molecular dynamics +_Coupling of two simulation engines, one that handles fluid dynamics +(macroscopic behavior) and another that takes care of molecular dynamics (microscopic behavior)._
@@ -92,14 +89,16 @@ _Coupling of two simulation engines, one that handles fluid dynamics # Terminology -The name ‘SimPhoNy’ stems from the SimPhoNy EU-project in which it was originally developed (see more details [here](https://www.simphony-project.eu/)). + +The name ‘SimPhoNy’ stems from the SimPhoNy EU-project in which it was originally developed (see more details [here](https://www.simphony-project.eu/)). Here are some additional terms that are used throughout the documentation: + 1. `API`: Application Programming Interface. A set of functions that allow the interaction with an application or system. -1. `OSP`: Open Simulation Platform. +1. `OSP`: Open Simulation Platform. A set of common standards and related tools that form the basic environment on top of which compatible and compliant simulation workflows can be developed and run. An OSP does not contain any simulation tools itself, it is the common framework enabling to couple and link them. -1. `backend`: a third party application or service. +1. `backend`: a third party application or service. Simulation engines and databases are examples of backends. 1. `wrapper`: a plugin for OSP-core that adds support to a new backend. It must allow the user to interact with the backend through the same API as OSP-core. @@ -109,10 +108,10 @@ Here are some additional terms that are used throughout the documentation: 1. `attribute`: a property of a class that has a data type. E.g., 'name' of the type String which could be used as an attribute of 'City'. 1. `individual`: an instance of a class. E.g., an instance of the class 'City' can be used to represent the city of Freiburg in which case it would have the attribute 'name' with the value 'Freiburg'. 1. `relationship`: a type of a way in which one individual relates to another. E.g., 'Has-A' which could use to form the relationship 'Freiburg (City) Has-A Dreisam (River)'. - 1. `entity`: a general term that can refer to a class, a relationship, attribute, or an individual. E.g., 'City', 'name', 'Has-A', the Freiburg individual are all entities. + 1. `entity`: a general term that can refer to a class, a relationship, attribute, or an individual. E.g., 'City', 'name', 'Has-A', the Freiburg individual are all entities. 1. `namespace`: an ontology identifier. E.g., 'city_ontology' which could be used as a namespace for the ontology that consists of the entities 'City', 'name' and 'Has-A'. - - Each entity is uniquely identified by its name and the namespace it is contained in. We call \.\ the `qualified entity name`. -1. `CUDS`: Common Universal Data Structure. A data structure that is used to uniformly represent ontology concepts in programming code. + - Each entity is uniquely identified by its name and the namespace it is contained in. We call \.\ the `qualified entity name`. +1. `CUDS`: Common Universal Data Structure. A data structure that is used to uniformly represent ontology concepts in programming code. - CUDS exposes an API that provides CRUD (Create, Read, Update and Delete) functionalities. - CUDS is a recursive data structure in that a CUDS object may contain other CUDS objects. - CUDS is the fundamental data type of OSP-core, a framework that establishes interoperability between software systems that are built on top of ontologies. diff --git a/docs/source/utils.md b/docs/source/utils.md index f12ff62..d64fb82 100644 --- a/docs/source/utils.md +++ b/docs/source/utils.md @@ -1,12 +1,15 @@ # Utilities + In this section we will compile a list of useful utility functions, tools and examples of their usage. These functions are part of OSP-core and are used as an extension of the [main API](./detailed_design.md#cuds-api). ## pico (Pico Installs Cuds Ontologies) + Our tool for installing ontologies is called `pico`. It is a recursive acronym that stands for _Pico Installs Cuds Ontologies_. There are 3 main operations that can be done with pico: + - Install ontologies. - List the installed ontologies. - Remove installed ontologies. @@ -20,17 +23,21 @@ There are different possible logging levels available, and they can be set via `--log-level `. The default value is `INFO`. #### pico installs -_Usage:_ + +_Usage:_ + - `pico install ` - `pico install ...` -- `pico install city foaf emmo dcat2` (the installation of these specific +- `pico install city foaf emmo dcat2` (the installation of these specific well-known ontologies is available via this shortcut) -_Behaviour:_ +_Behaviour:_ + - The ontology file is parsed, and the entities mapped to Python objects. - The Python objects can be imported via their namespace `from osp.core.namespaces import namespace`. _Example:_ + ```console (venv) user@PC:~$ pico install city INFO [osp.core.ontology.installation]: Will install the following namespaces: ['city'] @@ -41,14 +48,17 @@ INFO [osp.core.ontology.installation]: Installation successful ``` #### pico lists + _Usage:_ `pico list` -_Behaviour:_ +_Behaviour:_ + - The installed namespaces and packages are printed out. A package can be -uninstalled and can contain many namespaces. A namespace can be imported + uninstalled and can contain many namespaces. A namespace can be imported within the Python shell. _Example:_ + ```console Packages: - qe @@ -65,15 +75,19 @@ Namespaces: ``` #### pico uninstalls -_Usage:_ + +_Usage:_ + - `pico uninstall ` - `pico uninstall all` -_Behaviour:_ +_Behaviour:_ + - The specified packages are uninstalled. - All packages except the uninstalled ones are re-installed. _Example:_ + ```console (venv) user@PC:~$ pico uninstall city INFO [osp.core.ontology.installation]: Will install the following namespaces: ['qe'] @@ -84,6 +98,7 @@ INFO [osp.core.ontology.installation]: Uninstallation successful ``` #### Conflicts with other "pico" installations + Some Operating Systems might have a pre-existing tool called _pico_. In most cases, the previous commands should work, but if any problem arises, you can use the following alternative: @@ -93,39 +108,40 @@ python -m osp.core.pico ``` For example: + ```shell python -m osp.core.pico install city ``` ### Using pico as a Python module -`pico` can also be used within the Python shell. In particular, four +`pico` can also be used within the Python shell. In particular, four functions are available to be imported from the `osp.core.pico` module, ```python from osp.core.pico import install, namespaces, packages, uninstall ``` -that cover the three main operations that pico is meant to perform: installing -ontologies (`install`), uninstalling ontologies (`uninstall`), and listing the +that cover the three main operations that pico is meant to perform: installing +ontologies (`install`), uninstalling ontologies (`uninstall`), and listing the installed ontologies (`packages`, `namespaces`). Each function is used in a similar way to its command-line counterpart. - `install`: accepts _one or more_ positional arguments of string -type, which can be either paths to `yml` ontology installation files or -names of ontologies that can be installed via this shortcut. It is meant to -clone the -[behavior of its command-line counterpart](https://simphony.readthedocs.io/en/latest/utils.html#pico-installs). + type, which can be either paths to `yml` ontology installation files or + names of ontologies that can be installed via this shortcut. It is meant to + clone the + [behavior of its command-line counterpart](https://simphony.readthedocs.io/en/latest/utils.html#pico-installs). -- `uninstall`: accepts _one or more_ positional arguments of string type, - which must be names of already installed ontology packages. It also +- `uninstall`: accepts _one or more_ positional arguments of string type, + which must be names of already installed ontology packages. It also clones the [behavior of its command-line counterpart](https://simphony.readthedocs.io/en/latest/utils.html#pico-uninstalls). -- `packages`: accepts no arguments and returns an [iterator](https://wiki.python.org/moin/Iterator) - over the names of the installed packages. +- `packages`: accepts no arguments and returns an [iterator](https://wiki.python.org/moin/Iterator) + over the names of the installed packages. -- `namespaces`: accepts no arguments and returns an iterator yielding one +- `namespaces`: accepts no arguments and returns an iterator yielding one [`OntologyNamespace` object](https://simphony.readthedocs.io/en/latest/api_ref.html#osp.core.ontology.namespace.OntologyNamespace) for each installed namespace. Usage examples: @@ -137,27 +153,30 @@ Usage examples: ### Ontology installation folder -The installed ontologies are stored in the directory `~/.osp-ontologies` by -default. On Windows, `~` usually refers to the path +The installed ontologies are stored in the directory `~/.osp-ontologies` by +default. On Windows, `~` usually refers to the path `C:\Users\`. The installation directory can be changed by setting the -environment variable `OSP_ONTOLOGIES_DIR`. Such action would move it to +environment variable `OSP_ONTOLOGIES_DIR`. Such action would move it to `$OSP_ONTOLOGIES_DIR/.osp-ontologies`. ## Tips and tricks + The following are some utility functions and shortcuts for working with cuds. For those that are present in the util package, the import is `from osp.core import utils`. + - `utils.get_relationships_between(a, b)` returns a set with the relationships that connect `a` and `b` . - `a.get_attributes()` returns a dictionary with the name and the value of the attributes of `a`. - `a.is_a(oclass)` is True if the instance `a` is or inherits from `oclass`. - `osp.core.get_entity("namespace.entity")` returns the class associated with an `entity` in a -`namespace`. It can be used to instantiate objects. + `namespace`. It can be used to instantiate objects. - `[attr.argname for attr in oclass.attributes.keys()]` returns a list with the attributes of an `oclass`. - `[attr.namespace for attr in oclass.attributes.keys()]` returns a list with the namespace of the attributes of an `oclass`. ## Visualisation -There are two ways of visualising information about a Cuds structure, + +There are two ways of visualising information about a Cuds structure, one as a text output to the standard output ([pretty print](#pretty-print)), and another one as a [dot](https://www.graphviz.org/pdf/dotguide.pdf) graph ([cuds2dot](#cuds2dot)). @@ -168,17 +187,19 @@ Another useful dot graph visualisation tool called [ontology2dot](#ontology2dot) ``` ### Pretty print + _Location:_ `from osp.core.utils import pretty_print`. _Usage:_ `pretty_print(cuds_object)` -_Behaviour:_ +_Behaviour:_ - The UUID, oclass and attributes of the given object are printed. - All the related objects are also printed in a recursive fashion. - The relationship to the contained objects is stated. _Example:_ + ```py >>> pretty_print(emmo_town) Cuds object named : @@ -186,7 +207,7 @@ Cuds object named : type: city.City superclasses: city.City, city.PopulatedPlace, city.GeographicalPlace, cuba.Entity values: coordinates: [42 42] - description: + description: To Be Determined |_Relationship city.hasInhabitant: @@ -224,49 +245,59 @@ Cuds object named : coordinates: [0 0] ``` + ### Cuds2Dot _Location:_ `from osp.core.utils import Cuds2dot`. _Usage:_ `Cuds2dot(cuds_object).render()` -_Behaviour:_ +_Behaviour:_ + - Each entity is represented by a node. - The relationships are the edges connecting them. - The attributes, uuid and oclass are written inside the nodes. _Example:_ + ```py >>> Cuds2dot(emmo_town).render() ``` + ![](./_static/img/cuds2dot.png "cuds2dot sample image") ### Ontology2Dot + _Location:_ console entry point `osp.core.tools.ontology2dot`. _Usage:_ `ontology2dot` -_Behaviour:_ +_Behaviour:_ + - Each ontology entity is represented by a box. - Attributes and their default values are stated. -- Inheritance of entities is shown via *is_a*. +- Inheritance of entities is shown via _is_a_. - The inverse of each relationship is also represented. _Example:_ + ```sh ontology2dot osp/core/ontology/yml/ontology.city.yml ``` -![](./_static/img/ontology2dot.png "ontology2dot sample image") +![](./_static/img/ontology2dot.png "ontology2dot sample image") ## Search + To make searching (in-depth) for a particular cuds object easier, - we have implemented some simple search utility functions. +we have implemented some simple search utility functions. ### Simple search + _Location:_ `import osp.core.utils.simple_search` -_Usage:_ +_Usage:_ + - `find_cuds_object(criterion, root, rel, find_all, max_depth=float("inf"), current_depth=0, visited=None)` finds a cuds object under `root`, related via `rel` that returns `True` for `criterion` (boolean function). If `find_all` is set to `True`, it will return all elements, and not only the first found. @@ -316,6 +347,7 @@ _Examples:_ root=city_cuds, rel=city.hasInhabitant) ``` + ## Serialization JSON schema of CUDS objects When you serialize a CUDS object using the @@ -325,7 +357,7 @@ The method will traverse the hierarchical datastructure using Depth First Traversal. Therefore, its result is a json array composed of several flat CUDS objects. -This array can later be deserialized using the opposite +This array can later be deserialized using the opposite [`deserialize`](api_ref.html#osp.core.utils.general.deserialize). The serialization is done via [JSON-LD](https://json-ld.org/), diff --git a/docs/source/working_with_ontologies.md b/docs/source/working_with_ontologies.md index c6a98d9..cb5a417 100644 --- a/docs/source/working_with_ontologies.md +++ b/docs/source/working_with_ontologies.md @@ -1,13 +1,14 @@ # How to work with ontologies OSP-core supports ontologies in the following formats: + - [OWL ontologies](working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies) - [RDFS vocabularies](working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies) (_[limited support](#rdfs-vocabularies)_) - [OSP-core YAML ontology format](working_with_ontologies.md#osp-core-yaml-ontology-format) ## OWL ontologies and RDFS vocabularies -To install OWL ontologies or RDFS vocabularies in OSP-core, you have to +To install OWL ontologies or RDFS vocabularies in OSP-core, you have to create a configuration yaml file similar to the following one: ```yaml @@ -16,25 +17,25 @@ ontology_file: https://raw.githubusercontent.com/emmo-repo/EMMO/master/emmo-infe format: turtle reference_by_label: True namespaces: - mereotopology: http://emmo.info/emmo/top/mereotopology - physical: http://emmo.info/emmo/top/physical - top: http://emmo.info/emmo/top - semiotics: http://emmo.info/emmo/top/semiotics - perceptual: http://emmo.info/emmo/middle/perceptual - reductionistic: http://emmo.info/emmo/middle/reductionistic - holistic: http://emmo.info/emmo/middle/holistic - physicalistic: http://emmo.info/emmo/middle/physicalistic - math: http://emmo.info/emmo/middle/math - properties: http://emmo.info/emmo/middle/properties - materials: http://emmo.info/emmo/middle/materials - metrology: http://emmo.info/emmo/middle/metrology - models: http://emmo.info/emmo/middle/models - manufacturing: http://emmo.info/emmo/middle/manufacturing - isq: http://emmo.info/emmo/middle/isq - siunits: http://emmo.info/emmo/middle/siunits + mereotopology: http://emmo.info/emmo/top/mereotopology + physical: http://emmo.info/emmo/top/physical + top: http://emmo.info/emmo/top + semiotics: http://emmo.info/emmo/top/semiotics + perceptual: http://emmo.info/emmo/middle/perceptual + reductionistic: http://emmo.info/emmo/middle/reductionistic + holistic: http://emmo.info/emmo/middle/holistic + physicalistic: http://emmo.info/emmo/middle/physicalistic + math: http://emmo.info/emmo/middle/math + properties: http://emmo.info/emmo/middle/properties + materials: http://emmo.info/emmo/middle/materials + metrology: http://emmo.info/emmo/middle/metrology + models: http://emmo.info/emmo/middle/models + manufacturing: http://emmo.info/emmo/middle/manufacturing + isq: http://emmo.info/emmo/middle/isq + siunits: http://emmo.info/emmo/middle/siunits active_relationships: - - http://emmo.info/emmo/top/mereotopology#EMMO_8c898653_1118_4682_9bbf_6cc334d16a99 - - http://emmo.info/emmo/top/semiotics#EMMO_60577dea_9019_4537_ac41_80b0fb563d41 + - http://emmo.info/emmo/top/mereotopology#EMMO_8c898653_1118_4682_9bbf_6cc334d16a99 + - http://emmo.info/emmo/top/semiotics#EMMO_60577dea_9019_4537_ac41_80b0fb563d41 default_relationship: http://emmo.info/emmo/top/mereotopology#EMMO_17e27c22_37e1_468c_9dd7_95e137f73e7f ``` @@ -48,15 +49,15 @@ that contains multiple namespaces. Will be used for uninstallation: `pico uninst have executed a reasoner on your ontology, e.g. by using the `Export inferred axioms` functionality of [Protégé](https://protege.stanford.edu/). -**format** (optional): File format of the ontology file to be parsed. We +**format** (optional): 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`, `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`). -When not provided, it will be guessed from the file extension. However, such +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`). +When not provided, it will be guessed from the file extension. However, such guess may not always be correct. **reference_by_label** (default False): Whether the label should be used or the IRI suffix to reference @@ -87,12 +88,12 @@ pico install ### Limitations -At the moment, there are a few limitations on the supported features of OWL +At the moment, there are a few limitations on the supported features of OWL ontologies and RDFS vocabularies. #### OWL ontologies -Not all predicates of OWL ontologies are taken into +Not all predicates of OWL ontologies are taken into consideration. Among the used ones are: - `RDF.type` to determine the type of the entities. @@ -110,7 +111,7 @@ consideration. Among the used ones are: - The `RDFS.domain` of the `DatatypeProperties`, if it is a simple class. - Restrictions on the ontology classes. - Furthermore, all DataProperties are considered functional, see [this issue](https://github.com/simphony/osp-core/issues/416). -- Restrictions and compositions are also supported. They can be consulted +- Restrictions and compositions are also supported. They can be consulted using the [`axioms` attribute of ontology classes](jupyter/ontology_interface.html#Operations-specific-to-ontology-axioms). No reasoner is included. We plan to include a reasoner in the @@ -121,9 +122,9 @@ OWL DL standard. #### RDFS vocabularies -With respect to RDFS vocabularies, the `RDFS.Class` predicate is supported, -but the `RDFS.Property` predicate is not. This means that the main -limitation when using RDFS vocabularies is that only their classes are +With respect to RDFS vocabularies, the `RDFS.Class` predicate is supported, +but the `RDFS.Property` predicate is not. This means that the main +limitation when using RDFS vocabularies is that only their classes are detected, but their properties are ignored. ## OSP-core YAML ontology format @@ -167,8 +168,8 @@ pico install `namespace`: string > Defines the namespace of the current file. We recommend to use - all_lowercase for the namespace name, with underscore as separation. - All entities defined in this file will live in the namespace defined here. +> all_lowercase for the namespace name, with underscore as separation. +> All entities defined in this file will live in the namespace defined here. `requirements`: List[string] @@ -196,11 +197,12 @@ pico install Every declaration of an ontology entity must have the following keys: `description`: string + > For human consumption. An ontological short description of the carried -> semantics. Should have the form: entity is a superclass\_entity that +> semantics. Should have the form: entity is a superclass_entity that > has \ terms. > -`subclass_of`: List[**\`\`qualified entity name\`\`**]. +> `subclass_of`: List[**\`\`qualified entity name\`\`**]. > Its value is fixed on the ontology level. > > The subclass keyword expresses an **ontological is-a** @@ -225,24 +227,31 @@ The CUBA namespace contains a set of Common Universal Basic entities, that have The CUBA namespace is always installed in OSP-core. `cuba.Entity` + > The root for all ontology classes. Does not have a superclass. `cuba.Nothing` + > An ontology class, that is not allowed to have individuals. `cuba.relationship` + > The root of all relationships. Does not have a superclass. `cuba.attribute` + > The root of all attributes. Does not have a superclass. `cuba.Wrapper` + > The root of all wrappers. These are the bridge to simulation engines and databases. See the examples in examples/. `cuba.activeRelationship` + > The root of all active relationships. Active relationships express that one cuds object is in the container of another. `cuba.passiveRelationship` + > The inverse of `cuba.activeRelationship`. ### Attribute format @@ -274,7 +283,7 @@ It can additionally have the following keys: > The dimensions are always fixed. > > For example, a VECTOR:INT:4:2:1 would be: \ -> { [(a), (b)], [(c), (d)], [(e), (f)], [(g), (h)] } \ +> { [(a), (b)], [(c), (d)], [(e), (f)], [(g), (h)] } \ > where all elements (a, b, ...) are integers. > (the different delimiters are only used for visual purposes). > If no datatype is specified, it would be a `FLOAT` vector. @@ -285,7 +294,7 @@ It can additionally have the following keys: > For example: The datatype of entity numberOfOccurrences is INT. > ```{note} -> The implementation of the vectors is experimental and will be updated as soon as +> The implementation of the vectors is experimental and will be updated as soon as > EMMO has established an appropriate wait of representing them > ``` @@ -311,13 +320,15 @@ They can be either: It is a mapping from the **\`\`qualified entity name\`\`** of a relationship to the following keywords: `range` + > A class expression describing the individuals which are object of the relationship. `cardinality` + > The number of times individuals defined in `range` is allowed to be a object of the relationship. > To define the `cardinality` we use the following syntax: > - > - many / * / 0+ (default): Zero to infinity target objects are allowed. + > - many / \* / 0+ (default): Zero to infinity target objects are allowed. > - some / \+ / 1+: At least one target object is required. > - ? / 0-1: At most one target object is allowed. > - a+: At least a target objects are required. @@ -325,7 +336,9 @@ They can be either: > - a: Exactly a target objects are required. `exclusive` + > Whether the given `target` is the only allowed object. + - A composition of several class expressions. For example: ```yaml @@ -336,7 +349,7 @@ They can be either: This is the union of all individuals that are a city or a neighbourhood. We use the keyword `or` for union, `and` for intersection and `not` for complement. - After `or` and `and`, a list of class expressions for the union / intersection is expected. + After `or` and `and`, a list of class expressions for the union / intersection is expected. After `not` a single class expression is expected. The definition of class expressions is recursive. For example: @@ -359,6 +372,7 @@ It must have the keys described in [Ontology entities format](#ontology-entities It can contain further information: `attributes`: Dict[**\`\`qualified entity name\`\`**, default_value] + > Expects a mapping from the **\`\`qualified entity name\`\`** of an attribute to its default. > Each key must correspond to a subclass of `attribute`. For example: > @@ -375,38 +389,41 @@ It can contain further information: > If no default is given, the user is forced to specify a value each time he creates an individual. `subclass_of`: List[Class expression] + > In addition to qualified entity names of classes, class expressions are also allowed. > These class expressions restrict the individuals allowed in the class. Only those > individuals are allowed that are in the intersection of the class expressions. For example: > > ```yaml > PopulatedPlace: -> description: -> subclass_of: -> - city.GeographicalPlace -> - city.hasInhabitant: -> range: city.Citizen -> cardinality: many -> exclusive: true +> description: +> subclass_of: +> - city.GeographicalPlace +> - city.hasInhabitant: +> range: city.Citizen +> cardinality: many +> exclusive: true > ``` > > Here, a populated place is a geographical place which must have citizens as inhabitants. `disjoint_with`: List[Class expression] + > A list of class expressions that are not allowed to share any individuals with the cuds entity. `equivalent_to`: List[Class expression] + > A list of class expressions who contain the same individuals as the cuds entity. For example: > > ```yaml > PopulatedPlace: -> description: -> equivalent_to: -> - city.GeographicalPlace -> - city.hasInhabitant: -> range: city.Citizen -> cardinality: many -> exclusive: true +> description: +> equivalent_to: +> - city.GeographicalPlace +> - city.hasInhabitant: +> range: city.Citizen +> cardinality: many +> exclusive: true > ``` > > Here every geographical place that has citizens as inhabitants is automatically a populated place. @@ -419,6 +436,7 @@ It must have the keys described in [Ontology entities format](#ontology-entities Furthermore, it can contain the following information: `inverse`: **\`\`qualified entity name\`\`** or empty (None) + > If CUDS object A is related to CUDS object B via relationship `rel`, then B is related > with A via the inverse of `rel`. > @@ -427,14 +445,17 @@ Furthermore, it can contain the following information: > If no inverse is given, OSP-core will automatically create one. `domain`: Class expression + > A class expression describing the individuals that are allowed to be a subject of the relationship. > If multiple class expressions are given, the relationship's domain is the intersection of the class expressions. `range`: Class expression + > A class expression describing the individuals that are allowed to be object of the relationship. > If multiple class expressions are given, the relationship's range is the intersection of the class expression. `characteristics`: String + > A list of characteristics of the relationship. The following characteristics are supported: > > - reflexive diff --git a/docs/source/wrapper_development.md b/docs/source/wrapper_development.md index 4d880e6..a6e9243 100644 --- a/docs/source/wrapper_development.md +++ b/docs/source/wrapper_development.md @@ -1,9 +1,12 @@ # Wrapper development + For an skeleton structure of a wrapper, you can visit the [wrapper development repo](https://github.com/simphony/wrapper-development). For a tutorial on creating a simple wrapper, there is a [jupyter notebook](jupyter/wrapper_development.md) available. + ## Ontology + The end goal is to build one, unique and standard ontology with all the relevant entities and relationships. -This ontology could use modules where the entities regarding a certain domain are present. +This ontology could use modules where the entities regarding a certain domain are present. However, for the development of a wrapper, it is usually more practical to create a minimal temporary ontology with the entities required by a wrapper. Once the development is in a more stable stage, the development and merge @@ -21,92 +24,93 @@ These are the requirements for a minimal wrapper ontology:
Dummy ontology sample - ```yaml - --- - version: "M.m" +```yaml +--- +version: "M.m" - author: Parmenides +author: Parmenides - namespace: some_new_wrapper_ontology +namespace: some_new_wrapper_ontology - ontology: - - aRelationship: - description: "default relationship" - subclass_of: +ontology: + aRelationship: + description: "default relationship" + subclass_of: - cuba.activeRelationship - inverse: some_new_wrapper_ontology.pihsnoitalerA - default_rel: true + inverse: some_new_wrapper_ontology.pihsnoitalerA + default_rel: true - pihsnoitalerA: - description: "inverse of the default relationship" - subclass_of: - - cuba.passiveRelationship - inverse: some_new_wrapper_ontology.aRelationship + pihsnoitalerA: + description: "inverse of the default relationship" + subclass_of: + - cuba.passiveRelationship + inverse: some_new_wrapper_ontology.aRelationship ################ - SomeNewWrapper: - subclass_of: - - cuba.Wrapper + SomeNewWrapper: + subclass_of: + - cuba.Wrapper - value: - subclass_of: - - cuba.attribute + value: + subclass_of: + - cuba.attribute - SomeEntity: - subclass_of: - - cuba.Entity + SomeEntity: + subclass_of: + - cuba.Entity +``` - ```
## Coding + An advantage of the [3-layered-design](./getting_started.md#general-architecture) that we follow is the modularity and conceptual separation. The closer to the user, the higher the abstraction. This allows us to group and clearly define which components should and which ones should not be modified when creating a new wrapper. - - [Semantic layer](./detailed_design.md#semantic-layer): - Requires no work. - As presented in the previous section, only an entity representing the wrapper has to be present in the ontology. - - - [Interoperability layer](./detailed_design.md#interoperability-layer): - - [Session class](./detailed_design.md#session): - Represents the bulk of the work that a wrapper developer needs to do. - A new class inheriting from the appropriate Session Abstract Base Class must be coded. - It should at least implement all the inherited abstract methods. - - `__str__(self)`: String representation of the wrapper. - - `_apply_added(self, root_obj, buffer)`: Add all the elements in `buffer` to the engine. - - `_apply_updated(self, root_obj, buffer)`: Update all the elements in `buffer` in the engine. - - `_apply_deleted(self, root_obj, buffer)`: Remove all the elements in `buffer` from the engine. - - `_load_from_backend(self, uids, expired=None)`: Loads the given uids (and the dependant entities) - with the latest information from the backend. - Only loads the directly related information, not all the children recursively. - This method _must_ be implemented for a wrapper to work. - - Specific for a simulation: - - `_run(self, root_cuds_object)`: Call the run method on the simulation. - - Specific for a database: - - `_initialize(self)`: Initialise the database. - - `_load_first_level(self)`: Load the first level of children from the root from the database. - - `_init_transaction(self)`: Start the transaction. - - `_rollback_transaction(self)`: Rollback the transaction. - - `close(self)`: Close the connection. - - - [Syntactic layer](./detailed_design.md#syntactic-layer): - If none is available, one must be developed. - -To facilitate the creation of the session class on the interoperability layer, +- [Semantic layer](./detailed_design.md#semantic-layer): + Requires no work. + As presented in the previous section, only an entity representing the wrapper has to be present in the ontology. + +- [Interoperability layer](./detailed_design.md#interoperability-layer): + + - [Session class](./detailed_design.md#session): + Represents the bulk of the work that a wrapper developer needs to do. + A new class inheriting from the appropriate Session Abstract Base Class must be coded. + It should at least implement all the inherited abstract methods. + - `__str__(self)`: String representation of the wrapper. + - `_apply_added(self, root_obj, buffer)`: Add all the elements in `buffer` to the engine. + - `_apply_updated(self, root_obj, buffer)`: Update all the elements in `buffer` in the engine. + - `_apply_deleted(self, root_obj, buffer)`: Remove all the elements in `buffer` from the engine. + - `_load_from_backend(self, uids, expired=None)`: Loads the given uids (and the dependant entities) + with the latest information from the backend. + Only loads the directly related information, not all the children recursively. + This method _must_ be implemented for a wrapper to work. + - Specific for a simulation: + - `_run(self, root_cuds_object)`: Call the run method on the simulation. + - Specific for a database: + - `_initialize(self)`: Initialise the database. + - `_load_first_level(self)`: Load the first level of children from the root from the database. + - `_init_transaction(self)`: Start the transaction. + - `_rollback_transaction(self)`: Rollback the transaction. + - `close(self)`: Close the connection. + +- [Syntactic layer](./detailed_design.md#syntactic-layer): + If none is available, one must be developed. + +To facilitate the creation of the session class on the interoperability layer, there are several session abstract base classes that you can make your session -inherit from, which already include some additional generic functions common to a few +inherit from, which already include some additional generic functions common to a few typical applications: databases, triplestores and simulation engines. -On the diagram below, you may observe a simplified session inheritance scheme -for OSP-core. As a wrapper developer, you will most probably want to inherit -from one of following abstract classes: `WrapperSession`, `DbWrapperSession`, -`TripleStoreWrapperSession`, `SqlWrapperSession`, or `SimWrapperSession`. -Your new wrapper session would be located of the OSP-core box, -together among other wrapper sessions like the Simlammps, Sqlite or SqlAlchemy +On the diagram below, you may observe a simplified session inheritance scheme +for OSP-core. As a wrapper developer, you will most probably want to inherit +from one of following abstract classes: `WrapperSession`, `DbWrapperSession`, +`TripleStoreWrapperSession`, `SqlWrapperSession`, or `SimWrapperSession`. +Your new wrapper session would be located of the OSP-core box, +together among other wrapper sessions like the Simlammps, Sqlite or SqlAlchemy sessions. ```{uml} @@ -141,13 +145,13 @@ sessions. abstract class DbWrapperSession extends WrapperSession { commit() } - + abstract class TripleStoreWrapperSession extends DbWrapperSession { } abstract class SqlWrapperSession extends TripleStoreWrapperSession { } - + abstract class SimWrapperSession extends WrapperSession { run() } @@ -162,7 +166,7 @@ sessions. class SqlAlchemyWrapperSession implements SqlWrapperSession { } } - + rectangle "Your wrapper" as yourwrapper { class YourSession{ } @@ -196,6 +200,7 @@ sessions. ``` ## Engine installation + Most engines will require some sort of compilation or installation before being able to use them through Python. To facilitate the installation of the backend to the end users, a shell script with the necessary commands should be made available. @@ -204,77 +209,79 @@ It is also recommended to split the installation of the engine from the installa
Sample install_engine_requirements.sh - ```shell - #!/bin/bash - # - # Author: Ada Lovelace - # - # Description: This script install the requirements for some engine - # Used as part of the installation for SomeWrapper. - # - # Run Information: This script is called by install_engine.sh - - echo "Installing necessary requirements for the engine" - platform=$(python3 -mplatform) - - case $platform in - *"Ubuntu"*) - sudo apt-get update - sudo apt-get install cmake - ;; - *"centos"*) - sudo yum update - sudo yum install make -y - sudo yum install cmake -y - ;; - # Add other platforms here - esac - - ``` +```shell + #!/bin/bash + # + # Author: Ada Lovelace + # + # Description: This script install the requirements for some engine + # Used as part of the installation for SomeWrapper. + # + # Run Information: This script is called by install_engine.sh + + echo "Installing necessary requirements for the engine" + platform=$(python3 -mplatform) + + case $platform in + *"Ubuntu"*) + sudo apt-get update + sudo apt-get install cmake + ;; + *"centos"*) + sudo yum update + sudo yum install make -y + sudo yum install cmake -y + ;; + # Add other platforms here + esac + +``` +
Sample install_engine.sh - ```shell - #!/bin/bash - # - # Author: Ada Lovelace - # - # Description: This script installs SomeEngine and its Python binding - # Used as part of the installation for SomeWrapper. - # - # Run Information: This script is run manually. - - ################################### - ### Install engine requirements ### - ################################### - ./install_engine_requirements.sh - - ################################ - ### Download necessary files ### - ################################ - echo "Checking out a recent stable version" - git clone some-repo.com/some-engine.git - cd some-engine - - ############################ - ### Perform installation ### - ############################ - cmake cmake - make install - - ######################### - ### Test installation ### - ######################### - { - python3 -c 'from someEngine import engine; engine.test()' - } || { - echo "There was an error with the installation." - echo "Please, try again or contact the developer." - } +```shell + #!/bin/bash + # + # Author: Ada Lovelace + # + # Description: This script installs SomeEngine and its Python binding + # Used as part of the installation for SomeWrapper. + # + # Run Information: This script is run manually. + + ################################### + ### Install engine requirements ### + ################################### + ./install_engine_requirements.sh + + ################################ + ### Download necessary files ### + ################################ + echo "Checking out a recent stable version" + git clone some-repo.com/some-engine.git + cd some-engine + + ############################ + ### Perform installation ### + ############################ + cmake cmake + make install + + ######################### + ### Test installation ### + ######################### + { + python3 -c 'from someEngine import engine; engine.test()' + } || { + echo "There was an error with the installation." + echo "Please, try again or contact the developer." + } + +``` - ```
When the implementation of the wrapper is done, the user should be able to install all the necessary components via: @@ -285,6 +292,7 @@ When the implementation of the wrapper is done, the user should be able to insta ``` ### Dockerfile with the engine + Apart from a system installation, we highly recommend providing a `Dockerfile` with the engine and other minimal requirements, in case the system installation is not possible or desired. @@ -292,10 +300,10 @@ Similar to how OSP-core is the structure on top of which the wrappers are made, we designed a schema of Docker images where OSP-core is used as a base image. Thus, OSP-core has an image (currently using Ubuntu) that should be tagged `simphony/osp-core:`. -The Dockerfile of a wrapper will have that image in the `FROM` statement at the top, +The Dockerfile of a wrapper will have that image in the `FROM` statement at the top, and take care of installing the engine requirements (and the wrapper itself). -To fix the tagging of the images and the versioning compatibility, +To fix the tagging of the images and the versioning compatibility, the `Dockerfile` should be installed via the provided `docker_install.sh` script. It will tag the OSP-core image and call the Dockerfile in the root of the wrapper accordingly. @@ -304,24 +312,28 @@ making sure to leave the first two lines as they are in the [wrapper development `docker_install.sh` will only have to be modified with the proper tag for the wrapper image. ## Continuous Integration -GitLab provides Continuous Integration via the `.gitlab-ci.yml` file. + +GitLab provides Continuous Integration via the `.gitlab-ci.yml` file. This should be used for checking both the style and the functionality of the code automatically after each commit. -If the wrapper requires the installation of an engine, it would probably be best to install it in a Docker image +If the wrapper requires the installation of an engine, it would probably be best to install it in a Docker image and push the image to Gitlab Container Registry so that the CI jobs use that image as the base system in which to run. The `Dockerfile` for the Container Registry image will be very similar to the one used for installing the engine. However, here it might be useful to install other libraries like flake8 for style checks. ## Utility functions for wrapper development -We have developed some functions that will probably come in handy when developing a wrapper. + +We have developed some functions that will probably come in handy when developing a wrapper. You can find them in [osp.core.utils.wrapper_development](https://github.com/simphony/osp-core/blob/master/osp/core/utils/wrapper_development.py). ## Wrapper Examples + Some wrappers we are developing are: + - [SQLAlchemy](https://gitlab.cc-asp.fraunhofer.de/simphony/wrappers/sqlalchemy-wrapper) - [SQLite](https://github.com/simphony/osp-core/tree/master/osp/wrappers/sqlite) - [SimLammps](https://gitlab.cc-asp.fraunhofer.de/simphony/wrappers/simlammps) - [SimGromacs](https://gitlab.cc-asp.fraunhofer.de/simphony/wrappers/simgromacs) - [SimOpenFoam](https://gitlab.cc-asp.fraunhofer.de/simphony/wrappers/simopenfoam) -- [Quantum Espresso](https://github.com/simphony/quantum-espresso-wrapper) \ No newline at end of file +- [Quantum Espresso](https://github.com/simphony/quantum-espresso-wrapper) From 1947d8b64498df8f13e63d4c7fb8a991befb1020 Mon Sep 17 00:00:00 2001 From: dea Date: Tue, 5 Jul 2022 17:05:28 +0200 Subject: [PATCH 4/9] remove cib config --- .github/issue-branch.yml | 11 ----------- 1 file changed, 11 deletions(-) delete mode 100644 .github/issue-branch.yml diff --git a/.github/issue-branch.yml b/.github/issue-branch.yml deleted file mode 100644 index f721400..0000000 --- a/.github/issue-branch.yml +++ /dev/null @@ -1,11 +0,0 @@ -mode: chatops - -branchName: "${issue.number}-${issue.title}" - -autoCloseIssue: true - -branches: - - label: "*" - name: dev - -openDraftPR: true From 34b022ee6f7048dc0e424c441136a5cca96d85e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Manuel=20Dom=C3=ADnguez?= <43052541+kysrpex@users.noreply.github.com> Date: Fri, 29 Jul 2022 15:09:28 +0200 Subject: [PATCH 5/9] Wider page on wide monitors (#209) --- docs/source/_static/custom.css | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css index 6137013..d939c0d 100644 --- a/docs/source/_static/custom.css +++ b/docs/source/_static/custom.css @@ -14,3 +14,12 @@ h4 { background-color: #6580a1 !important; color: azure !important; } + +@media (min-width: 1200px) { + .container-xl { + max-width: 1550px; + } + #site-navigation { + max-width: 20%; + } +} \ No newline at end of file From 3f2e5caea641e229e9e97ce2a68cd657d1bc1c97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Manuel=20Dom=C3=ADnguez?= <43052541+kysrpex@users.noreply.github.com> Date: Fri, 29 Jul 2022 15:48:19 +0200 Subject: [PATCH 6/9] Fix Read the Docs build (#214) * Change requirements.txt * Fix typo in requirements.txt --- requirements.txt | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/requirements.txt b/requirements.txt index ef654e2..1438c7c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,13 +1,12 @@ git+https://github.com/simphony/osp-core.git#egg=osp-core -ipython==8.1.1 -jinja2==3.0.3 -jupyter==1.0.0 -markupsafe==2.1.1 -myst-parser==0.17.0 -nbsphinx==0.8.8 -sphinx==4.4.0 +jinja2 >= 3.0.3, < 4 +jupyter >= 1.0.0, < 2 +markupsafe >= 2.1.1, < 3 +myst-parser >= 0.18.0, < 0.19 +nbsphinx >= 0.8.9, < 0.9 +sphinx >= 4.4.0, < 5 sphinx-autobuild==2021.3.14 -sphinx_book_theme==0.2.0 -sphinxcontrib-plantuml==0.23 -sphinx-copybutton==0.5.0 -sphinx-panels==0.6.0 +sphinx_book_theme >= 0.3.2, < 0.4 +sphinxcontrib-plantuml >= 0.24, < 0.25 +sphinx-copybutton >= 0.5.0, < 0.6 +sphinx-panels >= 0.6.0, < 0.7 From b50edc52988bea56ee82a3a03b578fb76c438dff Mon Sep 17 00:00:00 2001 From: Pablo de Andres <9430234+pablo-de-andres@users.noreply.github.com> Date: Fri, 29 Jul 2022 15:56:43 +0200 Subject: [PATCH 7/9] Review content to make sure it matches the latest versions (#213) * Fix references, update requirements Authored-by: Pablo de Andres --- docs/source/_static/custom.css | 14 +- docs/source/api_ref.md | 7 +- docs/source/conf.py | 3 + docs/source/detailed_design.md | 6 +- docs/source/fundamentals.md | 15 +- docs/source/installation.md | 40 +- docs/source/jupyter/import_export.ipynb | 8 +- docs/source/jupyter/multiple_wrappers.ipynb | 128 +++- docs/source/jupyter/ontology_interface.ipynb | 588 +++++++++---------- docs/source/jupyter/simlammps.ipynb | 61 +- docs/source/ontologies_included.md | 20 +- docs/source/overview.md | 6 - docs/source/utils.md | 2 +- 13 files changed, 506 insertions(+), 392 deletions(-) diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css index d939c0d..23853a6 100644 --- a/docs/source/_static/custom.css +++ b/docs/source/_static/custom.css @@ -16,10 +16,10 @@ h4 { } @media (min-width: 1200px) { - .container-xl { - max-width: 1550px; - } - #site-navigation { - max-width: 20%; - } -} \ No newline at end of file + .container-xl { + max-width: 1550px; + } + #site-navigation { + max-width: 20%; + } +} diff --git a/docs/source/api_ref.md b/docs/source/api_ref.md index f14ee41..b328453 100644 --- a/docs/source/api_ref.md +++ b/docs/source/api_ref.md @@ -1,9 +1,4 @@ -```{eval-rst} -.. raw:: html - -

API Reference

- -``` +# API Reference This document is for developers and/or advanced users of OSP-core, it contains all API details. diff --git a/docs/source/conf.py b/docs/source/conf.py index c65da8a..11e03b1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,9 +23,12 @@ master_doc = "index" +myst_heading_anchors = 5 + plantuml = "java -jar lib/plantuml.jar" plantuml_output_format = "svg_img" +suppress_warnings = ["autosectionlabel.*"] exclude_patterns = ["**.ipynb_checkpoints"] # HTML output diff --git a/docs/source/detailed_design.md b/docs/source/detailed_design.md index 50d6799..4f6b83e 100644 --- a/docs/source/detailed_design.md +++ b/docs/source/detailed_design.md @@ -2,7 +2,7 @@ Here we will give an in-depth view of the design of the 3 layers. -For a more general overview, go to [getting started](./getting_started.md#general-architecture). +For a more general overview, go to [general architecture](general_architecture.md). ```{uml} :caption: Standard design @@ -685,7 +685,7 @@ However, these structures will be used in the different `_apply_` method Similar to how the `_apply_` methods are used to send information to the engine, `_load_from_backend` has the purpose of updating the semantic layer with the latest information from the backend. -You can see in the [`get` sequence diagram](#id3) that when the information has potentially +You can see in the [`get` sequence diagram](#get) that when the information has potentially changed in the backend (i.e the simulation has run, or a database has more data) the `get` has to fetch the latest version. To achieve this, OSP-core calls `_load_from_backend` with the list of desired uids, @@ -696,7 +696,7 @@ information and `yield` them. _Location:_ `osp.core.session.transport` -You may have noticed in the [session inheritance scheme](#id2) that there is `TransportSession` implementing the `WrapperSession`. +You may have noticed in the [session inheritance scheme](#session) that there is `TransportSession` implementing the `WrapperSession`. This session class is the way to connect to engines that are located in other machines through web sockets. The behaviour is as follows: diff --git a/docs/source/fundamentals.md b/docs/source/fundamentals.md index eff539c..a75e51c 100644 --- a/docs/source/fundamentals.md +++ b/docs/source/fundamentals.md @@ -164,7 +164,7 @@ and generalising into a middle and top level layers, and it is currently being f developed in multiple projects of the European Union. SimPhoNy is being developed with the intention of being compatible with EMMO, and an easy installation of the -ontology is available (further explained [here](./ontologies_included.md#working-with-emmo)). +ontology is available (further explained [here](ontologies_included.md#elementary-multiperspective-material-ontology-emmo)). There is also [documentation](https://ontology.pages.fraunhofer.de/documentation/latest/) available for developing an EMMO compliant ontology (requires login). @@ -232,14 +232,13 @@ The most used formats for storing RDF data are: The example triple in XML is: ```xml - - - + - - - - + + + + ``` - [N3](https://www.w3.org/TeamSubmission/n3/): Notation3 is designed with human readability as a motivator. diff --git a/docs/source/installation.md b/docs/source/installation.md index 3db3e5e..8e44333 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -1,35 +1,31 @@ # Installation For the installation and usage of the framework Python 3.6 or higher is -needed. OSP-core is available on PyPI, so it can be installed using `pip`: - -```shell -~/test$ pip install osp-core -``` - -However, we _highly_ encourage the use of a [virtual environment](https://docs.python.org/3/tutorial/venv.html) +needed. We _highly_ encourage the use of a [virtual environment](https://docs.python.org/3/tutorial/venv.html) or a [conda](https://docs.conda.io/en/latest/) environment. ```shell # virtual environment -~/test$ python3 -m venv SimPhoNy -~/test$ source SimPhoNy/bin/activate -(SimPhoNy) ~/test$ +python3 -m venv SimPhoNy +source SimPhoNy/bin/activate ``` ```shell # conda -~/test$ conda create -n -~/test$ conda activate +conda create -n +conda activate ``` -Unfortunately, OSP-core is not available on the Anaconda Repository, so -in both cases, after setting up the environment, it must be installed with -`pip install osp-core`. +OSP-core is available on PyPI, so it can be installed using `pip`: + +```shell +pip install osp-core +``` + +For an installation from source, see [here](#installing-osp-core-from-source). After installing OSP-core, you can install your ontology namespaces. -We provide the tool [`pico`](./utils.md#pico-installs-cuds-ontologies) -(**p**ico **i**nstalls **c**uds **o**ntologies) for that purpose. +We provide the [`pico`](utils.md#pico) tool for that purpose. ```sh pico install @@ -56,7 +52,7 @@ With OSP-core installed, if the wrapper has its own ontology, it _must_ be insta pico install ``` -For the wrappers that require the installation of a backend, a `install_engine.sh` script is provided. +For the wrappers that require the installation of a backend, a `install_engine.sh` script is usually provided. It will automatically call `install_engine_requirements.sh`, where the engine specific requirements are installed. ```shell @@ -66,18 +62,14 @@ It will automatically call `install_engine_requirements.sh`, where the engine sp Now, the wrapper can be installed: ```shell -python3 setup.py install +pip install . ``` ### Wrapper Docker image Some wrappers also provided a [Dockerfile](https://docs.docker.com/engine/reference/builder/) for an automatic installation in a container. -Simply run the `docker_install.sh` script. There is no need to install OSP-core either. - -```shell -./docker_install.sh -``` +The dockerfile should contain the information needed to run it inside. ## Installing OSP-core from source diff --git a/docs/source/jupyter/import_export.ipynb b/docs/source/jupyter/import_export.ipynb index f9795e7..870714e 100644 --- a/docs/source/jupyter/import_export.ipynb +++ b/docs/source/jupyter/import_export.ipynb @@ -30,8 +30,8 @@ "
\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", + "The full API specifications of the import and export functions can be found in the\n", + "[utilities API reference page](../api_ref.md#osp.core.utils.export_cuds).\n", " \n", "
\n", "\n" @@ -42,7 +42,7 @@ "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:" + "For our running example, we'll be using the *city ontology* that was already introduces in the [cuds API tutorial](./cuds_api.ipynb). First, make sure the city ontology is installed. If not, run the following command:" ] }, { @@ -284,7 +284,7 @@ "
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", + "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.ipynb) for more information). You can specify the session explicitly like so: `import_cuds('./data.ttl', session=session)`.\n", " \n", "" ] diff --git a/docs/source/jupyter/multiple_wrappers.ipynb b/docs/source/jupyter/multiple_wrappers.ipynb index 5cbb576..61434ee 100644 --- a/docs/source/jupyter/multiple_wrappers.ipynb +++ b/docs/source/jupyter/multiple_wrappers.ipynb @@ -5,11 +5,11 @@ "metadata": {}, "source": [ "# Tutorial: Multiple wrappers\n", - "This tutorial introduces the use of multiple data sources, and shows how can one exchange information between them. The code given here is based on [this example](https://github.com/simphony/osp-core/blob/master/examples/multiple_wrappers_example.py) and builds on the [introduction on the CUDS API](./cuds-api.ipynb).\n", + "This tutorial introduces the use of multiple data sources, and shows how can one exchange information between them. The code given here is based on [this example](https://github.com/simphony/osp-core/blob/master/examples/multiple_wrappers_example.py) and builds on the [introduction on the CUDS API](./cuds_api.ipynb).\n", "\n", "## Background\n", "One of the main strengths of CUDS objects is their ability to share information between different underlying data sources interchangeably.\n", - "Using OSP-core's innerworkings a data source can be represented as a CUDS object.\n", + "Using OSP-core's inner workings a data source can be represented as a CUDS object.\n", "A data source can be in turn a database, a simulation engine, or any other software package, which is able to either generate or store information.\n", "\n", "We refer to a CUDS object, which represents an underlying data source as a **wrapper**, as it wraps around the data source.\n", @@ -35,8 +35,8 @@ }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "INFO 2020-12-02 11:54:26,244 [osp.core.ontology.installation]: Will install the following namespaces: ['city']\n", "INFO 2020-12-02 11:54:26,280 [osp.core.ontology.yml.yml_parser]: Parsing YAML ontology file /mnt/c/Users/dea/Documents/Projects/simphony/osp-core/osp/core/ontology/docs/city.ontology.yml\n", @@ -96,7 +96,7 @@ "metadata": {}, "source": [ "The next statements imports the second data source session we will use in this example, namely a database, or more precisely the ORM toolkit [SQLAlchemy](https://www.sqlalchemy.org/) which we will use in turn to connect to a PostgreSQL database.\n", - "It will throws an error if it cannot find the `SQLAlchemyWrapperSession` as it needs to be installed from a separate repository. Please refer [here](https://gitlab.cc-asp.fraunhofer.de/simphony/wrappers/sqlalchemy-wrapper) for installation instructions." + "It will throws an error if it cannot find the `SQLAlchemyWrapperSession` as it needs to be installed from a separate repository. Please refer [here](https://github.com/simphony/simphony-sqlalchemy) for installation instructions." ] }, { @@ -143,8 +143,8 @@ }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "Input data to connect to Postgres table!\n" ] @@ -173,14 +173,14 @@ "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "" ] }, + "execution_count": 8, "metadata": {}, - "execution_count": 8 + "output_type": "execute_result" } ], "source": [ @@ -234,8 +234,8 @@ }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "EMMO town is my city!\n" ] @@ -290,9 +290,61 @@ }, "outputs": [ { - "output_type": "stream", "name": "stdout", - "text": "The database contains the following information about the city:\n- Cuds object named :\n uuid: 96a2f49c-8009-456a-ad69-1cb1dea7f128\n type: city.City\n superclasses: city.City, city.GeographicalPlace, city.PopulatedPlace, cuba.Entity\n values: coordinates: [0 0]\n description: \n To Be Determined\n\n |_Relationship city.hasInhabitant:\n | - city.Citizen cuds object named :\n | . uuid: 08e05374-0187-4114-a114-085431aeebde\n | . age: 25\n | - city.Citizen cuds object named :\n | . uuid: a084c4ba-c054-4afd-b194-b4e983743706\n | . age: 25\n | - city.Citizen cuds object named :\n | . uuid: 209926bc-6bcd-466c-a86a-807780e4789c\n | . age: 25\n | - city.Citizen cuds object named :\n | . uuid: 0a0a8488-7400-4f4e-9e44-dbf56782cd3c\n | . age: 25\n | - city.Citizen cuds object named :\n | . uuid: cdfe72ec-fc15-4a14-a516-88b576bf0a27\n | . age: 25\n | - city.Citizen cuds object named :\n | uuid: 4ec1b1af-341f-4aa5-845d-fb3f9c502c9c\n | age: 25\n |_Relationship city.hasPart:\n - city.Neighborhood cuds object named :\n . uuid: e1632cf5-24e3-4afb-b72b-757ef62d5bef\n . coordinates: [0 0]\n . |_Relationship city.hasPart:\n . - city.Street cuds object named :\n . . uuid: 19a6a5a4-c22c-4be7-98c4-c69b3ee613d2\n . . coordinates: [0 0]\n . - city.Street cuds object named :\n . uuid: 681f7441-e711-4375-ab70-074234206faa\n . coordinates: [0 0]\n - city.Neighborhood cuds object named :\n uuid: 574e4a68-92c8-4b0e-b41f-e0341b42b00b\n coordinates: [0 0]\nThe city has a new inhabitant:\n- Cuds object named :\n uuid: 7a263d53-9c4d-47ac-bb31-fa54d7920bcd\n type: city.Citizen\n superclasses: city.Citizen, city.LivingBeing, city.Person, cuba.Entity\n values: age: 32\n description: \n To Be Determined\n\n" + "output_type": "stream", + "text": [ + "The database contains the following information about the city:\n", + "- Cuds object named :\n", + " uuid: 96a2f49c-8009-456a-ad69-1cb1dea7f128\n", + " type: city.City\n", + " superclasses: city.City, city.GeographicalPlace, city.PopulatedPlace, cuba.Entity\n", + " values: coordinates: [0 0]\n", + " description: \n", + " To Be Determined\n", + "\n", + " |_Relationship city.hasInhabitant:\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: 08e05374-0187-4114-a114-085431aeebde\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: a084c4ba-c054-4afd-b194-b4e983743706\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: 209926bc-6bcd-466c-a86a-807780e4789c\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: 0a0a8488-7400-4f4e-9e44-dbf56782cd3c\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: cdfe72ec-fc15-4a14-a516-88b576bf0a27\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | uuid: 4ec1b1af-341f-4aa5-845d-fb3f9c502c9c\n", + " | age: 25\n", + " |_Relationship city.hasPart:\n", + " - city.Neighborhood cuds object named :\n", + " . uuid: e1632cf5-24e3-4afb-b72b-757ef62d5bef\n", + " . coordinates: [0 0]\n", + " . |_Relationship city.hasPart:\n", + " . - city.Street cuds object named :\n", + " . . uuid: 19a6a5a4-c22c-4be7-98c4-c69b3ee613d2\n", + " . . coordinates: [0 0]\n", + " . - city.Street cuds object named :\n", + " . uuid: 681f7441-e711-4375-ab70-074234206faa\n", + " . coordinates: [0 0]\n", + " - city.Neighborhood cuds object named :\n", + " uuid: 574e4a68-92c8-4b0e-b41f-e0341b42b00b\n", + " coordinates: [0 0]\n", + "The city has a new inhabitant:\n", + "- Cuds object named :\n", + " uuid: 7a263d53-9c4d-47ac-bb31-fa54d7920bcd\n", + " type: city.Citizen\n", + " superclasses: city.Citizen, city.LivingBeing, city.Person, cuba.Entity\n", + " values: age: 32\n", + " description: \n", + " To Be Determined\n", + "\n" + ] } ], "source": [ @@ -332,9 +384,55 @@ }, "outputs": [ { - "output_type": "stream", "name": "stdout", - "text": "The database contains the following information about the city:\n- Cuds object named :\n uuid: 96a2f49c-8009-456a-ad69-1cb1dea7f128\n type: city.City\n superclasses: city.City, city.GeographicalPlace, city.PopulatedPlace, cuba.Entity\n values: coordinates: [0 0]\n description: \n To Be Determined\n\n |_Relationship city.hasInhabitant:\n | - city.Citizen cuds object named :\n | . uuid: 08e05374-0187-4114-a114-085431aeebde\n | . age: 25\n | - city.Citizen cuds object named :\n | . uuid: a084c4ba-c054-4afd-b194-b4e983743706\n | . age: 25\n | - city.Citizen cuds object named :\n | . uuid: 209926bc-6bcd-466c-a86a-807780e4789c\n | . age: 25\n | - city.Citizen cuds object named :\n | . uuid: 0a0a8488-7400-4f4e-9e44-dbf56782cd3c\n | . age: 25\n | - city.Citizen cuds object named :\n | . uuid: cdfe72ec-fc15-4a14-a516-88b576bf0a27\n | . age: 25\n | - city.Citizen cuds object named :\n | . uuid: 4ec1b1af-341f-4aa5-845d-fb3f9c502c9c\n | . age: 25\n | - city.Citizen cuds object named :\n | uuid: 7a263d53-9c4d-47ac-bb31-fa54d7920bcd\n | age: 32\n |_Relationship city.hasPart:\n - city.Neighborhood cuds object named :\n . uuid: e1632cf5-24e3-4afb-b72b-757ef62d5bef\n . coordinates: [0 0]\n . |_Relationship city.hasPart:\n . - city.Street cuds object named :\n . . uuid: 19a6a5a4-c22c-4be7-98c4-c69b3ee613d2\n . . coordinates: [0 0]\n . - city.Street cuds object named :\n . uuid: 681f7441-e711-4375-ab70-074234206faa\n . coordinates: [0 0]\n - city.Neighborhood cuds object named :\n uuid: 574e4a68-92c8-4b0e-b41f-e0341b42b00b\n coordinates: [0 0]\n" + "output_type": "stream", + "text": [ + "The database contains the following information about the city:\n", + "- Cuds object named :\n", + " uuid: 96a2f49c-8009-456a-ad69-1cb1dea7f128\n", + " type: city.City\n", + " superclasses: city.City, city.GeographicalPlace, city.PopulatedPlace, cuba.Entity\n", + " values: coordinates: [0 0]\n", + " description: \n", + " To Be Determined\n", + "\n", + " |_Relationship city.hasInhabitant:\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: 08e05374-0187-4114-a114-085431aeebde\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: a084c4ba-c054-4afd-b194-b4e983743706\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: 209926bc-6bcd-466c-a86a-807780e4789c\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: 0a0a8488-7400-4f4e-9e44-dbf56782cd3c\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: cdfe72ec-fc15-4a14-a516-88b576bf0a27\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | . uuid: 4ec1b1af-341f-4aa5-845d-fb3f9c502c9c\n", + " | . age: 25\n", + " | - city.Citizen cuds object named :\n", + " | uuid: 7a263d53-9c4d-47ac-bb31-fa54d7920bcd\n", + " | age: 32\n", + " |_Relationship city.hasPart:\n", + " - city.Neighborhood cuds object named :\n", + " . uuid: e1632cf5-24e3-4afb-b72b-757ef62d5bef\n", + " . coordinates: [0 0]\n", + " . |_Relationship city.hasPart:\n", + " . - city.Street cuds object named :\n", + " . . uuid: 19a6a5a4-c22c-4be7-98c4-c69b3ee613d2\n", + " . . coordinates: [0 0]\n", + " . - city.Street cuds object named :\n", + " . uuid: 681f7441-e711-4375-ab70-074234206faa\n", + " . coordinates: [0 0]\n", + " - city.Neighborhood cuds object named :\n", + " uuid: 574e4a68-92c8-4b0e-b41f-e0341b42b00b\n", + " coordinates: [0 0]\n" + ] } ], "source": [ @@ -353,7 +451,11 @@ "source": [] } ], - "metadata": {}, + "metadata": { + "language_info": { + "name": "python" + } + }, "nbformat": 4, "nbformat_minor": 2 } diff --git a/docs/source/jupyter/ontology_interface.ipynb b/docs/source/jupyter/ontology_interface.ipynb index 456b0f4..c1aff06 100644 --- a/docs/source/jupyter/ontology_interface.ipynb +++ b/docs/source/jupyter/ontology_interface.ipynb @@ -2,6 +2,7 @@ "cells": [ { "cell_type": "markdown", + "metadata": {}, "source": [ "# Tutorial: Ontology interface\n", "\n", @@ -13,46 +14,43 @@ "\n", "\n", "This tutorial introduces the interface to the installed ontologies. The code presented is based on [this example](https://github.com/simphony/osp-core/blob/master/examples/ontology_example.py)." - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Background" - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "In an ontological framework, ontology entities are used as a knowledge representation form. Those can be further categorized in two groups: ontology individuals ([assertional knowledge](https://en.wikipedia.org/wiki/Abox)), and ontology classes, relationships and attributes ([terminological knowledge](https://en.wikipedia.org/wiki/Tbox)).\n", "\n", - "In a [previous tutorial](./cuds_api.html), we have discussed how to work with CUDS objects, which represent ontology individuals. In this tutorial, we present the API of all the other entities instead: ontology classes, relationships and attributes. These are defined in an ontology installation file in [YAML](../working_with_ontologies.md#osp-core-yaml-ontology-format) or [OWL](../working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies) format. The presented API enables you to access the entities and navigate within an ontology." - ], - "metadata": {} + "In a [previous tutorial](./cuds_api.ipynb), we have discussed how to work with CUDS objects, which represent ontology individuals. In this tutorial, we present the API of all the other entities instead: ontology classes, relationships and attributes. These are defined in an ontology installation file in [YAML](../working_with_ontologies.md#osp-core-yaml-ontology-format) or [OWL](../working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies) format. The presented API enables you to access the entities and navigate within an ontology." + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "In this tutorial, we will work both with the `city` namespace, the example namespace from OSP-core, and the `math` namespace from the [Elementary Multiperspective Material Ontology (EMMO)](https://github.com/emmo-repo/EMMO), for which an installation file is also provided with OSP-core.\n", "\n", "Please install the ontologies running the commands below if you have not installed them yet." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 1, - "source": [ - "# Install the ontologies\n", - "!pico install city\n", - "!pico install emmo" - ], + "metadata": { + "tags": [] + }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "INFO 2021-03-31 16:16:53,174 [osp.core.ontology.installation]: Will install the following namespaces: ['city']\n", "INFO 2021-03-31 16:16:53,187 [osp.core.ontology.yml.yml_parser]: Parsing YAML ontology file /home/jose/.local/lib/python3.9/site-packages/osp/core/ontology/docs/city.ontology.yml\n", @@ -84,16 +82,19 @@ ] } ], - "metadata": { - "tags": [] - } + "source": [ + "# Install the ontologies\n", + "!pico install city\n", + "!pico install emmo" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Accessing entities: the namespace object\n", "\n", - "To access ontology entities, we first need to know the aliases of the installed ontology namespaces. In each ontology [YAML installation file](../yaml.md), the namespace(s) that it contains is(are) stated at the top of the file. For example, at the top of the [city ontology installation file](https://github.com/simphony/osp-core/blob/master/osp/core/ontology/docs/city.ontology.yml) you may find:\n", + "To access ontology entities, we first need to know the aliases of the installed ontology namespaces. In each ontology [YAML installation file](../working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies), the namespace(s) that it contains is(are) stated at the top of the file. For example, at the top of the [city ontology installation file](https://github.com/simphony/osp-core/blob/master/osp/core/ontology/docs/city.ontology.yml) you may find:\n", "\n", "```yaml\n", "---\n", @@ -105,20 +106,19 @@ " ...\n", "```\n", "\n", - "Alternatively, you can use [pico ontology installation tool](../utils.md#pico-installs-cuds-ontologies) to see the installed namespaces:" - ], - "metadata": {} + "Alternatively, you can use [pico ontology installation tool](../utils.md#pico) to see the installed namespaces:" + ] }, { "cell_type": "code", "execution_count": 2, - "source": [ - "!pico list" - ], + "metadata": { + "tags": [] + }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "Packages:\n", "\t- city\n", @@ -152,31 +152,32 @@ ] } ], - "metadata": { - "tags": [] - } + "source": [ + "!pico list" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "Once we know the name of the namespace that we want to use, we import it in python. For this tutorial, we are importing the namespaces `city` and `math`. Through those imported namespace python objects, the entities within the namespaces can be accessed:" - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 3, + "metadata": { + "tags": [] + }, + "outputs": [], "source": [ "from osp.core.namespaces import city\n", "from osp.core.namespaces import math" - ], - "outputs": [], - "metadata": { - "tags": [] - } + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "There are several ways to access an ontology entity in OSP-core, which are summarized by the following list and will be demonstrated shortly after.\n", "\n", @@ -187,29 +188,29 @@ "- By **IRI**. The full [IRI](https://fusion.cs.uni-jena.de/fusion/blog/2016/11/18/iri-uri-url-urn-and-their-differences/) of an ontology entity is provided in order to fetch it.\n", "\n", "- By **string**. Using a string, for example `\"city.LivingBeing\"`. This is only useful in some special cases." - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "The **most convenient way** to access an ontology entity is using the **dot notation** in python. For example, `city.Citizen`. This method is a shorthand for fetching by suffix or label: \n", "\n", "- When the keyword `reference_by_label` is set to `True` (enabled) in the [ontology YAML installation file](../working_with_ontologies.md), the dot notation is a shorthand for fetching by label. This keyword is **enabled** in the `math` namespace.\n", "\n", "- 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." - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "To get a list of all the entities available within a namespace, run `list(namespace)`." - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "
\n", "
\n", @@ -220,231 +221,226 @@ "
\n", "
\n", "" - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "**Accessing an ontology entity by suffix**\n", "\n", "Let's fetch the Citizen class, whose IRI is `http://www.osp-core.com/city#Citizen`." - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "The keyword, `reference_by_label` is set to `False`, so one can just use the dot notation. " - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 4, - "source": [ - "city.Citizen" - ], + "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "" ] }, + "execution_count": 4, "metadata": {}, - "execution_count": 4 + "output_type": "execute_result" } ], - "metadata": {} + "source": [ + "city.Citizen" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "Another alternative is using the `get_from_suffix` method from the namespace object. This is useful when the suffix contains characters that Python does not accept as property names, such as spaces or dashes." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 5, - "source": [ - "city.get_from_suffix('Citizen')" - ], + "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "" ] }, + "execution_count": 5, "metadata": {}, - "execution_count": 5 + "output_type": "execute_result" } ], - "metadata": {} + "source": [ + "city.get_from_suffix('Citizen')" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "Note that the suffix is case sensitive, and therefore the following would produce an error." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 6, - "source": [ - "#city.citizen # -> Fails." - ], + "metadata": {}, "outputs": [], - "metadata": {} + "source": [ + "# city.citizen # -> Fails." + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "**Accessing an ontology entity by label**\n", "\n", "Let's fetch the Integer class, whose IRI is `http://emmo.info/emmo/middle/math#EMMO_f8bd64d5_5d3e_4ad4_a46e_c30714fecb7f`." - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "The keyword `reference_by_label` is set to `True`, so we just use the dot notation." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 7, - "source": [ - "math.Integer" - ], + "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "" ] }, + "execution_count": 7, "metadata": {}, - "execution_count": 7 + "output_type": "execute_result" } ], - "metadata": {} + "source": [ + "math.Integer" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "Another alternative is using the square bracket notation on the namespace object. This is useful when the suffix contains characters that Python does not accept as property names, such as spaces or dashes." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 8, - "source": [ - "math['Integer']" - ], + "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "" ] }, + "execution_count": 8, "metadata": {}, - "execution_count": 8 + "output_type": "execute_result" } ], - "metadata": {} + "source": [ + "math['Integer']" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "Fetching by label is NOT case sensitive when using the dot notation, but it is when using square brackets, so the following behavior is expected." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 9, - "source": [ - "#math['integer'] # -> Fails.\n", - "math.integer # -> Works." - ], + "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "" ] }, + "execution_count": 9, "metadata": {}, - "execution_count": 9 + "output_type": "execute_result" } ], - "metadata": {} + "source": [ + "# math['integer'] # -> Fails.\n", + "math.integer # -> Works." + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "**Accessing an ontology entity by IRI**\n", "\n", "This is only possible using the `get_from_iri` method from the namespace object. For example, let's fetch the Integer entity again." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 10, - "source": [ - "math.get_from_iri('http://emmo.info/emmo/middle/math#EMMO_f8bd64d5_5d3e_4ad4_a46e_c30714fecb7f')" - ], + "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "" ] }, + "execution_count": 10, "metadata": {}, - "execution_count": 10 + "output_type": "execute_result" } ], - "metadata": {} + "source": [ + "math.get_from_iri('http://emmo.info/emmo/middle/math#EMMO_f8bd64d5_5d3e_4ad4_a46e_c30714fecb7f')" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "**Access entities using a string**\n", "\n", "Sometimes you only have a string refering to an entity. Using the `get_entity` function you can get the corresponding python object easily:" - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 11, - "source": [ - "from osp.core.namespaces import get_entity # noqa: E402\n", - "\n", - "print(\"\\nYou can get an entity with a string\")\n", - "print(get_entity(\"city.LivingBeing\"))\n", - "print(get_entity(\"city.LivingBeing\") == city.LivingBeing)" - ], + "metadata": { + "tags": [] + }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "\n", "You can get an entity with a string\n", @@ -453,132 +449,123 @@ ] } ], - "metadata": { - "tags": [] - } + "source": [ + "from osp.core.namespaces import get_entity # noqa: E402\n", + "\n", + "print(\"\\nYou can get an entity with a string\")\n", + "print(get_entity(\"city.LivingBeing\"))\n", + "print(get_entity(\"city.LivingBeing\") == city.LivingBeing)" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Accessing an entity's name, IRI and namespace" - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "Each ontology entity has an associated name which can be accessed using the `name` property. " - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 12, - "source": [ - "city.LivingBeing.name" - ], + "metadata": { + "tags": [] + }, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "'LivingBeing'" ] }, + "execution_count": 12, "metadata": {}, - "execution_count": 12 + "output_type": "execute_result" } ], - "metadata": { - "tags": [] - } + "source": [ + "city.LivingBeing.name" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "The IRI of an entity might be accessed using the `iri` property." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 13, - "source": [ - "math.Real.iri" - ], + "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "rdflib.term.URIRef('http://emmo.info/emmo/middle/math#EMMO_18d180e4_5e3e_42f7_820c_e08951223486')" ] }, + "execution_count": 13, "metadata": {}, - "execution_count": 13 + "output_type": "execute_result" } ], - "metadata": {} + "source": [ + "math.Real.iri" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "In addition, it is possible to get the namespace object to which the entity belongs using the `namespace` property." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 14, - "source": [ - "math.Equation.namespace" - ], + "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "" ] }, + "execution_count": 14, "metadata": {}, - "execution_count": 14 + "output_type": "execute_result" } ], - "metadata": {} + "source": [ + "math.Equation.namespace" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Accessing super- and subclasses\n", "\n", "Using the properties `superclasses` and `subclasses` it is easy to navigate the ontology. Direct superclasses and subclasses can also be accessed:" - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 15, - "source": [ - "print(\"\\nYou can access the superclasses and the subclasses\")\n", - "print(city.LivingBeing.superclasses)\n", - "print(city.LivingBeing.subclasses)\n", - "\n", - "print(\"\\nYou can access the direct superclasses and subclasses\")\n", - "print(city.LivingBeing.direct_superclasses)\n", - "print(city.LivingBeing.direct_subclasses)\n", - "\n", - "print(\"\\nYou can access a description of the entities\")\n", - "print(city.LivingBeing.description)\n", - "\n", - "print(\"\\nYou can test if one entity is a subclass / superclass of another\")\n", - "print(city.Person.is_subclass_of(city.LivingBeing))\n", - "print(city.LivingBeing.is_superclass_of(city.Person))" - ], + "metadata": { + "tags": [] + }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "\n", "You can access the superclasses and the subclasses\n", @@ -598,22 +585,58 @@ ] } ], - "metadata": { - "tags": [] - } + "source": [ + "print(\"\\nYou can access the superclasses and the subclasses\")\n", + "print(city.LivingBeing.superclasses)\n", + "print(city.LivingBeing.subclasses)\n", + "\n", + "print(\"\\nYou can access the direct superclasses and subclasses\")\n", + "print(city.LivingBeing.direct_superclasses)\n", + "print(city.LivingBeing.direct_subclasses)\n", + "\n", + "print(\"\\nYou can access a description of the entities\")\n", + "print(city.LivingBeing.description)\n", + "\n", + "print(\"\\nYou can test if one entity is a subclass / superclass of another\")\n", + "print(city.Person.is_subclass_of(city.LivingBeing))\n", + "print(city.LivingBeing.is_superclass_of(city.Person))" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Testing the type of the entities\n", "\n", - "In the ontology, three types of entities can be defined: classes, relationships and attributes. OSP-core has its own vocabulary, the [CUBA namespace](../yaml.md#the-cuba-namespace), which describes, among other things, such entity types. Relationships are subclasses of `CUBA.RELATIONSHIP` and attributes are subclasses of `CUBA.ATTRIBUTE`. There are different Python objects for the different entity types. You can use both to check which type of entity you are dealing with:" - ], - "metadata": {} + "In the ontology, three types of entities can be defined: classes, relationships and attributes. OSP-core has its own vocabulary, the [CUBA namespace](../working_with_ontologies.md#the-cuba-namespace), which describes, among other things, such entity types. Relationships are subclasses of `CUBA.RELATIONSHIP` and attributes are subclasses of `CUBA.ATTRIBUTE`. There are different Python objects for the different entity types. You can use both to check which type of entity you are dealing with:" + ] }, { "cell_type": "code", "execution_count": 16, + "metadata": { + "tags": [] + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "You can test if an entity is a class\n", + "True\n", + "True\n", + "\n", + "You can test if an entity is a relationship\n", + "True\n", + "True\n", + "\n", + "You can test if an entity is a attribute\n", + "True\n", + "True\n" + ] + } + ], "source": [ "from osp.core.namespaces import cuba # noqa: E402\n", "\n", @@ -638,55 +661,27 @@ "print(isinstance(city.name, OntologyAttribute))\n", "print(city.name.is_subclass_of(cuba.attribute))\n", "\n" - ], - "outputs": [ - { - "output_type": "stream", - "name": "stdout", - "text": [ - "\n", - "You can test if an entity is a class\n", - "True\n", - "True\n", - "\n", - "You can test if an entity is a relationship\n", - "True\n", - "True\n", - "\n", - "You can test if an entity is a attribute\n", - "True\n", - "True\n" - ] - } - ], - "metadata": { - "tags": [] - } + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Operations specific to ontology classes\n", "\n", "The different types of entities differ in the operations they offer. For classes, you can access the attributes:" - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 17, - "source": [ - "print(\"\\nYou can get the attributes of an ontology class and their defaults\")\n", - "print(city.Citizen.attributes)\n", - "\n", - "print(\"\\nYou can get the non-inherited attributes and their defaults\")\n", - "print(city.Citizen.own_attributes)\n", - "print(city.LivingBeing.own_attributes)" - ], + "metadata": { + "tags": [] + }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "\n", "You can get the attributes of an ontology class and their defaults\n", @@ -698,68 +693,66 @@ ] } ], - "metadata": { - "tags": [] - } + "source": [ + "print(\"\\nYou can get the attributes of an ontology class and their defaults\")\n", + "print(city.Citizen.attributes)\n", + "\n", + "print(\"\\nYou can get the non-inherited attributes and their defaults\")\n", + "print(city.Citizen.own_attributes)\n", + "print(city.LivingBeing.own_attributes)" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "In addition, OSP-core has special support for the `owl:Restriction` and `owl:Composition` classes of the [Web Ontology Language (OWL)](https://en.wikipedia.org/wiki/Web_Ontology_Language) (check the [OWL ontology specification](https://www.w3.org/TR/owl2-syntax/) for more details). Such OWL classes are represented by the python classes `Restriction` and `Composition`. See [operations specific to ontology axioms](#Operations-specific-to-ontology-axioms) for more information.\n", "\n", "For example, in the city ontology, the citizens have a restriction on the name and age attributes: a citizen must have exactly one name and one age. These axioms can be accessed using the `axioms` property, which returns both the restriction and compositions affecting the class." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 18, - "source": [ - "tuple(str(x) for x in city.Citizen.axioms)" - ], + "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { "text/plain": [ "('city.name QUANTIFIER.EXACTLY 1', 'city.age QUANTIFIER.EXACTLY 1')" ] }, + "execution_count": 18, "metadata": {}, - "execution_count": 18 + "output_type": "execute_result" } ], - "metadata": {} + "source": [ + "tuple(str(x) for x in city.Citizen.axioms)" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Operations specific to ontology axioms" - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "For restrictions, the quantifier, the target, the restriction type and the relationship/attribute (depending on whether it is a restriction of the relationship type or attribute type) may be accessed." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 19, - "source": [ - "restriction = city.Citizen.axioms[0]\n", - "print(restriction)\n", - "print(restriction.quantifier)\n", - "print(restriction.target)\n", - "print(restriction.rtype)\n", - "print(restriction.attribute)" - ], + "metadata": {}, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "city.name QUANTIFIER.EXACTLY 1\n", "QUANTIFIER.EXACTLY\n", @@ -769,29 +762,30 @@ ] } ], - "metadata": {} + "source": [ + "restriction = city.Citizen.axioms[0]\n", + "print(restriction)\n", + "print(restriction.quantifier)\n", + "print(restriction.target)\n", + "print(restriction.rtype)\n", + "print(restriction.attribute)" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "For compositions, both the operator and operands can be accesed." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 20, - "source": [ - "from osp.core.ontology.oclass_composition import Composition\n", - "composition = tuple(x for x in math.Integer.axioms if type(x) is Composition)[0]\n", - "print(composition)\n", - "print(composition.operator)\n", - "print(composition.operands)" - ], + "metadata": {}, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "(math.Mathematical OPERATOR.AND perceptual.Symbol)\n", "OPERATOR.AND\n", @@ -799,28 +793,33 @@ ] } ], - "metadata": {} + "source": [ + "from osp.core.ontology.oclass_composition import Composition\n", + "composition = tuple(x for x in math.Integer.axioms if type(x) is Composition)[0]\n", + "print(composition)\n", + "print(composition.operator)\n", + "print(composition.operands)" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Operations specific to ontology relationships\n", "\n", "You can access the inverse of relationships." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 21, - "source": [ - "print(\"\\nYou can get the inverse of a relationship\")\n", - "print(city.hasInhabitant.inverse)" - ], + "metadata": { + "tags": [] + }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "\n", "You can get the inverse of a relationship\n", @@ -828,44 +827,30 @@ ] } ], - "metadata": { - "tags": [] - } + "source": [ + "print(\"\\nYou can get the inverse of a relationship\")\n", + "print(city.hasInhabitant.inverse)" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Operations specific to attributes\n", "\n", "You can acces the datatype and the argument name of attributes." - ], - "metadata": {} + ] }, { "cell_type": "code", "execution_count": 22, - "source": [ - "print(\"\\nYou can get the argument name of an attribute. \"\n", - " \"The argument name is used as keyword argument when instantiating CUDS objects.\")\n", - "print(city.age.argname)\n", - "\n", - "print(\"\\nYou can get the datatype of attributes\")\n", - "print(city.age.datatype)\n", - "\n", - "print(\"\\nYou can use the attribute to convert values \"\n", - " \"to the datatype of the attribute\")\n", - "result = city.age.convert_to_datatype(\"10\")\n", - "print(type(result), result)\n", - "\n", - "print(\"\\nAnd likewise to convert values to the python basic type \"\n", - " \"associated with the datatype of the attribute.\")\n", - "result = city.name.convert_to_basic_type(5)\n", - "print(type(result), result)" - ], + "metadata": { + "tags": [] + }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "\n", "You can get the argument name of an attribute. The argument name is used as keyword argument when instantiating CUDS objects.\n", @@ -882,44 +867,51 @@ ] } ], - "metadata": { - "tags": [] - } + "source": [ + "print(\"\\nYou can get the argument name of an attribute. \"\n", + " \"The argument name is used as keyword argument when instantiating CUDS objects.\")\n", + "print(city.age.argname)\n", + "\n", + "print(\"\\nYou can get the datatype of attributes\")\n", + "print(city.age.datatype)\n", + "\n", + "print(\"\\nYou can use the attribute to convert values \"\n", + " \"to the datatype of the attribute\")\n", + "result = city.age.convert_to_datatype(\"10\")\n", + "print(type(result), result)\n", + "\n", + "print(\"\\nAnd likewise to convert values to the python basic type \"\n", + " \"associated with the datatype of the attribute.\")\n", + "result = city.name.convert_to_basic_type(5)\n", + "print(type(result), result)" + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "Check the API Reference for more details on the methods [_convert_to_datatype_](../api_ref.md#osp.core.ontology.attribute.OntologyAttribute.convert_to_datatype) and [_convert_to_basic_type_](../api_ref.md#osp.core.ontology.attribute.OntologyAttribute.convert_to_basic_type)." - ], - "metadata": {} + ] }, { "cell_type": "markdown", + "metadata": {}, "source": [ "## Creating CUDS using ontology classes\n", "\n", - "You can call ontology classes to create CUDS objects. To learn more, have a look at the [CUDS API tutorial](./cuds_api.html)." - ], - "metadata": {} + "You can call ontology classes to create CUDS objects. To learn more, have a look at the [CUDS API tutorial](./cuds_api.ipynb)." + ] }, { "cell_type": "code", "execution_count": 23, - "source": [ - "print(\"\\nYou can instantiate CUDS objects using ontology classes\")\n", - "print(city.Citizen(name=\"Test Person\", age=42))\n", - "\n", - "print(\"\\nYou can check if a CUDS object is an instance of a ontology class\")\n", - "print(city.Citizen(name=\"Test Person\", age=42).is_a(city.Citizen))\n", - "print(city.Citizen(name=\"Test Person\", age=42).is_a(city.LivingBeing))\n", - "\n", - "print(\"\\nYou can get the ontology class of a CUDS object.\")\n", - "print(city.Citizen(name=\"Test Person\", age=42).oclass)\n" - ], + "metadata": { + "tags": [] + }, "outputs": [ { - "output_type": "stream", "name": "stdout", + "output_type": "stream", "text": [ "\n", "You can instantiate CUDS objects using ontology classes\n", @@ -934,9 +926,17 @@ ] } ], - "metadata": { - "tags": [] - } + "source": [ + "print(\"\\nYou can instantiate CUDS objects using ontology classes\")\n", + "print(city.Citizen(name=\"Test Person\", age=42))\n", + "\n", + "print(\"\\nYou can check if a CUDS object is an instance of a ontology class\")\n", + "print(city.Citizen(name=\"Test Person\", age=42).is_a(city.Citizen))\n", + "print(city.Citizen(name=\"Test Person\", age=42).is_a(city.LivingBeing))\n", + "\n", + "print(\"\\nYou can get the ontology class of a CUDS object.\")\n", + "print(city.Citizen(name=\"Test Person\", age=42).oclass)" + ] } ], "metadata": { diff --git a/docs/source/jupyter/simlammps.ipynb b/docs/source/jupyter/simlammps.ipynb index 053c656..484f140 100644 --- a/docs/source/jupyter/simlammps.ipynb +++ b/docs/source/jupyter/simlammps.ipynb @@ -9,7 +9,7 @@ "You can find the wrapper [here](https://gitlab.cc-asp.fraunhofer.de/simphony/wrappers/simlammps).\n", "\n", "## Background\n", - "A wrapper for LAMMPS has been present in SimPhoNy since its initial version, and it is the first simmulation engine we supported in version 3.\n", + "A wrapper for LAMMPS has been present in SimPhoNy since its initial version, and it is the first simulation engine we supported in version 3.\n", "\n", "This wrapper is a good example of the [3-layered-design](../detailed_design.md) where the Syntactic layer is a third party library.\n", "In this case we use PyLammps, a Python binding for LAMMPS created and maintained by the LAMMPS developers." @@ -25,7 +25,7 @@ "Like we explain in the [wrapper development section](../wrapper_development.md#engine-installation), there are two options:\n", "\n", "- Using Docker: run `./docker_install.sh`.\n", - "- Local installation: remember that you must have a compatible version of [OSP-core installed](../installation.md#osp-core-installation).\n", + "- Local installation: remember that you must have a compatible version of [OSP-core installed](../installation.md).\n", " \n", " Install the ontology via `pico install simlammps.ontology.yml.`\n", " \n", @@ -33,7 +33,7 @@ "\n", " - Note that you will be asked for a superuser password to install required libraries for the installation (make, libjpeg, libpng...)\n", "\n", - " - Currently we support Ubuntu and centos.\n", + " - Currently we support Ubuntu and centOS.\n", " \n", " Install the wrapper by running `python setup.py install`.\n", "\n", @@ -70,9 +70,11 @@ "metadata": {}, "outputs": [ { - "output_type": "stream", "name": "stdout", - "text": "LAMMPS output is captured by PyLammps wrapper\n" + "output_type": "stream", + "text": [ + "LAMMPS output is captured by PyLammps wrapper\n" + ] } ], "source": [ @@ -93,12 +95,14 @@ "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { - "text/plain": "" + "text/plain": [ + "" + ] }, + "execution_count": 3, "metadata": {}, - "execution_count": 3 + "output_type": "execute_result" } ], "source": [ @@ -158,12 +162,14 @@ "metadata": {}, "outputs": [ { - "output_type": "execute_result", "data": { - "text/plain": "" + "text/plain": [ + "" + ] }, + "execution_count": 4, "metadata": {}, - "execution_count": 4 + "output_type": "execute_result" } ], "source": [ @@ -242,9 +248,18 @@ "metadata": {}, "outputs": [ { - "output_type": "stream", "name": "stdout", - "text": "Atom fd4199d4-4d1a-425c-8010-60efca65bd1c:\n - Position: [1.5 6. 3. ]\n - Velocity: [1. 0. 0.]\nAtom f9a32d14-b638-4796-9407-4b1ae6be43cb:\n - Position: [3. 1. 5.]\n - Velocity: [2. 0. 2.]\nAtom db96a76f-4d70-4e19-b460-46ee286f831e:\n - Position: [7. 3. 0.]\n" + "output_type": "stream", + "text": [ + "Atom fd4199d4-4d1a-425c-8010-60efca65bd1c:\n", + " - Position: [1.5 6. 3. ]\n", + " - Velocity: [1. 0. 0.]\n", + "Atom f9a32d14-b638-4796-9407-4b1ae6be43cb:\n", + " - Position: [3. 1. 5.]\n", + " - Velocity: [2. 0. 2.]\n", + "Atom db96a76f-4d70-4e19-b460-46ee286f831e:\n", + " - Position: [7. 3. 0.]\n" + ] } ], "source": [ @@ -264,9 +279,19 @@ "metadata": {}, "outputs": [ { - "output_type": "stream", "name": "stdout", - "text": "Atom fd4199d4-4d1a-425c-8010-60efca65bd1c:\n - Position: [0.5 4. 6. ]\n - Velocity: [-1. -2. 3.]\nAtom f9a32d14-b638-4796-9407-4b1ae6be43cb:\n - Position: [6. 8. 8.]\n - Velocity: [ 3. -3. 3.]\nAtom db96a76f-4d70-4e19-b460-46ee286f831e:\n - Position: [9. 4. 0.]\n - Velocity: [2. 1. 0.]\n" + "output_type": "stream", + "text": [ + "Atom fd4199d4-4d1a-425c-8010-60efca65bd1c:\n", + " - Position: [0.5 4. 6. ]\n", + " - Velocity: [-1. -2. 3.]\n", + "Atom f9a32d14-b638-4796-9407-4b1ae6be43cb:\n", + " - Position: [6. 8. 8.]\n", + " - Velocity: [ 3. -3. 3.]\n", + "Atom db96a76f-4d70-4e19-b460-46ee286f831e:\n", + " - Position: [9. 4. 0.]\n", + " - Velocity: [2. 1. 0.]\n" + ] } ], "source": [ @@ -296,7 +321,11 @@ "source": [] } ], - "metadata": {}, + "metadata": { + "language_info": { + "name": "python" + } + }, "nbformat": 4, "nbformat_minor": 2 } diff --git a/docs/source/ontologies_included.md b/docs/source/ontologies_included.md index 5b40f58..d8ae60b 100644 --- a/docs/source/ontologies_included.md +++ b/docs/source/ontologies_included.md @@ -15,22 +15,22 @@ your ontology to be shipped with SimPhoNy. The included ontologies, together with their domains of application, are listed below. -- [Elementary Multiperspective Material Ontology (EMMO)](ontologies_included.html#elementary-multiperspective-material-ontology-emmo) +- [Elementary Multiperspective Material Ontology (EMMO)](#elementary-multiperspective-material-ontology-emmo) \- Applied sciences -- [Dublin Core Metadata Initiative (DCMI)](ontologies_included.html#dublin-core-metadata-initiative-dcmi) +- [Dublin Core Metadata Initiative (DCMI)](#dublin-core-metadata-initiative-dcmi) \- Metadata description -- [Data Catalog Vocabulary - Version 2 (DCAT2)](ontologies_included.html#data-catalog-vocabulary-version-2-dcat2) +- [Data Catalog Vocabulary - Version 2 (DCAT2)](#data-catalog-vocabulary---version-2-dcat2) \- Data catalogue information -- [Friend of a Friend (FOAF)](ontologies_included.html#friend-of-a-friend-foaf) +- [Friend of a Friend (FOAF)](#friend-of-a-friend-foaf) \- People and information on the web -- [The PROV Ontology (PROV-O)](ontologies_included.html#the-prov-ontology-prov-o) +- [The PROV Ontology (PROV-O)](#the-prov-ontology-prov-o) \- Provenance information -- [The City Ontology](ontologies_included.html#the-city-ontology) +- [The City Ontology](#the-city-ontology) \- Example ontology aimed at demonstrating the usage of SimPhoNy OSP-core The ontologies can be installed providing the right _[package identifier](working_with_ontologies.md#keywords)_ to -[pico](utils.md#pico-installs-cuds-ontologies). You can find such +[pico](utils.md#pico). You can find such package identifier and additional information on each ontology by clicking on the links from the list above. @@ -111,7 +111,7 @@ pico install dcmitype dcterms ``` Note that due to the fact that -[RDFS properties are not supported by OSP-core](working_with_ontologies.html#rdfs-vocabularies), +[RDFS properties are not supported by OSP-core](working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies), the properties in these two vocabularies will be ignored. Only the classes will be detected. @@ -196,13 +196,13 @@ pico install prov ## The City ontology The City ontology is a -[simple, example ontology](ontology_intro.html#an-example-the-city-ontology) +[simple, example ontology](ontology_intro.md#an-example-the-city-ontology) included with OSP-core. It provides a collection of concepts to describe people and buildings in a city, and is aimed at demonstrating the usage of SimPhoNy OSP-core. To install the -[city ontology](ontology_intro.html#an-example-the-city-ontology), use +[city ontology](ontology_intro.md#an-example-the-city-ontology), use ```sh pico install city diff --git a/docs/source/overview.md b/docs/source/overview.md index e6e6b6d..13a8a40 100644 --- a/docs/source/overview.md +++ b/docs/source/overview.md @@ -94,10 +94,6 @@ The name ‘SimPhoNy’ stems from the SimPhoNy EU-project in which it was origi Here are some additional terms that are used throughout the documentation: -1. `API`: Application Programming Interface. A set of functions that allow the interaction with an application or system. -1. `OSP`: Open Simulation Platform. - A set of common standards and related tools that form the basic environment on top of which compatible and compliant simulation workflows can be developed and run. - An OSP does not contain any simulation tools itself, it is the common framework enabling to couple and link them. 1. `backend`: a third party application or service. Simulation engines and databases are examples of backends. 1. `wrapper`: a plugin for OSP-core that adds support to a new backend. @@ -115,5 +111,3 @@ Here are some additional terms that are used throughout the documentation: - CUDS exposes an API that provides CRUD (Create, Read, Update and Delete) functionalities. - CUDS is a recursive data structure in that a CUDS object may contain other CUDS objects. - CUDS is the fundamental data type of OSP-core, a framework that establishes interoperability between software systems that are built on top of ontologies. -1. `CUDS class`: represents an ontology class (a concept) and encodes its ontological information. -1. `CUDS object`: is an instance of a CUDS class and represents an ontology individual. diff --git a/docs/source/utils.md b/docs/source/utils.md index d64fb82..ac6eac4 100644 --- a/docs/source/utils.md +++ b/docs/source/utils.md @@ -3,7 +3,7 @@ In this section we will compile a list of useful utility functions, tools and examples of their usage. These functions are part of OSP-core and are used as an extension of the [main API](./detailed_design.md#cuds-api). -## pico (Pico Installs Cuds Ontologies) +## pico Our tool for installing ontologies is called `pico`. It is a recursive acronym that stands for _Pico Installs Cuds Ontologies_. From a3b49204299f11a10e73586f110a1b8ec1190421 Mon Sep 17 00:00:00 2001 From: Pablo de Andres <9430234+pablo-de-andres@users.noreply.github.com> Date: Mon, 1 Aug 2022 09:34:35 +0200 Subject: [PATCH 8/9] Update pre-commit args (#215) * Update args for black and isort * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Bump version of black back Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .pre-commit-config.yaml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a2834a1..03f5fae 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -23,10 +23,14 @@ repos: rev: 22.6.0 hooks: - id: black - args: [--line-length, "79"] + args: + - --line-length=79 - repo: https://github.com/pycqa/isort rev: 5.10.1 hooks: - id: isort - args: [--profile, black, --filter-files, --line-length, "79"] + args: + - --profile=black + - --filter-files + - --line-length=79 From 6883e2f4867378464cfb051f63f99ce09c1d1586 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Manuel=20Dom=C3=ADnguez?= <43052541+kysrpex@users.noreply.github.com> Date: Wed, 7 Dec 2022 13:51:51 +0100 Subject: [PATCH 9/9] Bump version to 3.9.0 (#247) * Fix minor issue with tip boxes in import_export.ipynb and ontology_interface.ipynb * Bump version to 3.9.0 --- docs/source/jupyter/cuds_api.ipynb | 6 +++--- docs/source/jupyter/import_export.ipynb | 5 ++--- docs/source/jupyter/ontology_interface.ipynb | 9 +++------ docs/source/jupyter/wrapper_development.ipynb | 2 +- docs/source/links.md | 5 ++++- docs/source/utils.md | 6 +++--- 6 files changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/source/jupyter/cuds_api.ipynb b/docs/source/jupyter/cuds_api.ipynb index d972b39..4e9f092 100644 --- a/docs/source/jupyter/cuds_api.ipynb +++ b/docs/source/jupyter/cuds_api.ipynb @@ -8,7 +8,7 @@ "\n", "
\n", "\n", - "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/simphony/docs/master?filepath=docs%2Fsource%2Fjupyter%2Fcuds_api.ipynb \"Click to run the tutorial yourself!\")\n", + "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/simphony/docs/v3.9.0?filepath=docs%2Fsource%2Fjupyter%2Fcuds_api.ipynb \"Click to run the tutorial yourself!\")\n", " \n", "
\n", "\n", @@ -88,7 +88,7 @@ } }, "source": [ - "The first step is to install the city ontology. Use the tool pico for this. If you want to know more about ontology installation, check the documentation on the [pico ontology installation tool](https://simphony.readthedocs.io/en/latest/utils.html#pico-installs-cuds-ontologies), [YAML ontology installation files](https://simphony.readthedocs.io/en/latest/working_with_ontologies.html#osp-core-yaml-ontology-format), and [installing OWL ontologies](https://simphony.readthedocs.io/en/latest/working_with_ontologies.html#owl-ontologies-and-rdfs-vocabularies)." + "The first step is to install the city ontology. Use the tool pico for this. If you want to know more about ontology installation, check the documentation on the [pico ontology installation tool](https://simphony.readthedocs.io/en/v3.9.0/utils.html#pico-installs-cuds-ontologies), [YAML ontology installation files](https://simphony.readthedocs.io/en/v3.9.0/working_with_ontologies.html#osp-core-yaml-ontology-format), and [installing OWL ontologies](https://simphony.readthedocs.io/en/latest/working_with_ontologies.html#owl-ontologies-and-rdfs-vocabularies)." ] }, { @@ -552,7 +552,7 @@ } }, "source": [ - "The existing ontology individuals and the relationships among them have been depicted below, using the utility `pretty_print` (see the [Utilities section](https://simphony.readthedocs.io/en/latest/utils.html?highlight=pretty_print)). Note that some attributes that were not specified were set automatically to the default values specified in the ontology." + "The existing ontology individuals and the relationships among them have been depicted below, using the utility `pretty_print` (see the [Utilities section](https://simphony.readthedocs.io/en/v3.9.0/utils.html?highlight=pretty_print)). Note that some attributes that were not specified were set automatically to the default values specified in the ontology." ] }, { diff --git a/docs/source/jupyter/import_export.ipynb b/docs/source/jupyter/import_export.ipynb index 870714e..3bcdf2b 100644 --- a/docs/source/jupyter/import_export.ipynb +++ b/docs/source/jupyter/import_export.ipynb @@ -15,7 +15,7 @@ "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", + "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/simphony/docs/v3.9.0?filepath=docs%2Fsource%2Fjupyter%2Fimport_export.ipynb \"Click to run the tutorial yourself!\")\n", " \n", "
\n", "\n", @@ -33,8 +33,7 @@ "The full API specifications of the import and export functions can be found in the\n", "[utilities API reference page](../api_ref.md#osp.core.utils.export_cuds).\n", " \n", - "\n", - "\n" + "" ] }, { diff --git a/docs/source/jupyter/ontology_interface.ipynb b/docs/source/jupyter/ontology_interface.ipynb index c1aff06..5f2037a 100644 --- a/docs/source/jupyter/ontology_interface.ipynb +++ b/docs/source/jupyter/ontology_interface.ipynb @@ -8,7 +8,7 @@ "\n", "
\n", "\n", - "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/simphony/docs/master?filepath=docs%2Fsource%2Fjupyter%2Fontology_interface.ipynb \"Click to run the tutorial yourself!\")\n", + "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/simphony/docs/v3.9.0?filepath=docs%2Fsource%2Fjupyter%2Fontology_interface.ipynb \"Click to run the tutorial yourself!\")\n", " \n", "
\n", "\n", @@ -212,14 +212,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "
\n", - "
\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", + " \n", "
" ] }, diff --git a/docs/source/jupyter/wrapper_development.ipynb b/docs/source/jupyter/wrapper_development.ipynb index e1c5a60..ac752e8 100644 --- a/docs/source/jupyter/wrapper_development.ipynb +++ b/docs/source/jupyter/wrapper_development.ipynb @@ -8,7 +8,7 @@ "\n", "
\n", "\n", - "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/simphony/docs/master?filepath=docs%2Fsource%2Fjupyter%2Fwrapper_development.ipynb \"Click to run the tutorial yourself!\")\n", + "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/simphony/docs/v3.9.0?filepath=docs%2Fsource%2Fjupyter%2Fwrapper_development.ipynb \"Click to run the tutorial yourself!\")\n", " \n", "
\n", "\n", diff --git a/docs/source/links.md b/docs/source/links.md index 0fa64a6..86af25b 100644 --- a/docs/source/links.md +++ b/docs/source/links.md @@ -51,7 +51,10 @@ demonstrated under the project https://github.com/simphony/simphony-common. # Compatibility table -The following table describes the compatibilities between of SimPhoNy docs and OSP-core. +The following table describes the compatibilities between the SimPhoNy docs and +OSP-core up to version 2.5.1 of the documentation. For later releases, the +version number of the documentation matches the version number of the OSP-core +release to which it applies. ```{eval-rst} diff --git a/docs/source/utils.md b/docs/source/utils.md index ac6eac4..67b2137 100644 --- a/docs/source/utils.md +++ b/docs/source/utils.md @@ -132,17 +132,17 @@ Each function is used in a similar way to its command-line counterpart. type, which can be either paths to `yml` ontology installation files or names of ontologies that can be installed via this shortcut. It is meant to clone the - [behavior of its command-line counterpart](https://simphony.readthedocs.io/en/latest/utils.html#pico-installs). + [behavior of its command-line counterpart](https://simphony.readthedocs.io/en/v3.9.0/utils.html#pico-installs). - `uninstall`: accepts _one or more_ positional arguments of string type, which must be names of already installed ontology packages. It also - clones the [behavior of its command-line counterpart](https://simphony.readthedocs.io/en/latest/utils.html#pico-uninstalls). + clones the [behavior of its command-line counterpart](https://simphony.readthedocs.io/en/v3.9.0/utils.html#pico-uninstalls). - `packages`: accepts no arguments and returns an [iterator](https://wiki.python.org/moin/Iterator) over the names of the installed packages. - `namespaces`: accepts no arguments and returns an iterator yielding one - [`OntologyNamespace` object](https://simphony.readthedocs.io/en/latest/api_ref.html#osp.core.ontology.namespace.OntologyNamespace) for each installed namespace. + [`OntologyNamespace` object](https://simphony.readthedocs.io/en/v3.9.0/api_ref.html#osp.core.ontology.namespace.OntologyNamespace) for each installed namespace. Usage examples: