From cefa2346c1be2ac808978ccb362aa856e4b6026c Mon Sep 17 00:00:00 2001 From: kysrpex Date: Thu, 1 Apr 2021 13:34:38 +0000 Subject: [PATCH 1/5] Create draft PR for #81 From 6b3cafc1db2781425af1cb36a1c3c8e44a681b3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Manuel=20Dom=C3=ADnguez?= Date: Tue, 6 Apr 2021 10:01:32 +0200 Subject: [PATCH 2/5] Changed ordering and categories of sections. --- docs/source/index.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index 3508590..41d5bb5 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -24,7 +24,6 @@ Here you can browse though the general documentation of SimPhoNy. installation.md jupyter/cuds-api.ipynb jupyter/sessions_and_vars.ipynb - detailed_design.md utils.md .. toctree:: @@ -44,9 +43,14 @@ Here you can browse though the general documentation of SimPhoNy. jupyter/multiple-wrappers.ipynb jupyter/simlammps.ipynb jupyter/quantum-espresso.ipynb + + +.. toctree:: + :caption: For developers + wrapper_development.md jupyter/wrapper_development.ipynb - + detailed_design.md .. toctree:: :caption: Additional From 4985b62d7ad292dc069ba3438adc10cf9a3280cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Manuel=20Dom=C3=ADnguez?= Date: Tue, 6 Apr 2021 10:02:39 +0200 Subject: [PATCH 3/5] Moved session inheritance scheme to wrapper development section. --- docs/source/getting_started.md | 73 +------------------------ docs/source/wrapper_development.md | 88 ++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 72 deletions(-) diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md index 1212794..106c3a3 100644 --- a/docs/source/getting_started.md +++ b/docs/source/getting_started.md @@ -202,78 +202,7 @@ other_entity = another_namespace.SomeOtherEntity() The sessions are the interoperability classes that connect to where the data is stored. In the case of wrappers, they take care of keeping consistency between the backends (e.g. databases) and the internal registry. -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. - -To simplify the understanding and development of session classes, we have created a hierarchy: - -```eval_rst -.. uml:: - :caption: Simplified session inheritance scheme - :align: center - - rectangle "OSP-core" as OSP { - abstract class Session { - } - - class CoreSession implements Session { - } - - abstract class WrapperSession extends Session { - } - - class TransportSession implements WrapperSession { - } - - abstract class DbWrapperSession extends WrapperSession { - commit() - } - - abstract class SqlWrapperSession extends DbWrapperSession { - } - - abstract class SimWrapperSession extends WrapperSession { - run() - } - } - - rectangle "Sqlite wrapper" as sqlite { - class SqliteWrapperSession implements SqlWrapperSession { - } - } - - rectangle "SqlAlchemy wrapper" as sqlalchemy { - class SqlAlchemyWrapperSession implements SqlWrapperSession { - } - } - - rectangle "Simlammps wrapper" as simlammps { - class SimlammpsSession implements SimWrapperSession { - } - } - - ' ----------------------- - ' -------- NOTES -------- - ' ----------------------- - note as OSP.note_core - The CoreSession is the default - shared session for all Python objects - end note - OSP.note_core .. CoreSession - - note as note_db - The db changes are persisted via - cuds_object.session.commit() - end note - note_db .. DbWrapperSession - - note as OSP.note_sim - The simulation is run by calling - cuds_object.session.run() - end note - OSP.note_sim .. SimWrapperSession -``` - -As you can see, CoreSession is the default one used when instantiating a new object in your workspace. +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 diff --git a/docs/source/wrapper_development.md b/docs/source/wrapper_development.md index f41cb33..4b61247 100644 --- a/docs/source/wrapper_development.md +++ b/docs/source/wrapper_development.md @@ -96,6 +96,94 @@ This allows us to group and clearly define which components should and which one - [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 +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 +sessions. + +```eval_rst +.. uml:: + :caption: Simplified session inheritance scheme + :align: center + + rectangle "OSP-core" as OSP { + abstract class Session { + } + + class CoreSession implements Session { + } + + abstract class WrapperSession extends Session { + } + + class TransportSession implements WrapperSession { + } + + abstract class DbWrapperSession extends WrapperSession { + commit() + } + + abstract class TripleStoreWrapperSession extends DbWrapperSession { + } + + abstract class SqlWrapperSession extends TripleStoreWrapperSession { + } + + abstract class SimWrapperSession extends WrapperSession { + run() + } + } + + rectangle "Sqlite wrapper" as sqlite { + class SqliteWrapperSession implements SqlWrapperSession { + } + } + + rectangle "SqlAlchemy wrapper" as sqlalchemy { + class SqlAlchemyWrapperSession implements SqlWrapperSession { + } + } + + rectangle "Your wrapper" as yourwrapper { + class YourSession{ + } + } + + rectangle "Simlammps wrapper" as simlammps { + class SimlammpsSession implements SimWrapperSession { + } + } + + ' ----------------------- + ' -------- NOTES -------- + ' ----------------------- + note as OSP.note_core + The CoreSession is the default + shared session for all Python objects + end note + OSP.note_core .. CoreSession + + note as note_db + The db changes are persisted via + cuds_object.session.commit() + end note + note_db .. DbWrapperSession + + note as OSP.note_sim + The simulation is run by calling + cuds_object.session.run() + end note + OSP.note_sim .. SimWrapperSession +``` + ## Engine installation Most engines will require some sort of compilation or installation before being able to use them through Python. From 1b6ac9f67f5bd902409e7d9aebb14c3c5573e52f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Manuel=20Dom=C3=ADnguez?= Date: Tue, 6 Apr 2021 10:05:12 +0200 Subject: [PATCH 4/5] Missing space. --- docs/source/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/index.md b/docs/source/index.md index 41d5bb5..063e80f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -52,6 +52,7 @@ Here you can browse though the general documentation of SimPhoNy. jupyter/wrapper_development.ipynb detailed_design.md + .. toctree:: :caption: Additional :maxdepth: 2 From 3a20ffc1fae43a2197c8c7c7cb85309ee72181d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Manuel=20Dom=C3=ADnguez?= Date: Fri, 9 Apr 2021 11:15:25 +0200 Subject: [PATCH 5/5] Code review suggestions. --- docs/source/getting_started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md index 106c3a3..4abbb4e 100644 --- a/docs/source/getting_started.md +++ b/docs/source/getting_started.md @@ -199,8 +199,8 @@ other_entity = another_namespace.SomeOtherEntity() ``` ### Sessions -The sessions are the interoperability classes that connect to where the data is stored. -In the case of wrappers, they take care of keeping consistency between the backends (e.g. databases) and the internal registry. +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.