|
|
The MEEG-Driver is the main user interface of DUNEuro. Once it is constructed, it can be used for the computation and application of the transfer matrix as well as the direct forward computation. Below, the most important functions are listed, together with their required input parameters and their output.
|
|
|
|
|
|
General
|
|
|
- [`makeDomainFunction`](#makedomainfunction)
|
|
|
- [`write`](#writesolution-config)
|
|
|
|
|
|
EEG
|
|
|
- [`setElectrodes`](#setelectrodeselectrodes-config)
|
|
|
- [`solveEEGForward`](#solveeegforwarddipole-solution-config)
|
|
|
- [`evaluateAtElectrodes`](#evaluateatelectrodessolution)
|
|
|
- [`computeEEGTransferMatrix`](#computeeegtransfermatrixconfig)
|
|
|
- [`applyEEGTransfer`](#applyeegtransfertransfermatrix-dipoles-config)
|
|
|
|
|
|
MEG
|
|
|
- [`setCoilsAndProjections`](#setcoilsandprojectionscoils-projections)
|
|
|
- [`solveMEGForward`](#solvemegforwardeegsolution-config)
|
|
|
- [`computeMEGTransferMatrix`](#computemegtransfermatrixconfig)
|
|
|
- [`applyMEGTransfer`](#applymegtransfertransfermatrix-dipoles-config)
|
|
|
|
|
|
----
|
|
|
# General
|
|
|
----
|
|
|
## `makeDomainFunction()`
|
|
|
The main purpose of the domain function is to store the solution of a single EEG forward computation. It can the be used to write out the visualization or to evaluate the function at the electrodes.
|
|
|
### parameters: -
|
|
|
|
|
|
### returns:
|
|
|
- **function**
|
|
|
an object that is basically a FEM function represented by its DOF vector. However, as the exact storage of the DOF vector might differ between different FEM methods (e.g. CG-FEM uses one DOF per node, while DG-FEM uses DOFs per element that are blocked element-wise), the entries are hidden and there is currently no way to access them via this interface
|
|
|
|
|
|
----
|
|
|
## `write(config)`
|
|
|
|
|
|
Write out the volume conductor to a file. The output will include the mesh as well as the different conductivities. Depending on the solver type, it might include additional information.
|
|
|
|
|
|
### parameters:
|
|
|
- **config**
|
|
|
Configuration of the write process
|
|
|
|
|
|
For the different solver methods there are different options for the configuration. For fitted methods (e.g. CG and DG):
|
|
|
- **'format' : 'vtk'**
|
|
|
File format of the output. Currently only vtk is supported.
|
|
|
|
|
|
For the vtk output, there are additional options:
|
|
|
- **'filename' : string**
|
|
|
name of the output file without the file extension
|
|
|
- **'subsampling' : int (default: 0)**
|
|
|
number times the mesh should be subsampled for output. This is especially useful for hexahedral meshes, as we might have multilinear instead of linear basis functions and some tools (e.g. Paraview) do not properly visualize multilinear data.
|
|
|
- **'anisotropy.enable' : bool (default: false)**
|
|
|
usually, the conductivity is exported as the $\infty$-norm of the conductivity tensor. When this parameter is set, we additionally export the eigenvectors of the tensors, scaled by their corresponding eigenvalues. Note that this requires the *Eigen* library.
|
|
|
|
|
|
### returns: -
|
|
|
|
|
|
----
|
|
|
## `write(solution, config)`
|
|
|
Write out the volume conductor, the potential and its gradient to a file. The output will include the mesh as well as the different conductivities. If meg was set in the constructor, the flux will be written to the file as well. Depending on the solver type, it might include additional information.
|
|
|
### parameters:
|
|
|
- **solution**
|
|
|
Solution of the EEG forward problem
|
|
|
- **config**
|
|
|
Configuration of the write process
|
|
|
|
|
|
For the different solver methods there are different options for the configuration. For fitted methods (e.g. CG and DG):
|
|
|
- **'format' : 'vtk'**
|
|
|
File format of the output. Currently only vtk is supported.
|
|
|
|
|
|
For the vtk output, there are additional options:
|
|
|
- **'filename' : string**
|
|
|
see above
|
|
|
- **'subsampling' : int (default: 0)**
|
|
|
see above
|
|
|
- **'anisotropy.enable' : bool (default: false)**
|
|
|
see above
|
|
|
- **'potential.type' : {'vertex','cell'} (default: 'vertex')**
|
|
|
Whether the potential should be written out as vertex or as cell data.
|
|
|
- **'gradient.type' : {'vertex','cell'} (default: 'vertex')**
|
|
|
Whether the gradient of the potential should be written out as vertex or as cell data.
|
|
|
|
|
|
### returns: -
|
|
|
|
|
|
----
|
|
|
# EEG
|
|
|
----
|
|
|
## `setElectrodes(electrodes, config)`
|
|
|
The electrode positions are passed and projected to the mesh.
|
|
|
### parameters:
|
|
|
- **electrodes**
|
|
|
Positions of EEG sensors
|
|
|
- **config**
|
|
|
Configuration specifying how to set the electrode positions
|
|
|
|
|
|
There are different options for the configuration:
|
|
|
- **'type' : {'normal', 'closest_subentity_center'}**
|
|
|
This option specifies whether the electrode positions should be moved to the mesh by projecting them orthogonally to the surface or to set them to the closest subentity.
|
|
|
|
|
|
For the closest_subentity_center option, there are additional options:
|
|
|
- **'codims' : int**
|
|
|
Codimension (difference between world and entity dimension) of subentities to which the electrodes should be projected (e.g., '3' implies nodes, '2' edges,...).
|
|
|
|
|
|
### returns: -
|
|
|
|
|
|
----
|
|
|
## `solveEEGForward(dipole, solution, config)`
|
|
|
This function can be used to directly solve the linear system in order to compute the EEG forward solution, as opposed to using the transfer matrix approach. This is typically useful for a small number of dipoles, e.g., for visualization purposes.
|
|
|
### parameters:
|
|
|
- **dipole**
|
|
|
Dipole for which the EEG forward solution should be computed.
|
|
|
- **solution**
|
|
|
A function created using makeDomainFunction that will store the forward solution after this method is called.
|
|
|
- **config**
|
|
|
Configuration specifying how to set the electrode positions.
|
|
|
|
|
|
There are different options for the configuration:
|
|
|
- **'post_process' : bool**
|
|
|
This parameter specifies if the solution is post-processed. For the subtraction source model, this means that the analytical contribution to the solution is added.
|
|
|
- **'subtract_mean' : bool**
|
|
|
In case of fitted methods, the direct solution of the EEG forward problem is average-referenced if this parameter is set true.
|
|
|
- **'source_model' : configuration**
|
|
|
The source_model configuration contains further parameters that specify the source model in a tree structure:
|
|
|
|
|
|
- **'type' : {'partial_integration', 'venant', 'subtraction', 'whitney'}**
|
|
|
The type specifies the source model that is used for the discretization of the source.
|
|
|
|
|
|
Depending on the type (except for the partial integration source model), further parameters apply.
|
|
|
For the St. Venant source model, the following parameters are relevant:
|
|
|
- **'numberOfMoments' : int**
|
|
|
- **'weightingExponent' : int**
|
|
|
- **'relaxationFactor' : double**
|
|
|
- **'mixedMoments' : int**
|
|
|
- **'referenceLength' : int**
|
|
|
- **'relaxationFactor' : int**
|
|
|
- **'initialization' : {'single_element', 'closest_vertex'}**
|
|
|
- **'weightingExponent' : int**
|
|
|
- **'restrict' : bool**
|
|
|
|
|
|
For the Whitney source model, the following parameters apply:
|
|
|
- **'faceSources' : {'all', 'none'}**
|
|
|
- **'edgeSources' : {'all', 'internal', 'none'}**
|
|
|
- **'interpolation' : {'PBO', 'MPO'}**
|
|
|
- **'referenceLength' : int**
|
|
|
- **'restricted' : bool**
|
|
|
|
|
|
for the subtraction source model, the following parameters apply:
|
|
|
- **'intorderadd' : int**
|
|
|
- **'intorderadd_lb' : int**
|
|
|
These parameters specify the integration order.
|
|
|
|
|
|
Additionally to the source model specific parameters, the UDG method requires the following parameters:
|
|
|
- **'compartment' : int**
|
|
|
The index of the compartment of the source is specified (typically brain/gray matter).
|
|
|
- **'scalePointsToBBox' : bool**
|
|
|
In order to improve the condition number of the stiffenss matrix, the local basis functions on each cut-cell are scaled to the respective bounding box if this parameter is set true.
|
|
|
|
|
|
### returns: -
|
|
|
|
|
|
----
|
|
|
## `evaluateAtElectrodes(solution)`
|
|
|
After solving the EEG forward problem directly (solveEEGForward), the potential is evaluated at the electrode positions.
|
|
|
### parameters:
|
|
|
- **solution**
|
|
|
The EEG forward solution computed with solveEEGForward is passed.
|
|
|
### returns:
|
|
|
- **leadfield**
|
|
|
The potential at the electrodes
|
|
|
|
|
|
----
|
|
|
## `computeEEGTransferMatrix(config)`
|
|
|
The transfer matrix is computed, which is especially useful if the number of sources outnumbers the sensors, which is usually the case in source analysis applications.
|
|
|
### parameters:
|
|
|
- **config**
|
|
|
Configuration specifying different options for the numerical computation.
|
|
|
|
|
|
These options are:
|
|
|
- **reduction: double**
|
|
|
The relative reduction of the solver
|
|
|
- **compartment: int**
|
|
|
the index of the compartment for the sensors needs to be passed in case UDG is used.
|
|
|
|
|
|
### returns:
|
|
|
- **transferMatrix**
|
|
|
The EEG transfer matrix
|
|
|
|
|
|
----
|
|
|
## `applyEEGTransfer(transferMatrix, dipoles, config)`
|
|
|
After computing the transfer matrix (computeEEGTransferMatrix), it is multiplied with the right hand side in order to compute the EEG leadfield.
|
|
|
### parameters:
|
|
|
- **transferMatrix**
|
|
|
The transfer matrix computed using computeEEGTransferMatrix.
|
|
|
- **dipoles**
|
|
|
A function created using makeDomainFunction that will store the forward solution after this method is called.
|
|
|
- **config**
|
|
|
Configuration specifying the source model options, which is identical to the one passed in solveEEGForward (see above).
|
|
|
|
|
|
### returns:
|
|
|
- **leadfield**
|
|
|
EEG leadfield: The potential at the electrodes is computed.
|
|
|
|
|
|
----
|
|
|
# MEG
|
|
|
----
|
|
|
## `setCoilsAndProjections(coils, projections)`
|
|
|
### parameters:
|
|
|
none
|
|
|
### returns:
|
|
|
nothing
|
|
|
|
|
|
----
|
|
|
## `solveMEGForward(eegSolution, config)`
|
|
|
### parameters:
|
|
|
none
|
|
|
### returns:
|
|
|
nothing
|
|
|
|
|
|
----
|
|
|
## `computeMEGTransferMatrix(config)`
|
|
|
### parameters:
|
|
|
none
|
|
|
### returns:
|
|
|
nothing
|
|
|
|
|
|
----
|
|
|
## `applyMEGTransfer(transferMatrix, dipoles, config)`
|
|
|
### parameters:
|
|
|
none
|
|
|
### returns:
|
|
|
nothing |