Canonical LMM capability catalog

This is the authoritative catalog of LMM routes and their recorded evidence. Status terms are defined in model architecture. Evidence is indexed in model qualification; reusable machinery and exact reductions are in the primitive registry and model reductions.

R interface coverage inventory

This inventory follows the exported constructors, dispatch code and existing test sources; it is not a new numerical qualification run. The single-trait, multitrait, longitudinal, repeatability and direct/maternal tutorial models, plus grouped, AR(1) and exponential residual examples, have been executed with the 10,000-animal pedigree; other rows below still need a comparable user-workflow check. formula and formulas now select the same general gfit() adapter. Starts do not determine dispatch. Explicit scalar components can represent multiple independent pedigree/identity random intercepts. Named grouping vectors additionally declare correlated channels for a single response under a shared kernel. A typed gs_fit_control() explicitly selects the specialized compiled interface with complete starts. The broader public R API still contains capabilities beyond this adapter.

Model or family Simple gfit(formula = ...) Other exported R route Current interface assessment
Single-trait animal model Yes; short form or explicit gvc() Compiled via gs_fit_control(); gs_pedigree_records() / gs_pedigree_fit() 10K tutorial passed: automatic starts, REML, fixed solve, summary, estimates, all-animal predictions and record results
Multitrait animal model with missing responses Yes; named formulas and one pedigree component Compiled via gs_fit_control(); gs_multitrait_pedigree_records() / gs_multitrait_pedigree_fit() 10K tutorial passed; G/R and animal-trait predictions accessible; full interpretation/gallery check remains
Genetic random regression, irregular records Yes; one trait and numeric basis columns gs_longitudinal_pedigree_records() / gs_longitudinal_pedigree_fit() 10K tutorial passed; genetic basis coefficients accessible; trajectory and uncertainty walkthrough remains
Repeatability: animal plus permanent environment Yes; explicit scalar gvc() components Specialized repeatability or component LMM General adapter implemented; repeatability added to the 10K tutorial; distinct grouping columns identify separate effects
Animal plus litter, herd or other common environment Yes; explicit scalar random intercepts Component LMM; specialized compiled controls for bounded combinations Adapter tested with an extra common-group component against a tiny dense oracle; no separate 10K common-environment study
Identity-only random intercept Yes; explicit gvc(..., kernel = gs_identity()) Component LMM; persistent gs_group() Uses the scalar independent-component adapter; not a separate solver
Multiple independent random groups Yes; scalar or correlated intercept channels for one response gs_lmm_records(), gs_lmm_component(), gs_lmm_model(), gs_lmm_fit(); persistent covariance sums General adapter no longer has the compiled route’s one-identity-group restriction; multitrait and random-coefficient extensions remain pending
Correlated direct/maternal effects Yes; gvc(c(direct="id", maternal="dam"), "BW", kernel=PED) Two incidence channels sharing one pedigree relationship in gs_lmm_component(covariance = "unstructured") Dense GLS/BLUP and score checks passed; 10K pedigree / 14,844-record tutorial converged with automatic starts and default CHOLMOD controls; known channel IDs required
Maternal permanent environment Expressible; separate scalar identity component over a duplicate dam grouping column Add an independent identity component over dam IDs to the component model Correlated-plus-independent common-group fixed solve tested; full maternal-environment combination remains unverified
Correlated random coefficients / reaction norms One pedigree component, one trait only Weighted component channels sharing a relationship; generic longitudinal routes Basis and incidence must be supplied explicitly; broader combinations need workflow checks
Trait-specific effects / discrete GxE Restricted to the same single pedigree component across traits Component channels with absent incidence; persistent multivariate models; multitrait reduction where mappings agree Recipe-expressible within each route’s residual/missingness restrictions, not a universal formula feature
Grouped independent residual variances Yes; residual gvc(..., group = "sex") Specialized record constructors; gs_lmm_records(residual_group = ...); persistent weighted/group residual structures Dense references passed; 10K pedigree / 25,589-record tutorial converged with defaults; one response and random intercepts
AR(1) or continuous-exponential residual blocks Yes; residual gvc(..., structure = "ar1" / "exponential", block = "id", time = "time") gs_lmm_residual_ar1() / gs_lmm_residual_exponential() with component LMM Dense references and 10K tutorial passed; exponential uses explicit score tolerance 1e-4 with stricter stopping limitation documented; unique positions and one variance group per block; no transfer of stochastic qualification
Genomic and combined genomic/structured covariance No genomic gvc() kernel gs_genomic(), gs_dense_covariance(), gs_group(), gs_model_pedigree(), gs_sparse_random() with gs_model() / gs_model_fit() Public persistent R route; genotype input and matrix-free/dense route need a separate example
Generic multivariate covariance LMM No, except the specialized animal model above gs_multivariate_model() with trait covariance constructors, then gs_model_fit() Existing R tests cover unbalanced models; not yet a 10K gallery workflow
Complete multivariate RHE plus BLUP No gs_multivariate_rhe_blup() Separate estimation procedure; complete finite phenotypes required, not REML with missing traits
Generic longitudinal covariance LMM No, except specialized pedigree random regression gs_longitudinal_model() / gs_model_fit(); supplied basis and trait covariance R residual descriptor includes independent, compound symmetry, AR1, continuous AR1 and heterogeneous AR1; these are not all available in the component API
Balanced or arbitrary-record matrix-free longitudinal No gs_balanced_longitudinal_model() or gs_longitudinal_records_model() with gs_longitudinal_fit() RHE/REML/BLUP accessors exist; retain the recorded unresolved longitudinal failures below
Supplied relationship covariance or precision No gs_relationship_matrix() in component LMM; dense/sparse-random persistent constructors Bounded dense/packed inputs and supplied sparse precision are distinct. The relationship constructor defaults to a 5,000-level limit; a 10K case requires deliberate resource sizing
Fixed-rank factor analytic covariance No No public gs_lmm_component() covariance choice for FA Catalog records native implementation/evidence; R constructor gap, not a missing numerical algorithm
General direct/social effects with multiple contributors per record No No direct recipe constructor established by this audit A channel carries one level/weight per record; multi-contributor correlated social incidence must not be assumed to fit that contract
ssGBLUP / internally constructed H inverse No No dedicated constructor in the component/pedigree APIs Supplying a precomputed precision does not establish an implemented ssGBLUP workflow
ARMA, antedependence, spatial or Matern residual families No No matching fitted-family constructor found in the reviewed R APIs Supplying a fixed covariance matrix is not equivalent to estimating that covariance family

What users can retrieve

Result family Current access Gap to address in the gallery
General formula, pedigree and independent components summary(), coef(), gs_ranef(), fitted(), residuals(), diagnostics() Covariance and fixed effects in summary; named component predictions and record mapping. No common logLik() contract; route-specific likelihood/uncertainty remains in native diagnostics
Compiled formula Summary, fixed effects, random effects, record values and diagnostics through the gs_fit methods Public prediction uncertainty is explicitly rejected; do not advertise it from backend capabilities
Specialized pedigree Returned fit lists with variance/covariance, coefficients, status and route-specific prediction/uncertainty fields Different result layouts; verify ID labels, requested targets and availability for each recipe. Specialized repeatability lacks its own PEV route
Component LMM gs_lmm_fit() / gs_lmm_blup() return labelled components, predictions and diagnostics; dedicated print method No dedicated summary/coef/ranef S3 methods for this class in NAMESPACE; user examples currently need explicit result-field extraction
Persistent covariance summary(), coef(), vcov(), predict(), gs_ranef(), contrasts and Wald helpers Availability depends on requested route and uncertainty; do not infer it from a method name alone
Balanced/record longitudinal gs_longitudinal_rhe(), gs_longitudinal_reml(), gs_longitudinal_blup() Explain which estimation procedure ran and which results are valid

Solver policy and outstanding defaults

Use CHOLMOD with selected inversion as the reference configuration for the new sparse-direct model examples. Selecting CHOLMOD alone is insufficient: coordinate tracing can still do many solves. The three pedigree tutorial models already select linear_solver = "sparse_direct", direct_backend = "cholmod", exact_trace_method = "selected_inverse". The general formula adapter and compiled-control constructor now follow this default; explicit solver choices remain authoritative.

The source currently differs from that policy:

  • General pedigree formulas default to sparse direct, CHOLMOD and selected inversion. Explicit alternative backends use coordinate tracing unless the caller requests another trace method; unsupported requests are not repaired.
  • The four specialized pedigree control constructors default to PCG, automatic backend and coordinate tracing.
  • Compiled gs_fit_control() defaults to CHOLMOD and selected inversion. Its selected-inversion argument is trace_route, not exact_trace_method.
  • gs_lmm_control() already defaults to CHOLMOD. Its public signature does not expose the native component PCG/stochastic/adaptive controls; those native capabilities are a separate R-exposure gap.
  • Dense exact and matrix-free covariance routes are different algorithms; a global CHOLMOD substitution is not applicable to them.

Keep explicit solver choices and clear errors when requested CHOLMOD support is unavailable. Specialized low-level control defaults remain separate. The timing difference observed in the tutorial is not evidence that one backend is universally faster for every model and workload.

Minimal verification programme

Use 10,000 animals/individuals as the default demonstration size for scalable routes, with trait and observation counts stated separately. Tiny deterministic oracle tests remain tiny; dense reference routes and bounded uncertainty targets should not automatically be expanded to 10K dimensions.

Keep this coverage table as the inventory, the existing pedigree tutorial as the introductory example, and reuse build/examples/ for replaceable runtime outputs. Do not create a folder or a dated report for each attempted fit. Promote only selected, reviewed figures and concise results to website sources.

Check each recipe in this order: expressibility through exported R functions, correct model/ID mapping, convergence, result extraction, then agreement with an existing equivalent route or appropriate reference. Passing one example does not requalify every covariance/backend combination.

Implementation sequence

Work Current state Next acceptance target
Common explicit gvc() contract Formula aliases unified; supplied starts no longer select an engine Preserve this rule for every extension
Defaults and results General sparse-direct CHOLMOD selected inversion; shared summary and extraction for pedigree/independent components Broader likelihood and uncertainty contracts remain separate work
Independent components Scalar pedigree/identity intercept adapter implemented using the existing component engine Repeatability tutorial and tiny dense multi-group reference
Correlated channels Named grouping vectors lower to shared pedigree/identity channels for one response Direct/maternal tutorial, dense GLS/BLUP and natural-score checks; broader missing-incidence and multitrait support remains separate
Residual structures gvc() column bindings for grouped variance, AR1 and exponential blocks Dense GLS/BLUP, natural scores, group/time mapping and 10K tutorial workflows; multi-response and random-regression combinations remain separate
Additional relationships and model combinations Dedicated genomic and longitudinal R routes exist Map explicit kernels and trait/basis coordinates without hidden dispatch
Factor analytic covariance Native capability, R descriptor absent Agree identification/rank contract, then bind and verify

Source review covered NAMESPACE, R/pedigree-formula.R, R/zz-formula-reml.R, R/component-lmm.R, the four specialized pedigree wrappers, R/model.R, R/multivariate.R and R/balanced-longitudinal.R. Existing R tests include pedigree/formula/repeatability tests, test-model.R, test-multivariate.R, test-multivariate-rhe-blup.R, and balanced/record longitudinal tests. test-independent-formula.R adds dense GLS/BLUP and start/dispatch checks through the general adapter. Native evidence is not a substitute for exported-R workflow checks of the remaining recipes.

Scientific representation and public route

Qualification below is scoped evidence, not complete package qualification. The persistent gs_model_pedigree() and formula gs_pedigree() constructors are separately exported.

The formula-compiler rows refer to explicit gs_fit_control() requests with complete starts. General formula calls instead use the pedigree or independent component adapters; see the pedigree tutorial. Compiler-row exclusions must not be transferred to that adapter implicitly.

Representation Public R entry point Public C++ owner/entry point Status Scope
Single-trait covariance LMM gs_model(), gs_model_fit(); exact convenience gsuite_reml_dense() greml ModelSpec, exact-dense and matrix-free evaluators qualified Explicit fixed design and covariance components; exact dense is small-oracle work, matrix-free is scalable/stochastic
Formula pedigree single trait gs_pedigree(), gvc(), gfit() CompiledMmeSpecification / CompiledMmeSession qualified One pedigree intercept and residual through formula lowering
Formula pedigree multitrait, including missing traits named formulas, gs_pedigree(), gvc(), gfit() compiled MME patterned residual units qualified Observed scalar trait records; missing traits are absent, never imputed
Balanced longitudinal gs_balanced_longitudinal_model(), gs_longitudinal_fit() StructuredLongitudinalModel qualified Complete common grid, supplied bases, RHE/REML/BLUP and new-grid projection
Irregular generic record-longitudinal gs_longitudinal_records_model(), gs_longitudinal_fit() RecordLongitudinalModel qualified Observed scalar records, unequal counts, arbitrary order, supplied per-component bases
Pedigree single trait gs_pedigree_records(), gs_pedigree_fit() pedigree MME and pedigree REML sessions qualified All pedigree animals, including unphenotyped animals
Pedigree incomplete multitrait gs_multitrait_pedigree_records(), gs_multitrait_pedigree_fit() multitrait pedigree MME/REML sessions qualified Arbitrary observed trait subsets and correlated observed-pattern residual blocks
Pedigree irregular longitudinal random regression gs_longitudinal_pedigree_records(), gs_longitudinal_pedigree_fit() LongitudinalPedigreeMmeSufficientStatistics and retained session qualified One pedigree random-regression component, supplied basis, grouped independent residuals, prediction rows
Specialized repeatability gs_repeatability_pedigree_records(), gs_repeatability_pedigree_fit() repeatability pedigree REML session qualified Additive pedigree plus one identity permanent-environment intercept
Generic scalar-record component LMM gs_lmm_records(), gs_lmm_model(), gs_lmm_fit() ComponentLmm* and compiled MME qualified Multiple independent component groups and channels; identity, pedigree, or bounded supplied relationship
Identity/group/common-environment recipes gs_relationship_identity(), gs_lmm_component() component LMM identity relationship qualified Permanent environment, litter, herd, year, site, block, or equivalent names are composition recipes, not separate engines
Correlated direct/maternal or random-coefficient channels multi-channel gs_lmm_component(..., covariance = "unstructured") component-major shared-relationship channel block qualified Correlated channels must share one relationship component; cross-component covariance is unsupported
Fixed-rank factor-analytic covariance No public R constructor for this covariance layout greml FactorAnalyticCovarianceLayout and component/compiled-MME declarations qualified C++ covariance layout, exact REML and exact retained BLUP; fixed-state PCG and stochastic evaluation also qualified Declared rank, lower-triangular identification, positive pivots and specific variances; stochastic covariance optimization is unqualified
AR(1) residual blocks gs_lmm_residual_ar1() typed component-LMM residual blocks qualified Integer occasions, positive or negative interior rho, block-level variance groups
Continuous exponential residual blocks gs_lmm_residual_exponential() typed component-LMM residual blocks qualified Irregular finite times, positive interior phi, block-level variance groups

Model by numerical execution

Each cell classifies that exact model/backend/trace combination. Dense code is production only for the explicitly small exact route; elsewhere it is a test oracle.

Model route Dense PCG CHOLMOD coordinate CHOLMOD selected inverse PARDISO coordinate PARDISO selected_solve PEV Stochastic trace / SLQ
Generic single-trait covariance qualified qualified matrix-free not_applicable not_applicable not_applicable not_applicable qualified matrix-free Hutchinson/SLQ
Formula pedigree compiler not_applicable unsupported in the public formula route qualified qualified qualified unsupported in the formula result unsupported
Pedigree single trait oracle qualified qualified fixed covariance qualified fixed/REML qualified REML traces qualified fixed/REML qualified bounded exact target PEV/reliability qualified fixed-probe stochastic REML/SLQ
Pedigree incomplete multitrait oracle qualified qualified fixed covariance and fixed-common-probe stochastic REML optimization qualified fixed/REML qualified REML traces qualified fixed/REML qualified bounded exact within-animal PEV blocks qualified fixed-parameter evaluation and safeguarded covariance optimization; SLQ likelihood is available only when its requested precision passes
Pedigree irregular longitudinal oracle qualified qualified fixed covariance qualified fixed/REML qualified fixed/REML traces qualified fixed/REML qualified bounded coefficient and trajectory PEV/reliability unsupported in this sparse pedigree route
Specialized repeatability oracle qualified qualified fixed covariance qualified fixed/REML qualified REML traces qualified fixed/REML unsupported on the specialized public route unsupported
Generic component LMM oracle qualified qualified fixed-covariance C++ BLUP and fixed-budget or explicitly selected adaptive stochastic REML for identity/pedigree relationships, independent residuals, and scalar/complete or arbitrary missing channels qualified fixed/REML qualified; canonical trace and uncertainty route unsupported unsupported qualified fixed-state evaluation and safeguarded fixed/adaptive covariance optimization in the stated PCG scope; adaptive certification uses a declared fixed final prefix and SLQ likelihood is conditional on its precision contract
Component LMM with FA covariance covariance algebra oracle qualified qualified fixed-state coefficient/BLUP and fixed-state stochastic score/AI; stochastic covariance optimization and post-optimization BLUP implemented_unqualified qualified fixed state, exact REML, and retained BLUP prediction uncertainty not qualified for FA implemented_unqualified unsupported qualified fixed-state score/AI only; optimization and stochastic retained-state finalization are unqualified
Component LMM with supplied sparse precision oracle qualified qualified fixed-state coefficient/BLUP and stochastic score/AI evaluation only; covariance optimization implemented_unqualified qualified fixed/REML qualified retained uncertainty unsupported unsupported qualified fixed-state trace/score/AI; covariance optimization implemented_unqualified
Component LMM with AR(1) residuals oracle qualified qualified fixed-state evaluation and stochastic covariance optimization qualified fixed/REML qualified retained uncertainty unsupported unsupported qualified fixed-state evaluation and safeguarded covariance optimization
Component LMM with continuous-exponential residuals oracle qualified qualified fixed-state coefficient, derivative, trace, AI, and PCG evaluation; covariance optimization implemented_unqualified after line-search exhaustion qualified fixed/REML qualified retained uncertainty unsupported unsupported qualified fixed-state evaluation only; covariance optimization implemented_unqualified
Balanced longitudinal oracle qualified qualified matrix-free not_applicable not_applicable not_applicable not_applicable qualified Hutchinson/SLQ, including opt-in determinant deferral
Generic irregular record-longitudinal oracle qualified qualified matrix-free not_applicable not_applicable not_applicable not_applicable qualified Hutchinson/SLQ, including opt-in determinant deferral

PARDISO selected inversion is unsupported for every route. PARDISO capability metadata reports this explicitly and no fallback is permitted. Longitudinal pedigree coordinate tracing is a bounded moderate-problem PARDISO route; it does not imply that selected inversion is absent globally. The separate selected_solve cells above use documented retained-factor multi-RHS solves; they do not change PARDISO’s selected-inversion classification.

For incomplete multitrait stochastic REML, covariance optimization, optional approximate restricted likelihood, and all-animal BLUP are separate result capabilities. Score/AI convergence and BLUP can succeed when final SLQ exceeds its requested standard-error limit; in that case likelihood is explicitly unavailable and its estimate, uncertainty, and work remain diagnostic only.

The same separation applies to qualified stochastic component REML. Its missing-channel claim means absent canonical scalar records, not imputation or complete-case deletion. The scalable supplied sparse-precision constructor and structured-residual PCG/stochastic paths are retained implementations, but they are not a completed qualified combination. Supplied precision is fixed-state qualified; its stochastic optimizer is not. AR(1) fixed-state evaluation and stochastic optimization are qualified. Continuous exponential coefficient, derivative, trace, AI, and PCG evaluation is fixed-state qualified, whereas its stochastic optimizer ended in explicit score-merit line-search exhaustion. The combined supplied-precision/structured-residual stochastic illustration was not run. Exact CHOLMOD component capabilities in those rows remain qualified and unchanged.

The optional adaptive component policy preserves those scientific boundaries. It uses deterministic nested probe prefixes and phase-specific PCG tolerances for exploratory, accepted-state, and certification work; the fixed-budget path remains the default. Final convergence is always recomputed with the declared fixed certification prefix and requires score compatibility, deterministic stationarity, and an absolute transformed-parameter uncertainty envelope. Adaptive execution is qualified for the independent-residual identity/ pedigree scope. The bounded FA revisit ended with explicit insufficient parameter-step precision, so it does not change the FA row above.

Inference and output

Model route Fixed covariance REML optimization Retained BLUP / trajectories PEV / reliability Covariance boundary Resource/thread/retained-state diagnostics
Generic single-trait covariance qualified qualified exact or stochastic by selected route qualified qualified selected prediction/contrast uncertainty where requested qualified only for its documented scalar zero-eligible strategy qualified
Formula pedigree compiler qualified qualified positive interior qualified unsupported in the public formula result unsupported qualified
Pedigree single trait qualified qualified positive interior qualified all animals qualified CHOLMOD selected_inverse or PARDISO selected_solve complete-MME PEV/reliability unsupported qualified
Pedigree incomplete multitrait qualified qualified positive-interior G,R qualified all animal-trait coefficients qualified CHOLMOD selected_inverse or PARDISO selected_solve within-animal PEV blocks unsupported qualified
Pedigree irregular longitudinal qualified qualified positive-interior Q and grouped residuals qualified latent and observed/prediction trajectories qualified CHOLMOD selected_inverse or PARDISO selected_solve coefficient and trajectory PEV/reliability unsupported qualified
Specialized repeatability qualified qualified positive interior qualified unsupported on the specialized public route; use component LMM for qualified component uncertainty unsupported qualified
Generic component LMM, independent residual qualified by exact CHOLMOD and C++ PCG for identity/pedigree relationships with scalar, complete correlated, and arbitrary missing channels qualified exact hybrid EM-AI and fixed-common-probe stochastic explicit-AI optimization in the stated PCG scope qualified component coefficients/contributions and all known levels; stochastic optimization reuses the accepted response qualified retained CHOLMOD within-level blocks; unsupported from PCG qualified for zero scalar and rank-one two-channel blocks only qualified; optimizer, optional likelihood, BLUP, and logical solver states are distinct
Component LMM, fixed-rank FA covariance qualified through identical derived covariance in exact CHOLMOD and matrix-free PCG at fixed state exact CHOLMOD optimization qualified; stochastic optimization implemented_unqualified exact retained-state BLUP qualified; fixed-state PCG coefficients/BLUP qualified; stochastic post-optimization BLUP unqualified not qualified for this covariance layout singular/zero-specific boundaries unsupported qualified algebra, identification, derivatives, Jacobian diagnostics, fixed-state execution and exact result finalization
Component LMM, AR(1) residual qualified qualified positive-interior residual parameters by exact and stochastic routes qualified qualified for random components implemented_unqualified when combined with active random-component boundaries qualified
Component LMM, continuous-exponential residual qualified fixed state exact optimization qualified; stochastic optimization implemented_unqualified exact-route BLUP qualified; stochastic post-optimization BLUP not qualified qualified for random components on the exact route implemented_unqualified when combined with active random-component boundaries fixed-state diagnostics qualified
Component LMM, supplied sparse precision qualified fixed state exact optimization retains its existing scope; scalable stochastic optimization implemented_unqualified fixed-state PCG BLUP qualified exact-route uncertainty unchanged; unsupported from PCG implemented_unqualified fixed-state diagnostics qualified
Balanced longitudinal qualified qualified positive interior qualified latent/common-grid trajectories qualified selected-target conditional uncertainty; not selected-inverse MME PEV unsupported for singular Q qualified
Generic irregular record-longitudinal qualified qualified positive interior qualified observed/prediction records unsupported for full coefficient PEV/reliability unsupported qualified

All PEV/reliability entries are plug-in uncertainty conditional on fitted covariance parameters. PCG has no retained direct factor, so exact PEV is unsupported. PARDISO selected_inverse remains unsupported. PARDISO selected_solve instead solves the requested complete-MME target columns from the retained accepted factor, with explicit system, entry, batch, and memory bounds.

CHOLMOD support for longitudinal pedigree models

The irregular-record public path is qualified within the scope below. gs_longitudinal_pedigree_reml_control() exposes CHOLMOD selected-inverse traces and prediction error; the same canonical MME is consumed by LongitudinalPedigreeSparseDirectSession; focused native and R tests cover selected-inverse trace parity, retained-factor longitudinal PEV, trajectory uncertainty, and typed work accounting. The PCG block-preconditioned fixed solve and PARDISO coordinate-trace REML profile are independently qualified; they do not replace or weaken the CHOLMOD path.

Public API and implementation mapping

R API C++ implementation Relationship to shared machinery
gs_model_pedigree() with gs_model() / gs_model_fit() unified model facade structured pedigree term Ordered parent indices and optional Mendelian variances; separate from the formula kernel
gfit() with gs_pedigree() / gvc() compiled MME Formula lowering adapter over the shared compiled sparse-MME session; deliberately narrower than gs_lmm_*()
gs_pedigree_records(), gs_pedigree_start(), gs_pedigree_reml_control(), gs_pedigree_fit() scalar pedigree MME/REML Specialized animal-model adapter and reduction oracle
gs_multitrait_pedigree_records(), gs_multitrait_pedigree_start(), gs_multitrait_pedigree_reml_control(), gs_multitrait_pedigree_fit() multitrait pedigree MME/REML Specialized patterned-trait adapter over retained direct-session machinery
gs_longitudinal_pedigree_records(), gs_longitudinal_pedigree_start(), gs_longitudinal_pedigree_reml_control(), gs_longitudinal_pedigree_fit() longitudinal pedigree MME/REML Specialized irregular-record adapter using the compiled MME and retained direct session
gs_repeatability_pedigree_records(), gs_repeatability_pedigree_start(), gs_repeatability_pedigree_reml_control(), gs_repeatability_pedigree_fit() repeatability pedigree REML Specialized two-component reduction oracle; generic construction is a component-LMM recipe
gs_lmm_records(), gs_lmm_component(), gs_lmm_model(), gs_lmm_control(), gs_lmm_fit(), gs_lmm_blup() component LMM Canonical scalar-record compositional engine; identity/pedigree/supplied relationships, hybrid EM-AI, active boundaries, residual blocks, BLUP and uncertainty
gs_balanced_longitudinal_model(), gs_longitudinal_control(), gs_longitudinal_fit() structured longitudinal Specialized matrix-free common-grid workflow
gs_longitudinal_records_model() / gs_longitudinal_fit() record longitudinal Generic matrix-free observed-record workflow; not the pedigree sparse-MME API
gs_multivariate_model(), gs_multivariate_rhe_blup() multivariate covariance/inference Matrix-free complete/unbalanced multivariate workflows, separate from sparse pedigree multitrait
No direct R plan/session object CompiledMmePlan, CompiledMmeSession, gsolve retained direct/selected-inverse sessions Public native primitives consumed by model-specific R adapters; intentionally not serialized as mutable R sessions
No dedicated R constructor SparseIndexedCovarianceModel, SparseIndexedRemlSystem Public native sparse-indexed engine; its standalone native combinations are implemented_unqualified unless a catalogued adapter and focused evidence name them

Named biological models such as permanent environment, litter, herd-year, direct/maternal covariance, random slopes, and reaction norms are component recipes when their relationship and incidence contracts fit gs_lmm_*(). They must not receive duplicate model-specific production engines.

Implemented but unqualified combinations

  • Simultaneous component active boundaries and AR(1)/exponential residual correlation; both mechanisms are qualified separately.
  • Standalone combinations of the public native SparseIndexedCovarianceModel and SparseIndexedRemlSystem that have no matched public R adapter and focused end-to-end qualification.

These are qualification or route-integration gaps, not new global algorithms.

Genuinely unsupported combinations

  • PARDISO selected inversion.
  • Exact selected-inverse PEV from PCG.
  • Cross-component covariance outside channels sharing one relationship group.
  • Active semidefinite boundaries for covariance blocks larger than two, and zero/singular residual covariance.
  • Mixed residual structures in one component fit, heterogeneous temporal marginal scales, ARMA, antedependence, spatial, Matérn, and spatiotemporal residuals.
  • New random-effect levels in prediction rows.
  • Genotype/GRM construction, \(H^{-1}\), and ssGBLUP in the component/pedigree LMM APIs.
  • A general component formula parser; the canonical public component API is constructor-based.

Anti-duplication guard

Future work must not propose selected-inverse infrastructure, selected-inverse trace contractions, bounded retained-factor target solves, complete-MME PEV/reliability, identity/group components, permanent/common environment effects, correlated channels, structured longitudinal residual blocks, scalar/rank-one active boundaries, or existing pedigree/multitrait/longitudinal PCG/direct REML and BLUP as new global capabilities. A future extension must name the exact unsupported or implemented-unqualified cell it changes.

Evidence-based future selection

No additional implementation is needed for longitudinal pedigree CHOLMOD selected inversion or PEV/reliability: that public path is already qualified. Potential bounded future work, if prioritized, is limited to catalogued gaps:

  1. A qualification-only closure for an implemented_unqualified combination, such as component active boundaries together with correlated residual blocks, without adding either mechanism again.
  2. Specialized repeatability uncertainty integration, only if that public convenience route must expose the existing complete-MME machinery rather than using the qualified component recipe.
  3. A genuinely unsupported residual family or prediction contract selected from the catalog, implemented through the existing component and residual abstractions rather than a parallel model engine.

These candidates have no committed implementation schedule. Qualification work should be chosen only when the corresponding public combination is useful.

Scientific recipes and covariance definitions are summarized in model recipes; they do not assign qualification status.