spacr.fit_resources

Record process and GPU memory use for each regression stage.

Stage readings are included in run summaries and failure reports so resource exhaustion can be distinguished from other failures. Measurements are best-effort: missing psutil, an unavailable Torch runtime, or unsupported container metrics produce an unavailable reading rather than failing the fit.

Functions

describe_resources(→ str)	The per-stage table, for a summary or a failure report. "" when empty.
gpu_allocated(→ Optional[int])	The HIGH-WATER mark of torch's CUDA allocation, or None.
host_rss(→ Optional[int])	Resident bytes for this process, or None when unknowable.
peak(→ Dict[str, Any])	The largest reading recorded, and where it was taken.
readable(→ str)	Bytes as the unit a person decides in, or "not measured".
record_stage(→ Dict[str, Any])	Record the current fit stage and its memory use.

Module Contents

spacr.fit_resources.describe_resources(settings: Any) → str

The per-stage table, for a summary or a failure report. “” when empty.

Parameters:

settings – mapping-like fit settings carrying the recorded resource history.

spacr.fit_resources.gpu_allocated() → int | None

The HIGH-WATER mark of torch’s CUDA allocation, or None.

ASKED ONLY IF TORCH IS ALREADY IMPORTED. Importing it to take a measurement would make the measurement the most expensive thing in the stage, and on a settings panel it is the import this project has twice had to keep out (tests/test_a_settings_panel_does_not_import_torch.py).

Uses max_memory_allocated rather than the current allocation because fit tensors may already be released when a stage boundary is recorded. The high-water mark is cumulative across the process and therefore reports the largest allocation reached across a sequence of fits.

spacr.fit_resources.host_rss() → int | None

Resident bytes for this process, or None when unknowable.

/proc/self/statm first because it needs no dependency and no import; psutil second. A container that reports neither gets None, which the caller must not spell as zero – “nothing was using memory” and “nobody measured” are opposite findings.

spacr.fit_resources.peak(settings: Any) → Dict[str, Any]

The largest reading recorded, and where it was taken.

Parameters:

settings – mapping-like fit settings carrying the recorded resource history.

Empty when nothing was recorded – NOT zero, for the reason host_rss gives.

spacr.fit_resources.readable(total: int | None) → str

Bytes as the unit a person decides in, or “not measured”.

Parameters:

total – byte count to format, or None when no measurement exists.

spacr.fit_resources.record_stage(settings: Any, name: str) → Dict[str, Any]

Record the current fit stage and its memory use.

Updates the stage and resource-history entries in settings when it is mutable. Measurement and storage failures are ignored so diagnostics do not interrupt the fit.

Parameters:

• settings – Mutable fit settings or another mapping-like object.

• name – Name of the stage being entered.

Returns:

Dictionary containing the stage, resident memory, and allocated GPU memory. Unavailable measurements are None.