sim_tools.run_model¶

sim_tools.run_model(V0, Z0, DA0, task, outfile, seed=None, paramfile='parameters.py', symsyn=True, verbose=True, ram_use=0.2, **kwargs)[source]¶

Run a simulation using the neural population model

Parameters:

V0 : NumPy 1darray Initial conditions for excitatory neurons. If N regions are simulated then V0 has to have length N. Z0 : NumPy 1darray Initial conditions for inhibitory neurons. If N regions are simulated then Z0 has to have length N. DA0 : NumPy 1darray Initial conditions for dopamine levels. If N regions are simulated then DA0 has to have length N. task : str Specify which task should be simulated. Currently, only ‘rest’ and ‘speech’ are supported. outfile : str File-name (including path if not in working directory) of HDF5 container that will be created to save simulation results. See Notes for the structure of the generated container. Any existing file will be renamed. The user has to have writing permissions for the given location. seed : int Random number generator seed. To make meaningful comparisons between successive simulation runs, the random number seed should be fixed so that the solver uses the same Wiener process realizations. Also, if synaptic coupling strengths are sampled from a probability distribution, simulation results will vary from run to run unless the seed is fixed. paramfile : str Parameter file-name (including path if not in working directory) that should be used for simulation. The parameter file has to be a Python file (.py extension). For more details refer to Examples below. You should have received a sample parameter file (parameters.py) with this copy of sim_tools.py. symsyn : bool Boolean switch determining whether synaptic coupling strengths should be symmetrized between hemispheres (symsyn=True) or not. verbose : bool If True the code will print a summary of the most important parameters and all used keyword arguments (see below) in the simulation together with a progress bar to (roughly) estimate run time (requires the progressbar module). ram_use : float Fraction of memory to use for caching simulation results before writing to disk (0 < ram_use < 1). More available memory means fewer disk-writes and thus better performance, i.e, the larger ram_use the faster this code runs. However, if too much RAM is allocated by this routine it may stall the executing computer. By default, ram_use = 0.2, i.e., around 20% of available memory is used. kwargs : additional keyword arguments Instead of relying solely on a static file to define parameter values, it is also possible to pass on parameters to the code using keyword arguments (see Examples below). Note: parameters given as keyword arguments have higher priority than values set in paramfile, i.e., if p1 = 1 is defined in paramfile but p1 = 2 is a keyword argument, the code will use p1 = 2 in the simulation. This behavior was intentionally implemented to enable the use of this function within a parameter identification framework.

Returns:

Nothing : None Simulation results are saved in the HDF5 container specified by outfile. See Notes for details.

See also

plot_sim

plot simulations generated by run_model

Notes

Due to the (usually) high temporal resolution of simulations, results are not kept in memory (and thus returned as variable in the caller’s work-space) but saved directly to disk using the HDF5 container outfile. The code uses the HDF library’s data chunking feature to save entire segments on disk while running. By default the code will allocate around 20% of available memory to cache simulation results. Hence, more memory leads to fewer disk-writes during run-time and thus faster performance. The structure of the generated output container is as follows: all state variables and the dopaminergic gain Beta are stored at the top-level of the file. Additionally, the employed coupling matrix C and dopamine connection matrix D are also saved in the top level group. All used parameters are saved in the subgroup params.

References

[R12]

S. Fuertinger, J. C. Zinn, and K. Simonyan. A Neural Population Model Incorporating Dopaminergic Neurotransmission during Complex Voluntary Behaviors. PLoS Computational Biology, 10(11), 2014.

Examples

Let V0, Z0, and DA0 (NumPy 1darrays of length N) be initial conditions of the model. Assuming that a valid parameter file (called parameters.py) is located in the current working directory, the following call will run a resting state simulation and save the output in the HDF5 container sim_rest.h5

>>> run_model(V0,Z0,DA0,'rest','sim_rest.h5')

Assume another parameter file, say, par_patho.py hold parameter settings simulating a certain pathology. Then the command

>>> run_model(V0,Z0,DA0,'rest','patho/sim_rest_patho.h5',paramfile='par_patho.py')

runs a resting state simulation with the same initial conditions and saves the result in the container sim_rest_patho.h5 in the sub-directory patho (which must already exist, otherwise an error is raised).

If only one or two parameters should be changed from their values found in a given parameter file, it is probably more handy to change the value of these parameters from the command line, rather than to write a separate parameter file (that is identical to the original one except for two values). Thus, assume the values of VK and VL should be -0.4 and -0.9 respectively, i.e., different than those found in (the otherwise fine) par_patho.py. Then the command

>>> run_model(V0,Z0,DA0,'rest','patho/sim_rest_patho.h5',paramfile='par_patho.py',VK=-0.4,VL=-0.9)

runs the same resting state simulation as above but with VK=-0.4 and VL=-0.9. This feature can also be used to efficiently embed run_model in a parameter identification framework.