[towards v1.5.x] Bump RF storage to v1.5.x

[mcencini]

This PR partially addresses #258.

This only handles changes to RF storage format. The most substantial updates concerns sequence.py , block.py and read_seq.py/write_seq.py modules. Other changes are either very minor updates to include the new attributes in the pulse design routines (make_*.py) or are re-generation of the expected output for the test cases.

For the moment, I excluded a few tests failing due to some inconsistencies in gradient storage format when writing and reading again. I am planning to re-enabling them when bumping gradient storage format.

@btasdelen do you think this is small enough or should I try to further divide this? Thanks!

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
/home/runner/.local/lib/python3.12/site-packages/pypulseq
add_gradients.py	123	98	20%	44, 52, 58, 61, 65–241
add_ramps.py	36	36	0%	1–89
align.py	35	29	17%	39–77
calc_duration.py	25	1	96%	37
calc_ramp.py	218	214	2%	45–353
calc_rf_bandwidth.py	35	26	26%	45–78, 82–86
check_timing.py	87	27	69%	72, 76, 101, 194, 201, 211–255
compress_shape.py	30	1	97%	28
convert.py	40	8	80%	42, 48, 66, 72–73, 82, 88–89
event_lib.py	96	15	84%	6–9, 48–51, 70–71, 205–210, 247
make_adc.py	92	14	85%	63, 69, 72–76, 79, 128, 131, 135, 141, 145, 184, 186, 188, 196
make_adiabatic_pulse.py	132	39	70%	202–206, 226–230, 238–239, 262, 268, 337–356, 460–469, 507–515
make_arbitrary_grad.py	37	7	81%	68, 71, 74, 77, 81, 83, 103
make_arbitrary_rf.py	75	63	16%	93–179
make_block_pulse.py	48	3	94%	119–123, 126
make_delay.py	9	1	89%	27
make_digital_output_pulse.py	16	2	88%	39, 47
make_extended_trapezoid.py	56	12	79%	67, 70, 76, 82, 85, 88, 91, 94, 116, 134, 136, 139
make_extended_trapezoid_area.py	93	3	97%	52, 227, 230
make_gauss_pulse.py	72	21	71%	109, 136–140, 143–167, 174, 177
make_label.py	19	3	84%	36, 41, 43
make_sigpy_pulse.py	119	30	75%	12–13, 119, 122, 126, 163–167, 171, 174–175, 178–179, 194, 201, 206, 218, 221, 246–256, 270, 273, 303–313
make_sinc_pulse.py	70	10	86%	100, 106, 134–138, 142, 145–146, 149–150, 172
make_trapezoid.py	111	7	94%	177, 190, 196, 214, 232, 237, 255
make_trigger.py	16	2	88%	44, 52
opts.py	66	9	86%	78, 83, 102, 142, 166–170
points_to_waveform.py	9	1	89%	27
rotate.py	69	14	80%	15, 55, 66–69, 85–90, 112, 119–120
scale_grad.py	14	4	71%	28–30, 33
sigpy_pulse_opts.py	26	7	73%	34–41
split_gradient.py	39	31	21%	46–103
split_gradient_at.py	70	62	11%	48–158
traj_to_grad.py	13	9	31%	26–40
/home/runner/.local/lib/python3.12/site-packages/pypulseq/SAR
SAR_calc.py	113	98	13%	33–40, 55–62, 89–108, 129–132, 168–212, 242–246, 264–306
/home/runner/.local/lib/python3.12/site-packages/pypulseq/Sequence
block.py	371	62	83%	59, 62, 70, 76, 91, 99, 105, 108, 116, 119, 122, 130, 135, 144, 197, 246, 250, 266, 310–313, 319, 331–359, 403–404, 409, 415, 435, 499, 504, 540, 546, 573, 611, 645, 682, 706
calc_grad_spectrum.py	81	76	6%	68–190
calc_pns.py	40	31	22%	45–96
ext_test_report.py	140	13	91%	23, 58, 61, 65, 135, 200, 227–233
install.py	75	42	44%	31, 52, 69, 71, 112–131, 148, 181–184, 200–212, 254–278
parula.py	4	2	50%	19–86
read_seq.py	371	124	67%	43–44, 91, 94, 106, 111, 117, 124–125, 129, 138, 146–153, 155–158, 161, 169–171, 204, 209, 217–274, 281–296, 311–381, 386–403, 466, 469, 504, 512, 550, 574, 613, 655–659, 774, 785
sequence.py	746	232	69%	11–14, 102–112, 133–146, 184, 249–252, 299, 326, 343, 391, 419, 446–451, 488, 504, 595, 617, 658–661, 715, 753, 764–765, 771, 782, 788, 790, 798, 831–839, 860–882, 925, 927, 930, 956–957, 960–963, 999–1009, 1018–1020, 1064–1076, 1091–1092, 1128–1129, 1155, 1158, 1161, 1164, 1198–1201, 1333–1346, 1376, 1404, 1426–1428, 1449, 1480, 1491–1504, 1514–1539, 1573–1574, 1585–1603, 1627, 1657–1665, 1697–1807, 1836, 1850–1860, 1872
write_seq.py	176	19	89%	44, 68, 71–78, 126–142
/home/runner/.local/lib/python3.12/site-packages/pypulseq/utils
cumsum.py	14	1	93%	17
safe_pns_prediction.py	126	113	10%	50–87, 102–189, 197–214, 222, 244–250, 279–286, 310–336, 344–383, 396–411, 415
tracing.py	16	6	62%	33–34, 42, 54–55, 75
/home/runner/.local/lib/python3.12/site-packages/pypulseq/utils/siemens
asc_to_hw.py	58	53	9%	21–28, 48–106
readasc.py	48	45	6%	25–100
TOTAL	4479	1726	61%

Tests	Skipped	Failures	Errors	Time
1265	14 💤	0 ❌	0 🔥	1m 53s ⏱️

[btasdelen]

Yes, this is great, thank you! I will have a look at this in detail, soon. Meanwhile a thought: should we have tests that also checks the sequences written in v1.4.1 format (using write_v141() function) to make sure we are not breaking backwards compatibility?

[mcencini]

Good idea! I guess we'll need multiple expected output files for the different storage formats

[mcencini]

On a second thought, do we really want to support writing to older formats? I know MATLAB toolbox does, but doesn't that introduce a lot of maintainance overhead? After all, we do not have, let's say, write_131().

Just thinking out loud here, if we decide it is worth to support older revisions I am happy to include the corresponding tests.

[btasdelen]

I see what you mean. People who did not migrate their interpreters to 1.5 can stick with an older version of PyPulseq. I guess it boils down to the question, if we want people to use a newer version PyPulseq regardless, for them to have access to bug fixes and some of the new features.

We can also decide this down the line, probably.

[Copilot]

Pull Request Overview

This PR bumps the RF storage format to v1.5.0 and updates the internal representation of RF pulses by adding new fields (center, freq_ppm, phase_ppm) in key modules such as sequence.py, block.py, and read_seq.py. Additional changes include updates to expected output files and modifications to various pulse‐creation routines and helper functions to accommodate the new RF event tuple format.

• Updated RF library tuple structure and its handling in sequence, block, and read_seq modules.
• Added new parameters (freq_ppm, phase_ppm) and default values (e.g. use='undefined') to pulse‐creation routines.
• Minor updates to test outputs and examples to include the new attributes.

Reviewed Changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/*	Expected output files updated to reflect new RF event format changes
src/pypulseq/supported_labels_rf_use.py	Updated supported RF use labels by including 'other' and 'undefined'
src/pypulseq/make_*_pulse.py	Added new parameters (freq_ppm, phase_ppm) and updated docstrings accordingly
src/pypulseq/Sequence/(sequence.py, block.py, read_seq.py)	Modified RF storage handling and tuple mappings to support v1.5.0 format
pyproject.toml	Bumped project version from 1.4.2.post1 to 1.5.0
examples/scripts/*	Updated examples to pass explicit use parameters

Comments suppressed due to low confidence (3)

src/pypulseq/make_block_pulse.py:20

• The RF use validation logic is repeated across several pulse‐creation functions. Consider factoring this out into a shared helper function to ensure consistency and simplify future updates.

    system: Union[Opts, None] = None,

src/pypulseq/Sequence/sequence.py:1286

• The TODO comment suggests that the RF use mapping should be derived from get_supported_rf_uses() instead of being hardcoded. Please update or remove the TODO once a dedicated mapping mechanism is implemented.

        # TODO: fixme : use map built from pp.get_supported_rf_uses()

src/pypulseq/make_gauss_pulse.py:70

• The function's docstring should be updated to include and explain the new parameters (freq_ppm and phase_ppm) added to the RF event structure.

        slice select event.

[btasdelen]

Just added two minor comments to be addressed, other than that looks good. Can be merged afterward.