mtrk—A flexible environment for developing open-source MRI pulse sequences

Abstract

Purpose:

To introduce mtrk, a new open-source tool based on modern software-engineering principles that simplifies pulse-sequence design, implementation, and dissemination.

Methods:

The mtrk framework is vendor-agnostic and relies on a compact and human-readable descriptive language. Users can design pulse sequences using either a Python-based programming interface or an intuitive graphical interface. The graphical interface also allows for visualizing pulse-sequence diagrams. A driver sequence was developed to run mtrk sequences on MR scanners. A spin-echo sequence was designed with mtrk and converted to Pulseq for comparison. Both versions were compared to an equivalent vendor sequence in phantom and in vivo experiments.

Results:

Images from the mtrk and Pulseq versions were nearly identical and showed over 90% similarity compared to the vendor sequence, despite minor unavoidable design differences. Phantom images matched corresponding synthetic images simulated using the same pulse sequences.

Conclusion:

The mtrk framework simplifies the development of pulse sequences by providing an intuitive descriptive language and compatibility with the Pulseq format. Users can design and simulate pulse sequences using the graphical interface without any programming experience.

1 |. INTRODUCTION

Implementing novel acquisition ideas on clinical magnetic resonance imaging (MRI) scanners requires access to vendor-provided proprietary software development kits (SDKs), which can be difficult to use and are typically only available through formal research agreements with the vendors. The MRI community has proposed vendor-agnostic sequence programming frameworks to address intellectual property issues and the high complexity of the vendor SDKs, recognizing the need for unrestricted and standardized prototyping tools. These efforts were pioneered by ODIN¹ and SequenceTree.² Recently, the community has mostly focused on the Pulseq environment introduced by Layton et al. in 2016³.

Initially developed in MATLAB and later ported to the Python language,⁴ Pulseq uses a text format to represent sequences as a series of timing blocks. This approach simplifies the interpretation with a driver sequence at the scanner, but can result in large and complex files for advanced sequences. Pulseq files contain the timing instructions and waveforms of the sequence, ensuring that the events are compatible with the hardware limitations of the selected MRI scanner. Once calculated, the files cannot be easily changed. To modify an existing sequence, the source code originally used to generate the sequence file is required. Pulseq files can also be interpreted by external software, such as KomaMRI,⁵ which includes a Bloch simulator and provides tools to execute sequences for arbitrary phantom models using simplified system configurations.

In addition to providing a vendor-agnostic solution for describing pulse sequences, efforts have been undertaken to make pulse-sequence development more accessible to researchers without programming experience. For example, SequenceTree represents the sequence structure and events as a tree chart, while gammaSTAR⁶ implements mechanisms for sequence optimization and real-time acquisition. However, their graph representations of sequences may be less intuitive compared to the common timing-diagram representation of pulse sequences found in the literature.

The goal of this work is to introduce a novel open-source framework called mtrk, which addresses two main issues: (1) although the recent vendor-agnostic frameworks made sequence development more accessible, it remains complex and unintuitive for non-programmers; (2) the current solutions rely either on a fully unrolled description of the sequence or an intricate representation using several files, making it difficult to handle and adjust existing sequences without access to the source code. mtrk provides an intuitive graphical user interface (GUI) that enables users to build sequences directly from textbook-style descriptions, without requiring programming experience. Moreover, mtrk introduces a compact, modular Sequence Description Language (SDL) format that combines numerical waveform data with a block-based structure, enabling easier editing and external computations like sequence optimization.

2 |. METHODS

Figure 1 illustrates the mtrk architecture, centered around the SDL, which serves as an intermediate format between the sequence generator (e.g., a Python program) and the interpreter (e.g., the driver sequence). A Python-based application programming interface (API) and a web-based GUI were developed for generating SDL files. The web-based GUI also includes a tool for sequence visualization to facilitate testing and debugging. The mtrk source code is available on GitHub,⁷ along with a deployment script for automated installation in a virtual machine using the Vagrant⁸ tool.

FIGURE 1.

Schematic representation of the mtrk architecture. A Python programming interface, a web-based graphical interface, or an external tool can be used to describe a sequence in the Sequence Description Language (SDL) file format. The description can be visualized in the mtrk sequence viewer, executed at the scanner with the mtrk driver sequence, or converted to the Pulseq format for other use cases.

2.1 |. Sequence Description Language (SDL)

The SDL utilizes the common JavaScript Object Notation (JSON) syntax, allowing users to choose their preferred programming language or toolset for generating sequence files. This flexibility, and in particular the support for fully open-source tool chains without required license fees, is a key principle behind mtrk.

The SDL format defines seven sections (Figure 2: File, settings, info, instructions, objects, arrays, and equations), encompassing real-time events (RF, gradients, ADC), sequence structure, and reconstruction information. It can be freely extended if additional information should be incorporated into the file. Each section contains a dictionary of values, which are referenced using clear-language terms to make the description easily readable. The “instructions” section forms the core of the sequence description and contains one or multiple instruction lists, each with a unique name. During sequence execution, the interpreter iterates over all listed action steps, which may include real-time events (e.g., creating an RF pulse), helper events (e.g., increasing a counter variable), and calls of other instruction lists (with single or looped execution). Parameters for real-time events (e.g., RF or gradient pulses) are defined in the “objects” section, with property values that can be set in various ways (fixed values, predefined arrays, or equations). Helper events can be used to structure the sequence and to perform internal calculations, e.g., to implement RF-spoiling schemes (see the mtrk implementation of the educational MiniFLASH sequence in the GitHub repository⁹). At the same time, the SDL format is “unopinionated”, meaning that a plurality of possibilities exist to describe the same sequence, providing flexibility to the developers.

FIGURE 2.

The Sequence Description Language (SDL) is used to describe MR sequences. It is based on the JSON format and structures the information using keywords in plain language. SDL files contain seven main sections. Sections “file”, “settings”, and “info” form the header and provide metadata on the sequence, including information needed for the reconstruction. The section “instructions” defines the execution order and represents the looping structure with blocks and events that are specified in the later sections “objects”, “arrays”, and “equations”. Two different types of events can be listed in the “instructions” section: Real-time events (“grad”, “rf”, “adc”, “sync”) and helper events (“init”, “submit”, “mark”, “calc”). Real-time events represent operations executed by the scanner hardware, including the generation of RF pulses (“rf”), gradient pulses (“grad”), and data sampling (“adc”). Moreover, “sync” events can be used to generate trigger signals, such as TTL pulses. Helper events are internal operations to facilitate the sequence calculation and debugging. “init” and “submit” are used to label the beginning and end of blocks, “mark” can be used to place additional labels into blocks (e.g., for timing checks), and “calc” events can be used to perform internal calculations (e.g., to implement RF-spoiling schemes). Additional settings for real-time events are specified in the “objects” section, including the duration and number of sample points for “adc” events, and the selection of the waveforms for “grad” and “rf” events. The waveform shapes are described in the “arrays” section through lists of numerical values (amplitude from −1 to +1). “rf” and “grad” events can either use a fixed amplitude, or they can be dynamically scaled using provided arrays or equations. The latter are defined in the “equations” section and can incorporate counter variables and calculations from “calc” events. For simplicity, only one gradient event is shown in the diagram. Additional examples can be found in the mtrk GitHub repository.

2.2 |. Driver sequence

To demonstrate the feasibility of implementing pulse sequences with mtrk, a driver sequence was developed for Siemens MR scanners (running software versions VE11C, VE11S, XA50, and XA60) using the IDEA development kit. The driver sequence must be installed on the scanner and enables users to select an SDL file. It reads the SDL content, renders the instructions (i.e., it unrolls the sequence description into a continuous time series), and prepares individual real-time events using the API of the IDEA development kit. The driver sequence utilizes core IDEA classes for arbitrary RF pulses and arbitrary gradient waveforms to convert the SDL objects into native IDEA real-time events. Thus, the driver sequence does not need further information about the specific pulse shapes or types. Since all sequence parameters are included in the SDL file and can be easily modified using the mtrk GUI, the driver sequence does not provide controls for changing the parameters on the scanner console.

The SDL format can be adapted to work with any MR vendor. Although certain parameters are currently hard-coded for Siemens systems, vendor-specific characteristics, such as raster times and sequence headers, can be made configurable and included in the “settings” section. This flexibility enhances cross-vendor compatibility and promotes broader adoption.

2.3 |. Sequence development

A Python-based API (Figure S1) was implemented to support the generation of SDL files. Built using the Pydantic¹⁰ library, it enforces strict type validation when reading and writing the SDL files in JSON format to prevent runtime errors during the execution of the sequences on the scanner. The API provides functions for construction, population, and interpretation of an SDL file, along with helper functions to calculate waveforms and implement different readout trajectories. Furthermore, it includes a PyPulseq-based converter function to offer compatibility with Pulseq.

To simplify sequence development and make it accessible to users without programming experience, a complementary web-based GUI (Figure 3A) was developed. The GUI frontend was written in JavaScript, while the backend was developed using the Flask¹¹ web framework, importing functions of the mtrk Python API. The GUI was designed around the concept of an interactive sequence timing diagram. Real-time events can be intuitively added using a “drag-and-drop” interface, supported by a visual representation of the looping structure. The shapes of the events are defined using a waveform manager, which accepts numerical arrays with a constant raster time. The amplitude can be made variable by defining equations. To simplify the process for non-programmers, the GUI includes built-in tools for automatic waveform generation, covering the most commonly used schemes, such as sinc, SLR, and adiabatic RF pulses, as well as trapezoidal and optimized trapezoidal gradient pulses. Additionally, it supports readout generation for multiple acquisition strategies, including Cartesian, EPI, radial, and spiral trajectories. The GUI also includes a viewing tool (Figure 3B) for visualizing sequences from generated SDL files. It can be used for timing checks and the creation of figures for publications. The designer and viewer GUI tools, including waveform and readout generators, are demonstrated in the video provided in the Supplementary Materials.

FIGURE 3.

Sequence diagram of a spin-echo sequence generated using the mtrk designer (A), the mtrk viewer (RF pulses are scaled according to the flip angle FA to differentiate them) (B), and the conversion to Pulseq (C). The sequence was designed using the designer GUI by adding real-time events to the diagram. The SDL file was created by clicking the “download sequence” button at the bottom right of the UI. The SDL file was subsequently opened in the viewer GUI for inspection, converted to the Pulseq format using the Python API, and plotted for comparison.

To develop new sequences in mtrk, users can choose from three strategies: (1) writing the SDL file in Python using the API; (2) designing the sequence in the GUI without programming; or (3) creating the SDL file directly using a language that supports JSON. The Python API is best suited for complex sequences, especially those involving non-trivial control flows such as non-repeating or interleaved patterns. In contrast, the designer GUI is the most appropriate approach for simpler sequences, for modifying existing sequences, or for educational purposes. Advanced sequences may require custom-developed generators, which can be implemented in any language that supports the JSON format.

2.4 |. Proof-of-concept design of a spin-echo sequence

A basic 2D spin-echo sequence with single-line readout (se2d) was designed following the scheme shown in Figure 3A,B. Originally developed using the mtrk GUI, it was also implemented as a script with the Python API to provide an example of script-based sequence definition (file provided in the GitHub repository¹²).

The file was converted into the Pulseq format using the SDL-to-Pulseq converter script (Figure 3C). The two sequence files were transferred to two 3T scanners (MAGNETOM Vida—XA60 & Prisma—VE11C, Siemens Healthineers) along with the driver sequences for both mtrk and Pulseq. Data were acquired using a 20-channel head coil for a custom-made two-compartment phantom (VE11C & XA60) and a human volunteer (XA60 only). Scans were done with the mtrk and Pulseq variants of the se2d sequence and compared to a corresponding vendor sequence. Written informed consent was obtained from the human subject before examination, according to the study protocol approved by the Institutional Review Board (IRB).

Images were reconstructed in MATLAB by applying an inverse fast Fourier transform without additional post-processing. Reconstructed images were visually assessed for quality and quantitatively compared using four metrics: Signal-to-noise ratio (SNR),^13,14 peak SNR (PSNR), root-mean-square error (RMSE), and structural similarity index (SSIM). Three different contrasts were acquired: T1-weighted (T1-W), T2-weighted (T2-W), and proton-density weighted (ρ-W). The scan parameters included a 128 × 128 matrix, a 300 mm field-of-view, a bandwidth of 260 Hz/px, and two-fold readout oversampling. All acquisition parameters are summarized in Table 1.

TABLE 1.

Acquisition parameters for the phantom and volunteer experiments. Three contrasts were acquired with otherwise identical parameters (128 × 128 matrix, a 300mm field-of-view, a bandwidth of 260 Hz/px, and two-fold readout oversampling).

	TE (ms)	TR (ms)
T1-W phantom	10	500
T2-W phantom	400	5000
ρ-Wphantom	10	5000
T1-W volunteer	10	600
T2-W volunteer	80	4000
ρ-Wvolunteer	10	4000

To ensure compatibility of the mtrk sequences with other open-source tools, the Pulseq version of se2d was used to simulate images in KomaMRI using a numerical phantom, modeled after the two-compartment phantom used in the experiments. The phantom was characterized at the scanner using quantitative mapping techniques: Multi-echo spin-echo for T2 and ρ maps, and multi-echo gradient echo for T1 and T2* maps. The data simulated for the three contrasts were reconstructed using the same pipeline that was used for the experimental data. Images were normalized to the maximum pixel intensity for comparison with the experimental phantom images.

3 |. RESULTS

3.1 |. Sequence definition

The se2d sequence was created using the mtrk GUI and reproduced with a Python script (provided in the Supplementary materials), resulting in a 381-line-long SDL file. The conversion to Pulseq was done in less than 10 s using the SDL-to-Pulseq conversion script, resulting in a Pulseq file with 3904 lines. Both sequence-description files were imported into IDEA, and the corresponding sequence diagram was simulated using the respective mtrk and Pulseq driver sequences (XA60, VE11C). The diagrams matched accurately and showed the expected design of the sequence.

3.2 |. Phantom experiment

Images from the two-compartment phantom experiment are compared in Figure 4A–C, showing the same contrast and shape, with closely matching absolute difference and SSIM maps. The slight discrepancy observed between the vendor sequence and the se2d sequence is likely caused by implementation differences, which cannot be further investigated as the source code of the vendor sequence is not available. The mean values for SNR (Figure S2a), SSIM, RMSE, and PSNR within the phantom mask (Figure S3) are provided in Table S1. The PSNR for the se2d sequence was identical when comparing mtrk and Pulseq to the vendor sequence. When comparing mtrk to Pulseq, the RMSE remained below 1.2%, and the SSIM exceeded 99.5%, demonstrating the equivalence between the two frameworks and the accuracy of the SDL-to-Pulseq converter. The RMSE between the vendor sequence and the se2d sequence was below 8%, and the SSIM remained above 91.9%. The experiment was performed using two different software versions (XA60 and VE11C), confirming the reproducibility and generalizability (Figure S4).

FIGURE 4.

Images and analyses for a two-compartment phantom, the healthy volunteer, and the simulation acquired on a 3T scanner with a 20-channel head coil using the mtrk se2d sequence, its equivalent Pulseq sequence, and a matching protocol of a vendor sequence. (A,D,G) Images for three different contrasts, (B,E,H) comparison between sequences, and (C,F,I) SSIM maps.

3.3 |. Invivo experiments

Similar results were found for the volunteer experiments, as shown in Figures 4D–F, S2b and Table S1. Small differences between the mtrk and Pulseq images are due to minor motion artifacts. Images obtained with the vendor sequence closely match the se2d images in terms of contrast, but reveal a slight discrepancy along the slice selection. This difference is most likely due to differences in the slice-selection pulses, which cannot be further investigated as the vendor’s source code is inaccessible. When comparing the mtrk se2d to its Pulseq equivalent, the RMSE was under 4%, and the SSIM was above 93.7%.

3.4 |. Simulation

The simulation results are presented in Figure 4G–I and Table S1. The absolute difference and SSIM maps show good similarity between the simulated and experimental images for all three contrasts. However, minor differences exist at the edges, possibly caused by Gibbs ringing, partial volume, or susceptibility effects that appear differently in the experimental and the simulated images. Additionally, the normalization method differed between the simulated (performed in MATLAB after reconstruction) and the acquired data (performed on the raw data at the scanner).

4 |. DISCUSSION

This work presents a new open-source framework for the rapid development of MRI pulse sequences. Because the SDL provides a compact format to describe sequences and utilizes a common text-based syntax (JSON), sequence calculations can be performed on any platform. The approach enables new opportunities for streamlined fleet management, clinical workflow optimization, and dissemination of sequences (e.g., “sequence as a service”).

The compact size of the proposed SDL format allows for fast distribution of remotely calculated sequences over TCP/IP connections. This is possible because the SDL includes flow-control elements, such as loops, conditional blocks, and equations. Moreover, it can support dynamic sequence adaptation during runtime if necessary for real-time scanning applications. Since the SDL can be seen as a higher-level format compared to Pulseq, the conversion from Pulseq to SDL was achieved without losing functionality.

mtrk simplifies pulse sequence development by supporting both traditional programming through its Python API and web-based graphical development. Unlike the tree-chart-based approaches used in SequenceTree and the JEMRIS¹⁵ simulator, the mtrk GUI enables composing pulse sequences by designing waveforms, their amplitudes, and timings. This improves accessibility, particularly for students and users with limited programming experience, and facilitates broader engagement in pulse-sequence development, which normally has a steep learning curve.

Although a driver sequence is currently only available for Siemens scanners, the mtrk framework was designed to be vendor-agnostic through the use of a universal format. The work presented here showed that it is relatively straightforward to integrate support for reading and interpreting SDL files into a C/C++-based vendor framework.

The initial proof-of-concept experiments confirmed the feasibility of using mtrk for implementing pulse sequences. Conversion to Pulseq was accurate, yielding nearly identical results for both formats. The validation of open-source pulse sequences has been previously explored in a previous study¹⁶ that assessed the performance of Pulseq IRSE and TSE sequences against vendor equivalents on an ACR phantom using PSNR, SSIM, and SNR. In this work, we also validated the accuracy of the se2d sequence with respect to a comparable vendor sequence, showing high PSNR and SSIM. The overall close alignment found in both phantom and in vivo experiments suggests that mtrk can be used to generate sequences with comparable quality to vendor products. Additionally, the simulation experiments highlighted the potential for conducting experiments without access to a physical scanner, offering value for artifact and contrast evaluation as well as for student education.

The first version of mtrk has various limitations that will be addressed in future work. First, it was tested only with basic sequence types. We plan to implement more complex state-of-the-art sequences for further validation. Second, the user interface of the driver sequence does not reflect the sequence parameters used for calculating the SDL file, and it is not possible to change the parameters through the vendor interface. To adjust the parameters, it is currently necessary to recreate or modify the SDL file, which, while not difficult, can be less intuitive and user-friendly. This inconvenience was also seen in Pulseq and has recently been partially addressed.¹⁷

To address these limitations, we plan to add (1) further features to enable the SDL recalculation whenever settings are changed; (2) a reverse Pulseq-to-mtrk converter (although this may be challenging and result in limited compatibility); and (3) a larger template library with state-of-the-art sequences. Additionally, the mtrk framework will be evaluated as an educational tool in an academic setting.

5 |. CONCLUSION

This work introduces mtrk, a novel approach for pulse-sequence development based on a flexible descriptive language. Compared to traditional sequence programming with vendor-provided tools, it offers more intuitive and accessible development using a web-based GUI that does not require programming experience. Its compact SDL format ensures compatibility with remote calculation, which could facilitate sequence optimization and new concepts for sequence distribution. The mtrk source code has been released as an open-source package to support reproducibility, accessibility, and shareability.

Supplementary Material

Supporting Video

Video S1. Demonstration of the mtrk GUI.

Supporting Figures

Figure S1. Structure of the mtrk API and GUI source code. The designer API contains an sdlGenerator script, which creates the structure of an SDL file and calls the sdlFileGenerator script to write an SDL file with the given instructions. This API is connected to the mtrk designer GUI, which uses Flask in a backendToUI script and transfers information to a JavaScript web application.

Figure S2. SNR maps for both phantom (a) and healthy volunteer (b) for three contrasts (T1-W, T2-W, and ρ-W). The SNR was calculated using Kellman’s definition on the masked area of the signal.

Figure S3. Masks used to compute SNR, absolute difference, and SSIM mean values on the signal area for the phantom and the volunteer scan. They were obtained by thresholding all images and concatenating the obtained masks to ensure the inclusion of all signals from each acquisition.

Figure S4. Comparison of images between software versions (XA60 and VE11C) with simulated images for reference. Apart from slight artifact differences caused by the use of a different MR system, the experiment was properly reproduced, showing the expected contrasts with two different versions of the mtrk (and Pulseq) driver sequence.

Table S1. Signal-to-noise ratio (SNR), averaged on the masked area of the map, and comparative (comp.) values, with root mean square error (RMSE), mean structural similarity index measure (SSIM), and peak SNR (PSNR) compared against the vendor sequence (ref.) for three contrasts acquired in a 2-compartment phantom, a volunteers brain, and a simulation of the phantom at 3T.

Additional supporting information may be found in the online version of the article at the publisher’s website.

DATA AVAILABILITY STATEMENT

The source code of the mtrk framework, along with the installation and usage instructions, is provided in the GitHub repository: https://github.com/mtrk-dev. The driver sequence can be obtained on request from the corresponding author.