# scope_profiler.profile_config

*module*

Configuration for profiling managers.

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

## scope_profiler.profile_config.tomllib

*attribute* · *module attribute*

```python
tomllib = _tomllib
```

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

## scope_profiler.profile_config.GPUOptions

*class* · *dataclass*

```python
class GPUOptions(_OptionGroup)
```

Bases: `scope_profiler.profile_config._OptionGroup`

GPU timing and NVTX settings, as a group.

In a TOML config file this is the ``[profiling.gpu]`` table.

Attributes
----------
timing : bool or None
    Record CUDA-event elapsed device time per region
    (``use_gpu_timing``).
backend : str, object, or None
    CUDA-event backend (``gpu_timing_backend``): ``"auto"``, ``"torch"``,
    ``"cupy"``, or an object implementing ``record_event()`` and
    ``elapsed_time_ns(start_event, end_event)``.
sync_on_exit : bool or None
    Synchronize the device at region exit (``gpu_sync_on_exit``).
    Requires timing and removes CPU/GPU overlap; disabled by default.
nvtx : bool or None
    Emit NVTX ranges for NVIDIA Nsight tools (``use_nvtx``).

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

### scope_profiler.profile_config.GPUOptions.backend

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

```python
backend: Any = None
```

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

### scope_profiler.profile_config.GPUOptions.nvtx

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

```python
nvtx: bool | None = None
```

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

### scope_profiler.profile_config.GPUOptions.sync_on_exit

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

```python
sync_on_exit: bool | None = None
```

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

### scope_profiler.profile_config.GPUOptions.timing

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

```python
timing: bool | None = None
```

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

### scope_profiler.profile_config.GPUOptions.to_kwargs

*method*

```python
def to_kwargs() -> dict
```

Inherited from: `scope_profiler.profile_config._OptionGroup`

This group's explicitly-set fields, under their flat names.

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

## scope_profiler.profile_config.HDF5Options

*class* · *dataclass*

```python
class HDF5Options(_OptionGroup)
```

Bases: `scope_profiler.profile_config._OptionGroup`

HDF5 storage settings, as a group.

In a TOML config file this is the ``[profiling.hdf5]`` table.

Attributes
----------
compression : str or None
    Compression filter for timestamp and GPU-duration datasets
    (``hdf5_compression``): ``"gzip"``, ``"lzf"``, ``"zstd"``, or
    ``"auto"`` to compress only runs large enough to repay the write CPU.
compression_level : int or None
    GZIP level 0--9 or Zstandard level 1--22
    (``hdf5_compression_level``).
chunk_size : int or None
    Maximum events per dataset chunk (``hdf5_chunk_size``). Enables
    chunked partial reads even without compression.

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

### scope_profiler.profile_config.HDF5Options.chunk_size

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

```python
chunk_size: int | None = None
```

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

### scope_profiler.profile_config.HDF5Options.compression

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

```python
compression: str | None = None
```

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

### scope_profiler.profile_config.HDF5Options.compression_level

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

```python
compression_level: int | None = None
```

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

### scope_profiler.profile_config.HDF5Options.to_kwargs

*method*

```python
def to_kwargs() -> dict
```

Inherited from: `scope_profiler.profile_config._OptionGroup`

This group's explicitly-set fields, under their flat names.

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

## scope_profiler.profile_config.MemrayOptions

*class* · *dataclass*

```python
class MemrayOptions(_OptionGroup)
```

Bases: `scope_profiler.profile_config._OptionGroup`

Memray capture settings, as a group.

``ProfilingOptions(memray=MemrayOptions(enabled=True, native_traces=True))``
configures the same run as ``ProfilingOptions(use_memray=True,
memray_native_traces=True)``; use whichever reads better at the call
site. In a TOML config file the group is the ``[profiling.memray]``
table.

Attributes
----------
enabled : bool or None
    Record process-wide allocations with Memray (``use_memray``).
path : str or None
    Capture path (``memory_profile_path``); defaults to
    ``<file-stem>.memray.bin``.
native_traces : bool or None
    Capture native stack frames (``memray_native_traces``).
trace_python_allocators : bool or None
    Trace Python's own allocators (``memray_trace_python_allocators``).
    Creates much larger traces and has materially higher overhead.
follow_fork : bool or None
    Keep tracking across ``fork()`` (``memray_follow_fork``).

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

### scope_profiler.profile_config.MemrayOptions.enabled

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

```python
enabled: bool | None = None
```

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

### scope_profiler.profile_config.MemrayOptions.follow_fork

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

```python
follow_fork: bool | None = None
```

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

### scope_profiler.profile_config.MemrayOptions.native_traces

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

```python
native_traces: bool | None = None
```

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

### scope_profiler.profile_config.MemrayOptions.path

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

```python
path: str | None = None
```

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

### scope_profiler.profile_config.MemrayOptions.trace_python_allocators

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

```python
trace_python_allocators: bool | None = None
```

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

### scope_profiler.profile_config.MemrayOptions.to_kwargs

*method*

```python
def to_kwargs() -> dict
```

Inherited from: `scope_profiler.profile_config._OptionGroup`

This group's explicitly-set fields, under their flat names.

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

## scope_profiler.profile_config.ProfilingConfig

*class*

```python
class ProfilingConfig
```

Configuration for one profiling manager.

This class centralizes configuration for LIKWID performance counters,
buffer limits, and file paths. Each manager owns a separate instance, so
independently configured profiling sessions can coexist. Constructing it
is purely local: it reads the communicator for rank and size but issues no
MPI call of its own, so ``setup()`` does not have to be collective.

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

### scope_profiler.profile_config.ProfilingConfig.aggregation_mode

*property*

```python
aggregation_mode: bool
```

Whether regions retain aggregates instead of individual events.

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

### scope_profiler.profile_config.ProfilingConfig.buffer_limit

*property*

```python
buffer_limit: int
```

Initial per-region buffer capacity; buffers grow beyond it as needed.

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

### scope_profiler.profile_config.ProfilingConfig.capture_region_source

*property*

```python
capture_region_source: bool
```

Return whether a region's defining source is captured at creation.

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

### scope_profiler.profile_config.ProfilingConfig.comm

*property*

```python
comm: Intercomm | None
```

MPI communicator or None if MPI is unavailable.

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

### scope_profiler.profile_config.ProfilingConfig.deactivate_file_output

*property*

```python
deactivate_file_output: bool
```

Return whether the run writes no HDF5 file at all.

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

### scope_profiler.profile_config.ProfilingConfig.deactivate_profiling

*property*

```python
deactivate_profiling: bool
```

Return whether profiling is globally turned off.

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

### scope_profiler.profile_config.ProfilingConfig.enable_tags

*property*

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

Opt-in region tags this run records, or an empty tuple.

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

### scope_profiler.profile_config.ProfilingConfig.file_path

*property*

```python
file_path: str
```

Global output file path for combined profiling data.

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

### scope_profiler.profile_config.ProfilingConfig.gpu_sync_on_exit

*property*

```python
gpu_sync_on_exit: bool
```

Whether GPU regions wait for the device before recording CPU end time.

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

### scope_profiler.profile_config.ProfilingConfig.gpu_timing_backend

*property*

```python
gpu_timing_backend
```

CUDA-event timing backend selector or backend object.

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

### scope_profiler.profile_config.ProfilingConfig.hdf5_chunk_size

*property*

```python
hdf5_chunk_size: int | None
```

Maximum number of events per timestamp chunk.

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

### scope_profiler.profile_config.ProfilingConfig.hdf5_compression

*property*

```python
hdf5_compression: str | None
```

Compression filter used for timestamp datasets.

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

### scope_profiler.profile_config.ProfilingConfig.hdf5_compression_level

*property*

```python
hdf5_compression_level: int | None
```

Configured GZIP or Zstandard compression level.

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

### scope_profiler.profile_config.ProfilingConfig.label

*property*

```python
label: str | None
```

Short name for this run, or None if none was given to ``setup()``.

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

### scope_profiler.profile_config.ProfilingConfig.memory_profile_path

*property*

```python
memory_profile_path: Path | None
```

Memray capture path, or None when allocation profiling is off.

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

### scope_profiler.profile_config.ProfilingConfig.metadata

*property*

```python
metadata: dict
```

Environment metadata collected on this rank (hostname, OpenMP threads, ...).

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

### scope_profiler.profile_config.ProfilingConfig.metadata_detail

*property*

```python
metadata_detail: str
```

``"full"`` or ``"minimal"``: how much environment metadata is recorded.

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

### scope_profiler.profile_config.ProfilingConfig.output_mode

*property*

```python
output_mode: str
```

MPI HDF5 output strategy: auto, direct, or parallel.

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

### scope_profiler.profile_config.ProfilingConfig.paused

*property*

```python
paused: bool
```

Whether runtime timing collection is temporarily suspended.

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

### scope_profiler.profile_config.ProfilingConfig.perf_events

*property*

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

Requested Linux perf event names, or an empty tuple when disabled.

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

### scope_profiler.profile_config.ProfilingConfig.profile_mpi_calls

*property*

```python
profile_mpi_calls: bool
```

Whether mpi4py communicator operations are profiled.

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

### scope_profiler.profile_config.ProfilingConfig.recursive_profile

*property*

```python
recursive_profile: bool
```

Return whether recursive decorator profiling is enabled by default.

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

### scope_profiler.profile_config.ProfilingConfig.start_time_ns

*property*

```python
start_time_ns: int
```

The run's start time (ns, ``perf_counter_ns`` clock).

The moment the configuration was created. Persisted as metadata and
used as the timeline origin when reading the results back.

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

### scope_profiler.profile_config.ProfilingConfig.track_async

*property*

```python
track_async: bool
```

Whether every call records its asyncio task or greenlet.

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

### scope_profiler.profile_config.ProfilingConfig.track_threads

*property*

```python
track_threads: bool
```

Whether every call records the thread it ran on.

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

### scope_profiler.profile_config.ProfilingConfig.tracker

*property*

```python
tracker
```

This run's :class:`~scope_profiler.concurrency.ConcurrencyTracker`.

None unless ``track_threads`` is set, which is what keeps the default
configuration free of any thread, asyncio or greenlet hook.

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

### scope_profiler.profile_config.ProfilingConfig.use_gpu_timing

*property*

```python
use_gpu_timing: bool
```

Return whether CUDA-event GPU timing is enabled.

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

### scope_profiler.profile_config.ProfilingConfig.use_likwid

*property*

```python
use_likwid: bool
```

Return whether LIKWID profiling is enabled.

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

### scope_profiler.profile_config.ProfilingConfig.use_line_profiler

*property*

```python
use_line_profiler: bool
```

Return whether line_profiler profiling is enabled.

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

### scope_profiler.profile_config.ProfilingConfig.use_memray

*property*

```python
use_memray: bool
```

Return whether Memray allocation profiling is enabled.

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

### scope_profiler.profile_config.ProfilingConfig.use_nvtx

*property*

```python
use_nvtx: bool
```

Return whether NVTX annotations are enabled.

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

### scope_profiler.profile_config.ProfilingConfig.collect_likwid_results

*method*

```python
def collect_likwid_results(region_names) -> list
```

Close the LIKWID markers and return the run's counter results.

Tries three sources, richest first, so a host where LIKWID cannot do
the fancy parts still ends up with real numbers in the HDF5 file:

1. the perfmon read-back, run in a subprocess because it can crash
   the interpreter outright on hosts that cannot really count;
2. LIKWID's marker file, parsed directly --- real values, but no
   event names or derived metrics;
3. a marker-API snapshot taken before the markers were closed, for
   when there is no marker file at all.

See :mod:`scope_profiler.likwid_data` for why the first one is fenced
off.

Parameters
----------
region_names : iterable of str
    Region names to snapshot via the marker API.

Returns
-------
list of scope_profiler.likwid_data.LikwidRegionResult
    Empty when LIKWID is disabled, the process was not started under
    ``likwid-perfctr -m`` / ``likwid-mpirun -marker``, or the markers
    were already collected.

Notes
-----
A process can only do this once. Closing the markers tears the marker
API down, and querying it afterwards crashes the interpreter rather
than raising, so a second ``finalize()`` returns nothing instead of
reading again. The counters of the whole process therefore end up in
the file written by the *first* ``finalize()``.

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

### scope_profiler.profile_config.ProfilingConfig.likwid_environment

*method*

```python
def likwid_environment() -> dict
```

Return the ``LIKWID_*`` environment variables of this process.

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

### scope_profiler.profile_config.ProfilingConfig.pylikwid_markerclose

*method*

```python
def pylikwid_markerclose()
```

Close LIKWID markers to finalize measurement regions.

Idempotent: repeated calls (a second ``finalize()``, say) do nothing.

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

### scope_profiler.profile_config.ProfilingConfig.pylikwid_markerinit

*method*

```python
def pylikwid_markerinit()
```

Initialize LIKWID markers if LIKWID is enabled.

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

### scope_profiler.profile_config.ProfilingConfig.reset

*method* · *classmethod*

```python
def reset()
```

Compatibility no-op retained for callers of older releases.

Configurations are ordinary per-manager objects now, so there is no
process-wide instance to reset.

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

### scope_profiler.profile_config.ProfilingConfig.stop_memory_profiling

*method*

```python
def stop_memory_profiling() -> None
```

Finish Memray's process-wide allocation capture, if enabled.

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

## scope_profiler.profile_config.ProfilingOptions

*class* · *dataclass*

```python
class ProfilingOptions
```

A bag of :meth:`ProfileManager.setup` settings, to reuse or pass around.

Every field mirrors a ``setup()``/``session()`` keyword argument and
defaults to ``None``, meaning "unset - let ``setup()``'s own default, or
its ``config_path`` file, decide". Pass one to ``setup()`` or
``session()`` instead of repeating the same handful of keyword arguments
at every call site::

    options = ProfilingOptions(use_likwid=True, file_path="run.h5")
    ProfileManager.setup(options=options)
    # ... or, equivalently:
    with ProfileManager.session(options=options):
        ...

An explicit keyword argument passed alongside ``options`` still wins over
the same field on ``options``, so a shared ``ProfilingOptions`` can be
reused across runs with one-off overrides::

    ProfileManager.setup(options=options, file_path="run_b.h5")

Settings that share a prefix can also be given as groups --
:class:`MemrayOptions`, :class:`GPUOptions` and :class:`HDF5Options` --
which spell the same settings without the prefix::

    options = ProfilingOptions(
        file_path="run.h5",
        hdf5=HDF5Options(compression="gzip", compression_level=4),
    )

Setting one thing both ways raises ``ValueError`` rather than picking a
winner.

Attributes
----------
file_path : str or None
    Path to the output profiling data file (default:
    ``"profiling_data.h5"``).
label : str or None
    Short name for this run (default: None, i.e. the output file's
    stem). Post-processing uses it wherever a run has to be named --
    chart legends, the summary heading, ``scope-profiler inspect``, the
    JSON statistics - and it is stored in the output file as the
    ``label`` metadata field, so it survives into every later
    post-processing step.
use_likwid : bool or None
    Enable LIKWID hardware counter collection (default: False).
perf_events : sequence of str or None
    Linux ``perf_event_open`` events to collect per region (default: None).
use_line_profiler : bool or None
    Enable line-by-line profiling via line_profiler (default: False).
use_memray : bool or None
    Record process-wide memory allocations with Memray (default: False).
deactivate_profiling : bool or None
    Turn profiling off entirely (``setup()`` default: False). Every
    region becomes a no-op, so the instrumentation can stay in the code
    at near-zero cost instead of being removed.
use_nvtx : bool or None
    Add NVTX ranges to profiled regions for NVIDIA Nsight tools
    (default: False). Requires ``scope-profiler[nvtx]``.
use_gpu_timing : bool or None
    Record CUDA-event elapsed device time for each profiled region
    (default: False). CPU timestamps are still recorded, so the normal
    timeline remains enqueue-side timing.
gpu_sync_on_exit : bool or None
    Wait for the GPU device at region exit. Requires ``use_gpu_timing``
    and removes CPU/GPU overlap; disabled by default.
gpu_timing_backend : str, object, or None
    CUDA-event backend for ``use_gpu_timing``: ``"auto"``, ``"torch"``,
    ``"cupy"``, or a custom object implementing ``record_event()`` and
    ``elapsed_time_ns(start_event, end_event)`` (default: ``"auto"``).
deactivate_file_output : bool or None
    Write no HDF5 file at all (default: False), not even the run
    metadata. Pair it with ``finalize(return_results=True)`` to analyse a
    run entirely in memory.
recursive_profile : bool or None
    Enable recursive profiling for all decorated functions by default
    (default: False). Overridable per decorator with
    ``@ProfileManager.profile(..., recursive=...)``.
aggregation_mode : bool or None
    Record only count, inclusive total, minimum, maximum, and exclusive
    total per region (default: False). Timeline events are unavailable
    in this mode; it cannot be combined with line, GPU, NVTX, or LIKWID
    profiling.
profile_mpi_calls : bool or None
    Profile mpi4py operations made through predefined or derived
    communicators (default: False). mpi4py remains lazily imported.
track_threads : bool or None
    Record which thread each call ran on, and describe every thread the
    run touched (default: False). Required for correct results from
    concurrently used regions; see
    :class:`~scope_profiler.region_profiler.ThreadedProfileRegion`.
track_async : bool or None
    Also record which asyncio task or greenlet each call ran in, and how
    much of the call was spent awaiting (default: False). Implies
    ``track_threads``.
capture_region_source : bool or None
    Record where each region is defined - the ``with`` block or the
    decorated function - once per distinct source file, the first time
    any of its regions is created (default: False). See
    :attr:`~scope_profiler.region.Region.source_text`. Off by default:
    the cost tracks that file's total size (one ``ast.parse`` + tree
    walk), so it stays under a millisecond for a typical file but can
    reach tenths of a second per rank for a single file with thousands
    of lines, paid independently by every rank.
metadata_detail : {"minimal", "full"} or None
    How much of the run's environment is recorded (default:
    ``"minimal"``). ``"minimal"`` stores versions, platform, CPU model
    and thread/rank counts, and each region's and line profile's source
    file relative to the working directory (or by name alone, outside
    it). ``"full"`` adds the user name, host name, working directory,
    loaded modules, environment variables such as ``PATH`` and
    ``VIRTUAL_ENV``, ``SLURM_*`` variables and absolute source paths;
    opt into it for runs that stay on the machine they were recorded on.
buffer_limit : int or None
    Initial number of profiling events preallocated per region (default:
    1024). Buffers grow on demand, so this is a starting size rather
    than a limit; raise it for very hot regions to avoid repeated
    reallocation.
output_mode : str or None
    MPI file writer: ``"auto"``, ``"direct"``, or ``"parallel"``
    (default: ``"auto"``). ``auto`` prefers MPI-enabled h5py when
    compatible with the active instrumentation and otherwise lets ranks
    append directly to one serial-HDF5 file in token order.
hdf5_compression : str or None
    Compression filter for timestamp and GPU-duration datasets:
    ``None``, ``"auto"``, ``"gzip"``, ``"lzf"``, or ``"zstd"``
    (default: None). ``"auto"`` compresses at publication time, and only
    when the run is large enough for the saving to repay the write CPU.
hdf5_compression_level : int or None
    GZIP level 0--9 or Zstandard level 1--22 (default: None).
hdf5_chunk_size : int or None
    Maximum events per dataset chunk (default: None). Enables chunked
    partial reads even without compression.
enable_tags : sequence of str or None
    Opt-in region tags to record (default: None). Regions carrying a tag
    registered with :meth:`ProfileManager.register_opt_in_tag` - typically
    a library's own instrumentation - stay disabled unless one of their
    opt-in tags is listed here, in ``region_tags``, or in the
    comma-separated ``SCOPE_PROFILER_ENABLE_TAGS`` environment variable.
    ``"*"`` enables every opt-in tag.
memray : MemrayOptions or None
    The ``use_memray``/``memory_profile_path``/``memray_*`` settings as
    one group.
gpu : GPUOptions or None
    The ``use_gpu_timing``/``gpu_timing_backend``/``use_nvtx`` settings
    as one group.
hdf5 : HDF5Options or None
    The ``hdf5_*`` settings as one group.

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

### scope_profiler.profile_config.ProfilingOptions.aggregation_mode

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

```python
aggregation_mode: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.buffer_limit

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

```python
buffer_limit: int | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.capture_region_source

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

```python
capture_region_source: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.deactivate_file_output

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

```python
deactivate_file_output: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.deactivate_profiling

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

```python
deactivate_profiling: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.enable_tags

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

```python
enable_tags: list[str] | tuple[str, ...] | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.file_path

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

```python
file_path: str | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.gpu

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

```python
gpu: GPUOptions | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.gpu_sync_on_exit

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

```python
gpu_sync_on_exit: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.gpu_timing_backend

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

```python
gpu_timing_backend: Any = None
```

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

### scope_profiler.profile_config.ProfilingOptions.hdf5

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

```python
hdf5: HDF5Options | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.hdf5_chunk_size

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

```python
hdf5_chunk_size: int | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.hdf5_compression

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

```python
hdf5_compression: str | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.hdf5_compression_level

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

```python
hdf5_compression_level: int | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.label

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

```python
label: str | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.memory_profile_path

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

```python
memory_profile_path: str | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.memray

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

```python
memray: MemrayOptions | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.memray_follow_fork

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

```python
memray_follow_fork: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.memray_native_traces

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

```python
memray_native_traces: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.memray_trace_python_allocators

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

```python
memray_trace_python_allocators: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.metadata_detail

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

```python
metadata_detail: str | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.output_mode

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

```python
output_mode: str | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.perf_events

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

```python
perf_events: list[str] | tuple[str, ...] | str | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.profile_mpi_calls

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

```python
profile_mpi_calls: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.recursive_profile

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

```python
recursive_profile: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.track_async

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

```python
track_async: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.track_threads

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

```python
track_threads: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.use_gpu_timing

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

```python
use_gpu_timing: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.use_likwid

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

```python
use_likwid: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.use_line_profiler

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

```python
use_line_profiler: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.use_memray

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

```python
use_memray: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.use_nvtx

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

```python
use_nvtx: bool | None = None
```

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

### scope_profiler.profile_config.ProfilingOptions.to_kwargs

*method*

```python
def to_kwargs() -> dict
```

This options' explicitly-set fields, as ``setup()`` keyword arguments.

Group fields are expanded to the flat names they stand for. Setting
the same thing both ways raises ``ValueError`` rather than picking a
winner.

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

## scope_profiler.profile_config.SetupOptions

*class*

```python
class SetupOptions(TypedDict)
```

Bases: `TypedDict`

The keyword names :meth:`ProfileManager.setup` accepts, for typing.

``setup()`` and ``session()`` take their settings as ``**overrides``
rather than restating 28 keyword parameters, so this is what gives type
checkers and editors the names and types of those keywords. It mirrors
:class:`ProfilingOptions` exactly - ``test_setup_options_match_fields``
fails the build if the two ever drift.

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

### scope_profiler.profile_config.SetupOptions.aggregation_mode

*attribute* · *instance attribute*

```python
aggregation_mode: bool
```

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

### scope_profiler.profile_config.SetupOptions.buffer_limit

*attribute* · *instance attribute*

```python
buffer_limit: int
```

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

### scope_profiler.profile_config.SetupOptions.capture_region_source

*attribute* · *instance attribute*

```python
capture_region_source: bool
```

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

### scope_profiler.profile_config.SetupOptions.deactivate_file_output

*attribute* · *instance attribute*

```python
deactivate_file_output: bool
```

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

### scope_profiler.profile_config.SetupOptions.deactivate_profiling

*attribute* · *instance attribute*

```python
deactivate_profiling: bool
```

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

### scope_profiler.profile_config.SetupOptions.enable_tags

*attribute* · *instance attribute*

```python
enable_tags: list[str] | tuple[str, ...]
```

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

### scope_profiler.profile_config.SetupOptions.file_path

*attribute* · *instance attribute*

```python
file_path: str
```

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

### scope_profiler.profile_config.SetupOptions.gpu_sync_on_exit

*attribute* · *instance attribute*

```python
gpu_sync_on_exit: bool
```

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

### scope_profiler.profile_config.SetupOptions.gpu_timing_backend

*attribute* · *instance attribute*

```python
gpu_timing_backend: Any
```

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

### scope_profiler.profile_config.SetupOptions.hdf5_chunk_size

*attribute* · *instance attribute*

```python
hdf5_chunk_size: int
```

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

### scope_profiler.profile_config.SetupOptions.hdf5_compression

*attribute* · *instance attribute*

```python
hdf5_compression: str
```

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

### scope_profiler.profile_config.SetupOptions.hdf5_compression_level

*attribute* · *instance attribute*

```python
hdf5_compression_level: int
```

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

### scope_profiler.profile_config.SetupOptions.label

*attribute* · *instance attribute*

```python
label: str
```

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

### scope_profiler.profile_config.SetupOptions.memory_profile_path

*attribute* · *instance attribute*

```python
memory_profile_path: str
```

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

### scope_profiler.profile_config.SetupOptions.memray_follow_fork

*attribute* · *instance attribute*

```python
memray_follow_fork: bool
```

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

### scope_profiler.profile_config.SetupOptions.memray_native_traces

*attribute* · *instance attribute*

```python
memray_native_traces: bool
```

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

### scope_profiler.profile_config.SetupOptions.memray_trace_python_allocators

*attribute* · *instance attribute*

```python
memray_trace_python_allocators: bool
```

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

### scope_profiler.profile_config.SetupOptions.metadata_detail

*attribute* · *instance attribute*

```python
metadata_detail: str
```

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

### scope_profiler.profile_config.SetupOptions.output_mode

*attribute* · *instance attribute*

```python
output_mode: str
```

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

### scope_profiler.profile_config.SetupOptions.perf_events

*attribute* · *instance attribute*

```python
perf_events: list[str] | tuple[str, ...] | str
```

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

### scope_profiler.profile_config.SetupOptions.profile_mpi_calls

*attribute* · *instance attribute*

```python
profile_mpi_calls: bool
```

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

### scope_profiler.profile_config.SetupOptions.recursive_profile

*attribute* · *instance attribute*

```python
recursive_profile: bool
```

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

### scope_profiler.profile_config.SetupOptions.track_async

*attribute* · *instance attribute*

```python
track_async: bool
```

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

### scope_profiler.profile_config.SetupOptions.track_threads

*attribute* · *instance attribute*

```python
track_threads: bool
```

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

### scope_profiler.profile_config.SetupOptions.use_gpu_timing

*attribute* · *instance attribute*

```python
use_gpu_timing: bool
```

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

### scope_profiler.profile_config.SetupOptions.use_likwid

*attribute* · *instance attribute*

```python
use_likwid: bool
```

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

### scope_profiler.profile_config.SetupOptions.use_line_profiler

*attribute* · *instance attribute*

```python
use_line_profiler: bool
```

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

### scope_profiler.profile_config.SetupOptions.use_memray

*attribute* · *instance attribute*

```python
use_memray: bool
```

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

### scope_profiler.profile_config.SetupOptions.use_nvtx

*attribute* · *instance attribute*

```python
use_nvtx: bool
```

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

## scope_profiler.profile_config.load_profiling_config

*function*

```python
def load_profiling_config(path: str | os.PathLike[str]) -> dict
```

Load the ``[profiling]`` table from a TOML settings file.

A top-level table is also accepted for small files.  Paths in the file
retain TOML's normal meaning and are interpreted relative to the current
working directory, just like paths passed to :meth:`ProfileManager.setup`.

Settings may be written flat, or grouped into the ``memray``, ``gpu`` and
``hdf5`` sub-tables that mirror :class:`MemrayOptions`,
:class:`GPUOptions` and :class:`HDF5Options`::

    [profiling]
    file_path = "run.h5"

    [profiling.hdf5]
    compression = "gzip"
    compression_level = 4

Setting the same thing both ways is an error, not a silent precedence
rule.

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