scope_profiler.mpi_region
Container for per-rank Region data within an MPI-parallel profiling run.
Classes
| Name | Description |
|---|---|
MPIRegion | One named region across all ranks that recorded it. |
MPIRegionclass#
class MPIRegion(name: str, regions: dict[int, Region])One named region across all ranks that recorded it.
Indexing gives the per-rank :class:~scope_profiler.region.Region
(region[0]), while the properties on this class aggregate over every
rank. All durations are in seconds.
average_durationproperty#
average_duration: floatGet the mean duration over every call on every rank.
Note this pools all calls, so ranks with more calls weigh more heavily;
use average_durations() for the per-rank breakdown.
Returns
float Average duration in seconds, or 0.0 if no timing was recorded.
durationsproperty#
durations: np.ndarrayGet every recorded call duration on every rank, in seconds.
Returns
np.ndarray Pooled durations. Empty if no rank recorded timing.
exclusive_durationproperty#
exclusive_duration: floatAlias for :attr:total_exclusive_duration.
exclusive_durationsproperty#
exclusive_durations: np.ndarrayExclusive durations pooled across ranks, in seconds.
first_durationproperty#
first_duration: floatGet the duration of the call that started earliest across all ranks.
Returns
float Duration in seconds of the chronologically first call, or 0.0 if no rank recorded timing.
first_start_timeproperty#
first_start_time: floatGet the earliest start time across all ranks.
Returns
float The earliest start time among all ranks, in seconds, or 0.0 if no rank recorded timing.
gpu_average_durationproperty#
gpu_average_duration: float | NoneAverage CUDA-event elapsed device time across ranks, or None if absent.
gpu_durationsproperty#
gpu_durations: np.ndarray | NoneCUDA-event elapsed device times pooled across ranks, or None if absent.
gpu_total_durationproperty#
gpu_total_duration: float | NoneTotal CUDA-event elapsed device time across ranks, or None if absent.
has_event_dataproperty#
has_event_data: boolWhether every represented rank has per-call timestamps loaded.
has_gpu_timingproperty#
has_gpu_timing: boolWhether any rank recorded CUDA-event timings for this region.
has_sourceproperty#
has_source: boolWhether any rank captured this region’s call-site source.
has_timingproperty#
has_timing: boolWhether any rank recorded timestamps for this region.
inclusive_durationproperty#
inclusive_duration: floatTotal inclusive time across ranks, in seconds.
inclusive_durationsproperty#
inclusive_durations: np.ndarrayInclusive durations pooled across ranks, in seconds.
last_durationproperty#
last_duration: floatGet the duration of the call that ended latest across all ranks.
Returns
float Duration in seconds of the chronologically last call, or 0.0 if no rank recorded timing.
last_end_timeproperty#
last_end_time: floatGet the latest end time across all ranks.
Returns
float The latest end time among all ranks, in seconds, or 0.0 if no rank recorded timing.
max_durationproperty#
max_duration: floatGet the maximum duration across all ranks.
Returns
float The maximum duration among all ranks, in seconds.
min_durationproperty#
min_duration: floatGet the minimum duration across all ranks.
Returns
float The minimum duration among all ranks, in seconds.
nameproperty#
name: strName of the region.
num_callsproperty#
num_calls: intTotal number of calls summed over all ranks.
Returns
int Summed call count.
p50_durationproperty#
p50_duration: float | NoneMedian duration across all ranks, in seconds.
p95_durationproperty#
p95_duration: float | None95th-percentile duration across all ranks, in seconds.
p99_durationproperty#
p99_duration: float | None99th-percentile duration across all ranks, in seconds.
rank_imbalanceproperty#
rank_imbalance: floatMaximum per-rank total divided by the mean per-rank total.
A value of 1.0 means perfectly balanced ranks. Values are 0.0
when no calls were recorded or only one rank has timing data.
rank_imbalance_pctproperty#
rank_imbalance_pct: floatExcess of the slowest rank over the mean, as a percentage.
ranksproperty#
ranks: list[int]Sorted list of ranks that recorded this region.
regionsproperty#
regions: dict[int, Region]Dictionary of rank IDs to their corresponding Region objects.
source_fileproperty#
source_file: str | NonePath of the file this region is defined in, or None if not captured.
source_linenoproperty#
source_lineno: int | NoneLine the region’s call site starts at, or None if not captured.
source_textproperty#
source_text: str | NoneSource text of the region’s with block or decorated function.
std_durationproperty#
std_duration: floatGet the standard deviation over every call on every rank.
Returns
float Standard deviation in seconds, or 0.0 if no timing was recorded.
tagsproperty#
tags: tuple[str, ...]User-defined tags attached to this region.
total_durationproperty#
total_duration: floatGet the total duration summed over all ranks and calls.
Returns
float Total duration in seconds.
total_exclusive_durationproperty#
total_exclusive_duration: floatTotal time excluding nested regions, across ranks, in seconds.
average_durationsmethod#
def average_durations() -> dict[int, float]Get the average duration for each rank.
Returns
Dict[int, float] Dictionary mapping rank IDs to their average durations.
eventsmethod#
def events(ranks: list[int] | int | None = None, origin: float = 0.0) -> list[dict[str, Any]]Return one dict per recorded call, on every rank.
This is the long-form view custom plots and dataframes want: each entry is a single call rather than a per-region aggregate.
Parameters
ranks : list of int or int, optional
Restrict to these ranks (default: all ranks that recorded the
region). Ranks without data for this region are skipped.
origin : float, optional
Seconds subtracted from every timestamp, so passing
results.minimum_start_time yields a timeline starting at zero
(default: 0.0, i.e. raw timestamps).
Returns
list of dict
Entries with keys name, rank, call_index, start,
end and duration, in seconds, ordered by rank and then by
call order.
get_summarymethod#
def get_summary() -> dict[str, Any]Return statistics aggregated over every rank.
Returns
Dict[str, Any] Dictionary with name, num_ranks, num_calls (summed over ranks) and duration statistics in seconds, pooled over all calls on all ranks.
max_durationsmethod#
def max_durations() -> dict[int, float]Get the maximum duration for each rank.
Returns
Dict[int, float] Dictionary mapping rank IDs to their maximum durations.
min_durationsmethod#
def min_durations() -> dict[int, float]Get the minimum duration for each rank.
Returns
Dict[int, float] Dictionary mapping rank IDs to their minimum durations.
num_calls_per_rankmethod#
def num_calls_per_rank() -> dict[int, int]Get the call count for each rank.
Returns
Dict[int, int] Dictionary mapping rank IDs to their call counts.
percentile_durationmethod#
def percentile_duration(percentile: float) -> float | NoneReturn a pooled duration percentile across all ranks.
total_durationsmethod#
def total_durations() -> dict[int, float]Get the total duration for each rank.
Returns
Dict[int, float] Dictionary mapping rank IDs to their total durations.