Inhomogeneous parameters

[AdhocMan]

Implementation of #1650.

This PR adds inhomogeneous expressions (iexpr) and a wrapper struct scaled_mechanism (naming suggestions are welcome), to allow painting of mechanisms (currently limited to density), where selected parameters can be scaled by iexpr evaluated along a cell. The wrapper allows for the current mechanism API to remain unchanged.
Any iexpr can be converted from / to S-Expressions and added to the label dictionary.

A python example:

  # Create mechanism with custom conductance (range)
  m = arbor.mechanism('pas', {'g': 0.1})

  decor = arbor.decor()
  # paint a scaled density mechanism, where 'g' is scaled by the radius along the cell.
  decor.paint('"soma"', arbor.scaled_mechanism(arbor.density(m), {'g': '(add 2.0 (radius 0.5) (exp (distance 3.0 (terminal))))'}))

[thorstenhater]

Hi,

some minor comments, rest looks good.

[AdhocMan]

The code style issues should be addressed now. I've also tried to improve the documentation with custom images for distance and interpolation expressions.
What I'm not sure about, is removing the template argument from the scaled_mechanism struct. It depends on how likely we are going to extend this feature to other types of mechanisms, if at all. If not, naming it scaled_density might be better.

[thorstenhater]

Also, if you want to keep iexpr, motivate why they are called inhomogeneous.

[AdhocMan]

It's now "... to scale parameters on a cable cell, such that a parameter is inhomogenous along the cell." Did you have a longer explanation in mind or would this be fine?

[thorstenhater]

Finally his could be made clearer and best split into two sentences.

1. These expressions yield a scaling factor that can be applied to a base value of a parameter (currently only density mechanisms).
2. Example
3. The point of evaluation is the mid point...

Since 3. is a important detail, but does not add to the understanding of the concrete use.

[AdhocMan]

I've reformulated the text and changed the example to use a distance expression.

[thorstenhater]

One last (I promise!) clarification in the docs.

[thorstenhater]

I suggest to massage this a bit

Sometimes, it is useful to have parameters varying smoothly along the dendrite, for example with the distance from the root. 
:ref:`Inhomogenous expressions  <labels-iexpr>` allow modelling this behavior (the name is inspired by NeuroML's https://docs.neuroml.org/Userdocs/Schemas/Cells.html#schema-inhomogeneousparameter). 
These can be applied to mechanisms (and a subset of their parameters) and yield a scaling factor which is multiplied with the base value of the selected parameter. 
Currently Arbor supports only :ref:`density mechanisms <cablecell-density-mechs>` as targets.
Internally, the value of each expression is evaluated at mid-points of the cable partition of the cell.

[AdhocMan]

How about:

Mechanism parameters are usually homogeneous along a cell. However, sometimes it is useful to scale parameters based on inhomogeneous properties.
:ref:`Inhomogeneous expressions  <labels-iexpr>` provide a way to describe a desired scaling formula, which for example can include the cell radius or the distance to a given set of locations.
The name is inspired by NeuroML's https://docs.neuroml.org/Userdocs/Schemas/Cells.html#schema-inhomogeneousparameter.
Such an expression is evaluated along the cell and yields a scaling factor, which is multiplied with the base value of the selected parameter.
Internally, this evaluation and scaling is done at mid-points of the cable partition of the cell.
Currently, only parameters of :ref:`density mechanisms <cablecell-density-mechs>` can be scaled.

[thorstenhater]

Thanks, that reads way smoother now!

[thorstenhater]

I'll leave the commit message and merge to you @AdhocMan

[brenthuisman]

🎉