diff --git a/previews/PR284/.documenter-siteinfo.json b/previews/PR284/.documenter-siteinfo.json
index a16d4c65d..e768f961c 100644
--- a/previews/PR284/.documenter-siteinfo.json
+++ b/previews/PR284/.documenter-siteinfo.json
@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.2","generation_timestamp":"2024-04-16T15:35:23","documenter_version":"1.4.0"}}
\ No newline at end of file
+{"documenter":{"julia_version":"1.10.2","generation_timestamp":"2024-04-16T15:37:34","documenter_version":"1.4.0"}}
\ No newline at end of file
diff --git a/previews/PR284/api/index.html b/previews/PR284/api/index.html
index dc1ea2c05..e693d9f0c 100644
--- a/previews/PR284/api/index.html
+++ b/previews/PR284/api/index.html
@@ -4,103 +4,103 @@
julia> out1, out2 = component_name(arg1, arg2; kw1=valkw1, kw2=valkw2)
The preceding docstring block will always start with the way the component is called (outputs = component_name(inputs), followed by a brief description of what the component does. If necessary, a note block will be displayed. In general, the following subsections are optional: Arguments, Keywords, Returns, References, and Examples, but they will be provided as needed. These subsections are self-explanatory, making it intuitive to understand their purpose.
Please note that every subitem in the sections Arguments, Keywords, and Returns represents variables. They include practical information along with a description. The information enclosed in parentheses is optional but highly useful when provided.
::type: is the suggested type for the variable. If the input variable is of type ::type, there won't be any issues, but it's always possible to test other subtypes. If the variable is an output, it will be forced to the type ::type whenever possible.
=value: sometimes, for the inputs, a default value is defined if it is not assigned by the user.
[unit]: this is the suggested physical unit of measure for the variable. Everything will be fine if you stick with these units of measure.
opts: [opt1, opt2, ...]: sometimes, the input value can only be interpreted if it is one of the predefined values.
The Phantom struct. Most of its field names are vectors, with each element associated with a property value representing a spin. This struct serves as an input for the simulation.
The Phantom struct. Most of its field names are vectors, with each element associated with a property value representing a spin. This struct serves as an input for the simulation.
Creates a two-dimensional brain Phantom struct. Default ss=4 sample spacing is 2 mm. Original file (ss=1) sample spacing is .5 mm.
References
B. Aubert-Broche, D.L. Collins, A.C. Evans: "A new improved version of the realistic digital brain phantom" NeuroImage, in review - 2006
B. Aubert-Broche, M. Griffin, G.B. Pike, A.C. Evans and D.L. Collins: "20 new digital brain phantoms for creation of validation image data bases" IEEE TMI, in review - 2006
https://brainweb.bic.mni.mcgill.ca/brainweb
Keywords
axis: (::String, ="axial", opts=["axial", "coronal", "sagittal"]) orientation of the phantom
ss: (::Integer or ::Vector{Integer}, =4) subsampling parameter for all axes if scaler, per axis if 2 element vector [ssx, ssy]
us: (::Integer or ::Vector{Integer}, =1) upsampling parameter for all axes if scaler, per axis if 2 element vector [usx, usy], if used ss is set to ss=1
Creates a two-dimensional brain Phantom struct. Default ss=4 sample spacing is 2 mm. Original file (ss=1) sample spacing is .5 mm.
References
B. Aubert-Broche, D.L. Collins, A.C. Evans: "A new improved version of the realistic digital brain phantom" NeuroImage, in review - 2006
B. Aubert-Broche, M. Griffin, G.B. Pike, A.C. Evans and D.L. Collins: "20 new digital brain phantoms for creation of validation image data bases" IEEE TMI, in review - 2006
https://brainweb.bic.mni.mcgill.ca/brainweb
Keywords
axis: (::String, ="axial", opts=["axial", "coronal", "sagittal"]) orientation of the phantom
ss: (::Integer or ::Vector{Integer}, =4) subsampling parameter for all axes if scaler, per axis if 2 element vector [ssx, ssy]
us: (::Integer or ::Vector{Integer}, =1) upsampling parameter for all axes if scaler, per axis if 2 element vector [usx, usy], if used ss is set to ss=1
Creates a three-dimentional brain Phantom struct. Default ss=4 sample spacing is 2 mm. Original file (ss=1) sample spacing is .5 mm.
References
B. Aubert-Broche, D.L. Collins, A.C. Evans: "A new improved version of the realistic digital brain phantom" NeuroImage, in review - 2006
B. Aubert-Broche, M. Griffin, G.B. Pike, A.C. Evans and D.L. Collins: "20 new digital brain phantoms for creation of validation image data bases" IEEE TMI, in review - 2006
https://brainweb.bic.mni.mcgill.ca/brainweb
Keywords
ss: (::Integer or ::Vector{Integer}, =4) subsampling parameter for all axes if scaler, per axis if 3 element vector [ssx, ssy, ssz]
us: (::Integer or ::Vector{Integer}, =1) upsampling parameter for all axes if scaler, per axis if 3 element vector [usx, usy, usz]
start_end: (::Vector{Integer}, =[160,200]) z index range of presampled phantom, 180 is center
Creates a three-dimentional brain Phantom struct. Default ss=4 sample spacing is 2 mm. Original file (ss=1) sample spacing is .5 mm.
References
B. Aubert-Broche, D.L. Collins, A.C. Evans: "A new improved version of the realistic digital brain phantom" NeuroImage, in review - 2006
B. Aubert-Broche, M. Griffin, G.B. Pike, A.C. Evans and D.L. Collins: "20 new digital brain phantoms for creation of validation image data bases" IEEE TMI, in review - 2006
https://brainweb.bic.mni.mcgill.ca/brainweb
Keywords
ss: (::Integer or ::Vector{Integer}, =4) subsampling parameter for all axes if scaler, per axis if 3 element vector [ssx, ssy, ssz]
us: (::Integer or ::Vector{Integer}, =1) upsampling parameter for all axes if scaler, per axis if 3 element vector [usx, usy, usz]
start_end: (::Vector{Integer}, =[160,200]) z index range of presampled phantom, 180 is center
The Sequence struct. It contains events of an MRI sequence. Most field names (except for the DEF field) consist of matrices or vectors, where each column index represents a sequence block. This struct serves as an input for the simulation.
Arguments
GR: (::Matrix{Grad}) gradient matrix. Rows for x-y-z amplitudes and columns are for blocks
RF: (::Matrix{RF}) RF matrix. The 1 row is for the coil and columns are for blocks
ADC: (::Array{ADC,1}) ADC block vector
DUR: (::Vector, [s]) duration block vector
DEF: (::Dict{String, Any}) dictionary with relevant information of the sequence. Possible keys could be ["AdcRasterTime", "GradientRasterTime", "Name", "Nz", "Num_Blocks", "Nx", "Ny", "PulseqVersion", "BlockDurationRaster", "FileName", "RadiofrequencyRasterTime"]
The Sequence struct. It contains events of an MRI sequence. Most field names (except for the DEF field) consist of matrices or vectors, where each column index represents a sequence block. This struct serves as an input for the simulation.
Arguments
GR: (::Matrix{Grad}) gradient matrix. Rows for x-y-z amplitudes and columns are for blocks
RF: (::Matrix{RF}) RF matrix. The 1 row is for the coil and columns are for blocks
ADC: (::Array{ADC,1}) ADC block vector
DUR: (::Vector, [s]) duration block vector
DEF: (::Dict{String, Any}) dictionary with relevant information of the sequence. Possible keys could be ["AdcRasterTime", "GradientRasterTime", "Name", "Nz", "Num_Blocks", "Nx", "Ny", "PulseqVersion", "BlockDurationRaster", "FileName", "RadiofrequencyRasterTime"]
gr = Grad(f::Function, T::Real, N::Integer; delay::Real)
Generates an arbitrary gradient waveform defined by the function f in the interval t ∈ [0,T]. The time separation between two consecutive samples is given by T/(N-1).
Arguments
f: (::Function) function that describes the gradient waveform
T: (::Real, [s]) duration of the gradient waveform
N: (::Integer, =300) number of samples of the gradient waveform
Keywords
delay: (::Real, =0, [s]) delay time of the waveform
gr = Grad(f::Function, T::Real, N::Integer; delay::Real)
Generates an arbitrary gradient waveform defined by the function f in the interval t ∈ [0,T]. The time separation between two consecutive samples is given by T/(N-1).
Arguments
f: (::Function) function that describes the gradient waveform
T: (::Real, [s]) duration of the gradient waveform
N: (::Integer, =300) number of samples of the gradient waveform
Keywords
delay: (::Real, =0, [s]) delay time of the waveform
Δf: (::Real or ::Vector, [Hz]) RF frequency difference with respect to the Larmor frequency. This can be a number but also a vector to represent frequency modulated signals (FM).
Duration time in [s] of Grad struct or Grad array. When the input is a gradient vector, then the duration is the maximum duration of all the elements of the gradient vector.
Arguments
x: (::Grad or ::Vector{Grad}) RF struct or RF array
Returns
y: (::Float64, [s]) duration of the RF struct or RF array
Duration time in [s] of Grad struct or Grad array. When the input is a gradient vector, then the duration is the maximum duration of all the elements of the gradient vector.
Arguments
x: (::Grad or ::Vector{Grad}) RF struct or RF array
Returns
y: (::Float64, [s]) duration of the RF struct or RF array
Computes the $k$th-order moment of the Sequence seq given by the formula $\int_0^T t^k G(t) dt$.
Arguments
seq: (::Sequence) Sequence struct
k: (::Integer) order of the moment to be computed
Δt: (::Real, =1, [s]) nominal delta time separation between two time samples for ADC acquisition and Gradients
skip_rf: (::Vector{Bool}, =zeros(Bool, sum(is_RF_on.(seq)))) boolean vector which indicates whether to skip the computation for resetting the integral for excitation or refocusing RF type
Returns
Mk: (3-column ::Matrix{Real}) $k$th-order moment
Mk_adc: (3-column ::Matrix{Real}) $k$th-order moment sampled at ADC times
off_val: (::Number, =0) offset value for amplitude. Typically used to hide points in plots by setting it to Inf
max_rf_samples: (::Integer, =Inf) maximum number of samples for the RF struct
Returns
samples: (::NamedTuple) contains samples for gx, gy, gz, rf, and adc events. Each event, represented by e::NamedTuple, includes time samples (e.t) and amplitude samples (e.A)
Returns an array of phase compensation factors, $\exp(-\mathrm{i}\varphi)$, which are used to compensate the acquired signal $S$ by applying the operation $S_{\mathrm{comp}} = S \exp(-\mathrm{i}\varphi)$ after the simulation. This compensation is necessary because the signal typically exhibits a phase offset of $\varphi$ following RF excitation with a phase of $\varphi$. Such pulses are commonly employed in sequences involving RF spoiling.
Arguments
seq: (::Sequence) sequence struct
Returns
comp: (::Vector{Complex}, [rad]) array of phase compensations for every acquired sample
Returns a vector containing the start times of blocks in a sequence. The initial time is always zero, and the final time corresponds to the duration of the sequence.
Arguments
seq: (::Sequence) Sequence struct
Returns
T0: (::Vector, [s]) start times of the blocks in a sequence
A sampled version of a Sequence struct, containing vectors for event amplitudes at specified times. DiscreteSequence is the struct used for simulation.
Trapezoidal integration for every spin of a phantom.
Note
In practice, this function is used to integrate (Gx * x + Gy * y + Gz * z) * Δt for all the spins. NΔt is the length of Δt. Ns stands for the number of spins of a phantom. x is a matrix which rows represents different spins and columns are different times and the elements are the field Gx * x + Gy * y + Gz * z values.
Arguments
Δt: (1 x NΔt ::Matrix{Float64}, [s]) delta time 1-row array
x: (Ns x (NΔt+1) ::Matrix{Float64}, [T]) magnitude of the field Gx * x + Gy * y + Gz * z
Returns
y: (Ns x 1 ::Matrix{Float64}, [T*s]) vector where every element is the integral of (Gx * x + Gy * y + Gz * z) * Δt for every spin of a phantom
Trapezoidal cumulative integration over time for every spin of a phantom.
Arguments
Δt: (1 x NΔt ::Matrix{Float64}, [s]) delta time 1-row array
x: (Ns x (NΔt+1) ::Matrix{Float64}, [T]) magnitude of the field Gx * x + Gy * y + Gz * z
Returns
y: (Ns x NΔt ::Matrix{Float64}, [T*s]) matrix where every column is the cumulative integration over time of (Gx * x + Gy * y + Gz * z) * Δt for every spin of a phantom
Divides a list of indices from 1 to N into k groups.
Arguments
N: (::Integer) number of elements to be ordered
k: (::Integer) number of groups to divide the N elements.
Keywords
breaks: (::Vector{<:Integer}, =[]) array of indices where predefined breakpoints are placed.
Returns
array_of_ranges: (::Vector{UnitRange{<:Integer}}) array containing ranges of different groups. The target is k groups, but this could increase by adding elements to the breaks input array
Computes the $k$th-order moment of the Sequence seq given by the formula $\int_0^T t^k G(t) dt$.
Arguments
seq: (::Sequence) Sequence struct
k: (::Integer) order of the moment to be computed
Δt: (::Real, =1, [s]) nominal delta time separation between two time samples for ADC acquisition and Gradients
skip_rf: (::Vector{Bool}, =zeros(Bool, sum(is_RF_on.(seq)))) boolean vector which indicates whether to skip the computation for resetting the integral for excitation or refocusing RF type
Returns
Mk: (3-column ::Matrix{Real}) $k$th-order moment
Mk_adc: (3-column ::Matrix{Real}) $k$th-order moment sampled at ADC times
off_val: (::Number, =0) offset value for amplitude. Typically used to hide points in plots by setting it to Inf
max_rf_samples: (::Integer, =Inf) maximum number of samples for the RF struct
Returns
samples: (::NamedTuple) contains samples for gx, gy, gz, rf, and adc events. Each event, represented by e::NamedTuple, includes time samples (e.t) and amplitude samples (e.A)
Returns an array of phase compensation factors, $\exp(-\mathrm{i}\varphi)$, which are used to compensate the acquired signal $S$ by applying the operation $S_{\mathrm{comp}} = S \exp(-\mathrm{i}\varphi)$ after the simulation. This compensation is necessary because the signal typically exhibits a phase offset of $\varphi$ following RF excitation with a phase of $\varphi$. Such pulses are commonly employed in sequences involving RF spoiling.
Arguments
seq: (::Sequence) sequence struct
Returns
comp: (::Vector{Complex}, [rad]) array of phase compensations for every acquired sample
Returns a vector containing the start times of blocks in a sequence. The initial time is always zero, and the final time corresponds to the duration of the sequence.
Arguments
seq: (::Sequence) Sequence struct
Returns
T0: (::Vector, [s]) start times of the blocks in a sequence
A sampled version of a Sequence struct, containing vectors for event amplitudes at specified times. DiscreteSequence is the struct used for simulation.
Trapezoidal integration for every spin of a phantom.
Note
In practice, this function is used to integrate (Gx * x + Gy * y + Gz * z) * Δt for all the spins. NΔt is the length of Δt. Ns stands for the number of spins of a phantom. x is a matrix which rows represents different spins and columns are different times and the elements are the field Gx * x + Gy * y + Gz * z values.
Arguments
Δt: (1 x NΔt ::Matrix{Float64}, [s]) delta time 1-row array
x: (Ns x (NΔt+1) ::Matrix{Float64}, [T]) magnitude of the field Gx * x + Gy * y + Gz * z
Returns
y: (Ns x 1 ::Matrix{Float64}, [T*s]) vector where every element is the integral of (Gx * x + Gy * y + Gz * z) * Δt for every spin of a phantom
Trapezoidal cumulative integration over time for every spin of a phantom.
Arguments
Δt: (1 x NΔt ::Matrix{Float64}, [s]) delta time 1-row array
x: (Ns x (NΔt+1) ::Matrix{Float64}, [T]) magnitude of the field Gx * x + Gy * y + Gz * z
Returns
y: (Ns x NΔt ::Matrix{Float64}, [T*s]) matrix where every column is the cumulative integration over time of (Gx * x + Gy * y + Gz * z) * Δt for every spin of a phantom
Divides a list of indices from 1 to N into k groups.
Arguments
N: (::Integer) number of elements to be ordered
k: (::Integer) number of groups to divide the N elements.
Keywords
breaks: (::Vector{<:Integer}, =[]) array of indices where predefined breakpoints are placed.
Returns
array_of_ranges: (::Vector{UnitRange{<:Integer}}) array containing ranges of different groups. The target is k groups, but this could increase by adding elements to the breaks input array
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": sets the index ID of the available GPU in the host computer
Returns
sim_params: (::Dict{String,Any}) dictionary with simulation parameters
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
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": sets the index ID of the available GPU in the host computer
Returns
sim_params: (::Dict{String,Any}) dictionary with simulation parameters
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
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}$):
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}$):
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
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
return_window: (::Bool, =false) make the out be either 'nothing' or the Blink window, depending on whether the return_window keyword argument is set to true
show_window: (::Bool, =true) display the Blink window
Returns
out: (::Nothing or ::Blink.AtomShell.Window) returns either 'nothing' or the Blink window, depending on whether the return_window keyword argument is set to true.