convergence - bossanova

Convergence diagnostics for mixed-effects models.

Classes:

Name	Description
`ConvergenceMessage`	A convergence diagnostic message with technical and user-friendly parts.

Functions:

Name	Description
`diagnose_convergence`	Analyze model convergence state and generate diagnostic messages.
`format_convergence_warnings`	Format convergence messages for display as warning text.

Classes¶

ConvergenceMessage¶

ConvergenceMessage(category: str, technical: str, explanation: str, tip: str | None = None) -> None

A convergence diagnostic message with technical and user-friendly parts.

Attributes:

Name	Type	Description
`category`	`str`	Type of issue (“singular”, “correlation”, “boundary”, “convergence”)
`technical`	`str`	lme4-style technical message
`explanation`	`str`	User-friendly explanation of the issue
`tip`	`str \| None`	Actionable suggestion to fix the issue (optional)

Attributes¶

category¶

category: str

explanation¶

explanation: str

technical¶

technical: str

tip¶

tip: str | None = None

Functions¶

diagnose_convergence¶

diagnose_convergence(theta: np.ndarray, theta_lower: list[float], group_names: list[str], random_names: list[str] | dict[str, list[str]], re_structure: str | list[str] | dict[str, str], sigma: float, converged: bool, boundary_adjusted: bool, restarted: bool, optimizer_message: str = '', singular_tol: float = 0.0001, corr_tol: float = 0.99) -> list[ConvergenceMessage]

Analyze model convergence state and generate diagnostic messages.

Parameters:

Name	Type	Description	Default
`theta`	`ndarray`	Optimized theta parameters (Cholesky factors, relative scale).	required
`theta_lower`	`list[float]`	Lower bounds for each theta element.	required
`group_names`	`list[str]`	Names of grouping factors.	required
`random_names`	`list[str] \| dict[str, list[str]]`	Names of random effects per group.	required
`re_structure`	`str \| list[str] \| dict[str, str]`	RE structure per group (“intercept”, “diagonal”, “slope”).	required
`sigma`	`float`	Residual standard deviation (1.0 for GLMMs).	required
`converged`	`bool`	Whether optimizer reported convergence.	required
`boundary_adjusted`	`bool`	Whether boundary checking adjusted parameters.	required
`restarted`	`bool`	Whether restart_edge triggered a restart.	required
`optimizer_message`	`str`	Message from optimizer (for non-convergence).	`‘’`
`singular_tol`	`float`	Tolerance for near-zero variance detection.	`0.0001`
`corr_tol`	`float`	Tolerance for degenerate correlation detection (	corr

Returns:

Type	Description
`list[ ConvergenceMessage ]`	List of ConvergenceMessage objects describing any issues found.

format_convergence_warnings¶

format_convergence_warnings(messages: list[ConvergenceMessage]) -> str

Format convergence messages for display as warning text.

Uses paired format: technical message (deemphasized) followed by explanation (prominent), without explicit labels.

Parameters:

Name	Type	Description	Default
`messages`	`list[ ConvergenceMessage ]`	List of ConvergenceMessage objects.	required

Returns:

Type	Description
`str`	Formatted warning string.