KomaMRICore

out = 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 struct
• seq: (::Sequence) Sequence struct
• sys: (::Scanner) Scanner struct

Keywords

• sim_params: (::Dict{String,Any}, =Dict{String,Any}()) simulation parameter dictionary
• w: (::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)

mag = 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 axis
• sim_params: (::Dict{String, Any}, =Dict{String,Any}("Δt_rf"=>1e-6)) dictionary with simulation parameters

Returns

• mag: (::SpinStateRepresentation) final state of the magnetization vector

sim_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 MRIReco RawAcquisitionData, 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 the BlochDict() 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 use Float32 and Float64 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!)

Returns

• sim_params: (::Dict{String,Any}) dictionary with simulation parameters

get_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

print_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

gpu(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 Arrays.

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 Arrays.

See also f32 and f64 to change element type only.

Examples

x = gpu(x, CUDABackend())

cpu(x)

Tries to move object to CPU. This works for functions, and any struct marked with @functor.

See also gpu.

Examples

x = x |> cpu

f32(m)

Converts the eltype of model's parameters to Float32 Recurses into structs marked with @functor.

See also f64.

f64(m)

Converts the eltype of model's parameters to Float64 (which is Koma's default).. Recurses into structs marked with @functor.

See also f32.

raw = 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 matrix
• seq: (::Sequence) Sequence struct

Keywords

• phantom_name: (::String, ="Phantom") phantom name
• sys: (::Scanner, =Scanner()) Scanner struct
• sim_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)

mag = Mag(xy::Complex, z::Real)

The Magnetization struct.

Arguments

• xy: (::Complex{Float64}) magnetization of a spin in the xy plane
• z: (::Real) magnetization of a spin in the z plane

Returns

• mag: (::Mag) Magnetization struct

spinor = 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

s = 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]) φ angle
• nxy: (::Real) nxy factor
• nz: (::Real) nz factor

Returns

• s: (::Spinor) spinnor struct that represents the Q rotation matrix

Rodrigues' formula: Rotation matrix that when applied rotates with respect to "n" in an angle θ anti clock-wise

s = 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 the Rx rotation matrix

s = 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 the Ry rotation matrix

s = 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 the Rz rotation matrix