diff --git a/crates/mlsirm-core/src/fitstats.rs b/crates/mlsirm-core/src/fitstats.rs index 2b500fb92..f8c024c4a 100644 --- a/crates/mlsirm-core/src/fitstats.rs +++ b/crates/mlsirm-core/src/fitstats.rs @@ -2978,7 +2978,7 @@ pub fn poly_local_dependence( let z = n_cat - 1; // per-item, per-node category probabilities P_i(a | theta_t) - let (nodes, weights) = crate::quadrature::require_gh_rule(q_theta, "quadrature size")?; + let (nodes, weights) = crate::quadrature::require_gh_rule_unidim(q_theta, "quadrature size")?; let qn = nodes.len(); let mut probs = vec![0.0_f64; n_items * qn * n_cat]; for i in 0..n_items { @@ -3527,7 +3527,7 @@ pub fn poly_m2( } // cumulative-probability tensor S[(i*qn+t)*z + (c-1)] = P(Y_i >= c | theta_t) - let (nodes, weights) = crate::quadrature::require_gh_rule(q_theta, "quadrature size")?; + let (nodes, weights) = crate::quadrature::require_gh_rule_unidim(q_theta, "quadrature size")?; let qn = nodes.len(); let build_cum = |slope: &[f64], cat_params: &[f64]| -> Vec { let mut sc = vec![0.0_f64; n_items * qn * z]; diff --git a/crates/mlsirm-core/src/poly.rs b/crates/mlsirm-core/src/poly.rs index c2b93e159..71020aaa5 100644 --- a/crates/mlsirm-core/src/poly.rs +++ b/crates/mlsirm-core/src/poly.rs @@ -523,7 +523,7 @@ pub fn fit_poly_unidim( } validate_observed_categories(y, observed, n_cat)?; let is_obs = |p: usize, i: usize| observed.map_or(true, |o| o[p * n_items + i]); - let (nodes, weights) = crate::quadrature::require_gh_rule(q_theta, "q_theta")?; + let (nodes, weights) = crate::quadrature::require_gh_rule_unidim(q_theta, "q_theta")?; let log_w: Vec = weights.iter().map(|w| w.ln()).collect(); let qn = nodes.len(); @@ -828,7 +828,7 @@ pub fn fit_nominal( return Err(format!("item {i} has no observed responses")); } } - let (nodes, weights) = crate::quadrature::require_gh_rule(q_theta, "q_theta")?; + let (nodes, weights) = crate::quadrature::require_gh_rule_unidim(q_theta, "q_theta")?; let log_w: Vec = weights.iter().map(|w| w.ln()).collect(); let qn = nodes.len(); @@ -1401,7 +1401,7 @@ pub fn fit_poly_multigroup( } } let is_obs = |p: usize, i: usize| observed.map_or(true, |o| o[p * n_items + i]); - let (nodes, weights) = crate::quadrature::require_gh_rule(q_theta, "q_theta")?; + let (nodes, weights) = crate::quadrature::require_gh_rule_unidim(q_theta, "q_theta")?; let log_w: Vec = weights.iter().map(|w| w.ln()).collect(); let qn = nodes.len(); @@ -2209,7 +2209,7 @@ pub fn score_poly_eap( } } let is_obs = |p: usize, i: usize| observed.map_or(true, |o| o[p * n_items + i]); - let (nodes, weights) = crate::quadrature::require_gh_rule(q_theta, "q_theta")?; + let (nodes, weights) = crate::quadrature::require_gh_rule_unidim(q_theta, "q_theta")?; let log_w: Vec = weights.iter().map(|w| w.ln()).collect(); let qn = nodes.len(); let scores: Vec = (0..n_cat).map(|c| c as f64).collect(); @@ -2353,7 +2353,7 @@ pub fn poly_s_x2( let z = n_cat - 1; // highest category score Z let f_max = n_items * z; // perfect summed score F - let (nodes, weights) = crate::quadrature::require_gh_rule(q_theta, "q_theta")?; + let (nodes, weights) = crate::quadrature::require_gh_rule_unidim(q_theta, "q_theta")?; let qn = nodes.len(); // per-item category probabilities at each node: probs[(i*qn + t)*n_cat + zc] diff --git a/crates/mlsirm-core/src/poly_marginal.rs b/crates/mlsirm-core/src/poly_marginal.rs index fa88e091a..6149df7ce 100644 --- a/crates/mlsirm-core/src/poly_marginal.rs +++ b/crates/mlsirm-core/src/poly_marginal.rs @@ -249,7 +249,7 @@ pub fn fit_poly_lsirm( } } } - let (theta, t_w) = crate::quadrature::require_gh_rule(q_theta, "q_theta")?; + let (theta, t_w) = crate::quadrature::require_gh_rule_unidim(q_theta, "q_theta")?; let t_logw: Vec = t_w.iter().map(|w| w.ln()).collect(); let (xi_grid, x_logw) = xi_tensor_grid(q_xi, latent_dim)?; let n_xi = x_logw.len(); diff --git a/crates/mlsirm-core/src/quadrature.rs b/crates/mlsirm-core/src/quadrature.rs index f3260c459..c0d93f755 100644 --- a/crates/mlsirm-core/src/quadrature.rs +++ b/crates/mlsirm-core/src/quadrature.rs @@ -277,8 +277,287 @@ pub(crate) const GH_WEIGHTS_41: [f64; 41] = [ 8.308558938782659e-26, 2.2578639565831077e-30, ]; +pub(crate) const GH_NODES_81: [f64; 81] = [ + -16.925476835034505, + -16.070115288084143, + -15.363360220077677, + -14.73368054299171, + -14.153774548779939, + -13.609582762216585, + -13.092675857688906, + -12.597501586482979, + -12.120159198016569, + -11.657775826461798, + -11.208157786358138, + -10.769581337343361, + -10.340660046957302, + -9.9202569218315535, + -9.5074240510437793, + -9.101359871906519, + -8.7013781230942584, + -8.3068847821466427, + -7.9173605988965079, + -7.5323476392102702, + -7.1514387595211675, + -6.7742692606393824, + -6.4005101871838912, + -6.0298628868802302, + -5.6620545463576697, + -5.296834492223109, + -4.9339710978387394, + -4.573249173746504, + -4.2144677472925451, + -3.8574381575682382, + -3.5019824072656451, + -3.1479317248132901, + -2.7951252991803441, + -2.4434091567047238, + -2.0926351547129305, + -1.7426600709209537, + -1.3933447709042779, + -1.0445534384991042, + -0.69615285599343169, + -0.34801172249465351, + 0.0, + 0.34801172249465351, + 0.69615285599343169, + 1.0445534384991042, + 1.3933447709042779, + 1.7426600709209537, + 2.0926351547129305, + 2.4434091567047238, + 2.7951252991803441, + 3.1479317248132901, + 3.5019824072656451, + 3.8574381575682382, + 4.2144677472925451, + 4.573249173746504, + 4.9339710978387394, + 5.296834492223109, + 5.6620545463576697, + 6.0298628868802302, + 6.4005101871838912, + 6.7742692606393824, + 7.1514387595211675, + 7.5323476392102702, + 7.9173605988965079, + 8.3068847821466427, + 8.7013781230942584, + 9.101359871906519, + 9.5074240510437793, + 9.9202569218315535, + 10.340660046957302, + 10.769581337343361, + 11.208157786358138, + 11.657775826461798, + 12.120159198016569, + 12.597501586482979, + 13.092675857688906, + 13.609582762216585, + 14.153774548779939, + 14.73368054299171, + 15.363360220077677, + 16.070115288084143, + 16.925476835034505, +]; +pub(crate) const GH_WEIGHTS_81: [f64; 81] = [ + 2.4528055138979769e-63, + 2.5392599790110647e-57, + 1.4715361059410395e-52, + 1.7446471278413031e-48, + 7.0530127309631424e-45, + 1.2721951837934705e-41, + 1.2063175236617348e-38, + 6.7090375039002427e-36, + 2.3656319313870077e-33, + 5.6033548723345991e-31, + 9.3216634799383481e-29, + 1.1281327190756607e-26, + 1.0218473057257003e-24, + 7.0910770254680374e-23, + 3.844131066500376e-21, + 1.6549612938551538e-19, + 5.7382219378320453e-18, + 1.6218666315382721e-16, + 3.7761924960082651e-15, + 7.3091912739458981e-14, + 1.1856329334260767e-12, + 1.6232084074369437e-11, + 1.8874073283497914e-10, + 1.8743179035614513e-09, + 1.5975703422328164e-08, + 1.1739104500747906e-07, + 7.4658706303601696e-07, + 4.1240539582658024e-06, + 1.9848557310766824e-05, + 8.3465497037017855e-05, + 0.00030742200906347524, + 0.00099395000039951783, + 0.0028263907639617886, + 0.0070805561570686021, + 0.015649455812784971, + 0.030553610014116196, + 0.052747541031847783, + 0.080589300110354159, + 0.10903458212018821, + 0.13069487488539799, + 0.13882799390429282, + 0.13069487488539799, + 0.10903458212018821, + 0.080589300110354159, + 0.052747541031847783, + 0.030553610014116196, + 0.015649455812784971, + 0.0070805561570686021, + 0.0028263907639617886, + 0.00099395000039951783, + 0.00030742200906347524, + 8.3465497037017855e-05, + 1.9848557310766824e-05, + 4.1240539582658024e-06, + 7.4658706303601696e-07, + 1.1739104500747906e-07, + 1.5975703422328164e-08, + 1.8743179035614513e-09, + 1.8874073283497914e-10, + 1.6232084074369437e-11, + 1.1856329334260767e-12, + 7.3091912739458981e-14, + 3.7761924960082651e-15, + 1.6218666315382721e-16, + 5.7382219378320453e-18, + 1.6549612938551538e-19, + 3.844131066500376e-21, + 7.0910770254680374e-23, + 1.0218473057257003e-24, + 1.1281327190756607e-26, + 9.3216634799383481e-29, + 5.6033548723345991e-31, + 2.3656319313870077e-33, + 6.7090375039002427e-36, + 1.2063175236617348e-38, + 1.2721951837934705e-41, + 7.0530127309631424e-45, + 1.7446471278413031e-48, + 1.4715361059410395e-52, + 2.5392599790110647e-57, + 2.4528055138979769e-63, +]; + + +use std::sync::OnceLock; + +// The dense rule is intentionally separate: multidimensional tensor grids keep +// the legacy supported set so q in {61, 81} cannot create an accidental dense tensor grid. +// +// Golub, G. H., & Welsch, J. H. (1969). Calculation of Gauss quadrature rules. +// Mathematics of Computation, 23(106), 221–230. +// https://doi.org/10.1090/S0025-5718-69-99647-1. Their n-node Gaussian rule is +// exact for weighted polynomials through degree 2n-1. Bock, R. D., & Aitkin, +// M. (1981). Marginal maximum likelihood estimation of item parameters: +// Application of an EM algorithm. Psychometrika, 46(4), 443–459. +// https://doi.org/10.1007/BF02293801. Together these sources support q in +// {61, 81} as denser fixed approximations to the existing unidimensional +// standard-normal expectations used by calibration and diagnostics, not as +// adaptive error guarantees or multidimensional tensor-grid rules. + +static GH_61: OnceLock<(Vec, Vec)> = OnceLock::new(); + +static GH_81: OnceLock<(Vec, Vec)> = OnceLock::new(); + +fn gh_rule_81() -> (&'static [f64], &'static [f64]) { + let (nodes, weights) = GH_81.get_or_init(|| (GH_NODES_81.to_vec(), GH_WEIGHTS_81.to_vec())); + (nodes, weights) +} + +fn gh_rule_61() -> (&'static [f64], &'static [f64]) { + let (nodes, weights) = GH_61.get_or_init(|| { + // Generated from numpy.polynomial.hermite_e.hermegauss(61), normalized. + let positive = [ + 0.0, + 0.40063821105995046, + 0.80153826303172659, + 1.2029642303011723, + 1.6051847101182257, + 2.008475226640472, + 2.4131208142506848, + 2.8194188542255731, + 3.2276822527149105, + 3.638243067606806, + 4.0514567191649027, + 4.4677069572407992, + 4.8874118107487146, + 5.3110308195370264, + 5.7390739549506931, + 6.1721127891630712, + 6.6107947002797749, + 7.055861242232579, + 7.5081723365509907, + 7.9687387811758628, + 8.4387669441217881, + 8.9197218412129384, + 9.4134189285095022, + 9.9221626372550862, + 10.448964909729462, + 10.997909441340786, + 11.574803203521677, + 12.188457192776552, + 12.853564295912951, + 13.598659156615788, + 14.498533915900149, + ]; + let positive_weights = [ + 0.1598141411777855, + 0.14753749310915876, + 0.11605765134525153, + 0.077742307060467822, + 0.044299190141556276, + 0.021440700089215427, + 0.0087970077780564638, + 0.0030522259632903151, + 0.00089286291334885349, + 0.00021942509449102729, + 4.5111525791571688e-05, + 7.7204093582151049e-06, + 1.0935537165661111e-06, + 1.2734244397327087e-07, + 1.209624282534318e-08, + 9.2880342218154687e-10, + 5.7039803251286501e-11, + 2.7668880796351234e-12, + 1.0446062071534655e-13, + 3.015866131841913e-15, + 6.5184766419075028e-17, + 1.0277368048053688e-18, + 1.1444908106729494e-20, + 8.6411169244947458e-23, + 4.193948417922687e-25, + 1.2179530564067127e-27, + 1.9132142558327285e-30, + 1.3977653698327285e-33, + 3.7088060732095731e-37, + 2.2364824894989637e-41, + 9.3712287678837323e-47, + ]; + let mut nodes = positive + .iter() + .skip(1) + .rev() + .map(|x| -*x) + .collect::>(); + nodes.extend_from_slice(&positive); + let mut weights = positive_weights + .iter() + .skip(1) + .rev() + .copied() + .collect::>(); + weights.extend_from_slice(&positive_weights); + (nodes, weights) + }); + (nodes, weights) +} -/// Look up the embedded rule for `q` nodes; `None` when unsupported. pub(crate) fn gh_rule(q: usize) -> Option<(&'static [f64], &'static [f64])> { match q { 7 => Some((&GH_NODES_7, &GH_WEIGHTS_7)), @@ -291,6 +570,14 @@ pub(crate) fn gh_rule(q: usize) -> Option<(&'static [f64], &'static [f64])> { } } +pub(crate) fn gh_rule_unidim(q: usize) -> Option<(&'static [f64], &'static [f64])> { + match q { + 61 => Some(gh_rule_61()), + 81 => Some(gh_rule_81()), + _ => gh_rule(q), + } +} + /// Resolve an embedded rule with a consistent public-validation error. pub(crate) fn require_gh_rule( q: usize, @@ -302,6 +589,16 @@ pub(crate) fn require_gh_rule( } } +pub(crate) fn require_gh_rule_unidim( + q: usize, + name: &str, +) -> Result<(&'static [f64], &'static [f64]), String> { + match gh_rule_unidim(q) { + Some(rule) => Ok(rule), + None => Err(format!("unsupported {name} {q}")), + } +} + pub(crate) const SUPPORTED_Q: [usize; 6] = [7, 11, 15, 21, 31, 41]; #[cfg(test)] diff --git a/python/fast_mlsirm/polytomous.py b/python/fast_mlsirm/polytomous.py index 91e1bbc50..31a1d9053 100644 --- a/python/fast_mlsirm/polytomous.py +++ b/python/fast_mlsirm/polytomous.py @@ -41,7 +41,8 @@ MAX_POLY_QUADRATURE_POINTS = 4_096 MAX_POLY_BOOTSTRAP_REPLICATES = 10_000 MAX_POLY_CAT_ITEMS = 10_000 -_SUPPORTED_FIT_QUADRATURE_POINTS = (7, 11, 15, 21, 31, 41) +_SUPPORTED_FIT_QUADRATURE_POINTS = (7, 11, 15, 21, 31, 41, 61, 81) +_SUPPORTED_XI_QUADRATURE_POINTS = (7, 11, 15, 21, 31, 41) _NUMPY_INTEGER_SCALAR_TYPES = ( np.int8, np.int16, @@ -81,8 +82,8 @@ def _bounded_integer(value, name: str, lower: int, upper: int) -> int: def _quadrature_points(value) -> int: - """Validate and return the Gauss-Hermite quadrature node count ``q_theta``.""" - return _bounded_integer(value, "q_theta", 1, MAX_POLY_QUADRATURE_POINTS) + """Backward-compatible alias for the supported unidimensional rule set.""" + return _fit_quadrature_points(value) def _fit_quadrature_points(value) -> int: @@ -93,9 +94,23 @@ def _fit_quadrature_points(value) -> int: elif _is_exact_type(value_type, _NUMPY_INTEGER_SCALAR_TYPES): validated = int(value) else: - raise ValueError("q_theta must be one of 7, 11, 15, 21, 31, 41") + raise ValueError("q_theta must be one of 7, 11, 15, 21, 31, 41, 61, 81") if validated not in _SUPPORTED_FIT_QUADRATURE_POINTS: - raise ValueError("q_theta must be one of 7, 11, 15, 21, 31, 41") + raise ValueError("q_theta must be one of 7, 11, 15, 21, 31, 41, 61, 81") + return validated + + +def _fit_xi_quadrature_points(value) -> int: + """Validate the bounded tensor-grid node count for latent-space ``xi``.""" + value_type = type(value) + if value_type is int: + validated = value + elif _is_exact_type(value_type, _NUMPY_INTEGER_SCALAR_TYPES): + validated = int(value) + else: + raise ValueError("q_xi must be one of 7, 11, 15, 21, 31, 41") + if validated not in _SUPPORTED_XI_QUADRATURE_POINTS: + raise ValueError("q_xi must be one of 7, 11, 15, 21, 31, 41") return validated @@ -539,9 +554,13 @@ def fit_lsirm_polytomous( raise ValueError("latent_dim must be an integer in 1..3") from exc try: validated_q_theta = _fit_quadrature_points(q_theta) - validated_q_xi = _fit_quadrature_points(q_xi) + validated_q_xi = _fit_xi_quadrature_points(q_xi) except ValueError as exc: - raise ValueError("q_theta/q_xi must be one of 7, 11, 15, 21, 31, 41") from exc + raise ValueError( + "q_theta/q_xi must be one of the supported rules; " + "q_theta must be one of 7, 11, 15, 21, 31, 41, 61, 81; " + "q_xi must be one of 7, 11, 15, 21, 31, 41" + ) from exc validated_max_iter = _bounded_integer(max_iter, "max_iter", 1, MAX_MAX_ITER) validated_tol = _positive_real(tol, "tol") @@ -671,7 +690,7 @@ def item_fit_polytomous( """ n_items = fit.slope.shape[0] n_cat = fit.cat_params.shape[1] + 1 - q_theta = _quadrature_points(q_theta) + q_theta = _fit_quadrature_points(q_theta) if not np.isfinite(min_expected) or min_expected <= 0: raise ValueError("min_expected must be positive") y_int, observed = _poly_int_and_mask(responses, n_cat) @@ -732,7 +751,7 @@ def m2_polytomous( categorical data analysis. *Multivariate Behavioral Research, 49*(4), 305-328. https://doi.org/10.1080/00273171.2014.911075 """ - q_theta = _quadrature_points(q_theta) + q_theta = _fit_quadrature_points(q_theta) if hasattr(fit, "converged") and not bool(fit.converged): reason = getattr(fit, "termination_reason", "unknown") n_iter = getattr(fit, "n_iter", "unknown") @@ -801,7 +820,7 @@ def local_dependence_polytomous( """ n_items = fit.slope.shape[0] n_cat = fit.cat_params.shape[1] + 1 - q_theta = _quadrature_points(q_theta) + q_theta = _fit_quadrature_points(q_theta) y_int, observed = _poly_int_and_mask(responses, n_cat) if y_int.shape[1] != n_items: raise ValueError("responses column count must match the fitted item count") @@ -960,7 +979,7 @@ def person_fit_polytomous( """ n_items = fit.slope.shape[0] n_cat = fit.cat_params.shape[1] + 1 - q_theta = _quadrature_points(q_theta) + q_theta = _fit_quadrature_points(q_theta) if not np.isfinite(prior_mean): raise ValueError("prior_mean must be finite") if not np.isfinite(prior_sd) or prior_sd <= 0: @@ -1030,7 +1049,7 @@ def cat_simulate_polytomous( tt = np.asarray(true_theta, dtype=np.float64).ravel() if tt.size == 0 or not np.all(np.isfinite(tt)): raise ValueError("true_theta must be a non-empty finite 1-D array") - q_theta = _quadrature_points(q_theta) + q_theta = _fit_quadrature_points(q_theta) min_items = _bounded_integer(min_items, "min_items", 1, MAX_POLY_CAT_ITEMS) max_items = _bounded_integer(max_items, "max_items", min_items, MAX_POLY_CAT_ITEMS) effective_max_items = min(max_items, n_items) diff --git a/tests/test_cov_e_polytomous.py b/tests/test_cov_e_polytomous.py index 3e814ed43..43355add7 100644 --- a/tests/test_cov_e_polytomous.py +++ b/tests/test_cov_e_polytomous.py @@ -87,6 +87,19 @@ def test_fit_polytomous_rejects_bad_q_theta(): fit_polytomous(_responses(4, 2, 3), n_cat=3, q_theta=12) +def test_fit_polytomous_accepts_81_node_rule(): + fit = fit_polytomous(_responses(6, 2, 3), n_cat=3, q_theta=81, max_iter=1) + assert fit.slope.shape == (2,) + assert np.isfinite(fit.loglik) + + +def test_fit_lsirm_rejects_81_node_xi_rule(): + with pytest.raises(ValueError, match="q_theta/q_xi must be one of"): + fit_lsirm_polytomous( + _responses(4, 2, 3), n_cat=3, q_theta=81, q_xi=81, max_iter=1 + ) + + def test_fit_polytomous_requires_core(monkeypatch): monkeypatch.setattr(polytomous, "_core_module", lambda: None) with pytest.raises(RuntimeError, match="requires the compiled Rust core"): diff --git a/tests/unit/fitstats_tests.rs b/tests/unit/fitstats_tests.rs index d9139e290..ada5525c5 100644 --- a/tests/unit/fitstats_tests.rs +++ b/tests/unit/fitstats_tests.rs @@ -226,6 +226,22 @@ fn sx2_rejects_malformed_bank_controls_and_weights() { .err() .expect("expected invalid fdr error"); assert!(err.contains("fdr_q"), "got: {err}"); + + let err = s_x2( + &valid_bank, + &y, + &observed, + 2000, + &PriorSpec::standard(1), + &SX2Config { + q_theta: 61, + ..Default::default() + }, + None, + ) + .err() + .expect("binary S-X2 must preserve the bounded quadrature contract"); + assert_eq!(err, "unsupported quadrature size 61"); } #[test] diff --git a/tests/unit/quadrature_tests.rs b/tests/unit/quadrature_tests.rs index 1a3bec21d..392289aa3 100644 --- a/tests/unit/quadrature_tests.rs +++ b/tests/unit/quadrature_tests.rs @@ -9,4 +9,31 @@ fn required_rule_covers_success_and_error_contracts() { require_gh_rule(8, "quadrature size").unwrap_err(), "unsupported quadrature size 8" ); + assert!(crate::quadrature::gh_rule(61).is_none()); +} + +#[test] +fn dense_unidimensional_rule_is_normalized_and_symmetric() { + for q in [61, 81] { + let (nodes, weights) = crate::quadrature::gh_rule_unidim(q).unwrap(); + assert_eq!(nodes.len(), q); + assert_eq!(weights.len(), q); + assert!((weights.iter().sum::() - 1.0).abs() < 1e-14); + let second = nodes + .iter() + .zip(weights) + .map(|(node, weight)| weight * node.powi(2)) + .sum::(); + let fourth = nodes + .iter() + .zip(weights) + .map(|(node, weight)| weight * node.powi(4)) + .sum::(); + assert!((second - 1.0).abs() < 1e-14); + assert!((fourth - 3.0).abs() < 1e-12); + for i in 0..q { + assert!((nodes[i] + nodes[q - 1 - i]).abs() < 1e-14); + assert!((weights[i] - weights[q - 1 - i]).abs() < 1e-14); + } + } }