# API

## Isochromat Operators

`BlochSimulators.Isochromat`

— Type```
struct Isochromat{T<:Real} <: FieldVector{3,T}
x::T
y::T
z::T
end
```

Holds the x,y,z components of a spin isochromat in a FieldVector, which is a `StaticVector`

(from the package `StaticArrays`

) with custom fieldnames.

`BlochSimulators.decay`

— Method`decay(m::Isochromat{T}, E₁, E₂) where T`

Apply T₂ decay to transverse component and T₁ decay to longitudinal component of `Isochromat`

.

`BlochSimulators.initialize_states`

— Method`initialize_states(::AbstractResource, ::IsochromatSimulator{T}) where T`

Initialize a spin isochromat to be used throughout a simulation of the sequence.

This may seem redundant but to is necessary to share the same programming interface with `EPGSimulators`

.

`BlochSimulators.invert`

— Method`invert(m::Isochromat{T}, p::AbstractTissueParameters) where T`

Invert `Isochromat`

with B₁ insenstive (i.e. adiabatic) inversion pulse

`BlochSimulators.invert`

— Method`invert(m::Isochromat{T}, p::AbstractTissueParameters) where T`

Invert z-component of `Isochromat`

(assuming spoiled transverse magnetization so xy-component zero).

`BlochSimulators.regrowth`

— Method`regrowth(m::Isochromat{T}, E₁) where T`

Apply T₁ regrowth to longitudinal component of `Isochromat`

.

`BlochSimulators.rotate`

— Method`rotate(m::Isochromat, γΔtGRz, z, Δt, p::AbstractTissueParameters)`

Rotation of Isochromat without RF (so around z-axis only) due to gradients and B0 (i.e. refocussing slice select gradient).

`BlochSimulators.rotate`

— Method`rotate(m::Isochromat{T}, γΔtRF::Complex, γΔtGR::Tuple, (x,y,z), Δt, p::AbstractTissueParameters, Δω = zero(T)) where T`

RF, gradient and/or ΔB₀ induced rotation of Isochromat computed using Rodrigues rotation formula (https://en.wikipedia.org/wiki/Rodrigues%27*rotation*formula).

`BlochSimulators.sample_transverse!`

— Method`sample!(output, index::Union{Integer,CartesianIndex}, m::Isochromat)`

Sample transverse magnetization from `Isochromat`

. The "+=" is needed for 2D sequences where slice profile is taken into account.

`BlochSimulators.sample_xyz!`

— Method`sample_xyz!(output, index::Union{Integer,CartesianIndex}, m::Isochromat)`

Sample m.x, m.y and m.z components from `Isochromat`

. The "+=" is needed for 2D sequences where slice profile is taken into account.

## EPG Operators

`BlochSimulators.EPGStates`

— Type`EPGStates = Union{MMatrix{3}, SizedMatrix{3}}`

In the EPG model, the configuration state matrix `Ω`

will be updated inplace. On CPU, we use `StaticArrays.MMatrix`

. The MMatrix will not escape `_simulate!`

and therefore should not result in allocations. On GPU, we use shared memory (`CUDA.CuStaticSharedArray`

). The shared memory is allocated for all threads within a block simultaneously. We then take a `@view`

and wrap it in a `SizedArray`

. Without the `SizedArray`

, the type would be long and unreadable. By wrapping, we can then simply dispatch on a `SizedArray`

instead.

`BlochSimulators.F̄₋`

— Method`F̄₋(Ω)`

View into the second row of the configuration state matrix `Ω`

, corresponding to the `F̄₋`

states.

`BlochSimulators.F₊`

— Method`F₊(Ω)`

View into the first row of the configuration state matrix `Ω`

, corresponding to the `F₊`

states.

`BlochSimulators.Z`

— Method`Z(Ω)`

View into the third row of the configuration state matrix `Ω`

, corresponding to the `Z`

states.

`BlochSimulators.decay!`

— Method`decay!(Ω::EPGStates, E₁, E₂)`

T₂ decay for F-components, T₁ decay for `Z`

-component of each state.

`BlochSimulators.dephasing!`

— Method`dephasing!(Ω::EPGStates)`

Shift states around due to dephasing gradient: The `F₊`

go up one, the `F̄₋`

go down one and `Z`

do not change

`BlochSimulators.excite!`

— Method`excite!(Ω::EPGStates, RF::Complex, p::AbstractTissueParameters)`

Mixing of states due to RF pulse. Magnitude of RF is the flip angle in degrees. Phase of RF is the phase of the pulse. If RF is real, the computations simplify a little bit.

`BlochSimulators.excite!`

— Method`excite!(Ω::EPGStates, RF::T, p::AbstractTissueParameters) where T<:Union{Real, Quantity{<:Real}}`

If RF is real, the calculations simplify (and probably Ω is real too, reducing memory (access) requirements).

`BlochSimulators.initial_conditions!`

— Method`initial_conditions!(Ω::EPGStates)`

Set all components of all states to 0, except the Z-component of the 0th state which is set to 1.

`BlochSimulators.initialize_states`

— Method`initialize_states(::AbstractResource, sequence::EPGSimulator{T,Ns}) where {T,Ns}`

Initialize an `MMatrix`

of EPG states on CPU to be used throughout the simulation.

`BlochSimulators.initialize_states`

— Method`initialize_states(::CUDALibs, sequence::EPGSimulator{T,Ns}) where {T,Ns}`

Initialize an array of EPG states on a CUDA GPU to be used throughout the simulation.

`BlochSimulators.invert!`

— Method`invert!(Ω::EPGStates, p::AbstractTissueParameters)`

Invert `Z`

-component of states of all orders. *Assumes fully spoiled transverse magnetization*.

`BlochSimulators.invert!`

— Method`invert!(Ω::EPGStates)`

Invert with B₁ insenstive (i.e. adiabatic) inversion pulse

`BlochSimulators.regrowth!`

— Method`regrowth!(Ω::EPGStates, E₁)`

T₁ regrowth for Z-component of 0th order state.

`BlochSimulators.rotate!`

— Method`rotate!(Ω::EPGStates, eⁱᶿ::T) where T`

Rotate `F₊`

and `F̄₋`

states under the influence of `eⁱᶿ = exp(i * ΔB₀ * Δt)`

`BlochSimulators.rotate_decay!`

— Method`rotate_decay!(Ω::EPGStates, E₁, E₂, eⁱᶿ)`

Rotate and decay combined

`BlochSimulators.sample_transverse!`

— Method`sample_transverse!(output, index::Union{Integer,CartesianIndex}, Ω::EPGStates)`

Sample the measurable transverse magnetization, that is, the `F₊`

component of the 0th state. The `+=`

is needed for 2D sequences where slice profile is taken into account.

`BlochSimulators.sample_Ω!`

— Method`sample_Ω!(output, index::Union{Integer,CartesianIndex}, Ω::EPGStates)`

Sample the entire configuration state matrix `Ω`

. The `+=`

is needed for 2D sequences where slice profile is taken into account.

`BlochSimulators.spoil!`

— Method`spoil!(Ω::EPGStates)`

Perfectly spoil the transverse components of all states.

`BlochSimulators.Ω_eltype`

— Method`Ω_eltype(sequence::EPGSimulator{T,Ns}) where {T,Ns} = Complex{T}`

By default, configuration states are complex. For some sequences, they will only ever be real (no RF phase, no complex slice profile correction) and for these sequences a method needs to be added to this function.

## Tissue Parameters

`BlochSimulators.AbstractTissueParameters`

— Type`AbstractTissueParameters{N,T} <: FieldVector{N,T}`

Abstract type for structs that hold different combinations of tissue parameters.

**Possible fields**

`T₁::T`

: T₁ relaxation parameters of a voxel`T₂::T`

: T₂ relaxation parameters of a voxel`B₁::T`

: Scaling factor for effective B₁ excitation field within a voxel`B₀::T`

: Off-resonance with respect to main magnetic field within a voxel`ρˣ::T`

: Real part of proton density within a voxel`ρʸ::T`

: Imaginary part of proton density within a voxel

The structs are subtypes of FieldVector, which is a StaticVector with named fields (see the documentation of StaticArrays.jl). There are three reasons for letting the structs be subtypes of FieldVector:

- FieldVectors/StaticVectors have sizes that are known at compile time. This is beneficial for performance reasons
- The named fields improve readability of the code (e.g.
`p.B₁`

vs`p[3]`

) - Linear algebra operations can be performed on instances of the structs. This allows, for example, subtraction (without having to manually define methods) and that is useful for comparing parameter maps.

## Sequences

#### Abstract Types

`BlochSimulators.BlochSimulator`

— Type`BlochSimulator{T}`

The abstract type of which all sequence simulators will be a subtype. The parameter `T`

should be a number type (e.g. `Float64`

, `Float32`

) and the tissueparameters that are used as input to the simulator should have the same number type. By convention, a BlochSimulator will be used to simulate magnetization at echo times only without taking into account spatial encoding gradients (i.e. readout or phase encoding gradients). To simulate the magnetization at other readout times, including phase from spatial encoding gradients, an `AbstractTrajectory`

will be needed as well.

To make a simulator for a particular pulse sequence:

Make a struct that's a subtype of either

`IsochromatSimulator`

or`EPGSimulator`

. The struct will hold parameters that are necessary for performing the simulations.Add a method to

`simulate_magnetization!`

that implements the pulse sequence. For both performance and GPU compatibility, make sure that`simulate_magnetization!`

does not do any heap allocations. Examples for`pSSFP`

and`FISP`

sequences are found in`src/sequences`

.Add methods to

`output_eltype`

and`output_size`

that are used to allocate an output array within the simulate function.[Optional] Add a method to show for nicer printing of the sequence in the REPL

[Optional] Add a method to getindex to easily reduce the length of the sequence

[Optional] Add a constructor for the struct that takes in data from Matlab or something else and assembles the struct

**IMPORTANT**

The `simulate_magnetization!`

functions (which dispatch on the provided sequence) are assumed to be type-stable and non-allocating Should be possible to achieve when using functions from `operators/epg.jl`

`and`

operators/isochromat.jl` and a properly parametrized sequence struct.

`BlochSimulators.IsochromatSimulator`

— Type`IsochromatSimulator{T} <: BlochSimulator{T}`

Abstract type of which all sequence simulators that are based on the isochromat model will be a subtype. The parameter `T`

should be a number type (e.g. `Float64`

, `Float32`

) and the tissueparameters that are used as input to the simulator should have the same number type.

`BlochSimulators.EPGSimulator`

— Type`EPGSimulator{T,Ns} <: BlochSimulator{T}`

Abstract type of which all sequence simulators that are based on the EPG model will be a subtype. The parameter `T`

should be a number type (e.g. `Float64`

, `Float32`

) and the tissueparameters that are used as input to the simulator should have the same number type. The parameter `Ns`

corresponds to the maximum order of configuration states that are tracked in the simulations.

#### Interface

#### Examples

`BlochSimulators.Generic2D`

— Type`Generic2D{T,V,M,S} where {T<:AbstractFloat, V<:AbstractVector, M<:AbstractMatrix, S} <: IsochromatSimulator{T}`

Simulate a generic 2D sequence defined by arrays containing RF and gradient waveforms. Contains a loop over z locations to take into account slice profile effects. The Δt vector stores the time intervals for the waveforms.

**Fields**

`RF::V{Complex{T}}`

: Vector with (complex) RF values during each time interval`GR::M{T}`

: Matrix with GRx, GRy and GRz values during each time interval`sample::S`

: Vector with Bool's to indicate the sample points`Δt::V{T}`

: Vector with time intervals`z::V{T}`

: Vector with different positions along the slice direction

`BlochSimulators.Generic3D`

— Type`Generic3D{T,V<:AbstractVector{Complex{T}},W<:AbstractVector{T},M<:AbstractMatrix{T},S} <: IsochromatSimulator{T}`

Simulate a generic sequence defined by arrays containing RF and gradient waveforms. Unlike the Generic2D sequence, it is assumed that the excitation is homogenous over the voxel and therefore no summation over a slice direction is applied. The Δt vector stores the time intervals for the waveforms.

**Fields**

`RF::V{Complex{T}}`

: Vector with (complex) RF values during each time interval`GR::M{T}`

: Matrix with GRx, GRy and GRz values during each time interval`sample::S`

: Vector with Bool's to indicate the sample points`Δt::V{T}`

: Vector with time intervals

## Trajectories

#### Abstract types

`BlochSimulators.AbstractTrajectory`

— Type`AbstractTrajectory{T}`

The abstract type of which all gradient trajectories will be a subtype. The subtypes should contain fields that can describe the full trajectory during a sequence. The type T refers to the precision of the floating point values within the trajectory struct.

`BlochSimulators.SpokesTrajectory`

— Type`SpokesTrajectory{T} <: AbstractTrajectory{T}`

Typical Cartesian and radial trajectories have a lot in common: a readout can be described by a starting point in k-space and a Δk per sample point. To avoid code repetition, both type of trajectories are made a subtype of SpokesTrajectory such that some methods that would be the same for both trajectories otherwise are written for SpokesTrajectory instead.

#### Interface

#### Examples

`BlochSimulators.CartesianTrajectory`

— Type`CartesianTrajectory{T,I,U,V} <: SpokesTrajectory{T}`

Struct that is used to implement a typical Cartesian gradient trajectory. The trajectory is described in a compact fashion by only storing the starting position in k-space (`k_start_readout`

) for each readout as well as the step in k-space per readout point `Δk_adc`

.

Note that CartesianTrajectory and RadialTrajectory are essentially the same in when using when using this compact description. A SpokesTrajectory struct is therefore defined as a supertype of both and methods are defined for SpokesTrajectory instead to avoid code repetition.

The type parameters are intentionally left vague. The `J`

, for example, may be an integer for sequences where each readout has the same number of samples, but for sequences with different numbers of samples per readout it may be a vector of integers.

**Fields**

`nreadouts::I`

: The total number of readouts for this trajectory`nsamplesperreadout::I`

: The total number of samples per readout`Δt::T`

: Time between sample points`k_start_readout::U`

: Starting position in k-space for each readout`Δk_adc::U`

: k-space step Δkₓ per sample point (same for all readouts)`py::V`

: Phase encoding index for each readout`readout_oversampling::I`

: Readout oversampling factor

`BlochSimulators.kspace_coordinates`

— Method`kspace_coordinates(tr::CartesianTrajectory)`

Return matrix (nrsamplesperreadout, nrreadouts) with kspace coordinates for the trajectory. Needed for nuFFT reconstructions.

`BlochSimulators.magnetization_to_signal`

— Method`magnetization_to_signal(resource, magnetization, parameters, trajectory, coordinates, coil_sensitivities)`

Arguments

`magnetization`

: Matrix{Complex} of size (# readouts, # voxels) with phase-encoded magnetization at echo times.`parameters`

: Tissue parameters of all voxels, including spatial coordinates.`trajectory`

: Cartesian trajectory struct.`coordinates`

: Vector{Coordinates} with spatial coordinates for each voxel.`coil_sensitivities`

: Matrix{Complex} of size (# voxels, # coils) with coil sensitivities.

Output:

`signal`

: Vector of length (# coils) with each element a Matrix{Complex} of size (# readouts, # samples per readout)

Description:

As noted in the description of the simulate_signal function (see `src/simulate/signal.jl`

), we simulate the MR signal at timepoint `t`

from coil `i`

as: signalᵢ[t] = sum(m[t,v] * cᵢ[v] * ρ[v] for v in 1:(# voxels)), where `cᵢ`

is the coil sensitivity profile of coil `i`

, `ρ`

is the proton density map and `m`

the matrix with the magnetization at all timepoints for each voxel obtained through Bloch simulations.

The output (signalᵢ) for each coil is in principle a `Vector{Complex}`

`of length (# samples per readout) * (# readouts). If we reshape the output into a`

Matrix{Complex}`of size (# samples per readout, # readouts) instead, and do something similar for`

m`, then the signal value associated with the s-th sample point of the r-th readout can be expressed as signalᵢ[r,s] = sum( m[r,s,v]] * cᵢ[v] * ρ[v] for v in 1:(# voxels)).

The problem here is that we typically cannot store the full m. Instead, we compute the magnetization at echo times only. The reason is that, if mᵣ is the magnetization at the r-th echo time in some voxel, and E = exp(-Δt*R₂[v]) * exp(im*(Δkₓ*x[v])) is the change per sample point (WHICH FOR CARTESIAN SEQUENCES IS THE SAME FOR ALL READOUTS AND SAMPLES), then the magnetization at the s-th sample relative the the echo time can can be computed as mₛ = mᵣ * E[v]^s

Therefore we can write

signalⱼ[r,s] = sum( magnetization[r,v] * E[v]^s * ρ[v] * cⱼ[v] for v in 1:(# voxels)) signalⱼ[r,s] = magnetization[r,:] * (E.^s .* ρ .* cⱼ)

Because the (E.^s .* ρ .* cⱼ)-part is the same for all readouts, we can simply perform this computation for all readouts simultaneously as signalⱼ[:,s] = magnetization * (E.^s .* ρ .* cⱼ)

If we define the matrix Eˢ as E .^ (-(ns÷2):(ns÷2)-1), then we can do the computation for all different sample points at the same time as well using a single matrix-matrix multiplication: signalⱼ = magnetization * (Eˢ .* (ρ .* cⱼ))

The signalⱼ array is of size (# readouts, # samples per readout). We prefer to have it transposed, therefore we compute signalⱼ = transpose(Eˢ .* (ρ .* cⱼ)) * transpose(magnetization) instead.

For the final output, we do this calculation for each coil j and get a vector of signal matrices (one matrix for each coil) as a result.

Note that this implementation relies entirely on vectorized code and works on both CPU and GPU. The matrix-matrix multiplications are - I think - already multi-threaded so a separate multi-threaded implementation is not needed.

`BlochSimulators.sampling_mask`

— Method`sampling_mask(tr::CartesianTrajectory)`

For undersampled Cartesian trajectories, the gradient trajectory can also be described by a sampling mask.

`BlochSimulators.RadialTrajectory`

— Type`RadialTrajectory{T,I,U,V} <: SpokesTrajectory{T}`

Struct that is used to implement a typical radial gradient trajectory. The trajectory can is described in a compact fashion by only storing the starting position in k-space (`k_start_readout`

) for each readout as well as the step in k-space per readout point `Δk_adc`

.

Note that CartesianTrajectory and RadialTrajectory are essentially the same in when using when using this compact description. A SpokesTrajectory struct is therefore defined as a supertype of both and methods are defined for SpokesTrajectory instead to avoid code repetition.

The type parameters are intentionally left vague. The `J`

, for example, may be an integer for sequences where each readout has the same number of samples, but for sequences with different numbers of samples per readout it may be a vector of integers.

**Fields**

`nreadouts::I`

: The total number of readouts for this trajectory`nsamplesperreadout::I`

: The total number of samples per readout`Δt::T`

: Time between sample points`k_start_readout::U`

: Starting position in k-space for each readout`Δk_adc::U`

: k-space step Δk between each readout`φ::V`

: Radial angle for each readout`readout_oversampling::I`

: Readout oversampling factor

`BlochSimulators.add_gradient_delay!`

— Method`add_gradient_delay!(tr::RadialTrajectory, S)`

Apply gradient delay to radial trajectory in in-place fashion. The delay is described by the 2x2 matrix S and is assumed to influence the start of the readout only, not the readout direction.

`BlochSimulators.kspace_coordinates`

— Method`kspace_coordinates(tr::RadialTrajectory)`

Return matrix (nrsamplesperreadout, nrreadouts) with kspace coordinates for the trajectory. Needed for nuFFT reconstructions.

## Dictionary Simulation

Missing docstring for `simulate_magnetization(resource, sequence, parameters)`

. Check Documenter's build log for details.

`BlochSimulators._allocate_array_on_resource`

— Method`_allocate_array_on_resource(::CPUProcesses, _eltype, _size)`

Allocate a distributed array for use with multiple CPU processes. The array is distributed in the "voxel" dimension (last dimension) over the workers.

`BlochSimulators._allocate_array_on_resource`

— Method`_allocate_array_on_resource(::CUDALibs, _eltype, _size)`

Specialized allocation for CUDA-enabled devices.

`BlochSimulators._allocate_array_on_resource`

— Method`_allocate_array_on_resource(::Union{CPU1,CPUThreads}, _eltype, _size)`

Allocate a CPU array for use with a single CPU or multiple threads.

`BlochSimulators._allocate_magnetization_array`

— Method`_allocate_magnetization_array(resource, sequence, parameters)`

Allocate an array to store the output of the Bloch simulations (per voxel, echo times only) to be performed with the `sequence`

. For each `BlochSimulator`

, methods should have been added to `output_eltype`

and `output_size`

for this function to work properly.

**Arguments**

`resource::AbstractResource`

: The computational resource (e.g., CPU, GPU) to be used for the allocation.`sequence::BlochSimulator{T}`

: The simulator, which defines the type of simulation to be performed.`parameters::AbstractVector{<:AbstractTissueParameters{N,T}}`

: A vector with each element containing the tissue parameters for a voxel.

**Returns**

`magnetization_array`

: An array allocated on the specified`resource`

, formatted to store the simulation results for each voxel across the specified echo times.

`BlochSimulators.simulate_magnetization!`

— Method`simulate_magnetization!(magnetization, resource, sequence, parameters)`

Simulate the magnetization at echo times (without any spatial encoding gradients applied) for all combinations of tissue parameters contained in `parameters`

. Stores the magnetization response (typically the transverse magnetization at echo times) in the `magnetization`

array.

`magnetization::AbstractArray`

: Pre-allocated output array to store simulation results.`resource::AbstractResource`

: Computational resource (e.g.,`CPU1()`

,`CPUThreads()`

,`CPUProcesses()`

,`CUDALibs()`

).`sequence::BlochSimulator`

: Custom sequence struct`parameters::AbstractVector{<:AbstractTissueParameters}`

: Vector with different combinations of tissue parameters

`BlochSimulators.simulate_magnetization!`

— Method`simulate_magnetization!(magnetization, ::CPUThreads, sequence, parameters)`

Simulate magnetization for all elements of `parameters`

using single CPU mode.

`BlochSimulators.simulate_magnetization!`

— Method`simulate_magnetization!(magnetization, ::CPUProcesses, sequence, parameters)`

Distributes the simulations over multiple CPU workers.

`BlochSimulators.simulate_magnetization!`

— Method`simulate_magnetization!(magnetization, ::CPUThreads, sequence, parameters)`

Simulate magnetization for all elements of `parameters`

in a multi-threaded fashion.

`BlochSimulators.simulate_magnetization!`

— Method`simulate_magnetization!(magnetization, ::CUDALibs, sequence, parameters::CuArray)`

Perform the simulation on an NVIDIA GPU.

`BlochSimulators.simulate_magnetization`

— Method`simulate_magnetization(resource, sequence, parameters)`

Simulate the magnetization response (typically the transverse magnetization at echo times without any spatial encoding gradients applied) for all combinations of tissue parameters contained in `parameters`

.

This function can also be used to generate dictionaries for MR Fingerprinting purposes.

**Arguments**

`resource::AbstractResource`

: Either`CPU1()`

,`CPUThreads()`

,`CPUProcesses()`

or`CUDALibs()`

`sequence::BlochSimulator`

: Custom sequence struct`parameters::AbstractVector{<:AbstractTissueParameters}`

: Vector with different combinations of tissue parameters

**Returns**

`magnetization::AbstractArray`

: Array of size (output_size(sequence), length(parameters)) containing the magnetization response of the sequence for all combinations of input tissue parameters.

## Signal Simulation

Missing docstring for `simulate_signal(resource, sequence, parameters, trajectory, coil_sensitivities)`

. Check Documenter's build log for details.

`BlochSimulators._allocate_signal_array`

— Method`_allocate_signal_array(resource, trajectory::AbstractTrajectory, coil_sensitivities)`

Allocate an array to store the output of the signal simulation (all readout points, integrated over all voxels).

`BlochSimulators._signal_per_coil!`

— Method`_signal_per_coil!(signal, resource, magnetization, parameters, trajectory, coordinates, coil_sensitivities)`

Compute the signal for a given coil by calculating a volume integral of the transverse magnetization in each voxel for each time point separately (using the signal*at*time_point!` function).

`BlochSimulators._signal_per_coil!`

— Method`_signal_per_coil!(signal, ::CPU1, magnetization, parameters, trajectory, coordinates, coil_sensitivities)`

Loop over the time points to calculate the signal at that time point in a serial fashion on a single CPU.

`BlochSimulators._signal_per_coil!`

— Method`_signal_per_coil!(signal, ::CPUThreads, magnetization, parameters, trajectory, coordinates, coil_sensitivities)`

Loop over the time points to calculate the signal at that time point in a multi-threaded fashion.

`BlochSimulators._signal_per_coil!`

— Method`_signal_per_coil!(signal, ::CUDALibs, magnetization, parameters, trajectory, coordinates, coil_sensitivities)`

Let different threads of an NVIDIA CUDA device calculate the signal at different time points.

`BlochSimulators.magnetization_to_signal`

— Method`magnetization_to_signal(resource, magnetization, parameters, trajectory, coordinates, coil_sensitivities)`

Allocates memory for the signal and computes the signal for each coil separately using the `_signal_per_coil!`

function. That function is implemented for different computational resources and will be called based on the `resource`

argument. The default implementations loop over all time points and compute the volume integral of the transverse magnetization in each voxel for each time point separately.

This loop order is not necessarily optimal (and performance may be) across all trajectories and computational resources. If a better implementation is available, add new methods to this function for those specific combinations of resources and trajectories.

`BlochSimulators.magnetization_to_signal`

— Method`magnetization_to_signal(::CPUProcesses, dmagnetization, dparameters, trajectory, dcoordinates, dcoil_sensitivities)`

The "voxels" are assumed to be distributed over the workers. Each worker computes performs a volume integral over the voxels that it owns only (for all time points) using the CPU1() code. The results are then summed up across all workers.

`BlochSimulators.simulate_signal`

— Method`simulate_signal(resource, sequence, parameters, trajectory, coil_sensitivities)`

Simulate the MR signal at timepoint `t`

from coil `i`

as: `sᵢ(t) = ∑ⱼ cᵢⱼρⱼmⱼ(t)`

, where `cᵢⱼ`

is the coil sensitivity of coil `i`

at position of voxel `j`

, `ρⱼ`

is the proton density of voxel `j`

and `mⱼ(t)`

the (normalized) transverse magnetization in voxel `j`

obtained through Bloch simulations.

**Arguments**

`resource::AbstractResource`

: Either`CPU1()`

,`CPUThreads()`

,`CPUProcesses()`

or`CUDALibs()`

`sequence::BlochSimulator`

: Custom sequence struct`parameters::AbstractVector{<:AbstractTissueParameters}`

: Vector with tissue parameters for each voxel`trajectory::AbstractTrajectory`

: Custom trajectory struct`coordinates::AbstractVector{<:Coordinates}`

: Vector with spatial coordinates for each voxel`coil_sensitivities::AbstractMatrix`

: Sensitivity of coil`j`

in voxel`v`

is given by`coil_sensitivities[v,j]`

**Returns**

`signal::AbstractMatrix{<:Complex}`

: Simulated MR signal for the`sequence`

and`trajectory`

.

The matrix is of size (# samples, # coils).

## Utility Functions

`BlochSimulators.f32`

— Method`f32(x)`

Change precision of `x`

to `Float32`

. It uses `Functors.fmap`

to recursively traverse the fields of the struct `x`

. For custom structs (e.g. `<:BlochSimulator`

or `<:AbstractTrajectory`

), it is required that `typeof(x)`

be made a `Functors.@functor`

(e.g. `@functor FISP`

).

It may be necessary to add new adapt rules (by adding new methods to adapt_storage) if new structs with complicated nested fields are introduced.

`BlochSimulators.f64`

— Method`f64(x)`

Change precision of `x`

to `Float64`

. It uses `Functors.fmap`

to recursively traverse the fields of the struct `x`

. For custom structs (e.g. `<:BlochSimulator`

or `<:AbstractTrajectory`

), it is required that `typeof(x)`

be made a `Functors.@functor`

(e.g. `@functor FISP`

).

It may be necessary to add new adapt rules (by adding new methods to `adapt_storage`

) if new structs with complicated nested fields are introduced.

`BlochSimulators.gpu`

— Method`gpu(x)`

Move `x`

to CUDA device. It uses `Functors.fmap`

to recursively traverse the fields of the struct `x`

, converting `<:AbstractArrays`

to `CuArrays`

, and ignoring isbitsarrays. For custom structs (e.g. `<:BlochSimulator`

or `<:AbstractTrajectory`

), it is required that `typeof(x)`

be made a `Functors.@functor`

(e.g. `@functor FISP`

).

## Index

`BlochSimulators.AbstractTissueParameters`

`BlochSimulators.AbstractTrajectory`

`BlochSimulators.BlochSimulator`

`BlochSimulators.CartesianTrajectory`

`BlochSimulators.EPGSimulator`

`BlochSimulators.EPGStates`

`BlochSimulators.Generic2D`

`BlochSimulators.Generic3D`

`BlochSimulators.Isochromat`

`BlochSimulators.IsochromatSimulator`

`BlochSimulators.RadialTrajectory`

`BlochSimulators.SpokesTrajectory`

`BlochSimulators.F̄₋`

`BlochSimulators.F₊`

`BlochSimulators.Z`

`BlochSimulators._allocate_array_on_resource`

`BlochSimulators._allocate_array_on_resource`

`BlochSimulators._allocate_array_on_resource`

`BlochSimulators._allocate_magnetization_array`

`BlochSimulators._allocate_signal_array`

`BlochSimulators._signal_per_coil!`

`BlochSimulators._signal_per_coil!`

`BlochSimulators._signal_per_coil!`

`BlochSimulators._signal_per_coil!`

`BlochSimulators.add_gradient_delay!`

`BlochSimulators.decay`

`BlochSimulators.decay!`

`BlochSimulators.dephasing!`

`BlochSimulators.excite!`

`BlochSimulators.excite!`

`BlochSimulators.f32`

`BlochSimulators.f64`

`BlochSimulators.gpu`

`BlochSimulators.initial_conditions!`

`BlochSimulators.initialize_states`

`BlochSimulators.initialize_states`

`BlochSimulators.initialize_states`

`BlochSimulators.invert`

`BlochSimulators.invert`

`BlochSimulators.invert!`

`BlochSimulators.invert!`

`BlochSimulators.kspace_coordinates`

`BlochSimulators.kspace_coordinates`

`BlochSimulators.magnetization_to_signal`

`BlochSimulators.magnetization_to_signal`

`BlochSimulators.magnetization_to_signal`

`BlochSimulators.regrowth`

`BlochSimulators.regrowth!`

`BlochSimulators.rotate`

`BlochSimulators.rotate`

`BlochSimulators.rotate!`

`BlochSimulators.rotate_decay!`

`BlochSimulators.sample_transverse!`

`BlochSimulators.sample_transverse!`

`BlochSimulators.sample_xyz!`

`BlochSimulators.sample_Ω!`

`BlochSimulators.sampling_mask`

`BlochSimulators.simulate_magnetization`

`BlochSimulators.simulate_magnetization!`

`BlochSimulators.simulate_magnetization!`

`BlochSimulators.simulate_magnetization!`

`BlochSimulators.simulate_magnetization!`

`BlochSimulators.simulate_magnetization!`

`BlochSimulators.simulate_signal`

`BlochSimulators.spoil!`

`BlochSimulators.Ω_eltype`