check_sar

Contents

check_sar#

pypulseqpp.safety.check_sar()[source]#

Check window-averaged local and global SAR against their limits.

Parameters:
  • seq (Sequence) – Sequence to check.

  • model (VopModel) – VOPs and optional global matrices, in W/kg per unit drive squared; see read_vops() and example_vops(). With one global matrix per body model, a window’s global SAR is the largest over the models.

  • drive_per_hz (float or array_like) – Channel drive per Hz of RF amplitude, in the VOPs’ drive unit; a scalar or one value per channel.

  • local_limit (float, default=10.0) – Local SAR limit (W/kg); the default is the IEC 60601-2-33 normal-mode head limit.

  • global_limit (float, default=3.2) – Global SAR limit (W/kg); the default is the IEC 60601-2-33 normal-mode head limit.

  • default_shim (array_like, default=None) – Complex channel weights applied to a single-channel pulse in a block without an RF shim; when None, equal weights of magnitude 1 / sqrt(channels), whose squares sum to 1 as an RF shim’s do.

  • reference (Sequence or report, default=None) – What to compare with, in the same model and calibration: a sequence, such as a CP-mode FID, evaluated here with the same drive and default shim; or the report of an earlier call. Its window of largest global SAR gives the reference’s global SAR in each body model and its duration. The model needs its global matrices.

  • safety_factor (float, default=None) – Factor, at least 1, every local SAR is multiplied by; when None, the model’s metadata["safety_factor"], else 1.

  • global_safety_factor (float, default=None) – Factor, at least 1, every global SAR and global SAR ratio is multiplied by; when None, the model’s metadata["global_safety_factor"], else 1.

Returns:

  • is_ok (bool) – True when every window’s largest VOP SAR is within local_limit and, with a global matrix, its global SAR within global_limit.

  • report (SimpleNamespace) – The limits, safety_factor and global_safety_factor; tr_size and tr_start (blocks); windows, arrays first, last (1-based blocks), duration (s), local_sar, vop, global_sar (W/kg) and global_body, and with a reference local_to_head and global_ratio, each window’s terms of the two ratios below; worst_local and worst_global, each the sar, window and its first and last block, or None (worst_local also its vop and per_vop, the SAR of every VOP in that window, and worst_global its body and per_body, every body model’s global SAR in that window); and reference, or None without one.

    reference carries head and duration, the reference’s global SAR in each body model and the duration of its window; local_to_head, the largest over windows of the window’s local SAR over the smallest of head, with its vop and window; local_to_head_energy, the largest of that ratio times the window’s duration over the reference’s, with its energy_window; and global_sar_ratio and global_energy_ratio alike for global SAR, each body model’s over the reference’s in the same body model. Every window counts, a shortened last window included.

Raises:

ValueError – If a reference sequence plays nothing to compare with, the model has no global matrices to compare it through, a shim weighs a different number of channels than the model has, or a safety factor is below 1.

Notes

SAR is averaged over each window: each repetition repetition() returns, from block 1, and the blocks after the last full repetition as a shorter last window; or the whole sequence when it does not repeat. Every window is compared with the limits. A pulse drives channel c with drive_c * s_c * b_c(t): b its waveform in Hz, resampled every microsecond as pypulseqpp.calc_rf_power() does (one channel’s waveform on every channel for a single-channel pulse), and s its block’s RF shim, default_shim or equal weights whose squares sum to 1.

A window’s local SAR is the largest over the VOPs, an upper bound on its peak local SAR, times the safety factor. Where the reference is played at the global limit, local_to_head times that limit is the sequence’s local SAR at the same drive scale. The scale of drive_per_hz and of the matrices cancels in the reference ratios; relative channel gains do not, and neither do the two safety factors, which multiply only the sequence’s side: a factor on global SAR therefore enters as global_safety_factor, never as a scale on the global matrices. With a reference lasting its minimum TR, the energy ratios scale that minimum TR to this sequence’s repetition, at the energy each repetition deposits.