Differences between revisions 5 and 248 (spanning 243 versions)

Realistic head model: FEM with DUNEuro

[TUTORIAL UNDER REVISION]

Authors: Takfarinas Medani, Juan Garcia-Prieto, Francois Tadel, Sophie Schrader, Anand Joshi, Christian Engwer, Carsten Wolters, John Mosher and Richard Leahy

This tutorial explains how to use DUNEuro to compute the forward model using the finite element method (FEM). The FEM methods use a realistic volume mesh of the head generated from the segmentation of the MRI. The FEM models provide more accurate results than the spherical forward models and more realistic geometry and tissue properties than the BEM methods.

The scope of this page is limited to a basic example (head model with 3 layers). More advanced options for mesh generation and forward model computation are discussed in other tutorials: FEM mesh generation, FEM tensors estimation, FEM median nerve example. We assume that you have already followed the introduction tutorials, we will not discuss the general principles of forward modeling here.

Contents

DUNEuro
Requirements
FEM mesh
FEM forward model
Advanced models and options
Troubleshooting
Additional documentation

DUNEuro

DUNEuro is an open-source C++ software library for solving partial differential equations (PDE) in neurosciences using mesh-based methods. It is based on the DUNE library and its main features include solving the EEG and MEG forward problem and providing simulations for brain stimulation.

As distributed on the DUNEuro GitLab, the source code works only on Linux operating systems. Interfaces to Matlab and Python are possible, but you need to install and compile DUNEuro by yourself. For Brainstorm, we adapted this code and were able to generate binaries for the main operating systems (Windows, Linux and MacOS), which are downloaded automatically when needed as a Brainstorm plugin. This project is available on our GitHub repository bst-duneuro.

We would like to thank the DUNEuro team for their help with this integration work: Carsten Wolters, Christian Engwer, Sophie Schrader, Andreas Nuessing, Tim Erdbruegger, Marios Antonakakis, Johannes Vorwerk & Maria Carla Piastra.

Please cite the following papers if you use this software in your work:

Medani T, Garcia-Prieto J, Tadel F, Schrader S, Antonakakis M, Joshi A, Engwer C, Wolters CH, Mosher JC, Leahy RM, Realistic head modeling of electromagnetic brain activity: an integrated Brainstorm-DUNEuro pipeline from MRI data to the FEM solutions (preprint), SPIE Medical Imaging (2021)

Publications that make use of, or extend the DUNEuro library (listed on the duneuro website):

Piastra MC, Nüßing A, Vorwerk J, Bornfleth H, Oostenveld R, Engwer C, Wolters CH, The Discontinuous Galerkin Finite Element Method for Solving the MEG and the combined MEG/EEG Forward Problem, Frontiers in Neuroscience (2018)
Engwer C, Vorwerk J, Ludewig J, Wolters CH, A discontinuous Galerkin method to solve the EEG forward problem using the subtraction approach, SIAM Journal on Scientific Computing (2017)
Nüßing A, Wolters CH, Brinck H, Engwer C, The unfitted discontinuous Galerkin method for solving the EEG forward problem, IEEE Transactions on Biomedical Engineering (2016)

Requirements

In order to reproduce the computation present below on your computer, you need to fulfill all the conditions listed below. Alternatively, you can read this page as a reference documentation about DUNEuro and not try to reproduce the results.

You have a working copy of Brainstorm installed on your computer.
You have already followed the introduction tutorials, at least until #23.
You have followed the tutorial EEG and Epilepsy, as it is used for illustrating the computation.
DUNEuro: Software installed automatically as a Brainstorm plugin.
Iso2mesh: Software installed automatically as a Brainstorm plugin.

FEM mesh

In order to use the FEM computations of the electromagnetic field (EEG/MEG), the volume mesh of the head is required. Brainstorm integrates most of the modern open-source tools to generate realistic head mesh, either from nested surface mesh or from individual MR images (T1 or T1 and T2). This tutorial describes only a simple approach based on three nested surfaces meshed in 3D with Iso2mesh. For the full list of available methods and description of options, please refer to the tutorial FEM mesh generation.

Select the protocol TutorialEpilepsy, created while following the tutorial EEG and epilepsy.
Go to the anatomy view.
Select the three BEM surfaces: scalp, outer skull, inner skull.
Right-click > Generate FEM mesh > Iso2mesh-2021 > MergeMesh > Default options.
The FEM mesh appears in the database explorer after a short while. The first number indicates the number of vertices (i.e. nodes) of the tetrahedral mesh. To get the number of 3D elements (i.e. tetrahedrons) in this geometric model of the head: right-click on the file > File > View file contents. The structure of the file is describe in the tutorial FEM mesh generation.
Double-click on the FEM file to display it. From the Surface tab, you can change the resection locations by moving the bottom sliders, and you can control the display of each of the three layers individually. Click on the layer button in the toolbar, then adjust the color and transparency of the corresponding mesh. The figure below represents the FEM mesh in the center and the initial BEM layers on the right.

FEM forward model

To compute the forward model with the FEM method, we assume that you have followed the introduction tutorials and all the relative data are available(channels files, ...).

First, on the anatomy view, you need to select the head model. In the case where you have multiple FEM head models, brainstorm uses the model displayed on green color. You need also to select the cortex to use as the source space.

Then, switch to the view "Functional data (sorted by subjects)", 2nd button above the database explore. Right-click on the subject > Compute head model. Select DUNEuro FEM on the list.

For the 'Source space,' we recommend using the 'Cortex surface'. For the forward modeling method. Both EEG/MEG computations are possible (depending on your data), and you can mixe between the available forward methods for each modality.

When you press OK, the panel related to DUNEuro options is displayed where you have the possibilities to change the options.

At this level, the basic options are the list head's tissues and their conductivities. Brainstorm reads these parameters from the selected head model.

FEM tissues or layers: Brainstorm detects automatically the number of layers on your model. Users can select the desired layers to include for the FEM computation. According to the modalities, the recommended selections are:
- For EEG: select all the layers
- For MEG: use only select the inner layers (here brain)
- For SEEG: use only the inner layers
- For ECOG: use only the inner layers
- Any combinations that include MEG: use all the layers
In this case, there is Scalp (=head), Skull (=outer skull), and Brain (=inner skull).
FEM conductivities: Brainstorm detects automatically the number of layers and assigns the default isotropic value for each layer. However, you have the possibility to change these values according to your model.

For advanced users, check the advanced section and a more detailed example at this page FEM tensor.

When is finished, click on the "Ok". If you do not have the bst-duneuro toolbox, Brainstorm will ask you to install it, then click 'Yes'

Brainstorm will download the latest version of the bst-duneuro binaries for your operating system from the Github, and install it in Brainstorm user folder (~username/.brainstorm/bst-duneuro/). The calculation of the head model will start automatically. You may wait for a very long time, which depends on the mesh resolution, the number of sensors, and of course the capacity of your computer.

So, be patient, it's worth it... (for this model it's quite fast ... less than 10 min)

When it's finished, you have now a new head model for this subject in your database and can be used for the next steps/(back to tutorial 20 : Head modeling)

Anisotropy tensor from the DUNEuro options

In the case where the conductivity tensor are computed, Brainstorm detects and uses them for the FEM forward computation.

In this case, users can not change the conductivities values, since they are already computed as explained in this FEM tensor.

If at some points, for any reason, where users want to remove these FEM tensors, this can be done from the Brainstorm anatomy panel, select the FEM head model, right-click on the subject, and then "clear FEM tensor".

Advanced models and options

DUNEuro advanced options panel [to be completed]

From the previous panel, for advanced duneuro panel, click on the button "Show details", the following panel is displayed.

A set of advanced options are made available and can be easily changed. Here a short explanation is given for each option.

FEM layers & conductivities: same explanation as in the previous section. Moreover, in the case where the conductivity tensor are previously computed, Brainstorm detects these tensors and load them. In this case, the users can't change the conductivities scalar values, since they are not used. The following is displayed panel is displayed.
FEM solver type:
- CG or Continuous Galerkin: This is the standard Lagrangian method.
- DC or the Discontinuous Galerkin:

In this version, only the Fitted FEM approaches are integrated, that require the FEM mesh of the head model. Unfitted methods are also available within DUNEuro, and will be integrated soon in Brainstorm.

FEM source model: The list of the available source are
- Venant
- Subtraction
- Partial Integration

For more information about these methods, users can check this thesis (Vorwek thesis).

Source space
- Shrink source space: the location of dipoles are moved inward by the specified value in this field(in mm).
- Force source space: this is required in the case where the dipoles are not within the GM matter.
Outputs options
- Save transfer matrix:

All these parameters are stored and passed to the DUNEuro as a text file. This file is the main interface that passes the parameters from Brainstorm to DUNEuro. More details about the integration can be found in these links:

GitHub repository for the Brainstorm-DUNEuro compilation and integration
GitHub repository for the matlab-duneuro interface
Brainstorm-DUNEuro integration discussions:
- Brainstorm-simbio/DUNEuro implementation/head model generation
- Integrate the DUNEuro FEM computation
- Genration of the FEM tensor
- Generation of the FEM source space

FEM head model generation from MRI data

One of the advantages of the FEM is its ability to use more complex head models with realistic geometry. In this tutorial, we have shown a basic example, as an introduction.

For the generation of a more realistic head model, users can follow this FEM mesh tutorial to learn how to generate advanced FEM head models form magnetic resonance data.

FEM conductivity tensors generation from DWI data

Among the advantages of the FEM, the use of tissue anisotropy (conductivity). The estimation of the tissue anisotropy is performed with the Brainsuite diffusion pipeline (BDP). The diffusion tensor images (DTI) are estimated with Brainsuite from the diffusion-weighted images (DWI) and then converted to conductivity tensor using the effective medieum approach. In order to use this tool, you need to install Brainsuite software, the rest of the process is distributed within bst-duneuro.

For more information, users can follow this FEM tensor tutorial.

Troubleshooting

DUNEuro binaries may crash for various reasons: we tried to list the possible causes here. Many FEM forward modeling issues are related with memory overload or extremely long computation times. Reducing the size of the problem may help in many cases. If you cannot find a solution, please post the full error message on the Brainstorm user forum (you can copy-paste the error message from the Matlab command window after closing the error message box).

Grid error messages

Error message: Coordinate is outside of the grid, or grid is not convex
Explanation: Some dipoles are probably outside of the cortex, users need to correct the source space.
Solution: ?

Remove the neck

One way to reduce the size of the forward problem is to decrease the number of FEM elements in the head model. When the field of the MRI is large, you may have the mesh of the neck and even the shoulders. In most cases, it is safe to remove the lower part of the FEM mesh, below the nose and the brainstem. Right-click on the FEM mesh > Resect Neck.

Once the process is finished, a new FEM mesh appears in the database, with a tag "resect". The following figure shows the model before (743828 vertices / 4079587 elements) and after resection (613955 vertices / 3400957 elements). It will reduce the size of the problem by 20%.

Additional documentation

DUNEuro references

DUNEuro wiki: https://gitlab.dune-project.org/duneuro/duneuro/wikis/home
DUNEuro website: http://duneuro.org/
List of the parameters: https://docs.google.com/spreadsheets/d/1MqURQsszn8Qj3-XRX_Z8qFFnz6Yl2-uYALkV-8pJVaM/edit#gid=0

-  ⇤ ← Revision 5 as of 2019-09-08 23:03:56 → 
  Size: 2943
  Editor: TakfarinasMedani
  Comment:
+   ← Revision 248 as of 2021-08-16 14:31:33 → ⇥
  Size: 17293
  Editor: FrancoisTadel
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-= Realistic head model: FEM with Duneuro =
''Authors: Takfarinas MEDANI,''
+= Realistic head model: FEM with DUNEuro =
'''[TUTORIAL UNDER REVISION]'''
 Line 4:
-This forward model uses a finite element element method (FEM) and was developed by the '''...(l''''''ink)'''. It uses the volume mesh of the realistic head model. The goal of this forward solution is mostly for '''EEG users''', to provide more accurate results than the spherical models and more complex geometry than the BEM. It is not necessary for MEG users, as the "overlapping spheres" method gives similar results but much faster. This method is illustrated using the tutorial  [[http://neuroimage.usc.edu/brainstorm/Tutorials/Epilepsy|EEG and epilepsy]] or similar data ('''todo''').
+''Authors: [[https://neuroimage.usc.edu/brainstorm/AboutUs/tmedani|Takfarinas Medani]], Juan Garcia-Prieto, Francois Tadel, Sophie Schrader, Anand Joshi, Christian Engwer, Carsten Wolters, John Mosher and Richard Leahy ''
 Line 6:
-refe to these point : http://duneuro.org/
+{{attachment:logo_duneuro.png||align="right",height="82",width="187"}}
 Line 8:
-and to the documentation from here :
+This tutorial explains how to use [[http://duneuro.org/|DUNEuro]] to compute the forward model using the '''finite element method''' ('''FEM'''). The FEM methods use a realistic volume mesh of the head generated from the segmentation of the MRI. The FEM models provide more accurate results than the spherical forward models and more realistic geometry and tissue properties than the [[Tutorials/TutBem|BEM]] methods.
 Line 10:
-https://gitlab.dune-project.org/duneuro/duneuro/wikis/home
+The scope of this page is limited to a '''basic example''' (head model with 3 layers). More advanced options for mesh generation and forward model computation are discussed in other tutorials: [[Tutorials/FemMesh|FEM mesh generation]], [[Tutorials/FemTensors|FEM tensors estimation]], [[Tutorials/FemMedianNerve|FEM median nerve example]]. We assume that you have already followed the [[Tutorials|introduction tutorials]], we will not discuss the general principles of forward modeling here.
 Line 12:
-Here we will describe the FEM  and run some examples
+<<TableOfContents(2,2)>>
 Line 14:
-== Duneuro ==
duneuro is an open-source C++ software library for solving partial differential equations in neurosciences using mesh bases methods. It is based on the DUNE library and its main features include solving the electroencephalography (EEG) and magnetoencephalography (MEG) forward problem and providing simulations for brain stimulation.
+== DUNEuro ==
'''[[http://duneuro.org/|DUNEuro]] '''is an open-source C++ software library for solving partial differential equations (PDE) in neurosciences using mesh-based methods. It is based on the''' [[https://www.dune-project.org/|DUNE library]] '''and its main features include solving the EEG and MEG forward problem and providing simulations for brain stimulation.
 Line 17:
-http://duneuro.org/
+As distributed on the [[http://gitlab.dune-project.org/duneuro/duneuro|DUNEuro GitLab]], the source code works only on Linux operating systems. Interfaces to Matlab and Python are possible, but you need to install and compile DUNEuro by yourself. For Brainstorm, we adapted this code and were able to generate '''binaries''' for the main  operating systems''' '''(Windows, '''Linux '''and MacOS), which are '''downloaded automatically''' when needed as a [[Tutorials/Plugins|Brainstorm plugin]]. This project is available on our [[https://github.com/brainstorm-tools/bst-duneuro|GitHub repository bst-duneuro]].

We would like to thank the''' DUNEuro team '''for their help with this integration work: Carsten Wolters, Christian Engwer, Sophie Schrader, Andreas Nuessing, Tim Erdbruegger, Marios Antonakakis, Johannes Vorwerk & Maria Carla Piastra.

''' {{attachment:duneuroFromDune.JPG||width="546",height="187"}} '''

Please '''cite the following papers''' if you use this software in your work:

 * Medani T, Garcia-Prieto J, Tadel F, Schrader S, Antonakakis M, Joshi A, Engwer C,  Wolters CH, Mosher JC, Leahy RM, [[https://doi.org/10.1117/12.2580935|Realistic head modeling of electromagnetic brain activity: an integrated Brainstorm-DUNEuro pipeline from MRI data to the FEM solutions]] ([[http://www.sci.utah.edu/~wolters/PaperWolters/2021/MedaniEtAl_SPIE_2021.pdf|preprint]]), SPIE Medical Imaging (2021)

Publications that make use of, or extend the DUNEuro library (listed on the [[http://duneuro.org/|duneuro website]]):

 * Piastra MC, Nüßing A, Vorwerk J, Bornfleth H, Oostenveld R, Engwer C, Wolters CH, [[https://www.frontiersin.org/articles/10.3389/fnins.2018.00030/full|The Discontinuous Galerkin Finite Element Method for Solving the MEG and the combined MEG/EEG Forward Problem]], Frontiers in Neuroscience (2018)
 * Engwer C, Vorwerk J, Ludewig J, Wolters CH, [[https://epubs.siam.org/doi/abs/10.1137/15M1048392|A discontinuous Galerkin method to solve the EEG forward problem using the subtraction approach]], SIAM Journal on Scientific Computing (2017)
 * Nüßing A, Wolters CH, Brinck H, Engwer C, [[https://ieeexplore.ieee.org/document/7511781|The unfitted discontinuous Galerkin method for solving the EEG forward problem]], IEEE Transactions on Biomedical Engineering (2016)''' '''
-Line 20:
+Line 34:
-Duneuro is build on top of DUNE Library, at this time (sept 2019) these libraries work only on Linux systems. However we are able to run generate binaries for windows and can be easily used from Matlab for all platforms.
+In order to reproduce the computation present below on your computer, you need to fulfill all the conditions listed below. Alternatively, you can read this page as a reference documentation about DUNEuro and not try to reproduce the results.
-Line 22:
+Line 36:
-However if you want to use the source code of Duneuro you can visite: http://duneuro.org/
+ * You have a working copy of Brainstorm installed on your computer.
 * You have already followed the [[https://neuroimage.usc.edu/brainstorm/Introduction|introduction tutorials]], at least until #23.
 * You have followed the tutorial [[https://neuroimage.usc.edu/brainstorm/Tutorials/Epilepsy|EEG and Epilepsy]], as it is used for illustrating the computation.
 * '''DUNEuro''': Software installed automatically as a [[https://neuroimage.usc.edu/brainstorm/Tutorials/Plugins|Brainstorm plugin]].
 * '''Iso2mesh''': Software installed automatically as a [[https://neuroimage.usc.edu/brainstorm/Tutorials/Plugins|Brainstorm plugin]].
-Line 24:
+Line 42:
-We also put here :
+== FEM mesh ==
In order to use the FEM computations of the electromagnetic field (EEG/MEG), the volume mesh of the head is required. Brainstorm integrates most of the modern open-source tools to generate realistic head mesh, either from nested surface mesh or from individual MR images (T1 or T1 and T2). This tutorial describes only a simple approach based on three nested surfaces meshed in 3D with Iso2mesh. For the full list of available methods and description of options, please refer to the tutorial [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh|FEM mesh generation]].''' '''
-Line 26:
+Line 45:
-The main steps you need in order to compile for windows are listed here :
+ * Select the protocol TutorialEpilepsy, created while following the tutorial [[http://Tutorials/Epilepsy|EEG and epilepsy]].
 * Go to the anatomy view.
 * Select the three [[https://neuroimage.usc.edu/brainstorm/Tutorials/TutBem#BEM_surfaces|BEM surfaces]]: scalp, outer skull, inner skull.
 * Right-click > '''Generate FEM mesh''' > Iso2mesh-2021 > MergeMesh > Default options. <<BR>><<BR>> {{attachment:femMesh1.gif}} <<BR>> {{attachment:iso2mesh.gif}} ''' '''
 * The FEM mesh appears in the database explorer after a short while. The first number indicates the number of vertices (i.e. nodes) of the tetrahedral mesh. To get the number of 3D  elements (i.e. tetrahedrons) in this geometric model of the head: right-click on the file > File > View file contents. The structure of the file is describe in the tutorial [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh#On_the_hard_drive|FEM mesh generation]].<<BR>><<BR>> {{attachment:femMesh2.gif}}
 * Double-click on the FEM file to display it. From the Surface tab, you can change the resection locations by moving the bottom sliders, and you can control the display of each of the three layers individually. Click on the layer button in the toolbar, then adjust the color and transparency of the corresponding mesh. The figure below represents the FEM mesh in the center and the initial BEM layers on the right. {{attachment:femMesh3.gif}}
-Line 28:
+Line 52:
-https://github.com/svdecomposer/brainstorm-duneuro
+== FEM forward model ==
To compute the forward model with the FEM method, we assume that you have followed the [[https://neuroimage.usc.edu/brainstorm/Tutorials/TutBem?highlight=(bem)|introduction tutorials]] and all the relative [[https://neuroimage.usc.edu/brainstorm/Tutorials/HeadModel|data are available]](channels files, ...). ''' '''
-Line 30:
+Line 55:
-We distribute the binary files for Windows/Ubunto 64bit systems, you don't need to installan extra Microsoft software package to run '''Duneuro'''
+First, on the anatomy view, you need to select the head model. In the case where you have multiple FEM head models, brainstorm uses the model displayed on green color. You need also to select the cortex to use as the source space. ''' '''
-Line 32:
+Line 57:
- . Microsoft Visual C++ 2010 Redistributable Package (x64).
+''' {{attachment:femNode.JPG||width="250",height="200"}}   {{attachment:modelAndCortex.JPG||width="300",height="350"}} ''' ''' '''
-Line 34:
+Line 59:
-== FEM surfaces / Volume generation ==
=== Volume generation from surface files ===
In this part you can generate your FEM mesh from surfaces that you can get fron the segmentation software (brainSuite, FreeSurfer ....).
+Then, switch to the view "Functional data (sorted by subjects)", 2nd button above the database explore. Right-click on the subject > Compute head model. Select DUNEuro FEM on the list. ''' '''
-Line 38:
+Line 61:
-This process will
+''' {{attachment:ComputeHeadModelDuneuro.JPG||width="330",height="350"}} ''' ''' '''
-Line 40:
+Line 63:
-- merge the surfaces,
+For the 'Source space,' we recommend using the 'Cortex surface'. For the forward modeling method. Both EEG/MEG computations are possible (depending on your data), and you can mixe between the available forward methods for each modality. ''' '''
-Line 42:
+Line 65:
-- check the self intersecting
+When you press OK, the panel related to DUNEuro options is displayed where you have the possibilities to change the options.
-Line 44:
+Line 67:
-- fixe the size of the mesh
+{{attachment:duneuroBasicOptions.JPG||width="300",height="300"}}
-Line 46:
+Line 69:
-- generate the volum mesh
+At this level, the basic options are the list head's tissues and their conductivities. Brainstorm reads these parameters from the selected head model.
-Line 48:
+Line 71:
-- visual checking ...
+ * '''FEM tissues or layers: '''Brainstorm detects automatically the number of layers on your model. Users can select the desired layers to include for the FEM computation. According to the modalities, the recommended selections are:
  * For EEG: select all the layers
  * For MEG: use only select the inner layers (here brain)
  * For SEEG: use only the inner layers
  * For ECOG: use only the inner layers
  * Any combinations that include MEG: use all the layers
 In this case, there is Scalp (=head), Skull (=outer skull), and Brain (=inner skull).
-Line 50:
+Line 79:
-- TODO : may be we can add some mesh auqlity measures ??
+ * '''FEM conductivities:''' Brainstorm detects automatically the number of layers and assigns the default isotropic value for each layer. However, you have the possibility to change these values according to your model.
-Line 52:
+Line 81:
+For advanced users, check the advanced section and a more detailed example at this page [[https://neuroimage.usc.edu/brainstorm/FemTensors|FEM tensor]]''.''
-Line 53:
+Line 83:
+When is finished, click on the "Ok". If you do not have the bst-duneuro toolbox, Brainstorm will ask you to install it, then click 'Yes'
-Line 54:
+Line 85:
-=== Volume generation from T1 MRI data ===
+{{attachment:popupInstallDuneuro.JPG||width="400",height="150"}}
-Line 56:
+Line 87:
-=== Head model based on the level set approach ===
+Brainstorm will download the latest version of the bst-duneuro binaries for your operating system from the Github, and install it in Brainstorm user folder (~username/.brainstorm/bst-duneuro/). The calculation of the head model will start automatically. You may wait for a very long time, which depends on the mesh resolution, the number of sensors, and of course the capacity of your computer.
-Line 58:
+Line 89:
-== Forward model ==
=== Head model ===
Number of layers, conductivity value,
+So, be patient, it's worth it...''' '''''(for this model it's quite fast ... less than 10 min)''
-Line 62:
+Line 91:
-=== Electrode model ===
Check the position of the electrodes and align to the head model (projection if needed)
+When it's finished, you have now a new head model for this subject in your database and can be used for the next steps/[[https://neuroimage.usc.edu/brainstorm/Tutorials/HeadModel|(back to tutorial 20 : Head modeling)]] {{attachment:duneuroNode.JPG||width="400",height="150"}}
-Line 65:
+Line 93:
-=== Source model ===
+=== Anisotropy tensor from the DUNEuro options ===
In the case where the conductivity tensor are computed, Brainstorm detects and uses them for the FEM forward computation.
-Line 67:
+Line 96:
-=== Advanced paramaters ===
+{{attachment:duneuroBasicOptionsTensor.JPG||width="300",height="300"}}

In this case, users can not change the conductivities values, since they are already computed as explained in this [[https://neuroimage.usc.edu/brainstorm/FemTensors|FEM tensor]].

If at some points, for any reason, where users want to remove these FEM tensors, this can be done from the Brainstorm anatomy panel, select the FEM head model, right-click on the subject, and then "clear FEM tensor".

{{attachment:clearFemTensors.JPG||width="220",height="300"}}

== Advanced models and options ==
=== DUNEuro advanced options panel [to be completed] ===
From the previous panel, for advanced duneuro panel, click on the button "Show details", the following panel is displayed.

{{attachment:duneuroAdvancedOptions.JPG||width="700",height="550"}}

A set of advanced options are made available and can be easily changed. Here a short explanation is given for each option.

 * '''FEM layers & conductivities''': same explanation as in the previous section. Moreover, in the case where the conductivity tensor are previously computed, Brainstorm detects these tensors and load them. In this case, the users can't change the conductivities scalar values, since they are not used. The following is displayed panel is displayed.

 * '''FEM solver type''':
  * CG or Continuous Galerkin: This is the standard Lagrangian method.

  * DC or the Discontinuous Galerkin:

In this version, only the Fitted FEM approaches are integrated, that require the  FEM mesh of the head model. Unfitted methods are also available within DUNEuro, and will be integrated soon in Brainstorm.

 * FEM source model: The list of the available source are
  * Venant
  * Subtraction
  * Partial Integration

For more information about these methods, users can check this thesis (Vorwek thesis).

 * Source space
  * Shrink source space: the location of dipoles are moved inward by the specified value in this field(in mm).
  * Force source space: this is required in the case where the dipoles are not within the  GM matter.
 * Outputs options
  * Save transfer matrix:

All these parameters are stored and passed to the DUNEuro as a text file. This file is the main interface that passes the parameters from Brainstorm to DUNEuro. More details about the integration can be found in these links:

 * GitHub repository for the [[https://github.com/brainstorm-tools/bst-duneuro|Brainstorm-DUNEuro]] compilation and integration
 * GitHub repository for the [[https://github.com/tmedani/duneuro_interface|matlab-duneuro interface]]
 * Brainstorm-DUNEuro integration discussions:
  * [[https://github.com/brainstorm-tools/brainstorm3/issues/185|Brainstorm-simbio/DUNEuro implementation]]/head model generation
  * [[https://github.com/brainstorm-tools/brainstorm3/issues/242|Integrate the DUNEuro FEM computation]]
  * [[https://github.com/brainstorm-tools/brainstorm3/pull/282|Genration of the FEM tensor]]
  * [[https://github.com/brainstorm-tools/brainstorm3/issues/302|Generation of the FEM source space]]

=== FEM head model generation from MRI data ===
One of the advantages of the FEM is its ability to use more complex head models with realistic geometry. In this tutorial, we have shown a basic example, as an introduction.

For the generation of a more realistic head model, users can follow this [[https://neuroimage.usc.edu/brainstorm/Tutorials/FemMesh|FEM mesh tutorial]] to learn how to generate advanced FEM head models form magnetic resonance data.

=== FEM conductivity tensors generation from DWI data ===
Among the advantages of the FEM, the use of tissue anisotropy (conductivity). The estimation of the tissue anisotropy is performed with the Brainsuite diffusion pipeline ([[http://brainsuite.org/processing/diffusion/|BDP]]). The diffusion tensor images (DTI) are estimated with Brainsuite from the diffusion-weighted images (DWI) and then converted to conductivity tensor using the [[https://www.pnas.org/content/98/20/11697|effective medieum approach]]. In order to use this tool, you need to install [[http://forums.brainsuite.org/download/|Brainsuite]] software, the rest of the process is distributed within bst-duneuro.

For more information, users can follow this [[https://neuroimage.usc.edu/brainstorm/FemTensors|FEM tensor]] [[https://neuroimage.usc.edu/brainstorm/FemTensors|tutorial]].

== Troubleshooting ==
DUNEuro binaries may crash  for various reasons: we tried to list the possible causes here. Many FEM forward modeling issues are related with memory overload or  extremely long computation times. Reducing  the size of the problem may help in many cases. If you  cannot find a solution, please post the full error message on the  Brainstorm user forum (you can copy-paste the error message from the  Matlab command window after closing the error message box).

=== Grid error messages ===
 * Error message: Coordinate is outside of the grid, or grid is not convex
 * Explanation: Some dipoles are probably outside of the cortex, users need to correct the source space.
 * Solution: ?

=== Remove the neck ===
One way to reduce the size of the forward problem is to decrease the number of FEM elements in the head model. When the field of the MRI is large, you may have the mesh of the neck and even the shoulders. In most cases, it is safe to remove the lower part of the FEM mesh, below the nose and the brainstem. Right-click on the FEM mesh > '''Resect Neck'''.

{{attachment:resectNeck.JPG||width="600",height="150"}}

Once the process is finished, a new FEM mesh appears in the database, with a tag "resect". The following figure shows the model before (743828 vertices / 4079587 elements) and after resection (613955 vertices / 3400957 elements). It will reduce the size of the problem by 20%.

{{attachment:FemMeshAllandResect.JPG||width="600",height="150"}}
-Line 70:
+Line 172:
-== Reported Errors & alternative solution ==
'''<<TAG(Advanced)>>'''
+==== Related tutorials ====
 * [[Tutorials/FemMesh|FEM mesh generation]]
 * [[Tutorials/FemTensors|FEM tensors estimation]]
 * [[Tutorials/FemMedianNerve|FEM median nerve example]]
-Line 73:
+Line 177:
-== The MEEG forward problem with the FEM ==
== License ==
== Reference ==
+==== DUNEuro references ====
 * DUNEuro wiki: https://gitlab.dune-project.org/duneuro/duneuro/wikis/home
 * DUNEuro website: http://duneuro.org/
 * List of the parameters: https://docs.google.com/spreadsheets/d/1MqURQsszn8Qj3-XRX_Z8qFFnz6Yl2-uYALkV-8pJVaM/edit#gid=0

==== Brainstorm-DUNEuro integration ====
 * https://github.com/brainstorm-tools/bst-duneuro/issues/1
 * https://github.com/brainstorm-tools/brainstorm3/issues/242
 * https://github.com/brainstorm-tools/brainstorm3/issues/185