From e732634dd614bfb46677765e5e8188c4b396b749 Mon Sep 17 00:00:00 2001 From: Omar Awile Date: Wed, 8 May 2019 01:01:22 +0200 Subject: [PATCH] More documentation and included md files into sphinx doc (#191) - Updated README with extra information about NMODL, eprint and benchmarks - Change version to 0.2 in CMakeLists.txt - Avoided import nmodl.dsl as nmodl in README - Renamed ast_view to view in nmodl.ast module --- CMakeLists.txt | 2 +- CONTRIBUTING.md | 55 +++++++++++++- INSTALL.md | 151 ++++++++++++++++--------------------- README.md | 129 ++++++++++++++++++++++++------- docs/DoxygenLayout.xml | 2 +- docs/contents/visitors.rst | 14 ++-- docs/contributing.rst | 2 + docs/index.rst | 10 ++- docs/install.rst | 3 + docs/notebooks.rst | 11 +++ nmodl/ast.py | 15 +++- nmodl/dsl.py | 10 ++- 12 files changed, 279 insertions(+), 125 deletions(-) create mode 100644 docs/contributing.rst create mode 100644 docs/install.rst create mode 100644 docs/notebooks.rst diff --git a/CMakeLists.txt b/CMakeLists.txt index 54e1742787..8ee54585e1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -12,7 +12,7 @@ project(NMODL CXX) # CMake common project settings # ============================================================================= set(PROJECT_VERSION_MAJOR 0) -set(PROJECT_VERSION_MINOR 1) +set(PROJECT_VERSION_MINOR 2) set(CMAKE_BUILD_TYPE Debug) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED ON) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ca3d6a08ec..17b7f7519a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,12 @@ -# Contributing to the NMODL +# Contributing to the NMODL Framework -We would love for you to contribute to the NMODL and help make it better than it is today. As a +We would love for you to contribute to the NMODL Framework and help make it better than it is today. As a contributor, here are the guidelines we would like you to follow: - [Question or Problem?](#question) - [Issues and Bugs](#issue) - [Feature Requests](#feature) - [Submission Guidelines](#submit) + - [Development Conventions](#devconv) ## Got a Question? @@ -100,3 +101,53 @@ repository: ``` [github]: https://github.com/BlueBrain/nmodl + +## Development Conventions + +If you are developing NMODL, make sure to enable both `NMODL_FORMATTING` and `NMODL_PRECOMMIT` +CMake variables to ensure that your contributions follow the coding conventions of this project: + +```cmake +cmake -DNMODL_FORMATTING:BOOL=ON -DNMODL_PRECOMMIT:BOOL=ON +``` + +The first variable provides the following additional targets to format +C, C++, and CMake files: + +``` +make clang-format cmake-format +``` + +The second option activates Git hooks that will discard commits that +do not comply with coding conventions of this project. These 2 CMake variables require additional utilities: + +* [ClangFormat 7](https://releases.llvm.org/7.0.0/tools/clang/docs/ClangFormat.html) +* [cmake-format](https://github.com/cheshirekow/cmake_format) +* [pre-commit](https://pre-commit.com/) + +clang-format can be installed on Linux thanks +to [LLVM apt page](http://apt.llvm.org/). On MacOS, there is a +[brew recipe](https://gist.github.com/ffeu/0460bb1349fa7e4ab4c459a6192cbb25) +to install clang-format 7. _cmake-format_ and _pre-commit_ utilities can be installed with *pip*. + + +### Memory Leaks and clang-tidy + +If you want to test for memory leaks, do : + +``` +valgrind --leak-check=full --track-origins=yes ./bin/nmodl_lexer +``` + +Or using CTest as: + +``` +ctest -T memcheck +``` + +If you want to enable `clang-tidy` checks with CMake, make sure to have `CMake >= 3.5` and use following cmake option: + +``` +cmake .. -DENABLE_CLANG_TIDY=ON +``` + diff --git a/INSTALL.md b/INSTALL.md index c3320ab191..1d5ad2a8ff 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,58 +1,72 @@ -### Getting Started +# Installing the NMODL Framework + +## Getting Started These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. -#### Cloning Source +## Cloning Source -This project uses git submodules which must be cloned along with the repository itself: +The NMODL Framework is maintained on github. The best way to get the sources is to simply clone the repository. -``` +**Note**: This project uses git submodules which must be cloned along with the repository itself: + +```sh git clone --recursive https://github.com/BlueBrain/nmodl.git +cd nmodl ``` -#### Prerequisites +## Prerequisites -To build the project from source, modern C++ compiler with c++11 support is necessary. Make sure you have following packages available: +To build the project from source, a modern C++ compiler with c++11 support is necessary. Make sure you have following packages available: - flex (>=2.6) - bison (>=3.0) -- CMake (>=3.1) +- CMake (>=3.3) - Python (>=3.6) -- Python packages : jinja2 (>=2.10), pyyaml (>=3.13), pytest (>=4.0.0), sympy (>=1.2), textwrap +- Python packages : jinja2 (>=2.10), pyyaml (>=3.13), pytest (>=4.0.0), sympy (>=1.3), textwrap -##### On OS X +### On OS X -Often we have older version of flex and bison. We can get recent version of dependencies via brew/macport and pip: +Typically the versions of bison and flex provided by the system are outdated and not compatible with our requirements. +To get recent version of all dependencies we recommend using [homebrew](https://brew.sh/): -``` +```sh brew install flex bison cmake python3 +``` + +The necessary Python packages can then easily be added using the pip3 command. + +```sh pip3 install Jinja2 PyYAML pytest sympy ``` Make sure to have latest flex/bison in $PATH : -``` +```sh export PATH=/usr/local/opt/flex:/usr/local/opt/bison:/usr/local/bin/:$PATH ``` -##### On Ubuntu +### On Ubuntu -On Ubuntu (>=16.04) flex/bison versions are recent enough. We can install Python3 and dependencies using: +On Ubuntu (>=16.04) flex/bison versions are recent enough and are installed along with the system toolchain: +```sh +apt-get install flex bison gcc python3 python3-pip ``` -apt-get install python3 python3-pip + +The Python dependencies are installed using: + +```sh pip3 install Jinja2 PyYAML pytest sympy ``` -> On Blue Brain B5 Supercomputer, use : module load cmake/3.12.0 bison/3.0.5 flex/2.6.3 gcc/6.4.0 python3-dev - -#### Build Project +## Build Project -##### Using CMake +### Using CMake Once all dependencies are in place, build project as: -``` +```sh mkdir -p nmodl/build cd nmodl/build cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/nmodl @@ -61,15 +75,37 @@ make -j && make install And set PYTHONPATH as: -``` +```sh export PYTHONPATH=$HOME/nmodl/lib/python:$PYTHONPATH ``` -#### Testing Installed Module +#### Flex / Bison Paths + +If flex / bison are not in your default $PATH, you can provide the path to cmake as: + +``` +cmake .. -DFLEX_EXECUTABLE=/usr/local/opt/flex/bin/flex \ + -DBISON_EXECUTABLE=/usr/local/opt/bison/bin/bison \ + -DCMAKE_INSTALL_PREFIX=$HOME/nmodl +``` + +### Using Python setuptools -If you install NMODL using CMake, you can run tests from build directory as: +If you are mainly interested in the NMODL Framework parsing and analysis tools and wish to use them from Python, we +recommend building and installing using Python. +```sh +pip3 install --user . ``` + +This should build the NMODL framework and install it into your pip user `site-packages` folder such that it becomes +available as a Python module. + +## Testing the Installed Module + +If you have installed the NMODL Framework using CMake, you can now run tests from the build directory as: + +```bash $ make test Running tests... Test project /Users/kumbhar/workarena/repos/bbp/incubator/nocmodl/cmake-build-debug @@ -92,10 +128,9 @@ Test project /Users/kumbhar/workarena/repos/bbp/incubator/nocmodl/cmake-build-de ... ``` -We can use nmodl module from python as: +To test the NMODL Framework python bindings, you can try a minimal example in your Python 3 interpeter as follows: ```python -$ python3 >>> import nmodl.dsl as nmodl >>> driver = nmodl.NmodlDriver() >>> modast = driver.parse_string("NEURON { SUFFIX hh }") @@ -110,12 +145,13 @@ NEURON { NMODL is now setup correctly! -#### Generating Documentation +## Generating Documentation In order to build the documentation you must have additionally `pandoc` installed. Use your -system's package manager to do this (e.g. `apt install pandoc`). +system's package manager to do this (e.g. `sudo apt-get install pandoc`). -Once you have installed NMODL and setup the correct PYTHONPATH, you can build the documentation locally from the docs folder as: +Once you have installed NMODL and setup the correct `$PYTHONPATH`, you can build the documentation locally from the +docs folder as: ``` cd docs @@ -123,62 +159,9 @@ doxygen # for API documentation make html # for user documentation ``` +Alternatively, you can install the documentation using the Python setuptools script: -### Development Conventions - -If you are developing NMODL, make sure to enable both `NMODL_FORMATTING` and `NMODL_PRECOMMIT` -CMake variables to ensure that your contributions follow the coding conventions of this project: - -```cmake -cmake -DNMODL_FORMATTING:BOOL=ON -DNMODL_PRECOMMIT:BOOL=ON +```sh +python3 setup.py buildhtml ``` -The first variable provides the following additional targets to format -C, C++, and CMake files: - -``` -make clang-format cmake-format -``` - -The second option activates Git hooks that will discard commits that -do not comply with coding conventions of this project. These 2 CMake variables require additional utilities: - -* [ClangFormat 7](https://releases.llvm.org/7.0.0/tools/clang/docs/ClangFormat.html) -* [cmake-format](https://github.com/cheshirekow/cmake_format) -* [pre-commit](https://pre-commit.com/) - -clang-format can be installed on Linux thanks -to [LLVM apt page](http://apt.llvm.org/). On MacOS, there is a -[brew recipe](https://gist.github.com/ffeu/0460bb1349fa7e4ab4c459a6192cbb25) -to install clang-format 7. _cmake-format_ and _pre-commit_ utilities can be installed with *pip*. - - -##### Memory Leaks and clang-tidy - -If you want to test for memory leaks, do : - -``` -valgrind --leak-check=full --track-origins=yes ./bin/nmodl_lexer -``` - -Or using CTest as: - -``` -ctest -T memcheck -``` - -If you want to enable `clang-tidy` checks with CMake, make sure to have `CMake >= 3.5` and use following cmake option: - -``` -cmake .. -DENABLE_CLANG_TIDY=ON -``` - -##### Flex / Bison Paths - -If flex / bison is not in default $PATH, you can provide path to cmake as: - -``` -cmake .. -DFLEX_EXECUTABLE=/usr/local/opt/flex/bin/flex \ - -DBISON_EXECUTABLE=/usr/local/opt/bison/bin/bison \ - -DCMAKE_INSTALL_PREFIX=$HOME/nmodl -``` diff --git a/README.md b/README.md index af03258919..641bd150f2 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ The NMODL Framework is a code generation engine for **N**EURON **MOD**eling **L* Simulators like [NEURON](https://www.neuron.yale.edu/neuron/) use NMODL as a domain specific language (DSL) to describe a wide range of membrane and intracellular submodels. Here is an example of exponential synapse specified in NMODL: -``` +```python NEURON { POINT_PROCESS ExpSyn RANGE tau, e, i @@ -52,22 +52,25 @@ NET_RECEIVE(weight (uS)) { ### Installation -See [INSTALL.md](INSTALL.md) for detailed instructions to build the NMODL from source. +See [INSTALL.md](https://github.com/BlueBrain/nmodl/blob/master/INSTALL.md) for detailed instructions to build the NMODL from source. ### Using the Python API -Once the NMODL Framework is installed, you can use the Python parsing API as: +Once the NMODL Framework is installed, you can use the Python parsing API to load NMOD file as: ```python -import nmodl.dsl as nmodl -driver = nmodl.NmodlDriver() -mod_ast = driver.parse_file("expsyn.mod") +from nmodl import dsl +import os + +expsyn = os.path.join(dsl.example_dir(), "expsyn.mod") +driver = dsl.NmodlDriver() +modast = driver.parse_file(expsyn) ``` -`parse_file()]` returns Abstract Syntax Tree ([AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree)) representation of input NMODL file. One can look at the AST in JSON form as: +The `parse_file` API returns Abstract Syntax Tree ([AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree)) representation of input NMODL file. One can look at the AST by converting to JSON form as: ```python ->>> print (nmodl.to_json(mod_ast)) +>>> print (dsl.to_json(modast)) { "Program": [ { @@ -85,16 +88,24 @@ mod_ast = driver.parse_file("expsyn.mod") } ... ``` -You can also use AST visualization API to look at the AST: +Every key in the JSON form represent a node in the AST. You can also use visualization API to look at the details of AST as: -![alt text](docs/images/nmodl.ast.png "AST representation of expsyn.mod") +``` +from nmodl import ast +ast.view(modast) +``` +which will open AST view in web browser: -The central *Program* node represents the whole MOD file and each of it's children represent the block in the input NMODL file i.e. **expsyn.mod**. Once the AST is built, one can use exisiting visitors to perform various analysis/optimisations or one can write his own custom visitor using Python Visitor API. See [Python API tutorial](docs/notebooks/nmodl-python-tutorial.ipynb) for details. +![ast_viz](https://user-images.githubusercontent.com/666852/57329449-12c9a400-7114-11e9-8da5-0042590044ec.gif "AST representation of expsyn.mod") -One can also transform AST back into NMODL form simply as : +The central *Program* node represents the whole MOD file and each of it's children represent the block in the input NMODL file. + +Once the AST is created, one can use exisiting visitors to perform various analysis/optimisations. One can also easily write his own custom visitor using Python Visitor API. See [Python API tutorial](docs/notebooks/nmodl-python-tutorial.ipynb) for details. + +NMODL Frameowrk also allows to transform AST representation back to NMODL form as: ```python ->>> print (nmodl.to_nmodl(mod_ast)) +>>> print (dsl.to_nmodl(modast)) NEURON { POINT_PROCESS ExpSyn RANGE tau, e, i @@ -116,25 +127,25 @@ PARAMETER { ### High Level Analysis and Code Generation -The NMODL Framework provides rich model introspection and analysis capabilities using [various visitors TODO](). Here is an example of theoretical performance characterisation of channels and synapses from rat neocortical column microcircuit [published in 2015](https://www.cell.com/abstract/S0092-8674%2815%2901191-5): +The NMODL Framework provides rich model introspection and analysis capabilities using [various visitors](https://bluebrain.github.io/nmodl/html/doxygen/group__visitor__classes.html). Here is an example of theoretical performance characterisation of channels and synapses from rat neocortical column microcircuit [published in 2015](https://www.cell.com/abstract/S0092-8674%2815%2901191-5): -![alt text](docs/images/nmodl-perf-stats.png "Example of performance characterisation") +![nmodl-perf-stats](https://user-images.githubusercontent.com/666852/57336711-2cc0b200-7127-11e9-8053-8f662e2ec191.png "Example of performance characterisation") To understand how you can write your own introspection and analysis tool, see [this tutorial](docs/notebooks/nmodl-python-tutorial.ipynb). -Once analysis and optimization passes are performed, the NMODL Framework can generate optimised code for modern compute architectures including CPUs (Intel, AMD, ARM) and GPUs (NVIDIA, AMD) platforms. For example, [C++ TODO](), [OpenACC TODO](), [OpenMP TODO](), [CUDA TODO]() and [ISPC TODO]() backends are implemented and one can choose backends on command line as: +Once analysis and optimization passes are performed, the NMODL Framework can generate optimised code for modern compute architectures including CPUs (Intel, AMD, ARM) and GPUs (NVIDIA, AMD) platforms. For example, C++, OpenACC, OpenMP, CUDA and ISPC backends are implemented and one can choose these backends on command line as: ``` $ nmodl expsyn.mod host --ispc acc --cuda sympy --analytic ``` -Here is an example of generated ISPC kernel for [DERIVATIVE](https://www.neuron.yale.edu/neuron/static/py_doc/modelspec/programmatic/mechanisms/nmodl.html#derivative) block : +Here is an example of generated [ISPC](https://ispc.github.io/) kernel for DERIVATIVE block : ```c++ export void nrn_state_ExpSyn(uniform ExpSyn_Instance* uniform inst, uniform NrnThread* uniform nt ...) { uniform int nodecount = ml->nodecount; const int* uniform node_index = ml->nodeindices; - const double* uniform voltage = nt->_actual_v; + const double* uniform voltage = nt->actual_v; int uniform start = 0; int uniform end = nodecount; @@ -142,30 +153,96 @@ export void nrn_state_ExpSyn(uniform ExpSyn_Instance* uniform inst, uniform NrnT foreach (id = start ... end) { int node_id = node_index[id]; double v = voltage[node_id]; - inst->g[id] = inst->g[id] * vexp( -nt->_dt / inst->tau[id]); + inst->g[id] = inst->g[id] * vexp( -nt->dt / inst->tau[id]); } } ``` -To know more about code generation backends, [see here TODO](). +To know more about code generation backends, [see here](https://bluebrain.github.io/nmodl/html/doxygen/group__codegen__backends.html). NMODL Framework provides number of options (for code generation, optimization passes and ODE solver) which can be listed as: + +``` +$ nmodl -H +NMODL : Source-to-Source Code Generation Framework +Usage: /path/<>/nmodl [OPTIONS] file... [SUBCOMMAND] + +Positionals: + file TEXT:FILE ... REQUIRED One or more MOD files to process + +Options: + -h,--help Print this help message and exit + -H,--help-all Print this help message including all sub-commands + -v,--verbose Verbose logger output + -o,--output TEXT=. Directory for backend code output + --scratch TEXT=tmp Directory for intermediate code output + --units TEXT=/path/<>/nrnunits.lib + Directory of units lib file +Subcommands: +host + HOST/CPU code backends + Options: + --c C/C++ backend + --omp C/C++ backend with OpenMP + --ispc C/C++ backend with ISPC +acc + Accelerator code backends + Options: + --oacc C/C++ backend with OpenACC + --cuda C/C++ backend with CUDA +sympy + SymPy based analysis and optimizations + Options: + --analytic Solve ODEs using SymPy analytic integration + --pade Pade approximation in SymPy analytic integration + --cse CSE (Common Subexpression Elimination) in SymPy analytic integration + --conductance Add CONDUCTANCE keyword in BREAKPOINT +passes + Analyse/Optimization passes + Options: + --inline Perform inlining at NMODL level + --unroll Perform loop unroll at NMODL level + --const-folding Perform constant folding at NMODL level + --localize Convert RANGE variables to LOCAL + --localize-verbatim Convert RANGE variables to LOCAL even if verbatim block exist + --local-rename Rename LOCAL variable if variable of same name exist in global scope + --verbatim-inline Inline even if verbatim block exist + --verbatim-rename Rename variables in verbatim block + --json-ast Write AST to JSON file + --nmodl-ast Write AST to NMODL file + --json-perf Write performance statistics to JSON file + --show-symtab Write symbol table to stdout +codegen + Code generation options + Options: + --layout TEXT:{aos,soa}=soa Memory layout for code generation + --datatype TEXT:{float,double}=soa Data type for floating point variables +``` ### Documentation We are working on user documentation, you can find current drafts of : -* User documentation on [Read the Docs TODO]() -* Developer / API documentation with [Doxygen TODO]() +* [User Documentation](https://bluebrain.github.io/nmodl/) +* [Developer / API Documentation](https://bluebrain.github.io/nmodl/html/doxygen/index.html) + + +### Citation + +If you would like to know more about the the NMODL Framework, see following paper: + +* Pramod Kumbhar, Omar Awile, Liam Keegan, Jorge Alonso, James King, Michael Hines and Felix Schürmann. 2019. An optimizing multi-platform source-to-source compiler framework for the NEURON MODeling Language. In Eprint : arXiv:submit/2678839. ### Support / Contribuition -If you see any issue or need help, feel free to raise a ticket. If you would like to improve this framework, see open issues and [contribution guidelines](CONTRIBUTING.md). +If you see any issue, feel free to [raise a ticket](https://github.com/BlueBrain/nmodl/issues/new). If you would like to improve this framework, see [open issues](https://github.com/BlueBrain/nmodl/issues) and [contribution guidelines](CONTRIBUTING.md). -### Citation -If you are referencing NMODL Framework in a publication, please cite the following paper: +### Examples / Benchmarks + +The benchmarks used to test the performance and parsing capabilities of NMODL Framework are currently being migrated to GitHub. These benchmarks will be published soon in following repositories: -* Pramod Kumbhar, Omar Awile, Liam Keegan, Jorge Alonso, James King, Michael Hines and Felix Schürmann. 2019. An optimizing multi-platform source-to-source compiler framework for the NEURON MODeling Language. In Eprint arXiv: TODO. +* [NMODL Benchmark](https://github.com/BlueBrain/nmodlbench) +* [NMODL Database](https://github.com/BlueBrain/nmodldb) ### Authors diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml index 00930c097f..7ad780b56b 100644 --- a/docs/DoxygenLayout.xml +++ b/docs/DoxygenLayout.xml @@ -3,7 +3,7 @@ - + diff --git a/docs/contents/visitors.rst b/docs/contents/visitors.rst index dfc7d1a2a4..a058297972 100644 --- a/docs/contents/visitors.rst +++ b/docs/contents/visitors.rst @@ -1,11 +1,11 @@ Visitors -######### +######## -One of the strengths of NMODL python interface is access to inbuilt Visitors. +One of the strengths of the NMODL python interface is access to inbuilt Visitors. One can perform different queries and analysis on AST using different visitors. Let us start with examples of inbuilt visitors. Parsing Model and constructing AST -=================================== +================================== Once the NMODL is setup properly we should be able to import nmodl module and create the channel: @@ -63,11 +63,11 @@ If we simply print AST object, we can see JSON representation: Querying AST objects with Visitors -=================================== +=========== Lookup Visitor ---------------- +----------- As name suggest, lookup visitor allows to search different NMODL constructs in the AST. The `visitor` module provides access to inbuilt visitors. In order to use this visitor, we create an object of :class:`nmodl.visitor.AstLookupVisitor`: @@ -86,7 +86,7 @@ Assuming we have created :class:`nmodl.ast` object (as shown here), we can searc Symbol Table Visitor --------------------- +---------- Symbol table visitor is used to find out all variables and their usage in mod file. To use this, just create a visitor object as: @@ -107,7 +107,7 @@ Now we can query for variables in the symbol table based on name of variable: Custom AST Visitor -------------------- +---------- If predefined visitors are limited, we can implement new visitor using :class:`nmodl.visitor.AstVisitor` interface. Let us say we want to implement a visitor that prints every floating point numbers in MOD file. Here is how it can be done: diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000000..0d3640164b --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,2 @@ + +.. mdinclude:: ../CONTRIBUTING.md diff --git a/docs/index.rst b/docs/index.rst index 7bd03dd1a6..691512cc16 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,8 @@ About NMODL :maxdepth: 2 :caption: Introduction: - readme + readme.rst + install.rst .. toctree:: :maxdepth: 2 @@ -22,6 +23,7 @@ About NMODL :maxdepth: 3 :caption: Jupyter Notebooks: + notebooks.rst notebooks/nmodl-python-tutorial.ipynb notebooks/nmodl-odes-overview.ipynb notebooks/nmodl-kinetic-schemes.ipynb @@ -32,6 +34,12 @@ About NMODL notebooks/nmodl-nonlinear-solver.ipynb notebooks/nmodl-sympy-conductance.ipynb +.. toctree:: + :maxdepth: 2 + :caption: Contributing: + + contributing.rst + .. toctree:: :maxdepth: 2 :caption: Reference: diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000000..175b6101d3 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,3 @@ + +.. mdinclude:: ../INSTALL.md + diff --git a/docs/notebooks.rst b/docs/notebooks.rst new file mode 100644 index 0000000000..af42d04857 --- /dev/null +++ b/docs/notebooks.rst @@ -0,0 +1,11 @@ +The NMODL Jupyter notebooks +=========================== + +About the notebooks +------------------- + +To help you get started we have created several `Jupyter notebooks `_, which cover many aspects of using NMODL from Python +beginning from basic model parsing and AST visualization, continuing with using and writing your own AST visitors, and +finally understanding and using the NMODL ODE solvers. You can find the notebooks +`here `_ to run and test yourself. + diff --git a/nmodl/ast.py b/nmodl/ast.py index 811ad9675c..0e298a3058 100644 --- a/nmodl/ast.py +++ b/nmodl/ast.py @@ -1,8 +1,19 @@ from ._nmodl.ast import * # noqa from .config import * -def ast_view(nmodl_ast): - """Visualize given NMODL AST by converting to JSON form""" +def view(nmodl_ast): + """Visualize given NMODL AST in web browser + + In memory representation of AST can be converted to JSON + form and it can be visualized using AST viewer implemented + using d3.js. + + Args: + nmodl_ast: AST object of nmodl file or string + + Returns: + None + """ from ._nmodl import to_json from distutils.dir_util import copy_tree import getpass diff --git a/nmodl/dsl.py b/nmodl/dsl.py index 3e0414e612..e949194445 100644 --- a/nmodl/dsl.py +++ b/nmodl/dsl.py @@ -3,8 +3,16 @@ def example_dir(): + """Returns directory containing NMODL examples + + NMODL Framework is installed with few sample example of + channels. This method can be used to get the directory + containing all mod files. + + Returns: + Full path of directory containing sample mod files + """ import os - """Return directory containing NMODL examples""" installed_example = os.path.join(PROJECT_INSTALL_DIR, "share", "example") if os.path.exists(installed_example): return installed_example