Canonical LMM primitive registry
This section is the registry of reusable LMM primitives. Current dependency requirements are recorded in package metadata; qualification versions and workload limits belong to the linked evidence. It records reusable implementation primitives rather than named biological models. Capability combinations and their qualification status are in the model catalog; evidence and reductions are indexed in model qualification and model reductions.
Records, incidence, and ordering
| Primitive | Public owner / implementation | Current contract | Status |
|---|---|---|---|
| Formula scalar and patterned-trait records | gfit() lowering; greml compiled MME |
Observed scalar records, trait-scoped fixed references, deterministic trait/record maps | qualified |
| Pedigree longitudinal records | gs_longitudinal_pedigree_records(); LongitudinalPedigreeMmeSufficientStatistics |
Animal-major basis coefficients, grouped independent residuals, arbitrary caller order, prediction rows | qualified |
| Component scalar records | gs_lmm_records(); component-LMM canonicalizer |
Compact fixed and component coefficient references; one canonicalization pass; no global incidence matrix | qualified |
| Component channels | gs_lmm_channel() / ComponentLmmChannel |
Per-record level reference, scalar/basis weight, optional absent incidence; level-major then channel-major within a component | qualified |
| Residual blocks | gs_lmm_residual_*(); typed local block evaluators |
Stable block and variance-group domains, canonical within-block order, compact coefficient references, caller-order restoration | qualified |
| Sparse fixed rows | pedigree and component constructors | Coefficient indices and values are stored per record; global dense or sparse X, Z, or W is not constructed |
qualified |
Relationship and covariance primitives
| Primitive | Public owner / implementation | Current contract | Status |
|---|---|---|---|
| Identity relationship | gs_relationship_identity() |
Implicit identity precision, explicit unique external levels, unit diagonal and zero relationship log determinant | qualified |
| Pedigree relationship | gs_relationship_pedigree() and specialized pedigree APIs |
Shared pedigree kernel, stable external IDs, inbreeding, Henderson \(A^{-1}\), \(A_{ii}\), and log determinant | qualified |
| Supplied covariance or precision | gs_relationship_matrix() |
Bounded dense/packed covariance or dense/packed/sparse precision with declared representation, IDs, validation, and provenance | qualified |
| Scalar/diagonal/SPD channel covariance | gs_lmm_component(); typed parameter sources |
Natural values with log or log-Cholesky transforms and declared channel order | qualified |
| Fixed-rank factor-analytic covariance | greml FactorAnalyticCovarianceLayout; compiled/component parameter blocks |
Factor-major lower-triangular free loadings, positive log pivots, trait-order positive log specifics, derived covariance/precision/log determinant, analytic first derivatives, separate observed-curvature derivatives, and state-specific Jacobian diagnostics | qualified for C++ algebra, fixed-state exact/PCG/stochastic execution, exact CHOLMOD REML, and exact retained BLUP; stochastic optimization unqualified |
| Structured residual values | AR(1)/exponential typed parameter source | Canonical variance-group values followed by rho or phi; structured_values, not an SPD packed matrix |
qualified |
| Zero scalar/rank-one covariance boundary | component active-set session | Reduced latent MME, KKT entry/reactivation, deterministic rank-one orientation, external-coordinate restoration | qualified for scalar and two-channel blocks only |
Residual covariance primitives
| Primitive | Public entry point | Current contract | Status |
|---|---|---|---|
| Independent/grouped diagonal | gs_lmm_residual_independent() and specialized grouped residuals |
Positive variance per canonical residual group; singleton-block reduction is exact | qualified |
| Patterned multitrait SPD | multitrait pedigree and formula routes | Principal covariance block for each actually observed trait pattern; missing traits are absent | qualified |
| Discrete AR(1) blocks | gs_lmm_residual_ar1() |
Integer, unique occasions; \(\rho=\tanh(\eta)\); positive or negative interior correlation; exact derivatives | qualified |
| Continuous exponential blocks | gs_lmm_residual_exponential() |
Unique finite irregular times; \(\phi=\exp(\eta)\); exact derivatives and local determinant | qualified |
| Mixed/general component residual structures | none in the component API | ARMA, antedependence, heterogeneous temporal scale, spatial/Matérn, spatiotemporal, and structure mixtures | unsupported |
The table describes component and specialized pedigree residual primitives. The separate persistent gs_longitudinal_residual() interface also exposes compound symmetry and heterogeneous AR(1); those capabilities do not transfer to gvc() or component residual blocks. See the persistent interface.
Local residual covariance and factors may be dense within a bounded block. The global MME, relationship covariance, observation covariance, and incidence matrices remain sparse/operator-based and are never materialized densely.
Sparse execution and inference primitives
| Primitive | Owner | Current contract | Status |
|---|---|---|---|
| Deterministic sparse MME plan | greml compiled/component/pedigree sufficient statistics | Constant lower-CSC union pattern within an active-set epoch; direct accumulation from compact record references | qualified |
| Common component coefficient operator | greml compiled component plan / CompiledMmeSession |
Matrix-free canonical record gather/residual-weight/scatter plus compiled component precision; exact component coefficient ordering and RHS; no global incidence matrix | qualified for identity/pedigree stochastic REML with independent residuals, AR(1) fixed/optimization, and supplied-precision or continuous-exponential fixed-state evaluation; other supplied-precision/structured-residual optimizer combinations remain unqualified |
| Component block-Jacobi preconditioner | greml compiled numerical component state | Deterministic fixed block and per-level channel blocks from record-local and relationship-diagonal contributions; explicit factorization failure and storage/application accounting | qualified within the identity/pedigree, AR(1), and fixed-state supplied-precision/continuous-exponential scopes listed in the catalog |
| Scalable sparse relationship precision | greml make_scalable_sparse_precision_relationship |
Ordered lower-CSC precision plus caller-certified SPD, covariance log determinant, and covariance diagonal; no dense covariance materialization | qualified for fixed-state PCG and stochastic score/AI evaluation; covariance optimization remains implemented_unqualified |
| PCG coefficient solve | gsolve PCG; greml model operators | Matrix-free application, block preconditioning, verified true residual, fixed-covariance BLUP | qualified on catalogued routes |
| CHOLMOD retained session | gsolve SparseDirectFactorization / selected-inverse session |
Reusable symbolic analysis, numerical refactorization, determinant, multi-RHS solves, retained accepted factor | qualified |
| PARDISO retained session | gsolve sparse-direct session | Reusable symbolic analysis, requested solver threads, exact determinant and multi-RHS coordinate solves | qualified on catalogued routes |
| Retained-factor target block | greml prediction-error module over gsolve multi-RHS solves | Canonical requested coefficient columns, bounded batches, external-order restoration, exact \(C^{-1}[T,T]\) | qualified for PARDISO and CHOLMOD on the three sparse pedigree routes |
| Exact coordinate traces | greml trace plans over direct session | Bounded complete coordinate systems, batched multi-RHS work, no stochastic substitution | qualified on catalogued routes |
| CHOLMOD selected inversion | gsolve selected-inverse contract; greml contraction plans | One retained-factor selected extraction, closure/workspace preflight, exact trace and complete-MME uncertainty entries | qualified |
| PARDISO selected inversion | none | Retained PARDISO factor exposes no selected-inverse/diagonal-inverse contract | unsupported |
| Stochastic trace and SLQ | matrix-free generic/multivariate/longitudinal/component engines | Explicitly selected retained-probe Hutchinson/SLQ routes with typed work accounting | qualified only where listed in the catalog |
| Adaptive stochastic execution | greml compiled component inference | Typed exploratory/accepted/certification tiers; deterministic nested counter-Rademacher prefixes; incremental trace/score-covariance moments; matched-prefix paired trial merit; phase-specific PCG tolerances and work; fixed-prefix stationarity certification | qualified for the catalogued independent-residual identity/pedigree component scope; fixed-budget execution remains the default; stochastic FA optimization unqualified |
| Complete-MME PEV/reliability | greml prediction-error module | Random-effect block of complete \(C^{-1}\), animal-specific relationship diagonal, plug-in covariance conditioning | qualified by CHOLMOD selected_inverse and bounded PARDISO selected_solve on catalogued routes |
Optimization and finalization primitives
| Primitive | Owner | Current contract | Status |
|---|---|---|---|
| Likelihood-monotone AI | greml direct optimizers | Exact accepted likelihood, rank-aware AI, bounded transformed step, rejected likelihood-only candidates | qualified |
| Hybrid EM-AI | component LMM | Exact posterior-moment EM warm-up/rescue followed by monotone AI | qualified |
| Phase-aware stochastic explicit AI | greml compiled component and incomplete-pedigree inference | Fixed common probes, canonical symmetric transformed AI, parameter-step covariance \(\mathrm{AI}^{-1}\Sigma_g\mathrm{AI}^{-1}\), scale-invariant diagonal damping for under-resolved nonstationary steps, score compatibility plus absolute-precision stationarity certification, and explicit insufficient-precision/line-search statuses | qualified for the catalogued independent-residual component, incomplete-pedigree, and AR(1) scopes; continuous-exponential and FA optimization remain unqualified |
| Active covariance set | component LMM | Exact zero scalar and rank-one two-channel states with one-sided KKT and reactivation | qualified within stated scope |
| Retained BLUP | direct and qualified stochastic sessions | Accepted response coefficients reused independently of optional likelihood availability; no final response solve | qualified on catalogued routes |
| Retained prediction error | CHOLMOD/PARDISO direct sessions | CHOLMOD selected inversion or bounded target-column solves reuse the accepted factor; no refactorization or response solve | qualified on catalogued routes |
| Resource/thread diagnostics | all solver-facing public results | Coefficients, systems, workspace/factor limits, requested/resolved method, separate direct/support thread domains, truthful no-work states | qualified |
Public composition rule
Permanent environment, litter, herd, year, herd-year, block, site, direct and maternal effects, random slopes, and reaction norms are recipes built from the relationship, channel, and component primitives above. They are not missing model engines. Cross-component covariance is represented only by correlated channels sharing one relationship component.