mpylab.env.tem.probe_orientation module

Field-probe orientation and coordinate transformation helpers.

The functions in this module transform measurements from probe coordinates into TEM-cell coordinates. They deliberately distinguish signed vectors and synchronous waveforms from component magnitudes: a general three-dimensional rotation cannot be reconstructed from three unsigned component magnitudes.

exception mpylab.env.tem.probe_orientation.ProbeOrientationConflictError(graph_name, candidates)

Bases: ValueError

Report contradictory orientation definitions for one field probe.

Parameters:

  • graph_name (str) – Physical field-probe node name.

  • candidates (iterable of mapping) – Normalized source and orientation entries participating in the conflict.

graph_name

Physical field-probe node name.

Type:

str

candidates

Normalized source and orientation entries participating in the conflict.

Type:

tuple of dict

mpylab.env.tem.probe_orientation.format_probe_orientation_preflight(graph_name, orientation, source='default')

Return a readable preflight summary for one probe orientation.

Parameters:

  • graph_name (str) – Physical field-probe node name.

  • orientation (mapping, str, or None) – Orientation accepted by parse_probe_orientation().

  • source (str, optional) – Configuration source shown in the summary.

Returns:

Multiline orientation and cell-from-probe matrix summary.

Return type:

str

mpylab.env.tem.probe_orientation.map_probe_field_vector(data, orientation=None, *, data_kind='signed_vector')

Map a three-axis field reading into cell coordinates.

Parameters:

  • data (sequence of Quantity or float) – Probe x-, y-, and z-axis field components.

  • orientation (mapping, str, or None, optional) – Probe orientation accepted by parse_probe_orientation().

  • data_kind ({"signed_vector", "component_magnitudes"}, optional) – signed_vector applies the complete rotation matrix. For component_magnitudes only an axis permutation is physically identifiable; signs are ignored and general rotations are rejected.

Returns:

cell_x, cell_y, and cell_z field quantities.

Return type:

dict

mpylab.env.tem.probe_orientation.map_probe_field_waveform(data, orientation=None)

Rotate synchronous signed probe waveforms into cell coordinates.

Parameters:

  • data (sequence of three array-like objects) – Synchronous signed samples for probe x, y, and z. All arrays must have equal one-dimensional shapes.

  • orientation (mapping, str, or None, optional) – Probe orientation accepted by parse_probe_orientation().

Returns:

Arrays for cell_x, cell_y, and cell_z.

Return type:

dict

mpylab.env.tem.probe_orientation.mapped_probe_reading(value, orientation, *, data_kind='signed_vector')

Return cell-axis and unchanged probe-axis values for one reading.

Parameters:

  • value (sequence of Quantity or float) – Probe x-, y-, and z-axis field components.

  • orientation (mapping, str, or None) – Probe orientation accepted by parse_probe_orientation().

  • data_kind ({"signed_vector", "component_magnitudes"}, optional) – Physical interpretation of the three input components.

Returns:

Transformed cell-coordinate vector followed by the unchanged probe vector.

Return type:

tuple of (list, list)

mpylab.env.tem.probe_orientation.normalize_probe_orientation(orientation=None)

Return the normalized representation of a probe orientation.

Parameters:

orientation (mapping, str, or None, optional) – Signed axis map, rotation matrix, or fixed-cell-axis rotation angles.

Returns:

Signed axis map for a permutation, otherwise a normalized rotation matrix mapping probe coordinates to cell coordinates.

Return type:

dict

mpylab.env.tem.probe_orientation.parse_probe_axis_map(axis_map=None)

Parse a complete signed mapping from probe axes to cell axes.

Parameters:

axis_map (mapping of str to str, optional) – Mapping for cell_x, cell_y, and cell_z. Values use signed probe-axis expressions such as +probe_y or -probe_x.

Returns:

Parsed probe-axis index, sign, and normalized expression for every cell axis.

Return type:

dict

mpylab.env.tem.probe_orientation.parse_probe_orientation(orientation=None)

Parse a field-probe orientation into a cell-from-probe matrix.

Parameters:

orientation (mapping, str, or None, optional) – Signed axis map, rotation matrix, or fixed-cell-axis rotation angles. None selects DEFAULT_PROBE_AXIS_MAP.

Returns:

Rotation matrix, an axis_map when the rotation is a signed permutation, and its normalized representation.

Return type:

dict

mpylab.env.tem.probe_orientation.resolve_field_probe_orientations(measurement_graph, probe_names, config_probe_orientations=None)

Resolve orientations independently for multiple physical probes.

Parameters:

  • measurement_graph (mpylab.tools.mgraph.MGraph or compatible object) – Graph containing all requested field-probe nodes.

  • probe_names (iterable of str or str) – Physical field-probe node names.

  • config_probe_orientations (mapping, optional) – Per-node or direct application orientation.

Returns:

Resolution result from resolve_probe_orientation() for every physical probe node.

Return type:

dict

mpylab.env.tem.probe_orientation.resolve_probe_orientation(measurement_graph, graph_name, config_probe_orientations=None)

Resolve one physical field probe’s orientation and source.

Parameters:

  • measurement_graph (mpylab.tools.mgraph.MGraph or compatible object) – Graph containing the field-probe node, DOT attributes, and parsed INI sections.

  • graph_name (str) – Physical field-probe node name.

  • config_probe_orientations (mapping, optional) – Per-node or direct orientation supplied by the application.

Returns:

orientation contains the normalized mapping or matrix, source identifies the selected source, and candidates retains all agreeing explicit definitions.

Return type:

dict

Raises:

ProbeOrientationConflictError – If explicit sources define different normalized orientations.