Add multi-state neuron models

[jasperalbers]

This PR proposes to add multi-state neuron models used for studying infection dynamics as described in [1]. Building on the implementation of the binary neuron, these models can be in either of three states: S, I or R.
In particular, three new neuron models are added:

• the SIS neuron that can only be in states S or I where transitions from I to S are allowed
• the SIR neuron that can be in all three states S, I or R where transitions from R to S are forbidden
• the SIRS neuron that can be in all three states S, I or R where transitions from R back to S are allowed
  Their implementation closely follows the example set by the binary neuron.

If these models are deemed interesting enough to be added to the NEST simulator, we (@jasperalbers and @ClaudiaMer) would also add the corresponding documentation and tests. Here, we would be grateful for a pointer to a minimal example of what is required for both documentation and tests if that exists.

[1] https://arxiv.org/abs/2312.14851

[jessica-mitchell]

thanks @ClaudiaMer

[clinssen]

Thanks for the PR! I am basically fine with everything, just some small comments.

[clinssen]

should it be 0 < beta < 1 or 0 <= beta <= 1?

[ClaudiaMer]

In principle one could allow beta=0 or beta=1.
beta=0 however would make the dynamics trivial (no infection can take place), and lead to a non-sensical model.
beta=1 could be allowed, it makes the dynamics deterministic.

[heplesser]

I think allowing beta=0 would make sense, if only for testing purposes. As it has a consistent interpretation, we should not limit the freedom of the user.

[ClaudiaMer]

sorry, I was myself confused. Currently, we only raise an error if beta <0 or beta >1 (see line 193ff of sir_neuron.cpp) meaning that both beta=0 and beta=1 are currently allowed.

[heplesser]

Hi @ClaudiaMer and @jasperalbers! Sorry for coming late to the party and raising a number of questions, mostly inline. But I also have an higher-level question: Is it strictly necessary to introduce three new neuron models? Wouldn't it be possible to create one model with a parameter that allows choosing between SIS, SIR and SIRS dynamics? This would help to keep the model zoo and the amount of code to maintain smaller.

[heplesser]

For robust and readable code, it would be useful to not use magic numbers 0, 1, 2, explicitly, but rather define an

enum class InfectionState {
  SUSCEPTIBLE = 0,
  INFECTED,
 RECOVERED 
};

and to use those names here.

[ClaudiaMer]

is it not more convenient to track a single integer than three separate binary variables?

[heplesser]

Do we really need these there new types here or couldn't one use BINARY to distinguish from SPIKE? After a non-exhaustive search, I haven't been able to find any place where these new types are actually used in the code.

[ClaudiaMer]

This could lead to confusion as the sir_neuron and sirs_neuron can take more than two states.

[heplesser]

I don't see any need to introduce new names here, just use beta (and eta and mu). From the fact that you set the beta parameter of a SIR neuron it is sufficiently clear that this is the beta of a SIR neuron.

[ClaudiaMer]

We tried to do so in the beginning, but this threw some errors when we attempted to compile the code (unfortunately I don't remember which ones), thus we solved it this way.

[heplesser]

Does tau_m_ really make sense as parameter name, given that there is no membrane? Why not just tau?

[ClaudiaMer]

We tried to avoid introducing new parameters.

[heplesser]

I realize that the __ is inherited from the existing binary neurons, but it is not good style. Private members should be marked with a single _ at the end.

[ClaudiaMer]

I changed the names in update get_output_state__ to get_output_state_

[ClaudiaMer]

Hi @ClaudiaMer and @jasperalbers! Sorry for coming late to the party and raising a number of questions, mostly inline. But I also have an higher-level question: Is it strictly necessary to introduce three new neuron models? Wouldn't it be possible to create one model with a parameter that allows choosing between SIS, SIR and SIRS dynamics? This would help to keep the model zoo and the amount of code to maintain smaller.

We found it more convenient to introduce these three neurons as it makes the communication between neurons easier: Neurons need to communicate their change in state to other neurons, in particular, when they are infected and when then exit the infected state, this is communicated via spikes of multiplicity one and two. If there are multiple transitions (e.g. from the I to the S OR from the I to the R state), this could complicate the update rule in the neurons, which is why we distinguish SIS and SIRS neurons. Second, SIR neurons that are in the R state can be considered as "silent" as they are essentially frozen for the remainder of the dynamics, while SIRS or SIS neurons are not, as they will always allow for dynamic updates.
Finally, we thought that it would be more convenient for users to use three different neurons where the transitions are explicitly known instead of having to ensure that only allowed transitions are realized.
Of course it may be convenient to define a multi-state neuron which allows for all kinds of transitions between a arbitrary number of states in an arbitrary number of ways, but writing such a code is currently beyond my resources.