# scope_profiler.mpi_region

*module*

Container for per-rank Region data within an MPI-parallel profiling run.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L1-L1)

## scope_profiler.mpi_region.MPIRegion

*class*

```python
class MPIRegion
```

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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L11-L580)

### scope_profiler.mpi_region.MPIRegion.color

*attribute* · *instance attribute*

```python
color = None
```

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L32-L32)

### scope_profiler.mpi_region.MPIRegion.average_duration

*property*

```python
average_duration: float
```

Get 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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L328-L343)

### scope_profiler.mpi_region.MPIRegion.durations

*property*

```python
durations: np.ndarray
```

Get every recorded call duration on every rank, in seconds.

Returns
-------
np.ndarray
    Pooled durations. Empty if no rank recorded timing.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L176-L190)

### scope_profiler.mpi_region.MPIRegion.exclusive_duration

*property*

```python
exclusive_duration: float
```

Alias for :attr:`total_exclusive_duration`.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L323-L325)

### scope_profiler.mpi_region.MPIRegion.exclusive_durations

*property*

```python
exclusive_durations: np.ndarray
```

Exclusive durations pooled across ranks, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L210-L219)

### scope_profiler.mpi_region.MPIRegion.first_duration

*property*

```python
first_duration: float
```

Get 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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L473-L486)

### scope_profiler.mpi_region.MPIRegion.first_start_time

*property*

```python
first_start_time: float
```

Get 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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L505-L520)

### scope_profiler.mpi_region.MPIRegion.gpu_average_duration

*property*

```python
gpu_average_duration: float | None
```

Average CUDA-event elapsed device time across ranks, or None if absent.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L346-L357)

### scope_profiler.mpi_region.MPIRegion.gpu_durations

*property*

```python
gpu_durations: np.ndarray | None
```

CUDA-event elapsed device times pooled across ranks, or None if absent.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L193-L202)

### scope_profiler.mpi_region.MPIRegion.gpu_total_duration

*property*

```python
gpu_total_duration: float | None
```

Total CUDA-event elapsed device time across ranks, or None if absent.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L301-L310)

### scope_profiler.mpi_region.MPIRegion.has_event_data

*property*

```python
has_event_data: bool
```

Whether every represented rank has per-call timestamps loaded.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L55-L57)

### scope_profiler.mpi_region.MPIRegion.has_gpu_timing

*property*

```python
has_gpu_timing: bool
```

Whether any rank recorded CUDA-event timings for this region.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L78-L80)

### scope_profiler.mpi_region.MPIRegion.has_source

*property*

```python
has_source: bool
```

Whether any rank captured this region's call-site source.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L73-L75)

### scope_profiler.mpi_region.MPIRegion.has_timing

*property*

```python
has_timing: bool
```

Whether any rank recorded timestamps for this region.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L50-L52)

### scope_profiler.mpi_region.MPIRegion.inclusive_duration

*property*

```python
inclusive_duration: float
```

Total inclusive time across ranks, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L313-L315)

### scope_profiler.mpi_region.MPIRegion.inclusive_durations

*property*

```python
inclusive_durations: np.ndarray
```

Inclusive durations pooled across ranks, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L205-L207)

### scope_profiler.mpi_region.MPIRegion.last_duration

*property*

```python
last_duration: float
```

Get 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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L489-L502)

### scope_profiler.mpi_region.MPIRegion.last_end_time

*property*

```python
last_end_time: float
```

Get 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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L523-L538)

### scope_profiler.mpi_region.MPIRegion.max_duration

*property*

```python
max_duration: float
```

Get the maximum duration across all ranks.

Returns
-------
float
    The maximum duration among all ranks, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L455-L470)

### scope_profiler.mpi_region.MPIRegion.min_duration

*property*

```python
min_duration: float
```

Get the minimum duration across all ranks.

Returns
-------
float
    The minimum duration among all ranks, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L437-L452)

### scope_profiler.mpi_region.MPIRegion.name

*property*

```python
name: str
```

Name of the region.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L35-L37)

### scope_profiler.mpi_region.MPIRegion.num_calls

*property*

```python
num_calls: int
```

Total number of calls summed over all ranks.

Returns
-------
int
    Summed call count.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L222-L231)

### scope_profiler.mpi_region.MPIRegion.p50_duration

*property*

```python
p50_duration: float | None
```

Median duration across all ranks, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L403-L405)

### scope_profiler.mpi_region.MPIRegion.p95_duration

*property*

```python
p95_duration: float | None
```

95th-percentile duration across all ranks, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L408-L410)

### scope_profiler.mpi_region.MPIRegion.p99_duration

*property*

```python
p99_duration: float | None
```

99th-percentile duration across all ranks, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L413-L415)

### scope_profiler.mpi_region.MPIRegion.rank_imbalance

*property*

```python
rank_imbalance: float
```

Maximum 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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L418-L428)

### scope_profiler.mpi_region.MPIRegion.rank_imbalance_pct

*property*

```python
rank_imbalance_pct: float
```

Excess of the slowest rank over the mean, as a percentage.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L431-L434)

### scope_profiler.mpi_region.MPIRegion.ranks

*property*

```python
ranks: list[int]
```

Sorted list of ranks that recorded this region.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L45-L47)

### scope_profiler.mpi_region.MPIRegion.regions

*property*

```python
regions: dict[int, Region]
```

Dictionary of rank IDs to their corresponding Region objects.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L40-L42)

### scope_profiler.mpi_region.MPIRegion.source_file

*property*

```python
source_file: str | None
```

Path of the file this region is defined in, or None if not captured.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L83-L85)

### scope_profiler.mpi_region.MPIRegion.source_lineno

*property*

```python
source_lineno: int | None
```

Line the region's call site starts at, or None if not captured.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L88-L90)

### scope_profiler.mpi_region.MPIRegion.source_text

*property*

```python
source_text: str | None
```

Source text of the region's ``with`` block or decorated function.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L93-L95)

### scope_profiler.mpi_region.MPIRegion.std_duration

*property*

```python
std_duration: float
```

Get the standard deviation over every call on every rank.

Returns
-------
float
    Standard deviation in seconds, or 0.0 if no timing was recorded.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L360-L391)

### scope_profiler.mpi_region.MPIRegion.tags

*property*

```python
tags: tuple[str, ...]
```

User-defined tags attached to this region.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L98-L100)

### scope_profiler.mpi_region.MPIRegion.total_duration

*property*

```python
total_duration: float
```

Get the total duration summed over all ranks and calls.

Returns
-------
float
    Total duration in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L289-L298)

### scope_profiler.mpi_region.MPIRegion.total_exclusive_duration

*property*

```python
total_exclusive_duration: float
```

Total time excluding nested regions, across ranks, in seconds.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L318-L320)

### scope_profiler.mpi_region.MPIRegion.average_durations

*method*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L244-L253)

### scope_profiler.mpi_region.MPIRegion.events

*method*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L131-L173)

### scope_profiler.mpi_region.MPIRegion.get_summary

*method*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L102-L129)

### scope_profiler.mpi_region.MPIRegion.max_durations

*method*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L266-L275)

### scope_profiler.mpi_region.MPIRegion.min_durations

*method*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L255-L264)

### scope_profiler.mpi_region.MPIRegion.num_calls_per_rank

*method*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L233-L242)

### scope_profiler.mpi_region.MPIRegion.percentile_duration

*method*

```python
def percentile_duration(percentile: float) -> float | None
```

Return a pooled duration percentile across all ranks.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L393-L400)

### scope_profiler.mpi_region.MPIRegion.total_durations

*method*

```python
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.

[View source](https://github.com/max-models/scope-profiler/blob/devel/src/scope_profiler/mpi_region.py#L277-L286)