# Scripting Simulations¶

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 --upgrade pyqt5==5.12 pyqtwebengine==5.12 pyflakes==2.2 spyder==4.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')


• Linux:

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


• MacOS

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


## 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 together with the ernie.msh file of the example dataset. If the scripts are not in the same folder as the head mesh, you should also give the path to the head mesh.

• Python

from simnibs import sim_struct, run_simnibs

# Initalize a session
s = sim_struct.SESSION()
# Output folder
s.pathfem = 'tutorial/'

• MATLAB

% Initialize a session
s = sim_struct('SESSION');
% Output folder
s.pathfem = 'tutorial/';


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 selecting a coil model (list of avaliable coils).

• Python

# Initialize a list of TMS simulations
# Select coil
tmslist.fnamecoil = 'Magstim_70mm_Fig8.nii.gz'

• MATLAB

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


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

• Python

# Initialize a coil 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
# 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';


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
# 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
# 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
# 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';


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 are 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