spectrIm-QMRS
Version 3.0.1 Alpha
New in version 3.0.1 Alpha
The spectrIm-QMRS basis set simulator is the graphical front end to the ILV spin-system simulation work. ILV integrates the Liouville-von Neumann equations for coupled spin systems and creates sequence-specific metabolite responses that can be used as basis spectra for TDFDFit prior-knowledge fitting.
Quantitative MRS and MRSI fitting requires a basis set that is consistent with the pulse sequence, echo time, magnetic field, receiver carrier, spectral width, and acquisition length of the dataset under investigation. When this basis set does not match the measurement, the fitting engine may compensate by changing concentrations, linewidths, phases, or baselines in a way that looks plausible but is physically wrong.
ILV provides a route from a pulse sequence and a metabolite spin system to a quantum-mechanically simulated spectrum. In spectrIm-QMRS this is being connected directly to the automatic TDFDFit model creator: the intended clinical route is DICOM MRS data, sequence adaptation, basis-set simulation, TDFDFit model creation, and then fitting with the parallel CPU TDFDFit engine.
The older expert workflow of importing externally simulated MRUI numeric patterns into TDFDFitControl is still documented as a legacy/manual route on the TDFDFit basis-set loading walkthrough.
The clinical route is meant to make basis-set creation a controlled automatic step. spectrIm-QMRS reads the loaded dataset, selects or adapts a matching sequence definition, simulates the required metabolites, and builds a TDFDFit model for the current quantification task.
Spectroscopy experts can manually define spin systems, pulse sequence sectors, RF and gradient waveforms, acquisition timing, and simulation mode. This makes ILV a research tool for exploring new sequences and metabolites.
Both routes ultimately produce numerical basis patterns that can be inserted into a TDFDFit model and then fitted with the standard or parallel TDFDFit fitting engine.
The current v3 alpha GUI is organized into four main tabs. They separate the metabolite spin-system library, the pulse sequence library, the simulation preview settings, and the basis-set batch generation workflow.
The Metabolites tab lists the available spin systems. Each row connects a metabolite name with an ILV spin-system file, the observed nucleus, a reference frequency in ppm, and a status field. The user can include or exclude metabolites, add or remove entries, and open the resonance/coupling editor. The spin-system definition is where chemical shifts, relative spin amplitudes, and J-coupling structure are defined before simulation.
The Sequences tab is the graphical pulse sequence workspace. The upper table describes complete sequence definitions, including sequence type, variant, nucleus, B0, TE, TR, manufacturer, localization type, RF library, gradient library, status, remarks, and file path. The sector table below describes the individual building blocks of the selected sequence: RF pulses, delays, gradient delays, RF-gradient sectors, and acquisition sectors.
The lower part of the tab redraws the sequence timing as RF amplitude, RF phase, gradient channels, and ADC activity. This is the expert area for creating new sequences, cloning existing definitions, inserting sectors, defining sector details, and saving the sequence file.
This tab selects how ILV should be run before a full basis-set generation. It contains sub-tabs for single-spectrum simulation, 2D spectral simulation, and 1D/2D/3D spatial simulation. The displayed example shows a 2D spectral simulation setup with the selected sequence, metabolite, B0, transmit/receive carrier, and the incremented delay settings. Preview buttons allow the user to run or regenerate a simulation preview before committing to a full basis-set calculation.
The Single spectrum subtab is used for one metabolite and one sequence at a single spatial point. It is the fastest way to test whether a spin-system definition, RF pulse, carrier frequency, and acquisition setup produce the expected time-domain response and spectrum. The controls select the sequence, metabolite, B0 field, carrier position in ppm, transmit-carrier offset in Hz, and B1+ amplitude factor.
A sensitivity sweep can be run over either the B1+ amplitude factor or the transmit offset. This is important for sequence development: it lets the user inspect how robust a simulated metabolite response is to RF-amplitude scaling or off-resonance excitation. In the ILV parity work this kind of check was used as a practical guardrail: before a basis set is trusted, a single spin system and sequence should behave sensibly when the obvious experimental parameters are perturbed.
The same subtab also contains the current SLOW editing preview controls. SLOW editing uses two adiabatic 2pi pulse branches, labelled FULL and PARTIAL in the GUI. The user can define the center position, mhu, and beta for both branches, inspect the calculated bandwidth in ppm, and show the RF-pulse effect as a single spin-1/2 Bloch simulation from Mz=+1. The preview route generates FULL, PARTIAL, and DIFFERENCE responses. This is a research-level tool for developing and checking edited sequence behaviour before those responses are used as fitting basis functions.
The 2Ds NMR subtab is meant for explicit two-dimensional spectral simulations. It uses a sequence that contains an incrementable delay sector. The user selects the sequence and metabolite, sets B0 and the transmit/receive carrier, and then defines which sector or sectors are incremented, how many repeats are simulated, and the delay increment in milliseconds.
Conceptually, this subtab asks: what happens to the simulated signal when a specific evolution period in the sequence is stepped? This is useful for J-resolved and other two-dimensional NMR style experiments, and it is also useful when checking whether a sequence definition is internally consistent. The preview makes it possible to inspect the selected metabolite response before running a larger basis-set generation.
In practical terms, this subtab is an expert diagnostic layer. It is not the default clinical route, but it helps verify the sequence sector model that the clinical route depends on. If the incremented delay, carrier, or B0 is wrong, the resulting basis patterns will not describe the measured signal correctly.
The spatial simulation subtab extends the ILV calculation from a single spectrum to a grid of spatial positions. The user selects a spatial sequence and metabolite, sets B0 and the carrier, and then defines the X, Y, and Z simulation grid by start position, step size, and number of points in centimeters.
This mode is designed to evaluate the spatial behaviour of a pulse sequence: slice profiles, localization behaviour, transition regions, and spatially dependent density matrices. The current GUI can run the spatial density-matrix simulation, then calculate and display expectation-value profiles or maps after the user selects an operator. The displayed output can be shown as a 1D profile or as a 2D image with horizontal and vertical cross-sections. The 3D display is marked in the GUI as a future extension.
This is the natural place for expert validation of localization sequences. For example, the semiLASER prototype work in the ILV parity thread separated two questions that are easy to confuse: first, whether the first ADC sample occurs at the declared TE; second, whether the refocusing-pulse timing and gradient moments are physically balanced. Spatial simulation gives a way to inspect those sequence-design consequences before the same sequence is used to generate a metabolite basis set for clinical data.
The Basis-set generation tab turns the selected definitions into a set of simulated metabolite responses. It shows the ILV project folder, the output folder, B0, receiver carrier, selected sequence, and number of selected metabolites. The validation and refresh buttons check whether existing simulations are current, missing, or invalid. The simulation controls can generate missing/invalid basis spectra or regenerate all spectra. The result table stores the metabolite name, simulation status, spin information, sequence, carrier, result byte count, result file, model file, and log file.
A major goal of the v3 work is to reduce the clinical burden of basis-set simulation. The Java ILV GUI already contains logic that compares the selected ILV sequence with the loaded DICOM acquisition. It checks acquisition-relevant parameters such as TE, B0, ADC sample count, spectral width, and acquisition duration. If the selected sequence is a prototype or differs from the DICOM acquisition, spectrIm-QMRS can create an adapted runnable copy instead of overwriting the template.
For localization sequences such as PRESS and semiLASER, the GUI validates that the declared TE matches the timing from the excitation pulse midpoint to the first acquisition point. For semiLASER definitions with explicit timing tags, the code also checks the echo-balance relation between the refocusing pulse centers and the tau-prime delay.
The clinical vision is that the user loads an MRS or MRSI dataset, chooses the quantification route, and spectrIm-QMRS constructs the missing modelling components automatically. The software should identify the spectroscopy task, adapt or select the sequence definition, simulate the metabolite basis set with ILV, and pass the resulting basis spectra to the automatic TDFDFit model creator. The model can then be applied with Parallel pthreads-TDFDFit CPU Fitting.
In version 3.0.1 Alpha this workflow is already substantially implemented, but it is still an expert-supervised alpha feature. It should be checked against the sequence family, DICOM metadata, and expected metabolites before it is used for clinical or publication-quality quantification.
Choose metabolites and inspect or edit their resonance and coupling definitions.
Build or clone a pulse sequence from RF, gradient, delay, and acquisition sectors.
Run single-spectrum, 2D spectral, or spatial previews to verify the setup.
Validate definitions, simulate missing metabolites, and use the resulting patterns in TDFDFit.