Introduce an invariants block in NESTML neurons

[DimitriPlotnikov]

Currently, invariants in NESTML models are defined at the end of declarations double square braces, e.g.

V_m mV = -70 [[V_m > -100 and V_m <= 0]]

This notation is confusing and error prone (intuitively the constraint is useless, since V_m has the value -70 (user feedback))

invariants:
  -90 <= V_m <= 0 # This is an invariant. It is in-forced at anytime
  gls_err_tol > 0 # this is a guard. it is checked in SetStatus-call only.
end

Invariants should enforce state variables to be in the range during simulation (e.g. STATE_VAR is actively set to its lower or upper bound). Syntactically an invariant is always of the form lower_bound < STATE_VAR< upper_bound. An exception is thrown in SetStatus, if a value s being set is out of the range.

Guards is an arbitrary boolean expression (just an example) E_in + E_ex <= 42.. It can only be checked. Guards can be defined for all variables/expression, but they are checked only in SetStatus.

[kperun]

@DimitriPlotnikov While I think that in general, this is a good idea, some questions are left open. There are certainly cases where variables are bounded only in one direction (e.g. the current which is always non-negative but unbounded upwards). Here, it would no longer be possible to distinguish between guards and invariants. On the other hand, guards can also be used with range expressions, e.g. the default value of V_m can variate between -50mV and -70mV. I think the best solution here would be an introduction of two new keywords, e.g. guard and invariant.

[Silmathoron]

Actually, why not use only one simple keyword, like "constraint", which seems more intuitive to me for the user (which will not think in terms of guards nor invariants)?
If it is a state variable, then it is an invariant, regardless of the presence of one or two bounds (a missing left bound is replaced by -\infty and right by +\infty). If it is a parameter, then it is a guard...

[DimitriPlotnikov]

@Silmathoron
I'll try to summarize your proposal.

constraints:
  # it is checked in the update-method and in SetStatus. SetStatus throws an exception. 
  # During update the range is enforced. E.g. if V_m > 0mV then 0mV is returned.  
  # If V_m < -90mV, then -90mV is returned.
   -90mV <= V_m <= 0mV 
  # C_m is a parameter  
  # it is checked ONLY in SetStatus. But: in the model you cannot change the value of C_m, thus, it is ok.
   C_m <= 500pF 
   # or
  V_m <= 0mV # lower bound is assumed to be -infinity 
end

Without starting to implement this requirement, it would have considerable runtime overhead. In the best case I assume, that any assignment must be extended such that . In the best case this check will be performed every time the constrained variable is accessed.

Finally, what we still need is to able to model something like this (taken iaf_tum_2000):

[[t_ref_tot >= t_ref_abs]]

In this example the lefthandside and righthandside of the comparison could be arbitrary expressions.
(number includes the -inf and inf characters, $op in {!=, ==, <=, ...})

constraints:
  # is checked in SetStatus and update-method. Both borders are enforced during runtime
  #  umber1 < number2 must be checked by a context conditions
  number1 <= state_var <= number2 
  expression $op expression # checked in SetStatus only
end

[Silmathoron]

@DimitriPlotnikov I would be perfectly happy with your summarized block, it looks very simple and efficient to me, syntax-wize.

Regarding your comment on having to check every time the variable is accessed, yes, indeed, this should be performed every timestep at the beginning of the update function, but a boolean test is fast...

I'm not sure I understand your reference to the iaf_tum_2000 model, though... could you elaborate? They are both parameters, are they not?
My guess is that you mean that the constrain could actually involve a function of parameters and/or state variables and that this would be very annoying... but I'm not sure we have to tackle this type of problem, at least not right now, and it doesn't seem to be a problem that is related to the syntax ^^

[kperun]

@Silmathoron I will take a look on this one in near future. Is it still of interest to implement such a feature?

[Silmathoron]

Hey, @kperun I'm really sorry for the late reply: I saw your message but couldn't reply, and then I forgot...
Sure, this feature is still necessary in NESTML as far as I am concerned :)
I think Dimitry's last post sums up quite well what would be nice to implement.

[clinssen]

@kperun: would it be possible to turn this into a PR? Or should the semantics be discussed/formalised further?