Revise semantics and documentation of Disconnect

[heplesser]

Disconnect() needs revision, both the precise call semantics and the documentation. Some tests may then require adjustment.

Consider the following example:

n = nest.Create('parrot_neuron', n=2)
nest.Connect(n, n, syn_spec='static_synapse')
nest.Connect(n, n, syn_spec='stdp_synapse')
c = nest.GetConnections()

This will create four static and four stdp synapses. Now the following kinds of Disconnect() calls are possible:

1. Disconnect(c[2:6])
   • Deletes four connections, the last two static created and the first two stdp.
   • Does not allow any other arguments.
2. Disconnect(n, n)
   • Uses the default 'one-to-one' rule for disconnect
   • Requires that both NCs passed have the same size
   • Deletes connections between nodes in identical positions in the two NCs
   • Deletes four connections in the case above (1->1 and 2->2 once for each synapse type)
3. Disconnect(n, n, syn_spec={'synapse_model': 'static_synapse'})
   • As above, but deletes only the static 1->1 and 2->2 connections
4. Disconnect(n, n, conn_spec='all_to_all')
   • Deletes all connections
5. Disconnect(n, n, conn_spec='all_to_all', syn_spec={'synapse_model': 'static_synapse'})
   • Deletes only the four static synapses

{conn,syn}_spec can be passed as string or dictionary. If passed as dictionary, conn_spec must give a 'rule', and syn_spec must give a 'synapse_model'. Collocated synapses are not supported.

The documentation gives the impression that also other parameters could be passed in the syn_specs and this seems to be possible indeed, but to no effect (they are silently ignored). The idea was, at some point, that one should be able to filter which connections to delete by providing corresponding entries in syn_specs, but this is not supported at present, see

nest-simulator/nestkernel/conn_builder_impl.h

Line 36 in 88c47b9

BipartiteConnBuilder::single_disconnect_( size_t snode_id, Node& target, size_t target_thread )

.

One interesting use case might be to delete only connections with a specific rport.

To do:

1. The implementation needs to be adapted to raise an error if syn_spec contains other fields than 'synapse_model' (until support for more complex filters is implemented).
2. The documentation should be fully re-written to properly reflect how to use the function.