# SpinDoctor

Documentation | Workflows | Code coverage | Quality assurance |
---|---|---|---|

This is a Julia implementation of the SpinDoctor toolbox. The original MATLAB toolbox can be found at https://github.com/SpinDoctorMRI/SpinDoctor.

## Getting started

- The
`examples`

folder contains drivers showing how to create geometry and solve different problems. - The input files for the drivers are found in the folder
`examples/setups`

, and define different models. - Multiple neuron meshes are available from
RealNeuronMeshes. These can be loaded in
the file
`examples/setups/neuron.jl`

. - See the documentation page for more details.

## Gallery

### Setup recipes

DiskSetup | PlateSetup | SphereSetup |

CylinderSetup | SlabSetup | NeuronSetup |

### Matrix formalism with Laplace eigenfunctions

### Spinning spindle spins in SpinDoctor

The above graphic visualizes the real part of the magnetization as a z-displacement for the
spindle neuron geometry `03b_spindle4aACC`

(extracted from
NeuroMorpho). The gradient is a PGSE sequence in the x-direction.
The magnetization was saved for 200 time steps, and the exported VTK sequence was visualized
using ParaView.

### Test new gradient sequences with live plotting

Here the magnetization is shown in a dendrite branch during a three-dimensional gradient sequence.

## About

SpinDoctor is a software package that performs numerical simulations of diffusion magnetic resonance imaging (dMRI) for prototyping purposes.

SpinDoctor can be used

- to solve the Bloch-Torrey partial differential equation (BTDPE) to obtain the dMRI signal (the toolbox provides a way of robustly fitting the dMRI signal to obtain the fitted Apparent Diffusion Coefficient (ADC));
- to solve the diffusion equation for the homogenized ADC (HADC) model to obtain the ADC;
- a short-time approximation formula for the ADC is also included in the toolbox for comparison with the simulated ADC;
- Compute the dMRI signal using a matrix formalism (MF) analytical solution based Laplace eigenfunctions.

The PDEs and Laplace eigenvalue decompositions are solved by P1 finite elements. The geometry recipes create surface triangulations that are passed to TetGen to perform the finite element mesh generation. For 2D geometries, as similar approach is used, with Triangle.

SpinDoctor has support for the following features:

- multiple compartments connected through permeable membranes, with different
- initial spin densities,
- diffusion tensors,
- T2-relaxation, and
- permeability coefficients for the BTPDE and MF (the HADC assumes negligible permeability);

- diffusion-encoding gradient pulse sequences, including
- the pulsed gradient spin echo sequence (PGSE),
- the double-PGSE,
- the oscillating gradient spin echo (OGSE), and
- custom three-dimensional pulse sequences
`g⃗(t) = (g_x(t), g_y(t), g_z(t))`

;

- uniformly distributed gradient directions in 2D and 3D for high angular resolution diffusion imaging (HARDI).
- Live plotting utilities
- Export VTK snapshots or time series to visualize finite element magnetization fields in ParaView.

SpinDoctor also comes with a geometry generation module, allowing for

- multilayered spherical cells with a nucleus;
- multilayered disk and cylinder cells with a myelin layer;
- an extra-cellular space (ECS) enclosed in either a box, a convex hull, or a tight wrapping around the cells;
- stacks of plates or slab cells;
- deformation of canonical cells by bending and twisting.

In addition, a variety of neuron meshes is available, whose surface geometries were extracted from NeuroMopho.org. The neurons may also be enclosed in an extracellular space as described above.

## How to cite us

If you use our software for research, please consider citing us. See CITATION.md for further details.