nlsq.diagnostics.GradientHealthReport

class nlsq.diagnostics.GradientHealthReport(available=True, error_message=None, computation_time_ms=0.0, n_iterations=0, health_score=1.0, mean_gradient_norm=0.0, final_gradient_norm=0.0, mean_gradient_magnitudes=<factory>, variance_gradient_magnitudes=<factory>, max_imbalance_ratio=1.0, has_numerical_issues=False, vanishing_detected=False, imbalance_detected=False, stagnation_detected=False, issues=<factory>, health_status=HealthStatus.HEALTHY)

Bases: AnalysisResult

Report from gradient health monitoring during optimization.

Contains results from monitoring gradient behavior across iterations, including detection of vanishing gradients, gradient imbalance, and gradient stagnation.

This dataclass extends AnalysisResult to include gradient-specific metrics tracked during optimization using memory-efficient algorithms (sliding window for norms, Welford’s algorithm for running statistics).

Memory usage is bounded at <1KB regardless of iteration count.

n_iterations

Total number of iterations monitored.

Type:

int

health_score

Overall gradient health score in [0, 1]. Higher is healthier.

Type:

float

mean_gradient_norm

Mean gradient norm across all iterations.

Type:

float

final_gradient_norm

Gradient norm at the final iteration.

Type:

float

mean_gradient_magnitudes

Mean gradient magnitude per parameter (from Welford’s algorithm).

Type:

np.ndarray

variance_gradient_magnitudes

Variance of gradient magnitude per parameter (from Welford’s algorithm).

Type:

np.ndarray

max_imbalance_ratio

Maximum ratio between largest and smallest gradient components.

Type:

float

has_numerical_issues

Whether NaN or Inf values were detected in gradients.

Type:

bool

vanishing_detected

Whether vanishing gradients were detected.

Type:

bool

imbalance_detected

Whether gradient imbalance was detected.

Type:

bool

stagnation_detected

Whether gradient stagnation was detected.

Type:

bool

issues

List of detected gradient issues (GRAD-001, GRAD-002, GRAD-003).

Type:

list[ModelHealthIssue]

health_status

Overall health status based on detected issues.

Type:

HealthStatus

Examples

>>> report = GradientHealthReport(
...     n_iterations=100,
...     health_score=0.95,
...     mean_gradient_norm=0.1,
...     final_gradient_norm=0.001,
...     mean_gradient_magnitudes=np.array([0.1, 0.08, 0.12]),
...     variance_gradient_magnitudes=np.array([0.01, 0.01, 0.01]),
...     max_imbalance_ratio=1.5,
...     has_numerical_issues=False,
...     vanishing_detected=False,
...     imbalance_detected=False,
...     stagnation_detected=False,
...     issues=[],
...     health_status=HealthStatus.HEALTHY,
... )
>>> report.available
True
>>> report.health_score
0.95

n_iterations: int

health_score: float

mean_gradient_norm: float

final_gradient_norm: float

mean_gradient_magnitudes: ndarray

variance_gradient_magnitudes: ndarray

max_imbalance_ratio: float

has_numerical_issues: bool

vanishing_detected: bool

imbalance_detected: bool

stagnation_detected: bool

issues: list[ModelHealthIssue]

health_status: HealthStatus

__str__()

Return a human-readable summary of the gradient health report.

summary()

Return a summary string of the report.

Returns:

Human-readable summary of the gradient health analysis.

Return type:

str

__init__(available=True, error_message=None, computation_time_ms=0.0, n_iterations=0, health_score=1.0, mean_gradient_norm=0.0, final_gradient_norm=0.0, mean_gradient_magnitudes=<factory>, variance_gradient_magnitudes=<factory>, max_imbalance_ratio=1.0, has_numerical_issues=False, vanishing_detected=False, imbalance_detected=False, stagnation_detected=False, issues=<factory>, health_status=HealthStatus.HEALTHY)