clean up the howto

README.md

-# cell_algorithms
+# NestMC Prototype
+
+This is the repository for the NestMC prototype code. Unfortunately we do not have thorough documentation of how-to guides.
+Below are some guides for how to build the project and run the miniapp.
+Contact us or submit a ticket if you have any questions or want help.
 
 ```bash
 # clone repo
-git clone git@github.com:eth-cscs/cell_algorithms.git
-cd cell_algorithms/
+git clone git@github.com:eth-cscs/nestmc-proto.git
+cd nestmc-proto/
 
 # setup sub modules
 git submodule init
 git submodule update
 
 # setup environment
-# on a desktop system this might not be required
-# on a cluster this could be required
+# on a desktop system this is probably not required
+# on a cluster this is usually required to make sure that an appropriate
+# compiler is chosen.
 module load gcc
 module load cmake
 export CC=`which gcc`
@@ -31,8 +36,7 @@ cd tests
 ## MPI
 
 Set the `WITH_MPI` option either via the ccmake interface, or via the command line as shown below.
-For the time being our CMake configuration does not try to detect MPI.
-Instead, it relies on the user specifying an MPI wrapper for the compiler by setting the `CXX` and `CC` environment variables.
+To ensure that CMake detects MPI correctly, you should specify the MPI wrapper for the compiler by setting the `CXX` and `CC` environment variables.
 
 ```
 export CXX=mpicxx
@@ -47,7 +51,6 @@ Support for multi-threading requires Intel Threading Building Blocks (TBB).
 When TBB is installed, it comes with some scripts that can be run to set up the user environment.
 The scripts set the `TBB_ROOT` environment variable, which is used by the CMake configuration to find TBB.
 
-
 ```
 source <path to TBB installation>/tbbvars.sh
 cmake <path to CMakeLists.txt> -DWITH_TBB=ON
@@ -56,6 +59,9 @@ cmake <path to CMakeLists.txt> -DWITH_TBB=ON
 ### TBB on Cray systems
 
 To compile with TBB on Cray systems, load the intel module, which will automatically configure the environment.
+The guide below shows how to use the version of TBB that is installed as part of the Intel compiler toolchain.
+It is recommended that you install the most recent version of TBB yourself, and link against this, because older versions
+of TBB don't work with recent versions of GCC.
 
 ```
 # load the gnu environment for compiling the application
@@ -80,7 +86,7 @@ cmake <path to CMakeLists.txt> -DWITH_TBB=ON -DWITH_MPI=ON -DSYSTEM_CRAY=ON
 
 # targetting KNL
 
-## build modparser                                                                                       
+## build modparser
 
 The source to source compiler "modparser" that generates the C++/CUDA kernels for the ion channels and synapses is in a separate repository.
 It is included in our project as a git submodule, and by default it will be built with the same compiler and flags that are used to build the miniapp and tests.
@@ -116,8 +122,8 @@ which modcc
 
 ```bash
 # clone the repo and set up the submodules
-git clone TODO
-cd cell_algorithms
+git clone https://github.com/eth-cscs/nestmc-proto.git
+cd nestmc-proto
 git submodule init
 git submodule update
 
@@ -127,13 +133,6 @@ cd build_knl
 
 ## build miniapp
 
-# clone the repo and set up the submodules
-git clone https://github.com/bcumming/cell_algorithms.git
-cd cell_algorithms
-
-# checkout the knl branch
-git checkout knl
-
 # setup submodules
 git submodule init
 git submodule update

mechanisms/mod/exp2syn.mod

 NEURON {
-	POINT_PROCESS exp2syn
-	RANGE tau1, tau2, e
-	NONSPECIFIC_CURRENT i
+    POINT_PROCESS exp2syn
+    RANGE tau1, tau2, e
+    NONSPECIFIC_CURRENT i
 }
 
 UNITS {
-	(nA) = (nanoamp)
-	(mV) = (millivolt)
-	(uS) = (microsiemens)
+    (mV) = (millivolt)
 }
 
 PARAMETER {
-	tau1 = .5 (ms) : <1e-9,1e9>
-	tau2 = 2  (ms) : <1e-9,1e9>
-	e=0	(mV)
+    tau1 = 0.5 (ms)
+    tau2 = 2   (ms)
+    e    = 0   (mV)
 }
 
 ASSIGNED {
-	factor
+    factor
 }
 
 STATE {
-	A : (uS)
-	B : (uS)
+    A B
 }
 
 INITIAL {
-	LOCAL tp
-	A = 0
-	B = 0
-	tp = (tau1*tau2)/(tau2 - tau1) * log(tau2/tau1)
-	factor = -exp(-tp/tau1) + exp(-tp/tau2)
-	factor = 1/factor
+    LOCAL tp
+    A = 0
+    B = 0
+    tp = (tau1*tau2)/(tau2 - tau1) * log(tau2/tau1)
+    factor = 1 / (-exp(-tp/tau1) + exp(-tp/tau2))
 }
 
 BREAKPOINT {
-	SOLVE state METHOD cnexp
-	i = (B - A)*(v - e)
+    SOLVE state METHOD cnexp
+    i = (B - A)*(v - e)
 }
 
 DERIVATIVE state {
-	A' = -A/tau1
-	B' = -B/tau2
+    A' = -A/tau1
+    B' = -B/tau2
 }
 
 NET_RECEIVE(weight) {
-	A = A + weight*factor
-	B = B + weight*factor
+    A = A + weight*factor
+    B = B + weight*factor
 }
+

mechanisms/mod/expsyn.mod

@@ -5,22 +5,18 @@ NEURON {
 }
 
 UNITS {
-    (nA) = (nanoamp)
     (mV) = (millivolt)
-    (uS) = (microsiemens)
 }
 
 PARAMETER {
-    : the default for Neuron is 0.1
-    :tau = 0.1 (ms) : <1e-9,1e9>
-    tau = 2.0 (ms) : <1e-9,1e9>
+    tau = 2.0 (ms) : the default for Neuron is 0.1
     e = 0   (mV)
 }
 
 ASSIGNED {}
 
 STATE {
-    g : (uS)
+    g
 }
 
 INITIAL {
@@ -39,3 +35,4 @@ DERIVATIVE state {
 NET_RECEIVE(weight) {
     g = g + weight
 }
+

mechanisms/mod/hh.mod

-TITLE hh.mod   squid sodium, potassium, and leak channels
-
-: COMMENT
-:  This is the original Hodgkin-Huxley treatment for the set of sodium, 
-:   potassium, and leakage channels found in the squid giant axon membrane.
-:   ("A quantitative description of membrane current and its application 
-:   conduction and excitation in nerve" J.Physiol. (Lond.) 117:500-544 (1952).)
-:  Membrane voltage is in absolute mV and has been reversed in polarity
-:   from the original HH convention and shifted to reflect a resting potential
-:   of -65 mV.
-:  Remember to set celsius=6.3 (or whatever) in your HOC file.
-:  See squid.hoc for an example of a simulation using this model.
-:  SW Jaslove  6 March, 1992
-: ENDCOMMENT
-
-UNITS {
-    (mA) = (milliamp)
-    (mV) = (millivolt)
-    (S) = (siemens)
-}
-
 NEURON {
     SUFFIX hh
     USEION na READ ena WRITE ina
@@ -28,13 +7,17 @@ NEURON {
     GLOBAL minf, hinf, ninf, mtau, htau, ntau
 }
 
+UNITS {
+    (mV) = (millivolt)
+    (S) = (siemens)
+}
+
 PARAMETER {
-    gnabar = .12 (S/cm2)  : <0,1e9>
-    gkbar = .036 (S/cm2)  : <0,1e9>
-    gl = .0003 (S/cm2)    : <0,1e9>
+    gnabar = .12 (S/cm2)
+    gkbar = .036 (S/cm2)
+    gl = .0003 (S/cm2)
     el = -54.3 (mV)
     celsius = 6.3 (degC)
-    :celsius = 37 (degC)
 }
 
 STATE {
@@ -77,7 +60,7 @@ DERIVATIVE states {
     n' = (ninf-n)/ntau
 }
 
-PROCEDURE rates(v) :(mV))
+PROCEDURE rates(v)
 {
     LOCAL  alpha, beta, sum, q10
 
@@ -105,21 +88,13 @@ PROCEDURE rates(v) :(mV))
     ninf = alpha/sum
 }
 
+: We don't trap for zero in the denominator like Neuron, because function
+: inlining in modparser won't support it. There is a good argument that
+: vtrap should be provided as a built in of the language, because
+:   - it is a common pattern in many mechanisms.
+:   - it can be implemented efficiently on different back ends if the
+:     compiler has enough information.
 FUNCTION vtrap(x,y) {
-    : Traps for 0 in denominator of rate eqns.
-
-    : Disabled for function inlining...
-    : there is a very good case for making vtrap a builtin function for the language
-    : - it is ubiquitous: used in so many models of ion channels
-    : - platform specific optimizations written in assembly/intrinsics
-    :   required to facilitate vectorization/minimize branch misses
-
-    :if (fabs(x/y) < 1e-6) {
-    :    vtrap = y*(1 - x/y/2)
-    :}else{
-    :    vtrap = x/(exp(x/y) - 1)
-    :}
-
     vtrap = x/(exp(x/y) - 1)
 }
 

mechanisms/mod/pas.mod

-TITLE passive membrane channel
-
 UNITS {
     (mV) = (millivolt)
-    (mA) = (milliamp)
     (S) = (siemens)
 }
 
@@ -15,8 +12,8 @@ NEURON {
 INITIAL {}
 
 PARAMETER {
-    g = .001    (S/cm2) :<0,1e9>
-    e = -65 (mV) : we use -65 for the ball and stick model, instead of Neuron default of -70
+    g = .001 (S/cm2)
+    e = -65  (mV) : we use -65 for the ball and stick model, instead of Neuron default of -70
 }
 
 ASSIGNED {