Update documentation

README.rst

@@ -1,3 +1,5 @@
+.. !Only edit the file on the project root, as the one on docs/source is a copy!
+
 ************
 Introduction
 ************
@@ -27,3 +29,16 @@ while searching for object in a given room is left to separate tools.
 The package is designed as support tool for Assurance of Simulation Models, see DNV-RP-0513.
 
 The package is currently under development. More instructions and documentation will be added.
+
+Installation:
+-------------
+1.	Install the `sim-explorer` package: ``pip install sim-explorer``
+2.	Software dependencies: `matplotlib`, `numpy`, `libcosimpy`, `jsonpath-ng`
+3.	Latest release: Version 0.1, based on libcosimpy 0.0.2
+
+Contribute
+----------
+Anybody in the OSP community is welcome to contribute to this code, to make it better, 
+and especially including other features from model assurance, 
+as we firmly believe that trust in our models is needed 
+if we want to base critical decisions on the support from these models.

case_study/case.py

@@ -262,17 +262,17 @@ def read_spec_item(self, key: str, value: Any | None = None):
 
         In the simplest case, the key is a cases variable name. Optionally two elements can be added:
 
-        #. a range, denoted by `[range-spec]` : choosing elements of a multi-valued variable.
-          Note: when disecting the key, the actual length of the case variable is unknown, such that checks are limited.
-          Rules:
+        1. a range, denoted by `[range-spec]` : choosing elements of a multi-valued variable.
+           Note: when disecting the key, the actual length of the case variable is unknown, such that checks are limited.
+           Rules:
 
            * no '[]': addresses always the whole variable - scalar or multi-valued. rng = ''
            * '[int]': addresses a single element of a multi-valued variable. rng = 'int'
            * '[int,int, ...]': addresses several elements of a multi-valued variable. rng = 'int,int,...'
            * '[int...int]': addresses a range of elements of a multi-valued variable. rng = 'int:int', i.e. a slice
 
-        #. a time specification, denoted by `@time-spec` : action performed at specified time.
-          Rules:
+        2. a time specification, denoted by `@time-spec` : action performed at specified time.
+           Rules:
 
            * no '@': set actions are performed initially. get actions are performed at end of simulation (record final value)
            * @float: set/get action perfomred at specified time

docs/source/README.rst

@@ -1,3 +1,5 @@
+.. !Only edit the file on the project root, as the one on docs/source is a copy!
+
 ************
 Introduction
 ************
@@ -27,3 +29,16 @@ while searching for object in a given room is left to separate tools.
 The package is designed as support tool for Assurance of Simulation Models, see DNV-RP-0513.
 
 The package is currently under development. More instructions and documentation will be added.
+
+Installation:
+-------------
+1.	Install the `sim-explorer` package: ``pip install sim-explorer``
+2.	Software dependencies: `matplotlib`, `numpy`, `libcosimpy`, `jsonpath-ng`
+3.	Latest release: Version 0.1, based on libcosimpy 0.0.2
+
+Contribute
+----------
+Anybody in the OSP community is welcome to contribute to this code, to make it better, 
+and especially including other features from model assurance, 
+as we firmly believe that trust in our models is needed 
+if we want to base critical decisions on the support from these models.

docs/source/cases_specification.rst

@@ -1,38 +1,41 @@
 Cases specification format
 ==========================
 Cases specification is done using a json5-based format. 
-For an itroduction to the basic json format see `here <https://en.wikipedia.org/wiki/JSON>`_.
+For an introduction to the basic json format see `here <https://en.wikipedia.org/wiki/JSON>`_.
 Compared to that, the json5 variant has the following advantages
 
 * object (dict) keys do not need quotation marks
 * single and double quoted strings allowed
 * optional trailing commas
 * comments defined
 * json5 files can readily be transformed to full json format
+* jsonpath expressions working on the internal python representation work both on Json and Json5.
 
 Json5 is also used in other software, like SQLite.
 The main point for choosing json5 is thus its easier readability by humans,
 while it is still readily readable by machines.
 
 Cases files use the following general layout::
 
-    {header-lines,
-    variables : {
-        alias-variable-definition-lines
+    {header : {
+        name : exploration-project-name,
+        variables : {
+            alias-variable-definition-lines
+        },
+        optional-header-elements,
     },
     base : {
         optional description : "description-text",
         spec : {
             spec-lines,
+        optional-results-list,
+        optional-assert-sub-dict
     }},
     case-name : {
         case-specification-similar-to-base
     }
     # ... as many cases as desired
-    results : {
-        spec : [ # Note: this is a list of keys, as there are no values
-            results-spec-lines,   
-    ]}}
+}
 
 Header elements
 ---------------
@@ -62,11 +65,11 @@ The unique identification of a variable in a system requires an identificator co
 The identificators can thus become lengthy and difficult to work with. 
 In addition, there are system models with several components from the same model, where the user might want to address all of them (e.g. max power setting of thrusters). Moreover, FMI2 knows only scalar variables, while it would be nice to also be able to work with vectors, tables and their elements. 
 Therefore case study adops the principle that case variables are speparately defined. 
-The `variables` entry is a dictionary where one element is specified as
+The `variables` entry is a dictionary where each element is specified as
 
 `identificator : [component(s), variable_name(s), description]` 
 
-In more details
+In more detail
 
 *identificator* (key, mandatory)
     Case variable identificator unique within the whole system. 
@@ -80,6 +83,8 @@ In more details
     Variable name as specified in the modelDescription of the component.
     If several variables are specified the entry becomes a list and the variables shall have 
     the same properties with respect to type, causality and variability.
+    For example `pos[\*]` denotes all elements of a vector if modelDescription specifies pos[0], pos[1] and pos[2].
+
     Note that it is not required that the units of the variables in the list are the same. 
     For example a vector in spherical coordinates has length as first element and angle as second and third.
 *description* (optional)
@@ -89,11 +94,19 @@ A few examples of case variable definitions are
 
 * `g : ['bb', 'g', "Gravity acting on the ball"]`
 * `p_max : [['thruster1','thruster2'], 'max_power', 'Maximum power setting of all thrusters in the system']`
+
+   which could be abbreviated to 
+
+   `p_max : ['thruster\*, 'max_power, 'Maximum power setting of all thrusters in the system']`
 * `pos : ['pendulum', ['pendulum_length', 'pendulum_polar', 'pendulum_azimuth'], 'Position of pendulum in spherical coordinates']`
 
+   which could be abbreviated to 
+
+   `pos : ['pendulum', 'pendulum_\*', 'Position of pendulum in spherical coordinates']`
+
 Case specification
 ------------------
-A case specification conists of the elments
+A case specification consists of the elments
 
 *description* (optional)
     A optional, but highly recommended description of the case can be provided
@@ -102,35 +115,51 @@ A case specification conists of the elments
     Otherwise a case is assumed to be based on the `base` case (see below).
     In this way a hierarchy of case specifications can be built. 
     If this is done in a suitable way it can simplify case specifications considerably by avoiding a lot of double specification
-    and possible errors due to changes in paren cases which are not reflected in their children.
-    The special cases `base` and `results` shall not have parents (see below).
+    and possible errors due to changes in parent cases which are not reflected in their children.
+    The special case `base` shall not have a parent (see below).
 *spec* (mandatory)
     A dictionary of case variables and values, specifying the variable settings of the case, i.e. `variable : value(s)` . Details see below.
+*results* (optional)
+    An optional list of result variables (details see below)
+*assert* (optional)
+    An optional dictionary of assertion expressions, providing the possibility to automatically check model results. Details see below.
+
 
+The mandatory case *base*:
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+The base case, listing the base variable settings. All other cases are based on these settings. 
+It is not allowed to set variables in other cases if they are not set in the base case, as this would lead to moving targets, 
+i.e. the base case results would change after another case has been run.
 
-There are two special, mandatory cases:
+It is recommended to specify all general results as part of the `base` specification (see below)
 
-*base*
-    the base case, listing the base variable settings. All other cases are based on these settings. 
-    It is not allowed to set variables in other cases if they are not set in the base case, as this would lead to moving targets, 
-    i.e. the base case results would change after another case has been run.
-*results*
-    listing of results variables. 
-    Note that the variable specification consists only of case variables and no values and thus is represented by a  list, not a dictionary!
+Within consistent case specifications all case variables are used in the cases `base` (avoid unused case variables)
 
-Within consistent case specifications all case variables are used in the cases `base` or `results` (avoid unused case variables) 
 and variables which are set in a case are always also set in the case `base` (avoid moving targets).
 
+Specification of *results*:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+As part of the case specification, it is also specified which results should be retrieved:
+
+* All initial settings are automatically recorded at start time and are thus automaticaly included in the results Json5 file.
+* A case may specify a `result` section, containing a list of result variables to be reported.
+
+   Note that the variable specification consists only of case variables and no values and thus is represented by a  list, not a dictionary!
+   In addition, Json rules imply that list values must include explicit quotation marks to be recognized as strings.
+* A variable specification may use the string `'result'` or `'res'` to mark the respective variable as a result variable.
+  If that syntax is used, the variable is a key, which does not need explicit quotation marks.
+
+
 Variable specification
 ----------------------
 In the simplest case a variable specification consists of a dictionary element
 
 * `case_variable : value`, 
 * `case_variable : [value1, value2, ...]` in the case of a vector variable, 
-* avoiding the value(s) altogether in the case of results specifications (see above) or
-* `case_variable : 'NoValue'` within a normal case, representing a special result setting which applies only to this case,
-  i.e. only for the respective case this result is recorded. 
-  This setting should be used with care, since it is normally desired to have the same results setup for all cases, such that all cases can be compared.
+* `case_variable : 'result' or 'res'` within a normal case, representing a special result setting which applies to this case and all sub-cases,
+
+   It is recommended that results specifications are mainly included in the base case, such that all cases report the same variables and can be readily compared.
+   Only in special circumstances should other cases add variables to the results.
 
 The variable name specification (the key) is much richer than the simple cases listed above. In general the `case_variable` can be replaced by
 
@@ -148,44 +177,10 @@ Both extensions apply also to results specifications, i.e. results collection at
 With respect to results there is an additional keyword 'step' which can be used. `@step` leads to results collection at every communication point and 
 `@step interval` leads to results collection at the given fixed time interval. 
 `interval` is in this case a float number which should be larger than the basic time step. 
-It should be noted step specifications do not change the simulation and results collections happen always at the first communication point after the time is due.
-
-Simple example BouncingBall.cases
----------------------------------
-A simple example of a cases specification, based on the standard BouncingBall FMU::
-
-    {name        : 'BouncingBall',
-     description : 'Simple Case Study with the basic BouncingBall FMU (ball dropped from h=1m',
-     modelFile : "OspSystemStructure.xml",
-     timeUnit  : "second",
-     variables : {
-         g : ['bb', 'g', "Gravity acting on the ball"],
-         e : ['bb', 'e', "Coefficient of restitution"],
-    },
-    base : {
-        description : "Variable settings for the base case. All other cases are based on that",
-        spec: {
-            stepSize : 0.1,
-            stopTime : '3',
-            g        : -9.81,
-    }},
-    case1 : {
-        description : "Smaller coefficient of restitution e",
-        spec: {
-        e : 0.35,
-        e@1 : 0.5, # change restitution at time 1
-    }},
-    case2 : {
-        description : "Based case1 (e change), change also the gravity g",
-        parent : 'case1',
-        spec : {
-            g : -1.5
-    }},
-    # ... other case definitions
-    results : {
-        spec : [
-            h@step, # example of 'h' at every communication point
-            v@1.0, # example of result only at time 1
-            e,
-            g,
-   ]}}
+It should be noted that step specifications do not change the simulation and results collections happen always at the first communication point after the time is due.
+
+Simple example BouncingBall3D.cases
+-----------------------------------
+A simple example of a cases specification, based on the standard 3D BouncingBall FMU:
+
+.. literalinclude:: ../../tests/data/BouncingBall3D/BouncingBall3D.cases

docs/source/conf.py

@@ -15,7 +15,7 @@
 import sys
 
 sys.path.insert(0, os.path.abspath("../.."))
-shutil.copyfile("../../README.rst", "readme.rst")
+shutil.copyfile("../../README.rst", "./readme.rst")
 
 
 # -- Project information -----------------------------------------------------

tests/data/SimpleTable/results.js5

@@ -1,10 +1,10 @@
 {
 header : {
       case : 'caseX',
-      dateTime : '2024-11-04T09:28:29.831192',
+      dateTime : '2024-11-04T11:44:47.998474',
       cases : 'Testing',
-      file : 'C:/Users/JORMEN/Documents/SeaCo/case_study/tests/data/SimpleTable/test.cases',
-      casesDate : '2024-11-04T09:04:34.599983',
+      file : 'C:/Users/eis/Documents/Projects/Simulation_Model_Assurance/case_study/tests/data/SimpleTable/test.cases',
+      casesDate : '2024-11-01T21:33:55.186531',
       timeUnit : 'second',
       timeFactor : 1000000000.0},