Units + doc again

[schmidtijoe]

Describe the bug I've come across multiple instances where the use of units is unclear. Especially when looking at the doc (eg. of a function), example scripts of sequences and the code base in pypulseq/Sequence

• use of frequency offset in example scripts: In slice selective sequences one goes with rf.freq_offset = ( gs.amplitude * slice_thickness * (num_slices - (index_slice - 1) / 2)) . However, gs.amplitude is in [Hz], and slice_thickness is in [m]. Consequently, from $\omega = - \gamma B$ -> $2 \pi f = - \gamma g_s z = - g_s^{inHz} z$, follows that there is a $2 \pi$ missing in order to set the frequency offset in Hz. I did some phantom scanning with a self written slice selective sequence and indeed i get a brightening / darkening interference like pattern in slice direction when ommitting $2 \pi$ there.
• doc of rf.phase_offset parameter: The parameter is documented in the relevant functions (eg. make_sinc_pulse) as phase_offset in [Hz]. However, in example scripts it is used in radiance and also when going into pypulseq.sequence.export_waveforms it is used eg. as np.exp(1j * rf.phase_offset), which indicates units of [rad].

To Reproduce

• To exemplify the first issue further: A slice thickness of 0.7 mm and a TBW of 2.0 in make_sinc_pulse or make_gauss_pulse methods with return_gz=True results in a Pulse Bandwidth of around 976 Hz. Consequently, the gradient amplitude is $g_a$ ~ 1 393 728 Hz. Which turns out to be converted to a Gradient around 0.0327 T/m Gradient on the Scanner. Hence, gradient amplitude $g_a$ as used is in G[T/m] * $\gamma$ [Hz/T], which shows that a freq_offset set in above fashion e.g. only multiplying by the slice position in [m] would result in $\omega$ [rad] rather than $f$ [Hz] given above equation, if i am not mistaken.

Expected behavior

• Example scripts of slice selective sequences to show corrected frequency offset
• Documentation of functions involving rf.phase_offset to state units of [rad]

misc:

• pypulseq version: dev branch: 1.4.0

[mavel101]

I think you are using 2 different gammas in your 1st point. First gamma has rad/s/T, second one has Hz/T. Therefore you would have to add the factor 2pi also on the right side of your 2nd equation. A gradient amplitude in [Hz/m] times thickness in [m] should always give you a frequency offset in Hz just by looking at the units. Strange though, that you see artifacts in your slice selection. I agree, that units in the docs are often wrong, probably due to copy/paste issues.

[schmidtijoe]

Youre right. Ive mixed them :O good old Handbook of physics formulae tricked me. Sorry. I just new the error for the artifact is somewhere in the phase setting of the slices since it is related. But i am getting closer at fixing. The units of freq and phase offset seem right though! My bad!

[sravan953]

Hi all, can this issue be closed? Request you to continue reporting other documentation inconsistencies that you come across.