Merge pull request #269 from ModECI/development

Release v0.4.1

.github/workflows/ci.yml

@@ -52,6 +52,10 @@ jobs:
     - name: Install package
       run: python -m pip install .[test]
 
+    - name: Version info for installed packages
+      run: |
+          pip list
+
     - name: Test package
       run: |
         python -m pytest -ra tests/*.py

.gitignore

@@ -1,3 +1,7 @@
+# No BSON in the repo
+*.bson
+
+/abc_conditions
 examples/ONNX/data
 examples/ONNX/*.onnx
 
@@ -258,3 +262,7 @@ Thumbs.db #thumbnail cache on Windows
 *.onnx
 /examples/AB.json
 /examples/AB.yaml
+/examples/MDF/params_funcs_example
+/examples/MDF/params_funcs_example_3
+/examples/MDF/params_funcs_example_3.png
+/examples/MDF/params_funcs_example.png

README.md

@@ -54,9 +54,11 @@ Successful interfacing of MDF to existing disciplinary standards (such as [ONNX]
 
 **[Model metadata](https://github.com/ModECI/MDF/blob/main/docs/README.md#model)** There is the ability to add “metadata” to the **model**, **graph**, **nodes** and many of their sub elements which provide additional information about that element. While the metadata should not be essential to the mathematical description of the behavior/structure of the element, it could be useful for human interpretability of its function/purpose, or used when it is mapped to a specific application for simulation/visualization. Metadata can be added to the top level model to specify contact information, citations, acknowledgements, pointers to sample data and benchmark results, and environments in which the specified model was originally implemented and any that have been validated to support its execution.
 
-<p align="center"><img src="docs/images/MDFgraph1.png" width="700px"><br/><sup><i><b>Fig 2:</b> A simple graph with 3 nodes and 2 edges expressed in MDF.</i></sup></p>
+<p align="center"><img src="https://github.com/ModECI/MDF/raw/main/docs/images/MDFgraph1.png" width="700px"><br/>
+<sup><i><b>Fig 2:</b> A simple graph with 3 nodes and 2 edges expressed in MDF.</i></sup></p>
 
-<p align="center"><img src="docs/images/MDFgraph2.png" width="700px"><br/><sup><i><b>Fig 3:</b> This graph illustrates the ability to specify behavior that extends beyond the directed flow through the graph. Here, Node 1 generates a random number and transmits that number to Node 2. Node 2 will only run if the number it receives from Node 1 is greater than 10.</i></sup></p>
+<p align="center"><img src="https://github.com/ModECI/MDF/raw/main/docs/images/MDFgraph2.png" width="700px"><br/>
+<sup><i><b>Fig 3:</b> This graph illustrates the ability to specify behavior that extends beyond the directed flow through the graph. Here, Node 1 generates a random number and transmits that number to Node 2. Node 2 will only run if the number it receives from Node 1 is greater than 10.</i></sup></p>
 
 ## Installation
 

docs/MDF_specification.json

@@ -56,16 +56,16 @@
             "allowed_children": {
                 "nodes": {
                     "type": "Node",
-                    "description": "One or more :class:`Node`\\(s) present in the graph"
+                    "description": "One or more :class:`Node`(s) present in the graph"
                 },
                 "edges": {
                     "type": "Edge",
-                    "description": "Zero or more :class:`Edge`\\(s) present in the graph"
+                    "description": "Zero or more :class:`Edge`(s) present in the graph"
                 }
             }
         },
         "Node": {
-            "definition": "The values from these are processed via a number of :class:`Function`\\(s) and one or more final values\nare calculated on the :class:`OutputPort`\\(s)",
+            "definition": "A self contained unit of evaluation receiving input from other nodes on :class:`InputPort`(s). The values from these are processed via a number of :class:`Function`(s) and one or more final values\nare calculated on the :class:`OutputPort`(s)",
             "allowed_parameters": {
                 "metadata": {
                     "type": "Union[Any, NoneType]",
@@ -83,15 +83,15 @@
                 },
                 "functions": {
                     "type": "Function",
-                    "description": "The :class:`Function`\\(s) for computation the node"
+                    "description": "The :class:`Function`(s) for computation the node"
                 },
                 "parameters": {
                     "type": "Parameter",
-                    "description": "Dictionary of :class:`Parameter`\\(s) for the node"
+                    "description": "Dictionary of :class:`Parameter`(s) for the node"
                 },
                 "output_ports": {
                     "type": "OutputPort",
-                    "description": "The :class:`OutputPort`\\(s) containing evaluated quantities from the node"
+                    "description": "The :class:`OutputPort`(s) containing evaluated quantities from the node"
                 }
             }
         },
@@ -117,7 +117,7 @@
             }
         },
         "Function": {
-            "definition": "A single value which is evaluated as a function of values on :class:`InputPort`\\(s) and other Functions",
+            "definition": "A single value which is evaluated as a function of values on :class:`InputPort`(s) and other Functions",
             "allowed_parameters": {
                 "metadata": {
                     "type": "Union[Any, NoneType]",
@@ -142,7 +142,7 @@
             }
         },
         "Parameter": {
-            "definition": "referencing other :class:`Parameter`\\(s)), be evaluated by an inbuilt function with args, or change from a\n:code:`default_initial_value` with a :code:`time_derivative`.",
+            "definition": "A parameter of the :class:`Node`, which can be: 1) a specific fixed :code:`value` (a constant (int/float) or an array) 2) a string expression for the :code:`value` referencing other named :class:`Parameter`(s). which may be stateful (i.e. can change value over multiple executions of the :class:`Node`); 3) be evaluated by an\ninbuilt :code:`function` with :code:`args`; 4) or change from a :code:`default_initial_value` with a :code:`time_derivative`.",
             "allowed_parameters": {
                 "metadata": {
                     "type": "Union[Any, NoneType]",
@@ -198,7 +198,7 @@
             }
         },
         "OutputPort": {
-            "definition": "connected by an :class:`Edge`",
+            "definition": "The :class:`OutputPort` is an attribute of a :class:`Node` which exports information to another :class:`Node` connected by an :class:`Edge`",
             "allowed_parameters": {
                 "metadata": {
                     "type": "Union[Any, NoneType]",
@@ -223,7 +223,7 @@
             }
         },
         "Edge": {
-            "definition": ":class:`OutputPort` to a receiver's :class:`InputPort`.",
+            "definition": "An :class:`Edge` is an attribute of a :class:`Graph` that transmits computational results from a sender's :class:`OutputPort` to a receiver's :class:`InputPort`.",
             "allowed_parameters": {
                 "metadata": {
                     "type": "Union[Any, NoneType]",

docs/MDF_specification.yaml

@@ -48,15 +48,16 @@ specification:
         allowed_children:
             nodes:
                 type: Node
-                description: One or more :class:`Node`\(s) present in the graph
+                description: One or more :class:`Node`(s) present in the graph
             edges:
                 type: Edge
-                description: Zero or more :class:`Edge`\(s) present in the graph
+                description: Zero or more :class:`Edge`(s) present in the graph
     Node:
-        definition: 'The values from these are processed via a number of :class:`Function`\(s)
-            and one or more final values
+        definition: 'A self contained unit of evaluation receiving input from other
+            nodes on :class:`InputPort`(s). The values from these are processed via
+            a number of :class:`Function`(s) and one or more final values
 
-            are calculated on the :class:`OutputPort`\(s)'
+            are calculated on the :class:`OutputPort`(s)'
         allowed_parameters:
             metadata:
                 type: Union[Any, NoneType]
@@ -71,13 +72,13 @@ specification:
                 description: Dictionary of the :class:`InputPort` objects in the Node
             functions:
                 type: Function
-                description: The :class:`Function`\(s) for computation the node
+                description: The :class:`Function`(s) for computation the node
             parameters:
                 type: Parameter
-                description: Dictionary of :class:`Parameter`\(s) for the node
+                description: Dictionary of :class:`Parameter`(s) for the node
             output_ports:
                 type: OutputPort
-                description: The :class:`OutputPort`\(s) containing evaluated quantities
+                description: The :class:`OutputPort`(s) containing evaluated quantities
                     from the node
     InputPort:
         definition: The :class:`InputPort` is an attribute of a Node which allows
@@ -101,7 +102,7 @@ specification:
                 type: Union[str, NoneType]
                 description: The data type of the input received at a port.
     Function:
-        definition: A single value which is evaluated as a function of values on :class:`InputPort`\(s)
+        definition: A single value which is evaluated as a function of values on :class:`InputPort`(s)
             and other Functions
         allowed_parameters:
             metadata:
@@ -135,10 +136,14 @@ specification:
 
                     and args attributes will be None.'
     Parameter:
-        definition: 'referencing other :class:`Parameter`\(s)), be evaluated by an
-            inbuilt function with args, or change from a
+        definition: 'A parameter of the :class:`Node`, which can be: 1) a specific
+            fixed :code:`value` (a constant (int/float) or an array) 2) a string expression
+            for the :code:`value` referencing other named :class:`Parameter`(s). which
+            may be stateful (i.e. can change value over multiple executions of the
+            :class:`Node`); 3) be evaluated by an
 
-            :code:`default_initial_value` with a :code:`time_derivative`.'
+            inbuilt :code:`function` with :code:`args`; 4) or change from a :code:`default_initial_value`
+            with a :code:`time_derivative`.'
         allowed_parameters:
             metadata:
                 type: Union[Any, NoneType]
@@ -194,7 +199,8 @@ specification:
                     str, NoneType]
                 description: The new value of the Parameter if the test is true
     OutputPort:
-        definition: connected by an :class:`Edge`
+        definition: The :class:`OutputPort` is an attribute of a :class:`Node` which
+            exports information to another :class:`Node` connected by an :class:`Edge`
         allowed_parameters:
             metadata:
                 type: Union[Any, NoneType]
@@ -220,7 +226,9 @@ specification:
                 type: Union[str, NoneType]
                 description: The data type of the output sent by a port.
     Edge:
-        definition: :class:`OutputPort` to a receiver's :class:`InputPort`.
+        definition: An :class:`Edge` is an attribute of a :class:`Graph` that transmits
+            computational results from a sender's :class:`OutputPort` to a receiver's
+            :class:`InputPort`.
         allowed_parameters:
             metadata:
                 type: Union[Any, NoneType]

docs/README.md

@@ -93,22 +93,22 @@ A directed graph consisting of Node(s) connected via Edge(s)
   <tr>
     <td><b>nodes</b></td>
     <td><a href="#node">Node</a></td>
-    <td><i>One or more <a href="#node">Node</a>\(s) present in the graph</i></td>
+    <td><i>One or more <a href="#node">Node</a>(s) present in the graph</i></td>
   </tr>
 
 
   <tr>
     <td><b>edges</b></td>
     <td><a href="#edge">Edge</a></td>
-    <td><i>Zero or more <a href="#edge">Edge</a>\(s) present in the graph</i></td>
+    <td><i>Zero or more <a href="#edge">Edge</a>(s) present in the graph</i></td>
   </tr>
 
 
 </table>
 
 ## Node
-The values from these are processed via a number of <a href="#function">Function</a>\(s) and one or more final values
-are calculated on the <a href="#outputport">OutputPort</a>\(s)
+A self contained unit of evaluation receiving input from other nodes on <a href="#inputport">InputPort</a>(s). The values from these are processed via a number of <a href="#function">Function</a>(s) and one or more final values
+are calculated on the <a href="#outputport">OutputPort</a>(s)
 
 ### Allowed parameters
 <table>
@@ -140,21 +140,21 @@ are calculated on the <a href="#outputport">OutputPort</a>\(s)
   <tr>
     <td><b>functions</b></td>
     <td><a href="#function">Function</a></td>
-    <td><i>The <a href="#function">Function</a>\(s) for computation the node</i></td>
+    <td><i>The <a href="#function">Function</a>(s) for computation the node</i></td>
   </tr>
 
 
   <tr>
     <td><b>parameters</b></td>
     <td><a href="#parameter">Parameter</a></td>
-    <td><i>Dictionary of <a href="#parameter">Parameter</a>\(s) for the node</i></td>
+    <td><i>Dictionary of <a href="#parameter">Parameter</a>(s) for the node</i></td>
   </tr>
 
 
   <tr>
     <td><b>output_ports</b></td>
     <td><a href="#outputport">OutputPort</a></td>
-    <td><i>The <a href="#outputport">OutputPort</a>\(s) containing evaluated quantities from the node</i></td>
+    <td><i>The <a href="#outputport">OutputPort</a>(s) containing evaluated quantities from the node</i></td>
   </tr>
 
 
@@ -197,7 +197,7 @@ The <a href="#inputport">InputPort</a> is an attribute of a Node which allows ex
 </table>
 
 ## Function
-A single value which is evaluated as a function of values on <a href="#inputport">InputPort</a>\(s) and other Functions
+A single value which is evaluated as a function of values on <a href="#inputport">InputPort</a>(s) and other Functions
 
 ### Allowed parameters
 <table>
@@ -243,8 +243,8 @@ and args attributes will be None.</i></td>
 </table>
 
 ## Parameter
-referencing other <a href="#parameter">Parameter</a>\(s)), be evaluated by an inbuilt function with args, or change from a
-<b>default_initial_value</b> with a <b>time_derivative</b>.
+A parameter of the <a href="#node">Node</a>, which can be: 1) a specific fixed <b>value</b> (a constant (int/float) or an array) 2) a string expression for the <b>value</b> referencing other named <a href="#parameter">Parameter</a>(s). which may be stateful (i.e. can change value over multiple executions of the <a href="#node">Node</a>); 3) be evaluated by an
+inbuilt <b>function</b> with <b>args</b>; 4) or change from a <b>default_initial_value</b> with a <b>time_derivative</b>.
 
 ### Allowed parameters
 <table>
@@ -341,7 +341,7 @@ A condition to test on a Node's parameters, which if true, sets the value of thi
 </table>
 
 ## OutputPort
-connected by an <a href="#edge">Edge</a>
+The <a href="#outputport">OutputPort</a> is an attribute of a <a href="#node">Node</a> which exports information to another <a href="#node">Node</a> connected by an <a href="#edge">Edge</a>
 
 ### Allowed parameters
 <table>
@@ -385,7 +385,7 @@ connected by an <a href="#edge">Edge</a>
 </table>
 
 ## Edge
-<a href="#outputport">OutputPort</a> to a receiver's <a href="#inputport">InputPort</a>.
+An <a href="#edge">Edge</a> is an attribute of a <a href="#graph">Graph</a> that transmits computational results from a sender's <a href="#outputport">OutputPort</a> to a receiver's <a href="#inputport">InputPort</a>.
 
 ### Allowed parameters
 <table>

docs/sphinx/source/api/Installation.md

@@ -9,3 +9,13 @@ Python (>=3.7)
 ```
 pip install modeci_mdf
 ```
+## Additionally
+
+To generate generate Graph images in MDF you require Graphviz which uses dot.
+
+```
+pip install graphviz
+```
+To render the generated DOT source code, you also need to install [Graphviz](https://www.graphviz.org/) ([download page](https://www.graphviz.org/download/), [installation procedure for Windows](https://forum.graphviz.org/t/new-simplified-installation-procedure-on-windows/224).
+
+Make sure that the directory containing the dot executable is on your system's PATH (sometimes done by the installer; setting PATH on [Linux](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix), [Mac](https://stackoverflow.com/questions/22465332/setting-path-environment-variable-in-osx-permanently), and [Windows](https://www.computerhope.com/issues/ch000549.htm).