Warning and error catalog¶

The installed machine-readable catalog is pymixef/warning_catalog.json (catalog version 1.0.0). Structured records always include a stable code, severity, mathematical meaning, likely causes, and remediation.

Stable catalog¶

Code	Severity	Meaning	Recommended review
`DATA-ROWS-EXCLUDED-001`	review	the missingness/validity contract removed source rows	reconcile every exclusion in `DataAudit` with the analysis plan
`DATA-FACTOR-LEVEL-DROPPED-001`	review	a declared factor level has no retained rows	review filtering and prespecified contrasts; do not silently choose a new reference
`DATA-DUPLICATE-KEY-001`	review	more than one row shares a repeated-measures key	add defining keys or resolve duplicate source records
`DATA-TIME-ORDER-001`	error	time decreases within a source group	normalize time scale and stable-sort within group
`FORMULA-RANK-DEFICIENT-001`	review	a fixed coefficient is not independently estimable	inspect aliased columns, empty cells, interactions, and collinearity
`FORMULA-CONSTANT-SCALE-001`	error	a constant predictor has zero scaling denominator	remove scaling or correct the predictor
`COV-BOUNDARY-001`	review	a variance component is at/near zero	inspect eigenvalues, design information, profiles, and justified simpler structures
`COV-SINGULAR-001`	review	a covariance block is rank deficient/nearly singular	inspect group counts, random design, and singularity report
`COV-CORRELATION-BOUNDARY-001`	review	correlation is near ±1	inspect profiles and whether a diagonal structure is scientifically justified
`NUM-HESSIAN-INDEFINITE-001`	review	local curvature does not support ordinary Wald uncertainty	avoid naive Wald inference; inspect gradient, profiles, starts, and identification
`NUM-GRADIENT-LARGE-001`	review	optimizer termination did not reach the scaled-gradient tolerance	rescale, tighten controls, and compare starts/engines
`INFERENCE-BOUNDARY-LRT-001`	review	naive chi-square LRT is invalid at a variance boundary	use a documented mixture reference or parametric bootstrap
`ENGINE-APPROXIMATION-001`	information	the objective uses a named likelihood approximation	report method/controls and assess approximation sensitivity
`INTEROP-APPROXIMATED-001`	review	translation is only approximately equivalent	inspect compatibility and validate objective components
`SIM-MONTE-CARLO-ERROR-001`	information	simulation summary has material Monte Carlo error	increase deterministic-seed replicates and report Monte Carlo SE

Code families¶

DATA-*: row exclusion, invalid keys, missing covariates, or event changes;
FORMULA-*: unsafe, ambiguous, rank-deficient, or unsupported syntax;
COV-*: boundary, singularity, or invalid covariance;
OPT-*: optimizer termination or gradient concerns;
HESS-*: indefinite or ill-conditioned Hessian;
ODE-*: integration, event, or sensitivity failure;
ENGINE-*: model/estimator incompatibility;
INTEROP-*: transformed, approximated, or refused exchange semantics.

Load, construct, and emit warnings¶

from pymixef.warnings import (
    emit_warning,
    load_warning_catalog,
    warning_record,
)

catalog = load_warning_catalog()
record = warning_record("COV-SINGULAR-001")
emit_warning(record)

PyMixEFWarning is the base warning category. DataAuditWarning, CovarianceWarning, and NumericalWarning allow standard Python warning filters to target an operational area. A WarningRecord is structured data; emitting it is a separate choice.

Exception hierarchy¶

Errors that prevent calculation use PyMixEFError subclasses:

Exception	Area
`ValidationError`	general public contract
`FormulaError`	formula syntax or compilation
`DataError`	data adaptation/audit
`CovarianceError`	covariance declaration/calculation
`TransformError`	parameter transform
`IRVersionError`, `IRValidationError`	ModelIR version/schema/semantics
`PluginError`	discovery or registry
`UnsupportedCapabilityError`	capability is not implemented
`EngineCompatibilityError` / `UnsupportedEngineError`	model/engine/method mismatch
`CompatibilityError`	strict external translation/report check

Pharmacometric and backend modules define narrower subclasses documented on their generated API pages.

A successful optimizer return does not suppress scientific or numerical warnings. Use fit.convergence.trustworthy, not a raw success flag, when automating review.

The batch CLI returns exit code 4 when a fit completes with warning status. Pass --allow-warning only when the surrounding workflow explicitly accepts numerically suspect results. Failed fits return exit code 2.

The complete signatures are in pymixef.warnings and pymixef.errors.