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.

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()
    # Name of head mesh
    s.fnamehead = 'ernie.msh'
    # Output folder
    s.pathfem = 'tutorial/'
    
  • MATLAB

    % Initialize a session
    s = sim_struct('SESSION');
    % Name of head mesh
    s.fnamehead = 'ernie.msh';
    % 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 selecting a coil model (list of avaliable coils).

  • Python

    # Initialize a list of TMS simulations
    tmslist = s.add_tmslist()
    # 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
    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 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

Further Reading