Scripting Simulations

This tutorial is based on the Example Dataset. Please download it before continuing.

SimNIBS offers both Python and MATLAB interfaces for setting up and running simulations. In both, we use a set of nested structures to define the simulation, and then use the run_simnibs function to run the simulation.

Running Scripts

Python

Run SimNIBS Python scripts using the simnibs_python command so that your scripts run in the correct Python interpreter.

Spyder IDE Setup (optional)

You can install the Spyder IDE editor by running

simnibs_python -m pip install spyder==5.3.1

To start Spyder, run

simnibs_python -m spyder.app.start

MATLAB

Add the SimNIBS MATLAB functions to the MATLAB path. In default installations, you can call

  • Windows:

    addpath('C:\Users\<USER_NAME>\AppData\Local\SimNIBS\matlab_tools')

  • Linux:

    addpath('/home/<USER_NAME>/SimNIBS/matlab_tools')

  • MacOS

    addpath('/Users/<USER_NAME>/Applications/SimNIBS/matlab_tools')

Starting a SESSION and Selecting a Head Mesh

The base structure for SimNIBS scripts is the SESSION. It may contain many simulations of different types (TMS or tDCS), sharing the same head model.

We always start our scripts by initializing a SESSION class (Python) or struct (MATLAB), selecting a head mesh and the output folder. Here, we will assume that the scripts are placed in the same directory as the m2m_ernie directory of the example dataset. If the scripts are not in the same folder as the subject folder, you should also give the path to the subject folder.

  • Python

from simnibs import sim_struct, run_simnibs

# Initalize a session
s = sim_struct.SESSION()
# Name of head mesh
s.subpath = 'm2m_ernie'
# Output folder
s.pathfem = 'tutorial/'

  • MATLAB

    % Initialize a session
s = sim_struct('SESSION');
% Name of head mesh
s.subpath = 'm2m_ernie';
% Output folder
s.pathfem = 'tutorial/';

See also

Output and post-processing options are also configured in the SESSION structure. Please see the documentation for more details.

Setting up a TMS Simulation

Now, we want to set-up a TMS simulation. To do it, we add a TMSLIST to the SESSION structure and select a coil model (list of available coils).

  • Python

    # Initialize a list of TMS simulations
tmslist = s.add_tmslist()
# Select coil
tmslist.fnamecoil = os.path.join('legacy_and_other','Magstim_70mm_Fig8.ccd')

  • MATLAB

    % Initialize a list of TMS simulations
s.poslist{1} = sim_struct('TMSLIST');
% Select coil
s.poslist{1}.fnamecoil = fullfile('legacy_and_other','Magstim_70mm_Fig8.ccd');

Now we need to set a position for our coil. Suppose we want to place it on position C1, pointing posteriorly. You can do it by

  • Python

    # Initialize a coil position
pos = tmslist.add_position()
# Select coil centre
pos.centre = 'C1'
# Select coil direction
pos.pos_ydir = 'CP1'

  • MATLAB

    % Select coil centre
s.poslist{1}.pos(1).centre = 'C1';
% Select coil direction
s.poslist{1}.pos(1).pos_ydir = 'CP1';

We can set many coil positions to a single TMSLIST. For example, we can add one more coil position, now with the coil pointing towards Cz.

  • Python

    # Add another position
pos_superior = tmslist.add_position()
# Centred at C1
pos_superior.centre = 'C1'
# Pointing towards Cz
pos_superior.pos_ydir = 'Cz'

  • MATLAB

    % Centred at C1
s.poslist{1}.pos(2).centre = 'C1';
% Pointing towards Cz
s.poslist{1}.pos(2).pos_ydir = 'Cz';

See also

Coil positions are set through the POSITION structure. It also allows you to set stimulator intensity (dI/dt values) and define coil positions in other ways. Please see the documentation for more information.

Setting up a tDCS Simulation

To perform a tDCS simulation, we begin by setting a TDCSLIST structure to the SESSION and setting the current flow through each channel. Here, we will only use two electrodes and set the current to 1mA. The first electrode will be a cathode, and the second an anode.

  • Python

    # Initialize a tDCS simulation
tdcslist = s.add_tdcslist()
# Set currents
tdcslist.currents = [-1e-3, 1e-3]

  • MATLAB

    % Initialize a tDCS simulation
s.poslist{2} = sim_struct('TDCSLIST');
% Set currents
s.poslist{2}.currents = [-1e-3 1e-3];

Let’s first set the cathode. Suppose we want a 70x50mm rectangular over C3, pointing towards Cz.

  • Python

    # Initialize the cathode
cathode = tdcslist.add_electrode()
# Connect electrode to first channel (-1e-3 mA, cathode)
cathode.channelnr = 1
# Electrode dimension
cathode.dimensions = [50, 70]
# Rectangular shape
cathode.shape = 'rect'
# 5mm thickness
cathode.thickness = 5
# Electrode Position
cathode.centre = 'C3'
# Electrode direction
cathode.pos_ydir = 'Cz'

  • MATLAB

    % Connect electrode to first channel (-1e-3 mA, cathode)
s.poslist{2}.electrode(1).channelnr = 1;
% Electrode dimension
s.poslist{2}.electrode(1).dimensions = [50 70];
% Rectangular shape
s.poslist{2}.electrode(1).shape = 'rect';
% 5mm thickness
s.poslist{2}.electrode(1).thickness = 5;
% Electrode Position
s.poslist{2}.electrode(1).centre = 'C3';
% Electrode direction
s.poslist{2}.electrode(1).pos_ydir = 'Cz';

Now we need to configure the anode. Let’s set a 30x30mm circular electrode over C4.

  • Python

    # Add another electrode
anode = tdcslist.add_electrode()
# Assign it to the second channel
anode.channelnr = 2
# Electrode diameter
anode.dimensions = [30, 30]
# Electrode shape
anode.shape = 'ellipse'
# 5mm thickness
anode.thickness = 5
# Electrode position
anode.centre = 'C4'

  • MATLAB

    % Assign the electrode to the second channel
s.poslist{2}.electrode(2).channelnr = 2;
% Electrode diameter
s.poslist{2}.electrode(2).dimensions = [30 30];
% Electrode shape
s.poslist{2}.electrode(2).shape = 'ellipse';
% Electrode thickness
s.poslist{2}.electrode(2).thickness = 5;
% Electrode position
s.poslist{2}.electrode(2).centre = 'C4';

See also

Electrodes are defined through the highly flexible ELECTRODE structure. Please see the documentation for more information. Please note that it is also possible to connect multiple electrodes to a single channel, which is not possible to do in the GUI.

Running Simulations

After the simulations are set, we can use the run_simnibs function to run the simulations:

run_simnibs(s)

Now run the script in Python (using the simnibs_python command) or in MATLAB. After the simulations have finished running, the results can be found in the newly created tutorial/ folder.

More Examples

More examples can be found in the examples/ folder in your SimNIBS installation directory. In default installations, it can be found at

  • Windows:

    C:\Users\<USER_NAME>\AppData\Local\SimNIBS\examples

  • Linux:

    /home/<USER_NAME>/SimNIBS/examples

  • MacOS:

    /Users/<USER_NAME>/Applications/SimNIBS.app/examples

Further Reading