Merge pull request #325 from ModECI/development

Mainly documentation updates

.gitignore

@@ -276,3 +276,9 @@ Thumbs.db #thumbnail cache on Windows
 /examples/MDF/RNN/iaf_example.net.nml
 /examples/MDF/RNN/iaf_example__lems.xml
 /examples/MDF/RNN/iaf_example_lems_definitions.xml
+/examples/PyTorch/simple_pytorch_to_mdf
+/examples/PyTorch/simple_pytorch_to_mdf_torchviz
+/examples/PyTorch/Translated_mlp_pure_mdf.json
+/examples/PyTorch/simple_pytorch_to_mdf.1
+/examples/MDF/NLP/TestNLP_3
+/examples/MDF/NLP/TestNLP

docs/MDF_specification.json

@@ -34,7 +34,7 @@
             }
         },
         "Graph": {
-            "definition": "A directed graph consisting of Node(s) connected via Edge(s)",
+            "definition": "A directed graph consisting of :class:`~Node`s (with :class:`~Parameter`s and :class:`~Function`s evaluated internally) connected via :class:`~Edge`s.",
             "allowed_parameters": {
                 "metadata": {
                     "type": "Union[Any, NoneType]",

docs/MDF_specification.yaml

@@ -29,7 +29,8 @@ specification:
                 type: Graph
                 description: The collection of graphs that make up the MDF model.
     Graph:
-        definition: A directed graph consisting of Node(s) connected via Edge(s)
+        definition: A directed graph consisting of :class:`~Node`s (with :class:`~Parameter`s
+            and :class:`~Function`s evaluated internally) connected via :class:`~Edge`s.
         allowed_parameters:
             metadata:
                 type: Union[Any, NoneType]

docs/README.md

@@ -54,7 +54,7 @@ The top level construct in MDF is Model, which may contain multiple <a href="#gr
 </table>
 
 ## Graph
-A directed graph consisting of Node(s) connected via Edge(s)
+A directed graph consisting of <a href="#node">Node</a>s (with <a href="#parameter">Parameter</a>s and <a href="#function">Function</a>s evaluated internally) connected via <a href="#edge">Edge</a>s.
 
 ### Allowed parameters
 <table>

docs/generate.py

@@ -4,9 +4,27 @@
 import json
 import types
 import yaml
+import shutil
 
-mod = Model(id="Simple")
+shutil.copy("../README.md", "sphinx/source/api/Introduction.md")
 
+for ex in [
+    "ACT-R",
+    "MDF",
+    "NeuroML",
+    "ONNX",
+    "PsyNeuLink",
+    "PyTorch",
+    "Quantum",
+    "WebGME",
+]:
+    shutil.copy(
+        "../examples/%s/README.md" % ex,
+        f"sphinx/source/api/export_format/{ex}/{ex}.md",
+    )
+
+
+mod = Model(id="Simple")
 
 doc = mod.generate_documentation(format="markdown")
 

docs/sphinx/source/api/Export.md

@@ -1,5 +1,6 @@
-## Supported export Models
-This is the list of currently supported models which MDF supports
+# Supported export and import formats
+
+This is the list of currently supported export/import formats which MDF supports
 
  - ACT-R [README](https://github.com/ModECI/MDF/tree/main/examples/ACT-R#readme)
  - NeuroML [README](https://github.com/ModECI/MDF/tree/main/examples/NeuroML#readme)

docs/sphinx/source/api/Installation.md

@@ -4,12 +4,45 @@
 
 Python (>=3.7)
 
-## Installation
+## Quick start
 
 ```
 pip install modeci_mdf
 ```
-## Additionally
+
+## Installation from source
+To install the MDF package from source and run it locally:
+
+### 1) Clone this repository
+```
+git clone https://github.com/ModECI/MDF.git
+```
+### 2) Change to the directory
+```
+cd MDF
+```
+### 3) Create a virtual environment (e.g. called `mdf-env`)
+```
+pip install virtualenv
+virtualenv mdf-env
+```
+### 4) Activate the virtual environment
+```
+source mdf-env/bin/activate
+```
+### 5) Install the package
+```
+pip install .
+```
+
+Alternatively, to install MDF plus all of the modules required for the export/import interfaces (e.g. PsyNeuLink, NeuroML):
+
+```
+pip install .[all]
+```
+
+
+## Additional dependencies
 
 To generate generate Graph images in MDF you require Graphviz which uses dot.
 

docs/sphinx/source/api/Specification.rst

@@ -32,7 +32,7 @@ Allowed child    Data Type           Description
 =====
 Graph
 =====
-A directed graph consisting of Node(s) connected via Edge(s)
+A directed graph consisting of `Nodes <#node>`__ (with `Parameters <#parameter>`__ and `Functions <#function>`__ evaluated internally) connected via `Edges <#edge>`__.
 
 **Allowed parameters**
 

docs/sphinx/source/api/export_format/ACT-R/ACT-R.md

@@ -14,7 +14,7 @@ The below graph represents the basic structure of all ACT-R models in MDF:
 There are also more detailed graphs [count.png](count.png) and
 [addition.png](addition.png) for each example.
 
-### Count Model
+## Count Model
 
 [ACT-R](count.lisp) | [JSON](count.json) | [YAML](count.yaml) | [Python Script](count.py) | [Graph](count.png)
 
@@ -39,7 +39,7 @@ The script can use any values specified in [count.lisp](count.lisp), so the
 model can be modified and run multiple times in order to test different values.
 The [count](count.png) graph represents this example.
 
-### Addition Model
+## Addition Model
 
 [ACT-R](addition.lisp) | [JSON](addition.json) | [YAML](addition.yaml) | [Python Script](addition.py) | [Graph](addition.png)
 

docs/sphinx/source/api/export_format/MDF/MDF.md

@@ -8,35 +8,37 @@ Examples of Python, JSON and YAML files to illustrate the structure and usage of
 
 [Python source](simple.py) | [JSON](Simple.json) | [YAML](Simple.yaml)
 
-A simple example with 2 [Nodes](../../docs/README.md#node) connected by an [Edge](../../docs/README.md#edge):
+A simple example with 2 [Nodes](https://mdf.readthedocs.io/en/latest/api/Specification.html#node) connected by an [Edge](https://mdf.readthedocs.io/en/latest/api/Specification.html#edge):
 
 ![simple](images/simple.png)
 
-With more detail on [Nodes](../../docs/README.md#node) (showing [Input Ports](../../docs/README.md#inputport) (green), [Parameters](../../docs/README.md#parameter) (blue) and [Output Ports](../../docs/README.md#output_port)) (red) and [Edges](../../docs/README.md#edge):
+With more detail on [Nodes](https://mdf.readthedocs.io/en/latest/api/Specification.html#node) (showing [Input Ports](https://mdf.readthedocs.io/en/latest/api/Specification.html#inputport) (green), [Parameters](https://mdf.readthedocs.io/en/latest/api/Specification.html#parameter) (blue) and [Output Ports](https://mdf.readthedocs.io/en/latest/api/Specification.html#output_port)) (red) and [Edges](https://mdf.readthedocs.io/en/latest/api/Specification.html#edge):
+
 
  ![simple_3](images/simple_3.png)
 
+
 ## ABCD
 
 [Python source](abcd.py) | [JSON](ABCD.json) | [YAML](ABCD.yaml)
 
-Another simple example with more [Nodes](../../docs/README.md#node).
+Another simple example with more [Nodes](https://mdf.readthedocs.io/en/latest/api/Specification.html#node).
 
 ![abcd](images/abcd.png)   ![abcd_3](images/abcd_3.png)
 
 ## Arrays
 
 [Python source](arrays.py) | [JSON](Arrays.json) | [YAML](Arrays.yaml)
 
-An example using arrays for [Parameters](../../docs/README.md#parameter) and weights on [Edges](../../docs/README.md#edge).
+An example using arrays for [Parameters](https://mdf.readthedocs.io/en/latest/api/Specification.html#parameter) and weights on [Edges](https://mdf.readthedocs.io/en/latest/api/Specification.html#edge).
 
 ![arrays](images/arrays.png)
 
 ## States
 
 [Python source](states.py) | [JSON](States.json) | [YAML](States.yaml)
 
-An example with [Nodes](../../docs/README.md#node) containing persistent [States](../../docs/README.md#state).
+An example with [Nodes](https://mdf.readthedocs.io/en/latest/api/Specification.html#node) containing persistent [States](https://mdf.readthedocs.io/en/latest/api/Specification.html#state).
 
 ![states](images/states.png)
 
@@ -45,15 +47,15 @@ An example with [Nodes](../../docs/README.md#node) containing persistent [States
 
 [Python source](abc_conditions.py) | [JSON](abc_conditions.json) | [YAML](abc_conditions.yaml)
 
-A simple 3 [Nodes](../../docs/README.md#node) graph with scheduling [Conditions](../../docs/README.md#condition). For more examples of conditions see [here](conditions/README.md).
+A simple 3 [Nodes](https://mdf.readthedocs.io/en/latest/api/Specification.html#node) graph with scheduling [Conditions](https://mdf.readthedocs.io/en/latest/api/Specification.html#condition). For more examples of conditions see [here](conditions/README.md).
 
 ![abc_conditions](images/abc_conditions.png)
 
 ## Parameters and Functions
 
 [Python source](params_funcs.py) | [JSON](ParametersFunctions.json) | [YAML](ParametersFunctions.yaml)
 
-A simple [Node](../../docs/README.md#node) with a number of different types of [Parameters](../../docs/README.md#parameter) (in blue; fixed and **stateful**) and [Functions](../../docs/README.md#function) (in purple; can be built in or ONNX based).
+A simple [Node](https://mdf.readthedocs.io/en/latest/api/Specification.html#node) with a number of different types of [Parameters](https://mdf.readthedocs.io/en/latest/api/Specification.html#parameter) (in blue; fixed and **stateful**) and [Functions](https://mdf.readthedocs.io/en/latest/api/Specification.html#function) (in purple; can be built in or ONNX based).
 
 ![params_funcs](images/params_funcs.png)
 

docs/sphinx/source/api/export_format/ONNX/ONNX.md

@@ -31,6 +31,8 @@ This is an example of a PyTorch model with 2 nodes. First, the [script](simple_a
 
 [Python source](simple_abc.py) | [JSON](abc.json) | [YAML](abc.yaml)
 
+**Note: Example still in development!**
+
 This is an example of a PyTorch model that is implemented in `onnx_mdf/examples/simple_abc.py`. The model code
 is very simple:
 
@@ -72,23 +74,14 @@ inner `B` module has a loop construct.
 ![ABC](abc.png)
 
 
-It is exported to ONNX via a combination of tracing and scripting. The resulting ONNX model looks something
-like this:
-
-![ABC ONNX IR](examples/abc_ir.png)
-
-This ONNX IR representation can be converted to MDF. To run this full example, execute this command:
-
-```
-$ simple-abc-example
-```
-
-You can see the converted MDF models in [JSON](examples/abc-mdf.json) and [YAML](examples/abc-mdf.yml):
+It is exported to ONNX via a combination of tracing and scripting.
 
 ### ABCD Branching Conditional Model
 
 [Python source](simple_abcd.py) | [JSON](abcd.json) | [YAML](abcd.yaml)
 
+**Note: Example still in development!**
+
 This is an example of a PyTorch model that have four components (A, B, C, D). We loop over the whole
 model 10 iterations. A is executed only on the first iteration, B is executed every iteration, C is
 executed every 5 times B is executed, and D is executed every 10 times B is executed. A, B, C, and D are
@@ -153,13 +146,3 @@ class ABCD(torch.nn.Module):
 The ONNX IR representation of this model is shown below. The small computation sub-graphs
 contained in the if and else body attributes are not shown. These are either a simple multiplication and addition or
 an identity.
-
-![ABCD ONNX IR](examples/abcd/abcd_ir.svg)
-
-To run this example, execute the following command:
-
-```
-$ simple-abcd-example
-```
-
-You can see the converted MDF models in [JSON](examples/abcd/abc-mdf.json) and [YAML](examples/abcd/abcd-mdf.yml):