add .ipynb notebooks to document sympy & related routines

[lkeegan]

(more documentation to come in a later PR)

• nmodl-odes-overview contains a higher level overview of the approach to solving ODEs in nmodl
• nmodl-kinetic-schemes describes the Kinetic scheme maths & KineticBlockVisitor
• nmodl-sympy-solver describes the SympySolver visitor (incomplete)
• nmodl-linear-solver describes the sympy linear solver routines (incomplete)
• nmodl-nonlinear-solver describes the Newton solver & related sympy routines (incomplete)
• nmodl-sympy-conductance describes the SymyConductance visitor

also

• add README.md to notebooks folder, with links to interactive colab jupyter session
  • the links won't work yet as repo is still private & nmodl is not installed,
  • but once github repo is public & nmodl is on pypi, we can add ! pip install nmodl to top of notebook and they should work
• exposed inline/folding/renaming/kinetic visitors via pybind for use in these notebooks
• added nb-format cmake target to run nbconvert and clean_ipynb on notebooks
• updated yaml.load to avoid warning message: https://github.com/yaml/pyyaml/wiki/PyYAML-yaml.load(input)-Deprecation

[pramodk]

@lkeegan : which pyyaml version are you using? Locally I see :

Traceback (most recent call last):
  File "/Users/kumbhar/workarena/repos/bbp/incubator/nocmodl/src/language/code_generator.py", line 37, in <module>
    nmodl_nodes = LanguageParser("nmodl.yaml").parse_file()
  File "/Users/kumbhar/workarena/repos/bbp/incubator/nocmodl/src/language/parser.py", line 194, in parse_file
    rules = yaml.load(stream, Loader=yaml.FullLoader)
AttributeError: module 'yaml' has no attribute 'FullLoader'

Edit : Ok, I went through this. I assume many people will have older version, on my mac I see :

→ pip3 install pyyaml
Requirement already satisfied: pyyaml in /usr/local/lib/python3.7/site-packages (3.13)

So we need backward compatible change ?

[lkeegan]

it looks like we could use safe_load instead of load, which should be backwards compatible:
yaml/pyyaml#265

[pramodk]

@lkeegan : should I merge this or you want to push anything here?

[lkeegan]

@pramodk for me it's good to merge - I don't know if nbformat ornb-format is more common, but either is fine by me. I'll add some more documentation but in a separate PR.

[pramodk]

Bit puzzled by this :

I installed with cmake as :

 cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/nmodl
 make install
 export PYTHONPATH=~/nmodl/lib/python

and then I see

± |master {26} U:1 ?:29 ✗| → make nb-format
[NbConvertApp] Converting notebook /Users/kumbhar/workarena/repos/bbp/incubator/nocmodl/docs/notebooks/nmodl-kinetic-schemes.ipynb to notebook
[NbConvertApp] Executing notebook with kernel: python3
[NbConvertApp] ERROR | Error while converting '/Users/kumbhar/workarena/repos/bbp/incubator/nocmodl/docs/notebooks/nmodl-kinetic-schemes.ipynb'
Traceback (most recent call last):
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/nbconvertapp.py", line 407, in export_single_notebook
    output, resources = self.exporter.from_filename(notebook_filename, resources=resources)
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/exporters/exporter.py", line 178, in from_filename
    return self.from_file(f, resources=resources, **kw)
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/exporters/exporter.py", line 196, in from_file
    return self.from_notebook_node(nbformat.read(file_stream, as_version=4), resources=resources, **kw)
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/exporters/notebook.py", line 32, in from_notebook_node
    nb_copy, resources = super(NotebookExporter, self).from_notebook_node(nb, resources, **kw)
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/exporters/exporter.py", line 138, in from_notebook_node
    nb_copy, resources = self._preprocess(nb_copy, resources)
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/exporters/exporter.py", line 315, in _preprocess
    nbc, resc = preprocessor(nbc, resc)
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/preprocessors/base.py", line 47, in __call__
    return self.preprocess(nb, resources)
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/preprocessors/execute.py", line 354, in preprocess
    nb, resources = super(ExecutePreprocessor, self).preprocess(nb, resources)
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/preprocessors/base.py", line 69, in preprocess
    nb.cells[index], resources = self.preprocess_cell(cell, resources, index)
  File "/Users/kumbhar/Library/Python/3.7/lib/python/site-packages/nbconvert/preprocessors/execute.py", line 378, in preprocess_cell
    raise CellExecutionError.from_cell_and_msg(cell, out)
nbconvert.preprocessors.execute.CellExecutionError: An error occurred while executing the following cell:
------------------
ex1 = """
STATE {
    h m
}
KINETIC kin {
    ~ h <-> m (a,b)
}
"""
print(run_kinetic_visitor_and_return_derivative(ex1))
------------------

---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
<ipython-input-2-94297c938c99> in <module>
      7 }
      8 """
----> 9 print(run_kinetic_visitor_and_return_derivative(ex1))

<ipython-input-1-3a39c5f64d76> in run_kinetic_visitor_and_return_derivative(mod_string)
     10     nmodl.symtab.SymtabVisitor().visit_program(AST)
     11     # constant folding, inlining & local variable renaming passes
---> 12     nmodl.visitor.ConstantFolderVisitor().visit_program(AST)
     13     nmodl.visitor.InlineVisitor().visit_program(AST)
     14     nmodl.visitor.LocalVarRenameVisitor().visit_program(AST)

AttributeError: module 'nmodl._nmodl.visitor' has no attribute 'ConstantFolderVisitor'
AttributeError: module 'nmodl._nmodl.visitor' has no attribute 'ConstantFolderVisitor'

make[3]: *** [CMakeFiles/nb-format] Error 1
make[2]: *** [CMakeFiles/nb-format.dir/all] Error 2
make[1]: *** [CMakeFiles/nb-format.dir/rule] Error 2
make: *** [nb-format] Error 2

But I couldn't reproduce this in interactive session :

± |master {26} U:2 ?:30 ✗| → python
Python 3.7.2 (default, Feb 12 2019, 08:15:36)
[Clang 10.0.0 (clang-1000.11.45.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import nmodl.dsl as nmodl
>>> nmodl.visitor.ConstantFolderVisitor()
<nmodl._nmodl.visitor.ConstantFolderVisitor object at 0x104e209d0>
>>>

[pramodk]

Something wrong with make install :

-- Installing: /Users/kumbhar/nmodl/lib/python/nmodl/_nmodl.cpython-37m-darwin.so
-- Up-to-date: /Users/kumbhar/nmodl/lib/python//nmodl
-- Installing: /Users/kumbhar/nmodl/lib/python//nmodl/dsl.py
-- Installing: /Users/kumbhar/nmodl/lib/python//nmodl/symtab.py
-- Installing: /Users/kumbhar/nmodl/lib/python//nmodl/_nmodl.cpython-37m-darwin.so
-- Installing: /Users/kumbhar/nmodl/lib/python//nmodl/__init__.py

not sure why _nmodl.cpython-37m-darwin.so is getting installed twice and they seems to be different:

→ diff ./nmodl/_nmodl.cpython-37m-darwin.so ~/nmodl/lib/python/nmodl/_nmodl.cpython-37m-darwin.so
Binary files ./nmodl/_nmodl.cpython-37m-darwin.so and /Users/kumbhar/nmodl/lib/python/nmodl/_nmodl.cpython-37m-darwin.so differ

There are two .so files:

± |master {26} U:1 ?:30 ✗| → find . -name "*nmodl*.so"
./nmodl/_nmodl.cpython-37m-darwin.so
./src/pybind/_nmodl.cpython-37m-darwin.so

Not sure why but following works for me:

± |master {26} U:2 ?:30 ✗| → git diff
diff --git a/cmake/hpc-coding-conventions b/cmake/hpc-coding-conventions
--- a/cmake/hpc-coding-conventions
+++ b/cmake/hpc-coding-conventions
@@ -1 +1 @@
-Subproject commit 6b2f7346db5cf5d438aa35ee16d4cb7fe5a71e46
+Subproject commit 6b2f7346db5cf5d438aa35ee16d4cb7fe5a71e46-dirty
diff --git a/src/pybind/CMakeLists.txt b/src/pybind/CMakeLists.txt
index a66bcc7..b90d27e 100644
--- a/src/pybind/CMakeLists.txt
+++ b/src/pybind/CMakeLists.txt
@@ -46,5 +46,5 @@ add_custom_command(OUTPUT ${NMODL_PYTHON_FILES_OUT}
 # =============================================================================
 # Install python binding components
 # =============================================================================
-install(TARGETS _nmodl DESTINATION lib/python/nmodl)
 install(DIRECTORY ${PROJECT_SOURCE_DIR}/nmodl DESTINATION lib/python/)
+install(TARGETS _nmodl DESTINATION lib/python/nmodl)