SAR

Specific Absorption Rate post-processing, see Specific Absorption Rate (SAR) for the concept and the file formats.

Reading SAR Results

openEMS.sar_utils.readSAR(fn, f_idx=0)

Read a SAR result HDF5 file written by SAR_Calculation.

Thin wrapper around openEMS.utilities.HDF5Dump for the common case of reading a complete SAR result.

Parameters:

fnstr: Path to the SAR result HDF5 file.
f_idxint, optional: Frequency index to read (default 0).

Returns:

sarndarray, shape (nx, ny, nz): SAR values in W/kg.
meshlist of three 1-D ndarrays: Mesh node coordinates [x, y, z] in metres. This is mesh['lines'] from HDF5Dump.GetMesh() – a deliberate simplification for the common SAR use case (always Cartesian, coordinates already in metres). For full mesh metadata (type, scaling, names), for reading only a part of a large result, or for the /CellData and /CellWidth groups of a raw SAR dump, use HDF5Dump directly.
sar_datadict: Metadata from the file: ‘mass’ (kg), ‘frequency’ (Hz), ‘power’ (W), and any other dump attributes (e.g. ‘maxSAR’, ‘dump_type’).

SAR Calculation

Computes local or mass-averaged SAR from a raw SAR dump (dump_type=29). This is the same C++ implementation the sar_calc binary uses.

class openEMS.sar_calculation.SAR_Calculation

SAR averaging and calculation.

Keyword arguments accepted by the constructor (all optional):

massfloat: Averaging mass in grams (0 = local SAR, default 0).
methodstr: Spatial averaging method: ‘SIMPLE’ (default), ‘IEEE_C95_3’, or ‘IEEE_62704’. All three average over a cubical mass; see SetAveragingMethod(). Has no effect when mass is 0.
verboseint: Debug verbosity level.
autoRangefloat: Restrict the calculation to the cells within this many dB of the peak local SAR.
EnableCubeStatsbool: Record per-cube averaging statistics in the output file.

CalcFromHDF5(h5_fn, out_name, export_cube_stats=False, numThreads=0): Read raw field data from h5_fn, run the SAR calculation, and write results to out_name. Returns True on success. numThreads=0 uses all available hardware threads.

EnableAutoRange(dBmax)

Restrict the calculation to the region around the peak.

Only the cells whose local SAR is within dBmax dB of the peak local SAR are averaged, which speeds up large meshes with a localised hot spot. The result is written on the reduced mesh, so the output covers a smaller region than the input.

The averaged SAR of a cube is the mass weighted mean of the local SAR of its cells and can never exceed the largest local SAR inside that cube. Everything that is dropped here is therefore below the threshold after averaging as well, and the region is padded by roughly one averaging cube so that cubes centred just outside it are covered too. That padding is an estimate, so this remains a speedup and not a guarantee to find the global peak. A warning is printed if the peak that was found is itself below the threshold. Do not use the auto range for standard compliance work.

Parameters:

dBmaxfloat: Range below the peak local SAR, in dB. Values <= 0 disable the auto range.

EnableCubeStats()

Record per-cell averaging cube statistics in the output file.

This exposes how the averaging cube was found for every cell and is the main handle for validating the averaging against the conformance requirements of IEC/IEEE 62704-1 – it shows which cells got a proper centred cube, which fell back to a neighbouring one, and what mass and volume each cube actually enclosed.

Three datasets are added next to the SAR result:

f{n}_CubeType (unsigned byte)

How the cube for this cell was obtained:

0 – no averaging cube; background/air, or no cube could be built
1 to 6 – second pass: the cube was built with one face pinned to the cell, 1/2 = lower/upper x face, 3/4 = y, 5/6 = z
7 – first pass: a valid cube enclosing the target mass was found centred on the cell itself
8 – the cell was covered by another cell’s cube but never got a valid cube of its own

f{n}_CubeMass

Mass actually enclosed by the cube, in kg. Compare against the requested averaging mass to check the convergence tolerance.

f{n}_CubeVol

Volume of the cube, in m^3.

Note

Cube statistics can only be recorded for a single frequency. With more than one frequency of interest the calculation prints a warning and writes no statistics.

See Specific Absorption Rate (SAR) for the averaging methods and the output format.

EnableProgress(enable)

Enable or disable the progress indicator during averaging.

Parameters:

enablebool: Averaging a large mesh can take a while; this prints how far the calculation has come.

SetAveragingMass(mass): Set averaging mass in grams (0 = local SAR).

SetAveragingMethod(method, silent=True)

Set the spatial averaging method.

All three methods perform a real cubical mass averaging: a cube is grown around each tissue cell until it encloses the averaging mass, and the SAR is the absorbed power in that cube divided by its mass. They differ only in how strictly the cube has to qualify as valid, and therefore in how many cells end up being filled in from a neighbouring cell’s cube instead:

‘SIMPLE’ (default) accepts every cube that reaches the target mass, even one clipped by the edge of the dump box, so a cube is built for essentially every tissue cell. This avoids the surface artifacts that the fill-in step can introduce, but does not follow the validity rules of the standards.
‘IEEE_C95_3’ uses the same 5% mass tolerance, but additionally requires the cube to fit inside the dump box.
‘IEEE_62704’ is the strictest: the mass has to match to within 1e-6, and no more than 10% of the cube volume may be background (air). The latter is what rejects cubes sitting on a tissue surface.

Note that this is unrelated to local SAR: an averaging mass of 0 skips the averaging entirely and the method has no effect.

Parameters:

methodstr: ‘SIMPLE’, ‘IEEE_C95_3’ or ‘IEEE_62704’.
silentbool, optional: Suppress the confirmation message printed by the C++ code.

Returns:

bool: True on success, False if the method name is unknown.