gcubed.memory_profile

Optional memory profiling helpers for large model-solution phases.

The profiler is intentionally dormant unless GCUBED_MEMORY_PROFILE is enabled. When active, it appends JSON-lines records to GCUBED_MEMORY_PROFILE_OUTPUT or to steady_state_memory_profile.jsonl in the current working directory.

PROFILE_ENV_VAR: str = 'GCUBED_MEMORY_PROFILE'

PROFILE_OUTPUT_ENV_VAR: str = 'GCUBED_MEMORY_PROFILE_OUTPUT'

PROFILE_NONZERO_LIMIT_GIB_ENV_VAR: str = 'GCUBED_MEMORY_PROFILE_NONZERO_LIMIT_GIB'

PROFILE_COUNT_NONZERO_ENV_VAR: str = 'GCUBED_MEMORY_PROFILE_COUNT_NONZERO'

def memory_profile_enabled() -> bool:

Return whether memory profiling events should be written.

Args: None.

Returns: True when GCUBED_MEMORY_PROFILE is set to an enabled value; otherwise False.

Raises: No exceptions are raised intentionally.

def matrix_summary( matrix: Any, *, key: Any | None = None, known_nonzero: int | None = None, include_nonzero: bool = True) -> dict[str, typing.Any]:

Return size and optional density metadata for a matrix-like object.

Args: matrix: Matrix-like object to describe. NumPy arrays and SciPy-style sparse matrices are supported directly; other objects are handled when they expose compatible shape, dtype, nbytes, or nnz attributes. key: Optional matrix identifier to include in the summary. Tuple keys are converted to lists for JSON serialization. known_nonzero: Optional precomputed count of nonzero entries. When supplied, this value is used instead of inspecting the matrix. include_nonzero: Whether dense NumPy matrices should be scanned with np.count_nonzero when a nonzero count is not already known.

Returns: A dictionary containing the matrix key, type name, shape, dtype, estimated byte payload, element count, nonzero count, density, and optional density-skip reason. NumPy array summaries also contain C- and Fortran-contiguity flags and byte strides.

Raises: TypeError: Propagated if a matrix-like object exposes a malformed shape that cannot be iterated or converted to integer dimensions. ValueError: Propagated if a shape dimension cannot be converted to an integer.

Append one memory-profile event when profiling is enabled.

Args: label: Event name to write to the event field. model: Optional model object used to derive model_version, model_build, and model_id. configuration: Optional configuration object used instead of model.configuration for model-identifying fields. matrix: Optional matrix-like object to summarize in the event. matrix_key: Optional identifier for matrix. known_nonzero: Optional precomputed nonzero count for matrix. include_nonzero: Whether dense NumPy matrices should be scanned for a nonzero count when known_nonzero is not supplied. extra: Optional extra metadata to include under the extra field.

Returns: None. If profiling is disabled, the function returns without doing any work.

Raises: No exceptions are raised intentionally. OSError while creating the output directory or writing the JSON-lines event is logged and suppressed.

def memory_profile_matrix_dictionary( label: str, matrix_dictionary: Mapping[Any, Any], *, model: Any | None = None, configuration: Any | None = None, include_nonzero: bool = False, top_n: int = 12, extra: Mapping[str, Any] | None = None) -> None:

Append a summary event for a dictionary of matrices.

Args: label: Event name to write to the event field. matrix_dictionary: Mapping from matrix keys to matrix-like objects. None values are counted separately and skipped. model: Optional model object used to derive profile model context. configuration: Optional configuration object used instead of model.configuration for profile model context. include_nonzero: Whether matrix summaries should scan dense NumPy matrices for nonzero counts. top_n: Number of largest matrix summaries to include in the event. extra: Optional extra metadata to merge into the event's extra field after aggregate matrix statistics are calculated.

Returns: None. If profiling is disabled, the function returns without doing any work.

Raises: TypeError: Propagated from matrix_summary if any matrix-like object exposes a malformed shape. ValueError: Propagated from matrix_summary if any matrix-like object's shape dimensions cannot be converted to integers.

@contextmanager

def memory_profile_phase( label: str, *, model: Any | None = None, configuration: Any | None = None, extra: Mapping[str, Any] | None = None) -> Iterator[NoneType]:

Profile the start and end of a block of work.

Args: label: Base event name. :start and :end suffixes are added to the emitted events. model: Optional model object used to derive profile model context. configuration: Optional configuration object used instead of model.configuration for profile model context. extra: Optional metadata to attach to both start and end events. The end event also includes phase_seconds.

Yields: None while the caller's profiled block executes.

Returns: An iterator-compatible context manager that emits a start event before the block and an end event in a finally block.

Raises: Any exception raised by the caller's with block is propagated after the end event is attempted. The profiler itself raises no exceptions intentionally.