Power Result Types#

ProfileResult.power remains the compatible aggregate PowerResult. The following fields provide the typed execution and provenance contract for new code.

Authority rules:

• power_observation is authoritative for host-instrument integrity and GPIO evidence.
• power_terminal is authoritative for firmware completion, count, elapsed time, final phase, and error status.
• on_device_power is authoritative only for its named firmware-side monitor and fixed-N scope.
• power is the normalized compatibility aggregate used by existing callers. In external mode it reflects the host observation; in internal mode it is synthesized from on_device_power. Do not compare host and on-device energy unless their count, duration, scope, and integrity agree.

Power metadata (typed as of 0.2)#

PowerResult.metadata is the typed helia_profiler.power.metadata.PowerMetadata — a breaking change from the earlier dict[str, Any]. Every key the capture layer records is a named field, the diagnostics (sync, gate_failure, gate_duration_integrity, window_clock_ceiling, …) are their real objects rather than flattened dicts, and the vocabularies are enums (MeasurementScope, ObservationMode, PowerIntegrity).

Migrating existing code:

# before                                     # after
result.power.metadata["measurement_scope"]   result.power.metadata.measurement_scope
result.power.metadata.get("integrity")       result.power.metadata.integrity
result.power.metadata["sync"]["lockstep"]    result.power.metadata.sync.lockstep

The flat dict (exactly the shape written into summary.json) remains available as result.power.metadata.to_metadata_dict().

PowerMetadata(driver: str | None = None, device: str | None = None, io_voltage: float | None = None, gating_method: str | None = None, sync_input_index: int | None = None, stats_rate_hz: int | None = None, stats_scnt: int | None = None, window_count: int | None = None, gpi_poll_count: int | None = None, stat_packets: int | None = None, early_stopped: bool | None = None, capture_window_s: float | None = None, capture_safety_bound_s: float | None = None, short_gate_pulses_ignored: int | None = None, clean_infer_count: int | None = None, inference_count: int | None = None, source: str | None = None, measurement_scope: MeasurementScope | str | None = None, observation_mode: ObservationMode | None = None, integrity: PowerIntegrity | None = None, gate_rise_observed: bool | None = None, gate_fall_observed: bool | None = None, observation_deadline_s: float | None = None, power_firmware: str | None = None, power_plan: dict[str, Any] | None = None, sync: SyncHandshakeMetadata | None = None, sync_timing_s: GateTransitionTiming | None = None, gate_failure: GateFailure | None = None, gate_duration_integrity: GateDurationIntegrity | None = None, window_clock_ceiling: WindowClockCeiling | None = None, target_lifecycle: 'TargetLifecyclePlan | None' = None, short_gate_pulse_diagnostics: dict[str, Any] | None = None, whole_capture_summary: dict[str, Any] | None = None, fullrate_xcheck: dict[str, Any] | None = None, gating_diagnostics: dict[str, Any] | None = None, gated_vs_whole_current_ok: bool | None = None)

to_metadata_dict() -> dict[str, Any]

set_observation(*, observation_mode: ObservationMode, integrity: PowerIntegrity | str, gate_rise_observed: bool, gate_fall_observed: bool, observation_deadline_s: float) -> None

measurement_scope may hold a plain string for scopes reported by registered third-party drivers that HPX does not know; unknown scopes classify as not-gated.

Power observation#

PowerObservation(mode: ObservationMode, result: PowerResult, gate_rise_observed: bool, gate_fall_observed: bool, deadline_s: float, integrity: PowerIntegrity)

A GPIO-gated observation is valid for per-inference metrics. A free-form observation is diagnostic and carries degraded integrity.

Firmware terminal status#

PowerTerminalRecord(version: int, status: Literal['ok', 'error'], requested_count: int, completed_count: int, elapsed_us: int | None, final_phase: str, error_code: int, gate_asserted: bool, gate_lowered: bool)

This record is emitted after the measured window closes. It confirms the fixed inference count, elapsed time, final phase, error status, and GATE state.

On-device power summary#

OnDevicePowerSummary(source: str, scope: Literal['fixed_n_inference'], energy_nj: int, duration_us: int, inference_count: int, overflow: bool, charge_nc: int | None = None, bus_voltage_uv: int | None = None, calibration_id: str | None = None)

This optional payload is reserved for firmware-side monitors such as INA228. It uses integer base units and identifies the fixed-N measurement window, count, duration, overflow state, source, and calibration provenance.