Utilizing Built-in Models#

@Tianqiu Zhang @Chaoming Wang

BrainPy enables modularity programming and easy model debugging. To build a complex brain dynamics model, you just need to group its building blocks. In this section, we are going to talk about what building blocks we provide, and how to use these building blocks.

import brainpy as bp
import brainpy.math as bm

bm.set_platform('cpu')

Models in brainpy.dyn#

brainpy.dyn has provided many convenient channels, neurons, synapse, and other models for users. The following figure is a glimpse of the provided models.

New models will be continuously updated in the page of API documentation.

Initializing a neuron model#

All neuron models implemented in brainpy are subclasses of brainpy.dyn.NeuGroup. The initialization of a neuron model just needs to provide the geometry size of neurons in a population group.

hh = bp.neurons.HH(size=1)  # only 1 neuron

hh = bp.neurons.HH(size=10)  # 10 neurons in a group

hh = bp.neurons.HH(size=(10, 10))  # a grid of (10, 10) neurons in a group

hh = bp.neurons.HH(size=(5, 4, 2))  # a column of (5, 4, 2) neurons in a group

Generally speaking, there are two types of arguments can be set by users:

  • parameters: the model parameters, like gNa refers to the maximum conductance of sodium channel in the brainpy.dyn.HH model.

  • variables: the model variables, like V refers to the membrane potential of a neuron model.

In default, model parameters are homogeneous, which are just scalar values.

hh = bp.neurons.HH(5)  # there are five neurons in this group

hh.gNa
120.0

However, neuron models support heterogeneous parameters when performing computations in a neuron group. One can initialize heterogeneous parameters by several ways.

1. Array

Users can directly provide an array as the parameter.

hh = bp.neurons.HH(5, gNa=bm.random.uniform(110, 130, size=5))

hh.gNa
JaxArray([122.192924, 125.95139 , 114.511345, 122.27126 , 114.39388 ],            dtype=float32)

2. Initializer

BrainPy provides wonderful supports on initializations. One can provide an initializer to the parameter to instruct the model initialize heterogeneous parameters.

hh = bp.neurons.HH(5, ENa=bp.init.OneInit(50.))

hh.ENa
JaxArray([50., 50., 50., 50., 50.], dtype=float32)

3. Callable function

You can also directly provide a callable function which receive a shape argument.

hh = bp.neurons.HH(5, ENa=lambda shape: bm.random.uniform(40, 60, shape))

hh.ENa
JaxArray([59.987877, 56.06326 , 43.771053, 53.228992, 49.78434 ], dtype=float32)

Here, let’s see how the heterogeneous parameters influence our model simulation.

# we create 3 neurons in a group. Each neuron has a unique "gNa"

model = bp.neurons.HH(3, gNa=bp.init.Uniform(min_val=100, max_val=140))
runner = bp.dyn.DSRunner(model, monitors=['V'], inputs=['input', 5.])
runner.run(100.)

bp.visualize.line_plot(runner.mon.ts, runner.mon.V, plot_ids=[0, 1, 2], show=True)
../_images/9315f3e8d9c38e2380f6b29ba7ed5666d2e109a73e10a038e28b98815f2b54d4.png

Similarly, the setting of the initial values of a variable can also be realized through the above three ways: Array, Initializer, and Callable function. For example,

hh = bp.neurons.HH(
   3,
   V_initializer=bp.init.Uniform(-80., -60.),  # Initializer
   m_initializer=lambda shape: bm.random.random(shape),  # function
   h_initializer=bm.random.random(3),  # Array
)
print('V: ', hh.V)
print('m: ', hh.m)
print('h: ', hh.h)
V:  Variable([-78.496025, -77.036995, -72.28617 ], dtype=float32)
m:  Variable([0.40498435, 0.000857  , 0.40790236], dtype=float32)
h:  Variable([0.5012727 , 0.90631044, 0.96595407], dtype=float32)

Initializing a synapse model#

Initializing a synapse model needs to provide its pre-synaptic group (pre), post-synaptic group (post) and the connection method between them (conn). The below is an example to create an Exponential synapse model:

neu = bp.neurons.LIF(10)

# here we create a synaptic projection within a population
syn = bp.synapses.compat.ExpCUBA(pre=neu, post=neu, conn=bp.conn.All2All())

BrainPy’s build-in synapse models support heterogeneous synaptic weights and delay steps by using Array, Initializer and Callable function. For example,

syn = bp.synapses.compat.ExpCUBA(neu, neu, bp.conn.FixedProb(prob=0.1),
                     g_max=bp.init.Uniform(min_val=0.1, max_val=1.),
                     delay_step=lambda shape: bm.random.randint(10, 30, shape))
syn.g_max
JaxArray([0.5460913 , 0.98663217, 0.8724222 , 0.62892395, 0.18731643,
          0.400298  , 0.96323854, 0.54389703, 0.7557717 , 0.42726317,
          0.5927771 ], dtype=float32)
syn.delay_step
JaxArray([22, 14, 14, 28, 18, 10, 11, 19, 15, 11], dtype=int32)

However, in BrainPy, the built-in synapse models only support homogenous synaptic parameters, like the time constant \(\tau\). Users can customize their synaptic models when they want heterogeneous synaptic parameters.

Similar, the synaptic variables can be initialized heterogeneously by using Array, Initializer, and Callable functions.

Changing model parameters during simulation#

In BrainPy, all the dynamically changed variables (no matter it is changed inside or outside the jitted function) should be marked as brainpy.math.Variable. BrainPy’s built-in models also support modifying model parameters during simulation.

For example, if you want to fix the gNa in the first 100 ms simulation, and then try to decrease its value in the following simulations. In this case, we can provide the gNa as an instance of brainpy.math.Variable when initializing the model.

hh = bp.neurons.HH(5, gNa=bm.Variable(bm.asarray([120.])))

runner = bp.dyn.DSRunner(hh, monitors=['V'], inputs=['input', 5.])
# the first running
runner.run(100.)
bp.visualize.line_plot(runner.mon.ts, runner.mon.V, show=True)
../_images/3a2b296d69bef06d9bc8562082396b4a786741360666a582ff52b4837263116a.png
# change the gNa first
hh.gNa[:] = 100.

# the second running
runner.run(100.)
bp.visualize.line_plot(runner.mon.ts, runner.mon.V, show=True)
../_images/739171065b2d8be9b6cae498f080d5b1349a51ea292cab7ca4c2e2a33e12f4bb.png

Examples of using built-in models#

Here we show users how to simulate a famous neuron models: The Morris-Lecar neuron model, which is a two-dimensional “reduced” excitation model applicable to systems having two non-inactivating voltage-sensitive conductances.

group = bp.neurons.MorrisLecar(1)

Then users can utilize various tools provided by BrainPy to easily simulate the Morris-Lecar neuron model. Here we are not going to dive into details so please read the corresponding tutorials if you want to learn more.

runner = bp.dyn.DSRunner(group, monitors=['V', 'W'], inputs=('input', 100.))
runner.run(1000)

fig, gs = bp.visualize.get_figure(2, 1, 3, 8)
fig.add_subplot(gs[0, 0])
bp.visualize.line_plot(runner.mon.ts, runner.mon.W, ylabel='W')
fig.add_subplot(gs[1, 0])
bp.visualize.line_plot(runner.mon.ts, runner.mon.V, ylabel='V', show=True)
../_images/736b5d901931ad5f03e2c850a0edc4ec8e2e4c22b6ebc305b0c979e5eb5d5cb7.png

Next we will also give users an intuitive understanding about building a network composed of different neurons and synapses model. Users can simply initialize these models as below and pass into brainpy.dyn.Network.

neu1 = bp.neurons.HH(1)
neu2 = bp.neurons.HH(1)
syn1 = bp.synapses.AMPA(neu1, neu2, bp.connect.All2All())
net = bp.dyn.Network(pre=neu1, syn=syn1, post=neu2)

By selecting proper runner, users can simulate the network efficiently and plot the simulation results.

runner = bp.dyn.DSRunner(net, inputs=[('pre.input', 5.)], monitors=['pre.V', 'post.V', 'syn.g'])
runner.run(150.)

import matplotlib.pyplot as plt

fig, gs = bp.visualize.get_figure(2, 1, 3, 8)
fig.add_subplot(gs[0, 0])
plt.plot(runner.mon.ts, runner.mon['pre.V'], label='pre-V')
plt.plot(runner.mon.ts, runner.mon['post.V'], label='post-V')
plt.legend()

fig.add_subplot(gs[1, 0])
plt.plot(runner.mon.ts, runner.mon['syn.g'], label='g')
plt.legend()
plt.show()
../_images/8f10d78701aed3bf7449de0593094cdba72b00797473c7806f1e7cdf499a96a4.png