KomaMRICore
Simulation functions
KomaMRICore.simulate
— Functionout = simulate(obj::Phantom, seq::Sequence, sys::Scanner; sim_params, w)
Returns the raw signal or the last state of the magnetization according to the value of the "return_type"
key of the sim_params
dictionary.
This is a wrapper function to run_sim_time_iter
, which converts the inputs to the appropriate types and discretizes the sequence before simulation. The reported simulation time only considers run_sim_time_iter
, as the preprocessing duration should be negligible compared to the simulation time (if this is not the case, please file a bug report).
Arguments
obj
: (::Phantom
) Phantom structseq
: (::Sequence
) Sequence structsys
: (::Scanner
) Scanner struct
Keywords
sim_params
: (::Dict{String,Any}
,=Dict{String,Any}()
) simulation parameter dictionaryw
: (::Blink.AtomShell.Window
,=nothing
) the window within which to display a progress bar in the Blink Window UI. If this variable is anything other than 'nothing', the progress bar will be considered
Returns
out
: (::Vector{Complex}
or::SpinStateRepresentation
or::RawAcquisitionData
) depending on whether "return_type" is "mat", "state" or "raw" (default), respectively
Examples
julia> seq_file = joinpath(dirname(pathof(KomaMRI)), "../examples/5.koma_paper/comparison_accuracy/sequences/EPI/epi_100x100_TE100_FOV230.seq");
julia> sys, obj, seq = Scanner(), brain_phantom2D(), read_seq(seq_file)
julia> raw = simulate(obj, seq, sys)
julia> plot_signal(raw)
KomaMRICore.simulate_slice_profile
— Functionmag = simulate_slice_profile(seq; z, sim_params)
Returns magnetization of spins distributed along z
after running the Sequence struct.
Arguments
seq
: (::Sequence
) Sequence struct
Keywords
z
: (=range(-2e-2,2e-2,200)
) range for the z axissim_params
: (::Dict{String, Any}
,=Dict{String,Any}("Δt_rf"=>1e-6)
) dictionary with simulation parameters
Returns
mag
: (::SpinStateRepresentation
) final state of the magnetization vector
KomaMRICore.default_sim_params
— Functionsim_params = default_sim_params(sim_params=Dict{String,Any}())
This function returns a dictionary containing default simulation parameters while also allowing the user to define some of them.
Arguments
sim_params
: (::Dict{String,Any}
,=Dict{String,Any}()
) user-defined dictionary with simulation parameters. The following lists its keys along with their possible values:- "return_type": defines the output of the
simulate
function. Possible values are"raw"
,"mat"
, and"state"
, corresponding to outputting a MRIRecoRawAcquisitionData
, the signal values, and the last magnetization state of the simulation, respectively - "sim_method": defines the type of simulation. The default value is
Bloch()
, but you can alternatively use theBlochDict()
simulation method. Moreover, you have the flexibility to create your own methods without altering the KomaMRI source code - "Δt": raster time for gradients
- "Δt_rf": raster time for RFs
- "precision": defines the floating-point simulation precision. You can choose between
"f32"
and"f64"
to useFloat32
andFloat64
primitive types, respectively. It's important to note that, especially for GPU operations, using"f32"
is generally much faster - "Nblocks": divides the simulation into a specified number of time blocks. This parameter is designed to conserve RAM resources, as KomaMRI computes a series of simulations consecutively, each with the specified number of blocks determined by the value of
"Nblocks"
- "Nthreads": divides the Phantom into a specified number of threads. Because spins are modeled independently of each other, KomaMRI can solve simulations in parallel threads, speeding up the execution time
- "gpu": is a boolean that determines whether to use GPU or CPU hardware resources, as long as they are available on the host computer
- "gpu_device": default value is 'nothing'. If set to integer or device instance, calls the corresponding function to set the device of the available GPU in the host computer (e.g. CUDA.device!)
- "return_type": defines the output of the
Returns
sim_params
: (::Dict{String,Any}
) dictionary with simulation parameters
GPU helper functions
KomaMRICore.get_backend
— Functionget_backend(use_gpu)
Gets the simulation backend to use. If use_gpu=false or there are no available GPU backends, returns CPU(), else, returns the GPU backend (currently either CUDABackend(), MetalBackend(), ROCBackend(), or oneAPIBackend()).
The GPU package for the corresponding backend (CUDA.jl, Metal.jl, AMDGPU.jl, or oneAPI.jl) must be loaded and functional, otherwise KomaMRI will default to using the CPU.
Arguments
- 'use_gpu': ('::Bool') If true, attempt to use GPU and check for available backends
Returns
- 'backend': (::KernelAbstractions.backend) The backend to use
KomaMRICore.print_devices
— Functionprint_devices()
Simple function to print available devices. Calls internal get_backend() function to get the appropriate GPU / CPU backend and prints device information.
Arguments
- 'use_gpu': ('::Bool') If true, check for loaded / functional GPU backends and print appropriate warnings if no GPU backends have been loaded
KomaMRICore.gpu
— Functiongpu(x)
Moves 'x' to the GPU. For this function to work, a GPU backend will need to be loaded with 'using AMDGPU / CUDA / Metal / oneAPI.
This works for functions, and any struct marked with @functor
.
Use cpu
to copy back to ordinary Array
s.
See also f32
and f64
to change element type only.
Examples
using CUDA
x = x |> gpu
gpu(x, backend)
Tries to move x
to the GPU backend specified in the 'backend' parameter.
This works for functions, and any struct marked with @functor
.
Use cpu
to copy back to ordinary Array
s.
See also f32
and f64
to change element type only.
Examples
x = gpu(x, CUDABackend())
KomaMRICore.cpu
— Functioncpu(x)
Tries to move object to CPU. This works for functions, and any struct marked with @functor
.
See also gpu
.
Examples
x = x |> cpu
KomaMRICore.f32
— Functionf32(m)
Converts the eltype
of model's parameters to Float32
Recurses into structs marked with @functor
.
See also f64
.
KomaMRICore.f64
— Functionf64(m)
Converts the eltype
of model's parameters to Float64
(which is Koma's default).. Recurses into structs marked with @functor
.
See also f32
.
Signal to RawAquisitionData
(MRD)
KomaMRICore.signal_to_raw_data
— Functionraw = signal_to_raw_data(signal, seq; phantom_name, sys, sim_params)
Transforms the raw signal into a RawAcquisitionData struct (nearly equivalent to the ISMRMRD format) used for reconstruction with MRIReco.
Arguments
signal
: (::Matrix{Complex}
) raw signal matrixseq
: (::Sequence
) Sequence struct
Keywords
phantom_name
: (::String
,="Phantom"
) phantom namesys
: (::Scanner
,=Scanner()
) Scanner structsim_params
: (::Dict{String, Any}
,=Dict{String,Any}()
) simulation parameter dictionary
Returns
raw
: (::RawAcquisitionData
) RawAcquisitionData struct
Examples
julia> seq_file = joinpath(dirname(pathof(KomaMRI)), "../examples/1.sequences/epi_se.seq")
julia> sys, obj, seq = Scanner(), brain_phantom2D(), read_seq(seq_file)
julia> sim_params = KomaMRICore.default_sim_params(); sim_params["return_type"] = "mat"
julia> signal = simulate(obj, seq, sys; sim_params)
julia> raw = signal_to_raw_data(signal, seq)
julia> plot_signal(raw)
SpinRepresentationState
's
KomaMRICore.Mag
— Typemag = Mag(xy::Complex, z::Real)
The Magnetization struct.
Arguments
xy
: (::Complex{Float64}
) magnetization of a spin in the xy planez
: (::Real
) magnetization of a spin in the z plane
Returns
mag
: (::Mag
) Magnetization struct
Spinor
rotation matrix (RF excitation)
KomaMRICore.Spinor
— Typespinor = Spinor(α, β)
Spinor(α, β) with Cayley-Klein parameters α and β. Based on "Introduction to the Shinnar-Le Roux algorithm", Patrick Le Roux (1995). A spinor is a way to represent 3D rotations, the underlying representation is a 2 X 2 complex unitary matrix ($\alpha,\beta\in\mathbb{C}$):
\[R=\left[\begin{array}{cc} \alpha & -\beta^{*}\\ \beta & \alpha^{*} \end{array}\right],\]
with $|\alpha|^2+|\beta|^2 = 1$.
This later operates on the $2\times2$ representation of $(x,y,z)$ as follows $V^{+} = R V R^{*}$.
Arguments
α
: (::Complex{Float64}
) Cayley-Klein parameter αβ
: (::Complex{Float64}
) Cayley-Klein parameter β
Returns
spinor
: (::Spinor
) Spinor struct
KomaMRICore.Q
— Functions = Q(φ, nxy, nz)
Spinor rotation matrix. Counter-clockwise rotation of φ
with respect to the axis of rotation n=(nx, ny, nz).
Pauly, J., Le Roux, P., Nishimura, D., & Macovski, A. (1991). Parameter relations for the Shinnar-Le Roux selective excitation pulse design algorithm (NMR imaging). IEEE Transactions on Medical Imaging, 10(1), 53-65. doi:10.1109/42.75611
\[\varphi=-\gamma\Delta t\sqrt{\left|B_{1}\right|^{2}+\left(\boldsymbol{G}\cdot\boldsymbol{x} \right)^{2}}=-\gamma\Delta t\left\Vert \boldsymbol{B}\right\Vert\]
\[\boldsymbol{n}=\boldsymbol{B}/\left\Vert \boldsymbol{B}\right\Vert\]
Arguments
φ
: (::Real
,[rad]
) φ anglenxy
: (::Real
) nxy factornz
: (::Real
) nz factor
Returns
s
: (::Spinor
) spinnor struct that represents theQ
rotation matrix
KomaMRICore.Un
— FunctionRodrigues' formula: Rotation matrix that when applied rotates with respect to "n" in an angle θ anti clock-wise
KomaMRICore.Rx
— Functions = Rx(θ)
Spinor counter-clockwise rotation matrix with angle θ
with respect to x-axis.
Arguments
θ
: (::Real
,[rad]
) angle with respect to x-axis
Returns
s
: (::Spinor
) spinor struct that represents theRx
rotation matrix
KomaMRICore.Ry
— Functions = Ry(θ)
Spinor counter-clockwise rotation matrix with angle θ
with respect to y-axis.
Arguments
θ
: (::Real
,[rad]
) angle with respect to y-axis
Returns
s
: (::Spinor
) spinor struct that represents theRy
rotation matrix
KomaMRICore.Rz
— Functions = Rz(φ)
Spinor counter-clockwise rotation matrix with angle φ
with respect to z-axis.
Arguments
φ
: (::Real
,[rad]
) angle with respect to z-axis
Returns
s
: (::Spinor
) spinnor struct that represents theRz
rotation matrix