analysis¶

Offline, dependency-free views of a sweep directory. Each reads the per-cell status and metrics sidecars directly (no Hydra or xarray), so they load instantly and work mid-sweep. See the exploration → paper guide for how they fit an exploration workflow.

show ¶

show(root, *, metrics=None, sort=None)

Read the sweep under root and return a status/metrics table.

Parameters:

Name	Type	Description	Default
`root`		A sweep `working_dir` (the parent of the numeric per-cell job dirs).	required
`metrics`	`list[str] \| None`	Restrict the metric columns to these names, in this order (default: every metric found, discovery order). An unknown name raises `ValueError` (like `sort=`); repeats are deduplicated.	`None`
`sort`	`str \| None`	Column to sort rows by (a swept param, `"status"`, or a metric). Defaults to the swept params in grid order. A metric that shares a swept param's name is shown (and sorted) as `"<name> (metric)"`.	`None`

Returns:

Type	Description
`ShowResult`	`.rows` (one dict per cell) and `.table` (the rendered string); the table is also printed.

best ¶

best(root, metric, *, mode='max')

Return the completed cell that optimizes metric across the sweep.

Parameters:

Name	Type	Description	Default
`root`		A sweep `working_dir`.	required
`metric`	`str`	The metric to optimize; it must be a finite scalar in each cell.	required
`mode`	`str`	`"max"` (default) or `"min"`.	`'max'`

Raises:

Type	Description
`ValueError`	If `mode` is invalid, or no completed cell has `metric` as a finite scalar (the error lists the scalar metrics that are available).
`FileNotFoundError`	If `root` is not a directory.

diff ¶

diff(a, b, *, metrics=None)

Compare two sweep directories a and b.

Cells are aligned by their swept-param combination. For each shared cell the delta b - a is computed for every metric that is a finite scalar in both — and only when the cell is completed on BOTH sides (a failed/skipped cell may carry a stale sidecar from a prior attempt; its row appears with empty deltas). Cells present in only one sweep are reported separately, along with a diff of the two runs' environment provenance (git/packages/python/accelerator).

Returns:

Type	Description
`DiffResult`	`.rows` (shared-cell deltas), `.only_in_a` / `.only_in_b` (combos), `.provenance` (`{field: (a, b)}`), and `.table`; the table prints.

table ¶

table(root, *, path=None, metrics=None)

Export a sweep's cells as CSV: one row per cell with its swept params, status, and metrics.

Parameters:

Name	Type	Description	Default
`root`		A sweep `working_dir`.	required
`path`		If given, write the CSV there and return the `Path`. Otherwise return the CSV as a string.	`None`
`metrics`	`list[str] \| None`	Restrict the metric columns to these names, in this order (default: every metric found, discovery order); repeats are deduplicated. A metric sharing a swept param's name is emitted as `"<name> (metric)"`.	`None`

Raises:

Type	Description
`FileNotFoundError`	If `root` is not a directory.
`ValueError`	If `metrics` contains a name that is not a metric of this sweep.