# scope_profiler.metadata

*module*

Collects descriptive metadata about the environment a profiling run executed in.

Metadata is gathered on every rank but only rank 0's copy is persisted (see
``ProfileManager.finalize``), so it describes the run as a whole. Per-task
values such as ``SLURM_PROCID`` therefore reflect rank 0.

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

## scope_profiler.metadata.METADATA_DETAILS

*attribute* · *module attribute*

```python
METADATA_DETAILS = ('minimal', 'full')
```

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

## scope_profiler.metadata.MetadataValue

*attribute* · *module attribute*

```python
MetadataValue = str | int | list[str]
```

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

## scope_profiler.metadata.check_metadata_detail

*function*

```python
def check_metadata_detail(detail: str) -> str
```

Return ``detail`` if it is a known level, else raise ``ValueError``.

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

## scope_profiler.metadata.collect_metadata

*function*

```python
def collect_metadata(mpi_size: int = 1, detail: str = 'minimal') -> dict[str, MetadataValue]
```

Gather metadata describing the current run's environment.

Parameters
----------
mpi_size : int, optional
    Number of MPI ranks the run was launched with (default: 1). Used to
    derive ``total_cores`` (``mpi_size * omp_num_threads``), a single
    combined parallelism value useful as a scaling-plot x-axis.
detail : {"minimal", "full"}, optional
    ``"minimal"`` (default) records only ``timestamp``, ``platform``,
    ``chip_information``, ``python_version``, ``scope_profiler_version``,
    ``omp_num_threads``, ``mpi_size``, ``total_cores`` and, for a
    single-process run, ``num_nodes`` (1): no user name,
    host name (also part of ``uname``), working directory, loaded
    modules, environment variables or ``SLURM_*`` variables. ``"full"``
    records everything below.

Returns
-------
dict
    Mapping of metadata field name to a str, int or list-of-str value,
    suitable for storing as HDF5 attributes. Derived fields use
    lower-case names; captured environment variables keep their own
    upper-case names (``PATH``, ``SLURM_JOB_ID``, ...) and are only
    present when set.

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

## scope_profiler.metadata.count_nodes

*function*

```python
def count_nodes(comm) -> int
```

Number of distinct hosts the ranks of ``comm`` run on.

Collective: every rank of ``comm`` must call it, and every rank gets the
same count back. One small ``allgather`` of host names, run once per
run, never per event.

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