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()andexample_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 magnitude1 / 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’smetadata["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’smetadata["global_safety_factor"], else 1.
- Returns:
is_ok (bool) – True when every window’s largest VOP SAR is within
local_limitand, with a global matrix, its global SAR withinglobal_limit.report (SimpleNamespace) – The limits,
safety_factorandglobal_safety_factor;tr_sizeandtr_start(blocks);windows, arraysfirst,last(1-based blocks),duration(s),local_sar,vop,global_sar(W/kg) andglobal_body, and with a referencelocal_to_headandglobal_ratio, each window’s terms of the two ratios below;worst_localandworst_global, each thesar,windowand itsfirstandlastblock, or None (worst_localalso itsvopandper_vop, the SAR of every VOP in that window, andworst_globalitsbodyandper_body, every body model’s global SAR in that window); andreference, or None without one.referencecarriesheadandduration, 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 ofhead, with itsvopandwindow;local_to_head_energy, the largest of that ratio times the window’s duration over the reference’s, with itsenergy_window; andglobal_sar_ratioandglobal_energy_ratioalike 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 channelcwithdrive_c * s_c * b_c(t):bits waveform in Hz, resampled every microsecond aspypulseqpp.calc_rf_power()does (one channel’s waveform on every channel for a single-channel pulse), andsits block’s RF shim,default_shimor 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_headtimes that limit is the sequence’s local SAR at the same drive scale. The scale ofdrive_per_hzand 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 asglobal_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.