Merge pull request #107 from pnnl/birmiwal.rahul_development

Birmiwal.rahul development

.github/workflows/update_docs.yml

@@ -0,0 +1,42 @@
+name: Automate Documentation Build #name of action
+
+on: #trigger event
+  push:
+    branches:
+      - master #execute on a push to master branch
+
+permissions:
+  contents: write #grant access to write to master branch
+
+jobs: #define set of jobs. Here there is only one job, each job is instantiated on a Github-hosted runner
+  docs: #name of the job
+    runs-on: ubuntu-latest #runner runs on latest version of Ubuntu
+    steps: #this job is associated with a series of steps
+
+      # step 1: syntax for telling GHA to use this repository's code as "root" directory. Rest of GHA is able to have access
+      - uses: actions/checkout@v3
+      # step 2: #syntax for telling GHA to set-up Python on this runner associated for this whole job
+      - uses: actions/setup-python@v3
+
+      # Step 3: define a step that install dependencies (Sphinx etc) for this runner
+      - name: Install dependencies #name of this step
+        run: | #indicate that following script is meant to be multi-line
+          pip install sphinx sphinx_rtd_theme myst_parser 
+
+      # Step 4: Build docs using sphinx. TZ=UTC needed to circumvent a nuance of running Sphinx on GHA runner
+      - name: Sphinx build
+        run: |
+          TZ=UTC sphinx-build docs html
+          
+      # Step 5: Deploy the newly built docs to gh-pages branch
+      - name: Deploy to GitHub Pages
+        #uses a github action "extension" called actions-gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/master' #ensure that we are on the master branch
+
+        #following is syntax for using actions-gh-pages action
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: html/ #docs to publish to html directory
+          force_orphan: true #common command associated with deploying a GitHub Page

README.md

@@ -151,7 +151,28 @@ problem = nm.problem.Problem(nodes=[map], loss=loss)
 
 ## Installation
 
-For either pip or conda installation, first clone the neuromancer package.
+### PIP Install (recommended)
+
+Consider using a dedicated virtual environment (conda or otherwise) with Python 3.9+ installed. 
+
+```bash
+pip install neuromancer
+```
+Example usage: 
+
+```bash
+import torch
+from neuromancer.system import Node
+
+fun_1 = lambda x1, x2: 2.*x1 - x2**2
+node_3 = Node(fun_1, ['y1', 'y2'], ['y3'], name='quadratic')
+# evaluate forward pass of the node with dictionary input dataset
+print(node_3({'y1': torch.rand(2), 'y2': torch.rand(2)}))
+
+```
+### Manual Install
+
+First clone the neuromancer package.
 A dedicated virtual environment (conda or otherwise) is recommended. 
 
 Note: If you have a previous neuromancer env it would be best at this point to create a new environment given the following instructions.
@@ -160,13 +181,6 @@ Note: If you have a previous neuromancer env it would be best at this point to c
 git clone -b master https://github.com/pnnl/neuromancer.git --single-branch
 ```
 
-### PIP Install
-Recommended installation.  
-Pip installation is broken up into required dependencies for core Neuromancer
-and dependencies associated with the examples, tests, and generating the documentation.
-Below we give instructions to install all dependencies in a conda virtual enviroment via pip. 
-You need at least pip version >= 21.3.
-
 #### Create and activate virtual environment
 
 ``` bash

docs/conf.py

@@ -37,6 +37,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.inheritance_diagram',
     'sphinx.ext.todo',
+    'sphinx.ext.githubpages',
     'sphinx.ext.viewcode'
 ]
 

docs/readme.md

@@ -1,44 +1,70 @@
-Instructions for updating the documentation and hosting on open source github repo.
-
-On the same level as your Neuromancer repo, make a docs directory 
-and then clone the gh-pages branch of the repo at github.com/pnnl/neuromancer
-
-```bash
-
-$ mkdir docs; cd docs
-$ git clone https://github.com/pnnl/neuromancer.git -b gh-pages --single-branch
-$ mv neuromancer html
-
-```
-
-You will want to install sphinx in order to autogenerate the documentation
-
-```bash
-
-$ conda activate neuromancer
-$ conda install sphinx -c anaconda
-$ conda install -c conda-forge sphinx_rtd_theme
-
-```
-Now navigate to the docs folder in neuromancer and run the makefile to generate docs. 
-
-
-```bash
-
-$ cd ../neuromancer/docs
-$ make html
-
-```
-
-Now navigate to the gh-pages branch you cloned (now called html instead of neuromancer).  
-Take a look at the generated documentation by loading index.html in your browser. 
-If everything looks good then add, commit, and push to the repo. 
-
-```bash
-
-$ cd ../../docs/html
-$ git add *.html; git add objects.inv; git add search_index.js
-$ git commit -m 'Added new documentation for NM version x.xx'
-$ git push origin gh-pages
-
-```
+#### Update: Automated Documentation Process 
+Documentation will now be built and deployed to gh-pages branch (https://pnnl.github.io/neuromancer/) automatically on 
+merge with master branch. This is done through a Github Actions (GHA) script found at ./github/workflows/update_docs.yml. 
+No need to manually build on your local machine. 
+
+For information on the update_docs.yml GHA script, please refer to the end of this readme.
+
+For reference, the manual instructions for updating the documentation is shown below: 
+
+#### Manual Process for Documentation Updates
+On the same level as your Neuromancer repo, make a docs directory 
+and then clone the gh-pages branch of the repo at github.com/pnnl/neuromancer
+
+```bash
+
+$ mkdir docs; cd docs
+$ git clone https://github.com/pnnl/neuromancer.git -b gh-pages --single-branch
+$ mv neuromancer html
+
+```
+
+You will want to install sphinx in order to autogenerate the documentation
+
+```bash
+
+$ conda activate neuromancer
+$ conda install sphinx -c anaconda
+$ conda install -c conda-forge sphinx_rtd_theme
+
+```
+Now navigate to the docs folder in neuromancer and run the makefile to generate docs. 
+
+
+```bash
+
+$ cd ../neuromancer/docs
+$ make html
+
+```
+
+Now navigate to the gh-pages branch you cloned (now called html instead of neuromancer).  
+Take a look at the generated documentation by loading index.html in your browser. 
+If everything looks good then add, commit, and push to the repo. 
+
+```bash
+
+$ cd ../../docs/html
+$ git add *.html; git add objects.inv; git add search_index.js
+$ git commit -m 'Added new documentation for NM version x.xx'
+$ git push origin gh-pages
+
+```
+
+#### Information on GitHub Actions
+GitHub Actions is a continuous integration platform that allows for a set of actions to be executed
+on any trigger event associated with any branch of a repository. GHA are defined in a yaml workflow (e.g)
+update_docs.yml. This particular workflow, update_docs.yml, will run on any push to the master branch. 
+GHA workflows are associated with a set of jobs. Each job is assigned a GitHub-hosted runner. A set of job(s) 
+gets triggered based on the "on" clause at the top of of the workflow -- in this case a push to master. 
+A job is defined as a set of steps. A step can be defined with a (uses, name, with, runs) block where uses defines the 
+prerequisite steps needed for the runner to execute the associated runs(s). In this case we tell the 
+runer to use the latest Ubuntu version. We also tell the runner to use python using the GHA syntactical sugar
+"actions/setup-python@v3". It also uses "this" repo using the GHA syntactical sugar actions/checkout@v3. 
+Step 3 in the workflow is equivalent to the install sphinx steps as outline in the manual process. Step 4
+is equivalent to the "make html" command in the manual process. Step 5 leverages a GHA "extension" called 
+actions-gh-pages (https://github.com/peaceiris/actions-gh-pages) to push the sphinx documentation to a 
+gh-pages branch. The syntax used here is specific to actions-gh-pages. Before deploying to the master branch, 
+we check that we are "on" the master branch. This statement might be obsolete due to the trigger event (push 
+to master) defined at the top of this workflow; however, it is included due to recommended use within actions-gh-pages
+

src/neuromancer/system.py

@@ -82,7 +82,7 @@ def forward(self, input):
         repeated ndelay times to initialize the buffer.
 
         :param input: (dict: str: 2-d tensor (batch, dim)) Dictionary of single step tensor inputs
-        :return: (dict: str: 2-d Tensor (batch, dim)) Dictionary of single step tensor outputs
+        :return: (dict: str: 3-d Tensor (ndelay, batch, dim)) Dictionary of tensor outputs
         """
         for k in self.input_keys:
             self.history[k].append(input[k])
@@ -254,6 +254,4 @@ def forward(self, input_dict):
                 indata = {k: data[k][:, i] for k in node.input_keys}  # collect what the compute node needs from data nodes
                 outdata = node(indata)  # compute
                 data = self.cat(data, outdata)  # feed the data nodes
-        return data  # return recorded system measurements
-
-
+        return data  # return recorded system measurements