= Realistic head model: BEM with OpenMEEG =
''Authors: Francois Tadel, Alexandre Gramfort''

This forward model uses a symmetric boundary element  method (symmetric BEM) and was developed by the French public research institute INRIA ([[http://openmeeg.github.io|website]]).  It uses three realistic layers (scalp, inner skull, outer skull). The goal of this forward solution is mostly for '''EEG users''', to provide more accurate results than the spherical models. 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]].

{{attachment:openmeeg.gif||width="274px",height="75px"}}

<<TableOfContents(2,2)>>

== Requirements ==
On Windows 64bit systems, you need to install an extra Microsoft software package to run OpenMEEG: Microsoft Visual C++ 2010 Redistributable Package (x64).<<BR>>http://www.microsoft.com/en-us/download/details.aspx?id=14632

== BEM surfaces ==
We need three realistic layers extracted from the subject's MRI (scalp, inner skull, outer skull), plus the source space (cortical surface). These layers are sometimes complicated to generate. In the case you do not have any way to calculate the inner skull and outer skull surfaces, Brainstorm can generate rough approximations based on the subject's cortex and head surfaces and ICBM152's inner and outer skull surfaces. The surfaces created with Brainstorm are by construction non-intersecting.

 1. Select the protocol TutorialEpilepsy.
 1. Go to the anatomy view (first button on top of the database explorer).
 1. Right-click on the subject folder > '''Generate BEM surfaces'''. You can set the approximate number of vertices you want for each layer. For this example, leave the default parameters and click on Ok. <<BR>><<BR>> {{attachment:bemPopup.gif}}  {{attachment:bemOptions.gif}}
 1. At the end of the process, three new surfaces are added to the database:<<BR>><<BR>> {{attachment:bemFiles.gif}}  {{attachment:bem3d.gif||width="299",height="260"}}

==== How to set the number of vertices per layer ====
 * The more vertices for each layer, the more accurate your head model. If there are not enough vertices, OpenMEEG may consider that the surfaces are intersecting and crash before the computation, or it may finish but at the end the model may be instable with a few vertices with values much higher than all the others.
 * On the other hand, using more vertices on each layer increases a lot the amount of memory necessary and the computation time. If your system hangs, if it takes 24hrs to run or if you get "Out of memory" errors, you should decrease the number of vertices for each layer.
 * The default values are high (1922 vertices per layer), to ensure that by default the results are good. If you can afford it computationally, you should use these '''1922 vertices''' per layer. If you have to decrease these values, you can try for instance with '''1082 vertices '''(scalp) and '''642 vertices '''(outer skull and innser skull).
 * If you are using the default ICBM152 anatomy, you do not need to run this, you can directly use the head/outerskull/innerskull surfaces in the the default anatomy folder. The number of vertices is much lower, but we know this anatomy to be stable, you should not need to recalculate new surfaces with more vertices.

== Forward model ==
 1. Switch to the view "Functional data (sorted by subjects)", 2nd button above the database explore.
 1. Right-click on the channel file > '''Compute head model'''. Select '''OpenMEEG BEM''' in the list. <<BR>><<BR>> {{attachment:headmodeler.gif||width="670",height="326"}}
 1. Explanations of the options:
  * '''BEM Layers & conductivities''': You can select how many layers you want to use for the BEM model. The possible options in our case are Scalp (=head), Skull (=outer skull), and Brain (=inner skull). The values on the right are the relative conductivities of each layer.
   * For EEG: Use all the layers
   * For MEG: Use only the inner skull layer
  * '''Use adjoint formulation''': Decrease significantly the amount of memory that is necessary in memory and on the hard drive, but much longer.
  * '''Use adaptive integration''': This produces a more accurate solution, mostly in the cases of dipoles (vertices of the cortex surface) that are very close to the inner skull layer. Keep this option selected.
  * '''Process dipoles by blocks''': If you consistently run into crashes, it could be because you don't have enough memory available. You can try to process the dipoles by smaller blocks. It would be longer but could work. Select this option only if you have memory errors.
 1. Download OpenMEEG software? '''Yes'''.<<BR>> This will download the latest version of the OpenMEEG binaries for your operating system from INRIA website, and install it in Brainstorm user folder (~username/.brainstorm/openmeeg/)<<BR>><<BR>> {{attachment:openmeegDownload.gif}}
 1. Then the calculation of the head model will automatically start. You may wait for a very long time. Be patient, it's worth it...<<BR>><<BR>> {{attachment:openmeegWait.gif}}
 1. You have now a new head model for this subject.<<BR>><<BR>> {{attachment:treeFinal.gif}}

== Errors ==
OpenMEEG may crash for various reasons: we tried to list the possible causes here, referenced by error message. 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).

=== Linux ===
 * OpenMEEG error #1:<<BR>>./om_assemble:  /usr/local/MATLAB/R2013b/sys/os/glnxa64/libstdc++.so.6: version  `GLIBCXX_3.4.19’ not found (required by ./om_assemble)
  * '''Cause''': Your version of Matlab uses a version of library libstdc++ that is older than the one required by OpenMEEG.
  * '''Solution''': If your operating system is up-to-date, you should have a newer version available on your hard drive. You need to tell Matlab to use the local version of libstdc++ instead of the one shipped with Matlab. In order to do this, open a terminal and start Matlab in the following way: <<BR>>LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 /usr/local/bin/matlab
  * You might need to adjust the path to the Matlab executable (get it by typing "which matlab") or the libstdc++ library (type "locate libstdc++.so.6" and pick the one in /usr/lib)

=== All systems ===
 * OpenMEEG cannot be downloaded:
  * '''Cause''': You have a proxy that is not configured correctly with Matlab.
  * '''Solution''': Download OpenMEEG manually (http://openmeeg.gforge.inria.fr/download/) and use the Brainstorm menu Update > Update OpenMEEG > Install.
 *

== Additional documentation on the forum ==
Download problems:

 * [[http://neuroimage.usc.edu/forums/showthread.php?1066-Impossible-to-download-OpenMEEG|http://neuroimage.usc.edu/forums/showthread.php?1066]]

Binary issues / Error #-1073741515:

 * [[http://neuroimage.usc.edu/forums/showthread.php?744-Problem-with-BST-and-Windows-7|http://neuroimage.usc.edu/forums/showthread.php?744]]
 * http://neuroimage.usc.edu/forums/showthread.php?767
 * http://neuroimage.usc.edu/forums/showthread.php?1145

Library issues / Error #1:

 * http://neuroimage.usc.edu/forums/showthread.php?1309-compute-head-model-issue

Memory allocation failed:

 * http://neuroimage.usc.edu/forums/showthread.php?1138

Intersecting meshes:

 * http://neuroimage.usc.edu/forums/showthread.php?1030
 * http://neuroimage.usc.edu/forums/showthread.php?1305

Format of the Gain matrix in the headmodel file:

 * http://neuroimage.usc.edu/forums/showthread.php?918
 * http://neuroimage.usc.edu/forums/showthread.php?1353

== License ==
OpenMEEG is distributed under the French opensource license [[http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html|CeCILL-B]]. It is     intended to give users the freedom to modify and redistribute the     software. It is therefore compatible with popular opensource licenses     such as the GPL and BSD licenses. The CeCILL-B license imposes to     anybody distributing a software incorporating OpenMEEG the obligation     to give credits (by citing the appropriate publications), in order for     all contributions to be properly identified and acknowledged.

The references to be acknowledged are:

 * Gramfort A, Papadopoulo T, Olivi E, Clerc M<<BR>>[[http://www.biomedical-engineering-online.com/content/9/1/45|OpenMEEG: opensource software for quasistatic bioelectromagnetics]]<<BR>>BioMedical Engineering OnLine 45:9, 2010
 * Kybic J, Clerc M, Abboud T, Faugeras O, Keriven R, Papadopoulo T<<BR>>[[http://ieeexplore.ieee.org/xpls/abs_all.jsp?isnumber=30034&arnumber=1375158&count=10&index=1|A common formalism for the integral formulations of the forward EEG problem]]<<BR>>IEEE Transactions on Medical Imaging, 24:12-28, 2005 | [[ftp://ftp-sop.inria.fr/odyssee/Publications/2005/kybic-clerc-etal:05.pdf|pdf]]

<<EmbedContent(http://neuroimage.usc.edu/bst/get_feedback.php?Tutorials/TutBem)>>