API Reference
+ +``` +This document is for developers and/or advanced users of OSP-core, it contains all API details. -## Cuds class +## CUDS ```eval_rst .. autoclass:: osp.core.cuds.Cuds :members: :show-inheritance: ``` -## Registry class +## Ontology interface ```eval_rst -.. autoclass:: osp.core.session.registry.Registry +.. 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: ``` -## Session classes +## Sessions ```eval_rst .. autoclass:: osp.core.session.session.Session :members: @@ -42,7 +72,14 @@ This document is for developers of OSP-core, it contains the API functions :show-inheritance: ``` -## utils +## Registry +```eval_rst +.. autoclass:: osp.core.session.registry.Registry + :members: + :show-inheritance: +``` + +## Utilities ```eval_rst .. autoclass:: osp.core.utils.cuds2dot.Cuds2dot :members: diff --git a/docs/source/conf.py b/docs/source/conf.py index d6522b6..2bbab9b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -12,22 +12,23 @@ # -- Project information ----------------------------------------------------- project = 'SimPhoNy' # Version is given in setuptools -copyright = '2020, Materials Data Science and Informatics team at Fraunhofer IWM' +copyright = ('2021, Materials Data Science and ' + 'Informatics Team at Fraunhofer IWM') author = 'Materials Data Science and Informatics team at Fraunhofer IWM' # -- General configuration --------------------------------------------------- extensions = [ - 'recommonmark', # md + 'recommonmark', # 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.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', # Jupyter - Syntax highlight workaround + 'IPython.sphinxext.ipython_console_highlighting', # nb syntax highlight 'sphinx.ext.autosectionlabel', # Auto-generate section labels. - 'sphinx-jsonschema' # Generate JSON schema for serialized CUDS + 'sphinx_panels' # Create panels in a grid layout or as drop-downs ] master_doc = 'index' @@ -35,14 +36,11 @@ plantuml = 'java -jar lib/plantuml.jar' plantuml_output_format = 'svg_img' -templates_path = ['_templates'] - # 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' @@ -55,14 +53,12 @@ latex_documents = [('index', 'SimPhoNy_docs.tex', 'SimPhoNy documentation', - 'Materials Data Science and Informatics team at Fraunhofer IWM', + ('Materials Data Science and ' + 'Informatics team at Fraunhofer IWM'), "manual", - "false", - ),] + "false",)] latex_logo = '_static/img/simphony_logo_dark.png' -latex_elements = { 'figure_align': 'H', - } - +latex_elements = {'figure_align': 'H'} def setup(app): diff --git a/docs/source/contact.md b/docs/source/contact.md index 4293900..3003224 100644 --- a/docs/source/contact.md +++ b/docs/source/contact.md @@ -3,6 +3,6 @@ If you see something wrong, missing, or in need of clarification, you can direct create an issue in [here](https://github.com/simphony/docs/issues). Any other questions, issues or comments can be directed to [Pablo de Andres](mailto:pablo.de.andres@iwm.fraunhofer.de), -[Matthias Urban](mailto:matthias.urban@iwm.fraunhofer.de) and +[Jose Manuel Dominguez](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. \ No newline at end of file +from the Materials Data Science and Informatics Team, Fraunhofer IWM. diff --git a/docs/source/contribute.md b/docs/source/contribute.md index 325c0cb..2774f1b 100644 --- a/docs/source/contribute.md +++ b/docs/source/contribute.md @@ -43,6 +43,14 @@ All wrappers and OSP-core are part of a common directory structure: The changes should be clearly explained in the issue/Pull Request. - Once the features for a release have been reached, `dev` will be merged to `master/main`, every commit in the `master/main` branch theoretically being a new release. +In the next image it can be seen how the branches usually look during this workflow, and the different commits used to synchronise them: + +![](\"attachment:1de166aa-9888-4fe1-9794-406012a2ebe4.png\")
\n",
+ " Time flies like an arrow
- - From a syntactic perspective, we can see that _time_ is the subject. A noun. - _Flies_ is the verb, and so on. - If we analyse literally the meaning, we can picture time moving with a motion alike that of an arrow. - - On the other hand, we know the real meaning of the sentence is different. - Here we can deduce that the arrow is used to represent a fast movement, - and that characteristic is then applied to time. This is the semantic knowledge. - - In a semantic approach, we don't just see words as a series of symbols, but as a link to a sign. - And we can apply different rules and behaviours to different concepts because of the properties inherent to each entity. - - If we now look at: - -Fruit flies like a banana
- - The moment we get to the word _banana_, - we realise something is wrong. Syntactically, this sentence could be equivalent to the previous one. - However, we know that _bananas_ do not usually fly. - And so we decide to change the syntactic interpretation. - _Fruit flies_ becomes the subject, _like_ the verb and _a banana_ the object. - Now it makes sense semantically as well. - - In this semantic realm, the concept of ontologies that will be presented in further sections plays a major role. -#### Requirement simplification - Since we know what a user means from the semantic approach, - we can use this to automatise and simplify the setup and initialisation of processes using default settings. - - For example, a user could decide they want to run a simple simulation, with a certain level of detail - (let's say low, medium or high). - This could be translated into a meaningful initial state that might suffice a general situation. -#### Coupling and linking - In the domain of physics simulations, another interesting use case is coupling and linking. - - For example, a certain engine might be useful for representing structures made up of atomistic particles - (molecular dynamics). - - Another software tool could be focussed on representing bodies of fluids (fluid dynamics). - If both tools can communicate (i.e. there exists some interoperability between them), - they could both be run and synced simultaneously to create more complex scenarios. - - Furthermore, a truly interoperable platform would enable users to store and - access data in databases or other repositories of information. - - - diff --git a/docs/source/ontologies_included.md b/docs/source/ontologies_included.md index 18a69f0..3474e0d 100644 --- a/docs/source/ontologies_included.md +++ b/docs/source/ontologies_included.md @@ -22,14 +22,11 @@ pico install city Take a look at our [examples](jupyter/cuds-api.md) to see how you can build your own city! -## Working with EMMO using OSP-core +## Working with EMMO The second ontology that is ready to be used out of the box is the European -Materials Modelling Ontology, or EMMO in short. This ontology is an effort -to develop an ontology for applied sciences. It is based on physics, -analytical philosophy and information and communication technologies. -Its source code is open and [available on Github](https://github.com/emmo-repo/EMMO). -If you want to develop an emmo compliant ontology, see [the documentation](https://ontology.pages.fraunhofer.de/documentation/latest/). +Materials Modelling Ontology, or EMMO in short. +For a short introduction, see the [fundamentals](./fundamentals.md#emmo). You can install EMMO using [Pico](utils.md#pico-installs-cuds-ontologies). diff --git a/docs/source/overview.md b/docs/source/overview.md new file mode 100644 index 0000000..10f4691 --- /dev/null +++ b/docs/source/overview.md @@ -0,0 +1,118 @@ +# Overview + +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. + +
+
+