Support for Pulseq v1.5.0

[btasdelen]

Missing functionality to support new interpreter features:

• [x] RF storage now includes RF center position, also supports frequency/phase offsets in PPM.
• [x] ADC also supports frequency/phase offsets in PPM.
• [x] Arbitrary gradients include first and last points.
• [ ] Soft delay extension (See #264 ).

Some functions/functionality that are not crucial for support but nice to have to catch up with Matlab Pulseq Toolbox.

• [ ] Demo sequences that use above features.
• [ ] calcMomentsBtensor()
• [x] paperPlot() or simply improved plotting.
• [x] Oversampling of arbitrary gradients.
• [x] Scale gradients checks for system limits.

Missing functionality for v1.5.1:

• [ ] Rotation extension.
• [ ] RF shim extension.

[Tooine]

Hi,

I'm using pypulseq to develop MR Fingerprinting sequences. While I was using those sequences only with the KomaMRI simulator until very recently (without problem), I can now access a real MR scanner to test them. Yet, the scanner interpreter is up to date and only accepts pulseq 1.5 sequences...

So I was wondering when we might expect pypulseq to be compatible with pulseq 1.5? Depending on the availability, perhaps I should translate my code into Matlab.

Also, I'm just curious to know if there exists a way to modify "by hand" a 1.4 pulseq sequence file to make it compatible for 1.5?

Thanks!

[schuenke]

Hi @Tooine

In principle the Pulseq 1.5 interpreter should be compatible with Pulseq 1.4.x files. However, there is/was a bug in the code prohibiting the execution of older seq-files (including the gre_example sequence provided with the 1.5.0 interpreter code btw). Here is the corresponding Issue (https://github.com/pulseq/pulseq/issues/104) in the Pulseq repo. Maxim provided a fix in one of the comments: https://github.com/pulseq/pulseq/issues/104#issuecomment-2769385592

and if you are interested in MRF, you might want to check our public repo for cardiac MRF: https://github.com/PTB-MR/cMRF The paper should (hopefully) be published soon.

EDIT: @Tooine: Initializing every label that you use with "0" at the beginning of each sequence might also be enough, but I didn't verify this on my own yet.

[Tooine]

Thanks for the quick reply @schuenke!

I have seen this issue on Pulseq but I though it was only fix in Matlab ... To what I understand now, the file Arbitrary.cpp in which we should make the modification is a file of the interpreter, not the (py)pulseq code, right? Can you confirm that? (sorry I don't have access to the interpreter myself so I'm just guessing as I did not find the file elsewhere)

[fzimmermann89]

Yes, it is part of the interpreter.

[fzimmermann89]

I think as a work around, maxim mentioned setting all used labels to zero in the beginning of the sequence? This could be done with pypulseq without modifying the interpreter

[Tooine]

Sure, gonna try both possibilities! Many thanks :-)

[btasdelen]

So I was wondering when we might expect pypulseq to be compatible with pulseq 1.5? Depending on the availability, perhaps I should translate my code into Matlab.

Among the essential 4 features, I implemented the soft delay, but it is not tested at all. The rest still needs to be implemented. Since there are substantial changes to the file format, I anticipate bugs, especially related to reproducibility (i.e. generating the same .seq file given the same inputs as the Matlab pulseq).

The other 3 features look less involving, but we will see. Personally, I can most likely start working on this again late May. Depending on who else wants to work on this, we can release during the summer, hopefully.

[mcencini]

So I was wondering when we might expect pypulseq to be compatible with pulseq 1.5? Depending on the availability, perhaps I should translate my code into Matlab.

Among the essential 4 features, I implemented the soft delay, but it is not tested at all. The rest still needs to be implemented. Since there are substantial changes to the file format, I anticipate bugs, especially related to reproducibility (i.e. generating the same .seq file given the same inputs as the Matlab pulseq).

The other 3 features look less involving, but we will see. Personally, I can most likely start working on this again late May. Depending on who else wants to work on this, we can release during the summer, hopefully.

Hi, I would be happy to help. I also wanted to include rotation extension (currently under development on MATLAB repo, version 1.5.1). Would that be ok? Thanks again for this package :D Matteo

[btasdelen]

@mcencini feel free to test #264. I added rotation extension to TODO, but it might be a better idea to merge previous changes first to avoid conflicts.

[mcencini]

@btasdelen following conversation in #264, I would be totally in favor of splitting the #288 PRs in multiple smaller and easier to review PRs (e.g., #289). As these smaller PRs would likely not be functional (not compatible with any interpreter), I would prefer not to open PRs to the current master branch. Would it be possible for the maintainers to create a v1.5.0 branch starting from master that I could use for this? Is that a good idea?

[btasdelen]

@mcencini I think that is a good idea. I created a branch called v1.5.0_dev, we can use that one.

[mcencini]

@btasdelen I have now finished preparing multiple branches covering all the main features (except for softDelay, as you are currently handling it). As we planned, I will open the PRs sequentially to minimize review workload. I could start looking into the extra features - I was wondering what Scale gradients checks for system limits would be, is it something which is currently implemented in MATLAB toolbox? If so, where that would be? Thanks again!

[btasdelen]

@mcencini Thank you so much for your support. I will make sure to review them soon.

It is this function in Matlab: https://github.com/pulseq/pulseq/blob/master/matlab/%2Bmr/scaleGrad.m, there are simple checks after the scaling to ensure values are within the system limit. PyPulseq equivalent is this function: https://github.com/imr-framework/pypulseq/blob/master/src/pypulseq/scale_grad.py

[mcencini]

Great! I think it can fit within the v1.5.0-grad branch (which also contain oversampling support) - compared to rf and ADC, the gradient storage change is quite minimal otherwise 😃 and thank you so much for the reviews!

[mcencini]

I am now including paperPlot porting in my v1.5.0-plot branch. While doing this, I had a look to the Sequence methods returning waveforms, times etcetera. I was wondering, do we really need to keep seq.waveforms_export()? It does not have a MATLAB counterpart and seems not to be used anywhere in the code, in addition to looking superseeded by other similar overlapping functions (e.g., waveform_and_times()). It may look a bit confusing for user, doesn't it? Any thoughts?

[btasdelen]

It is somewhat redundant, but it provides the waveforms interpolated to the raster, so the user doesn't have to interpolate it if they need to. I am fine either way, I am not sure if it is being used.

[mcencini]

Ok, I added seq.waveforms_export() back.

Once #264 is merged, we'll have all the four core 1.5.0 features. We also have support for oversampling and scale gradients checks (#294) and, once #296 is merged, also paperPlot. calcAdcSeg was proposed in discussion #194, maybe @felixlandmeyer would be interested in opening a PR.

Of the remaining 1.5.0 features, calcMomentsBtensor() seems the most involving (in theory, we miss also mr.calcRfPower() and seq.calcRfPower(), but these should be easier). If you agree, I would first move with merging v1.5.0_dev into master and address RF shim and Rotations (especially the latter gives huge benefits for users interested to Non Cartesian design, see pulseq/pulseq#117). I have both ready (Rotation relying on #244, which I also worked on). What do you think?

[felixlandmeyer]

@mcencini calcAdcSeg has been added in #196 and was released with #266.

[mcencini]

@mcencini calcAdcSeg has been added in #196 and was released with #266.

Sweet! Sorry I missed that :D thank you very much!

[schuenke]

hey @btasdelen @mcencini @felixlandmeyer @FrankZijlstra @fzimmermann89

thanks for all your work and sorry for beeing inactivate for such a long time. I was on several trips and vacation and didn't really find the time in between to contribute myself and/or review any of your implementations. I will try to catch up in the next days and check where I can contribute. Let me know if there is something specific I should do.

[btasdelen]

@schuenke No worries! I hope you had a great vacation!

I think the most urgent item is to publish v1.5.0. Heavy work on that is already done, further review is welcome and approval is required. The plan was to merge #264 into first as it is an extension and pretty independent of the v1.5.0 stuff, then merge v1.5.0_dev branch. @mcencini can create a PR for that. I reviewed individual moving parts of his effort, but since format changes required completion to work on the scanner, they are not battle tested.

#299 is a bug fix. It would be nice to merge it first.