# scope_profiler.mpi_wrappers

*module*

Opt-in profiling wrappers for ``mpi4py`` communicators and requests.

Importing this module never imports mpi4py. Pass an existing communicator to
``profile_mpi_comm``, or explicitly call ``profile_mpi4py`` to patch predefined
communicators for the duration of a run. Importing scope-profiler therefore
cannot initialize MPI in a serial process.

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

## scope_profiler.mpi_wrappers.MPIRegionMetadata

*class* · *dataclass*

```python
class MPIRegionMetadata
```

Structured metadata decoded from a Python or native MPI region name.

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

### scope_profiler.mpi_wrappers.MPIRegionMetadata.bytes

*attribute* · *instance attribute*

```python
bytes: int
```

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

### scope_profiler.mpi_wrappers.MPIRegionMetadata.communicator

*attribute* · *instance attribute*

```python
communicator: int
```

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

### scope_profiler.mpi_wrappers.MPIRegionMetadata.kind

*attribute* · *instance attribute*

```python
kind: str
```

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

### scope_profiler.mpi_wrappers.MPIRegionMetadata.operation

*attribute* · *instance attribute*

```python
operation: str
```

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

### scope_profiler.mpi_wrappers.MPIRegionMetadata.peer

*attribute* · *instance attribute*

```python
peer: int
```

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

### scope_profiler.mpi_wrappers.MPIRegionMetadata.request

*attribute* · *class attribute* · *instance attribute*

```python
request: str | None = None
```

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

### scope_profiler.mpi_wrappers.MPIRegionMetadata.root

*attribute* · *instance attribute*

```python
root: int
```

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

### scope_profiler.mpi_wrappers.MPIRegionMetadata.tag

*attribute* · *instance attribute*

```python
tag: int
```

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

## scope_profiler.mpi_wrappers.ProfiledMPIComm

*class*

```python
class ProfiledMPIComm
```

A transparent communicator proxy for common mpi4py operations.

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.communicator

*property*

```python
communicator: Any
```

The unwrapped mpi4py communicator.

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.Allreduce

*method*

```python
def Allreduce(sendbuf, recvbuf, op=None)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.Barrier

*method*

```python
def Barrier()
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.Bcast

*method*

```python
def Bcast(buf, root: int = 0)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.Irecv

*method*

```python
def Irecv(buf, source: int = -1, tag: int = -1) -> ProfiledMPIRequest
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.Isend

*method*

```python
def Isend(buf, dest: int, tag: int = 0) -> ProfiledMPIRequest
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.Recv

*method*

```python
def Recv(buf, source: int = -1, tag: int = -1, status=None)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.Reduce

*method*

```python
def Reduce(sendbuf, recvbuf, op=None, root: int = 0)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.Send

*method*

```python
def Send(buf, dest: int, tag: int = 0)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.allreduce

*method*

```python
def allreduce(sendobj, op=None)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.barrier

*method*

```python
def barrier()
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.bcast

*method*

```python
def bcast(obj, root: int = 0)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.irecv

*method*

```python
def irecv(buf=None, source: int = -1, tag: int = -1) -> ProfiledMPIRequest
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.isend

*method*

```python
def isend(obj, dest: int, tag: int = 0) -> ProfiledMPIRequest
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.recv

*method*

```python
def recv(buf=None, source: int = -1, tag: int = -1, status=None)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.reduce

*method*

```python
def reduce(sendobj, op=None, root: int = 0)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIComm.send

*method*

```python
def send(obj, dest: int, tag: int = 0)
```

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

## scope_profiler.mpi_wrappers.ProfiledMPIRequest

*class*

```python
class ProfiledMPIRequest
```

A request proxy that attributes blocking completion time to MPI wait.

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

### scope_profiler.mpi_wrappers.ProfiledMPIRequest.Wait

*method*

```python
def Wait(status=None)
```

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

### scope_profiler.mpi_wrappers.ProfiledMPIRequest.wait

*method*

```python
def wait(status=None)
```

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

## scope_profiler.mpi_wrappers.format_mpi_region

*function*

```python
def format_mpi_region(operation: str, *, bytes: int = -1, peer: int = -1, root: int = -1, tag: int = -1, communicator: int = -1, request: str | None = None) -> str
```

Return the canonical region name shared by Python and C++ wrappers.

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

## scope_profiler.mpi_wrappers.message_nbytes

*function*

```python
def message_nbytes(value: Any, *, pickle_objects: bool = True) -> int
```

Estimate payload bytes for an mpi4py object or buffer specification.

Buffer-mode calls are exact when their datatype exposes ``Get_size``.
Object-mode values use their buffer size when possible. With
``pickle_objects=True`` (the default for this explicit helper), other
objects use the size of their protocol-5 pickle. ``-1`` means unknown.

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

## scope_profiler.mpi_wrappers.parse_mpi_region

*function*

```python
def parse_mpi_region(name: str) -> MPIRegionMetadata | None
```

Decode a canonical MPI region name, or return ``None`` for another region.

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

## scope_profiler.mpi_wrappers.profile_mpi4py

*function*

```python
def profile_mpi4py(mpi_module: Any = None, *, pickle_object_sizes: bool = False, lazy: bool = False) -> Iterator[None]
```

Temporarily profile mpi4py's predefined communicators.

When *lazy* is true, mpi4py is wrapped only if the target imports it. This
lets ``scope-profiler run --mpi-calls`` enable MPI-call profiling without
importing or initializing MPI for an ordinary serial program. Both globals
and Python's import function are restored even when the program raises.

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

## scope_profiler.mpi_wrappers.profile_mpi_comm

*function*

```python
def profile_mpi_comm(communicator: Any, *, pickle_object_sizes: bool = False) -> ProfiledMPIComm
```

Wrap a communicator without importing mpi4py.

Set ``pickle_object_sizes=True`` to measure serialized object-mode payloads
at the cost of one extra serialization per call. It is off by default to
avoid overhead and repeated ``__reduce__`` side effects.

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