plurimath 0.11.16 → 0.11.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/dependent-tests.yml +2 -2
  3. data/.github/workflows/docs.yml +26 -0
  4. data/.github/workflows/gum-reference.yml +48 -0
  5. data/.github/workflows/performance-ci-legs.yml +54 -0
  6. data/.github/workflows/performance.yml +99 -0
  7. data/.github/workflows/roundtrip-cases.yml +33 -0
  8. data/.rubocop_todo.yml +0 -138
  9. data/Gemfile +13 -0
  10. data/Rakefile +2 -0
  11. data/docs/asciimath.adoc +578 -0
  12. data/docs/core-model-contract.adoc +748 -0
  13. data/docs/gum-evaluation.adoc +368 -0
  14. data/docs/latex.adoc +335 -0
  15. data/docs/mathml.adoc +638 -0
  16. data/docs/native-evaluation-request.md +28 -0
  17. data/docs/numeric-request.md +19 -0
  18. data/docs/omml.adoc +589 -0
  19. data/docs/performance-contract.adoc +279 -0
  20. data/docs/pma.adoc +949 -0
  21. data/docs/quantity-request.md +19 -0
  22. data/docs/uncertainty-asciimath-tree.md +2 -3
  23. data/docs/uncertainty.adoc +401 -425
  24. data/docs/unicodemath.adoc +453 -0
  25. data/docs/unitsml.adoc +414 -0
  26. data/lib/plurimath/asciimath/constants.rb +0 -98
  27. data/lib/plurimath/asciimath/mapper/rules.rb +1400 -0
  28. data/lib/plurimath/asciimath/mapper.rb +148 -0
  29. data/lib/plurimath/asciimath/parse.rb +26 -18
  30. data/lib/plurimath/asciimath/parser.rb +25 -11
  31. data/lib/plurimath/asciimath/slice_adapter.rb +1 -1
  32. data/lib/plurimath/asciimath.rb +1 -1
  33. data/lib/plurimath/catalog.rb +4 -5
  34. data/lib/plurimath/cli/convert.rb +3 -2
  35. data/lib/plurimath/cli.rb +2 -1
  36. data/lib/plurimath/configuration.rb +3 -0
  37. data/lib/plurimath/evaluation_request/quantity.rb +254 -0
  38. data/lib/plurimath/evaluation_request.rb +160 -0
  39. data/lib/plurimath/latex/constants.rb +0 -84
  40. data/lib/plurimath/latex/mapper.rb +418 -0
  41. data/lib/plurimath/latex/parse.rb +28 -288
  42. data/lib/plurimath/latex/parser.rb +49 -4
  43. data/lib/plurimath/latex.rb +1 -1
  44. data/lib/plurimath/math/core.rb +266 -1
  45. data/lib/plurimath/math/evaluation/accuracy.rb +62 -0
  46. data/lib/plurimath/math/evaluation/calibration.rb +85 -0
  47. data/lib/plurimath/math/evaluation/compiled_polynomial.rb +99 -0
  48. data/lib/plurimath/math/evaluation/compiled_rational.rb +131 -0
  49. data/lib/plurimath/math/evaluation/conformity.rb +133 -0
  50. data/lib/plurimath/math/evaluation/correlated_normal_sampler.rb +74 -0
  51. data/lib/plurimath/math/evaluation/covariance.rb +173 -0
  52. data/lib/plurimath/math/evaluation/distribution_sampler.rb +126 -0
  53. data/lib/plurimath/math/evaluation/evaluator.rb +236 -22
  54. data/lib/plurimath/math/evaluation/grouped_statistics.rb +56 -0
  55. data/lib/plurimath/math/evaluation/gum.rb +410 -0
  56. data/lib/plurimath/math/evaluation/implicit_model.rb +66 -0
  57. data/lib/plurimath/math/evaluation/monte_carlo.rb +198 -0
  58. data/lib/plurimath/math/evaluation/quantity_evaluator.rb +127 -0
  59. data/lib/plurimath/math/evaluation/result.rb +45 -0
  60. data/lib/plurimath/math/evaluation/statistics.rb +102 -0
  61. data/lib/plurimath/math/evaluation/taylor.rb +162 -0
  62. data/lib/plurimath/math/evaluation/wichmann_hill.rb +40 -0
  63. data/lib/plurimath/math/evaluation.rb +22 -0
  64. data/lib/plurimath/math/formula/mrow.rb +6 -1
  65. data/lib/plurimath/math/formula.rb +22 -4
  66. data/lib/plurimath/math/function/abs.rb +3 -1
  67. data/lib/plurimath/math/function/arccos.rb +1 -1
  68. data/lib/plurimath/math/function/arcsin.rb +1 -1
  69. data/lib/plurimath/math/function/arctan.rb +1 -1
  70. data/lib/plurimath/math/function/bar.rb +2 -1
  71. data/lib/plurimath/math/function/base.rb +2 -1
  72. data/lib/plurimath/math/function/binary_function.rb +1 -1
  73. data/lib/plurimath/math/function/ceil.rb +3 -1
  74. data/lib/plurimath/math/function/color.rb +2 -1
  75. data/lib/plurimath/math/function/cos.rb +1 -1
  76. data/lib/plurimath/math/function/cosh.rb +1 -1
  77. data/lib/plurimath/math/function/cot.rb +1 -1
  78. data/lib/plurimath/math/function/coth.rb +1 -1
  79. data/lib/plurimath/math/function/csc.rb +1 -1
  80. data/lib/plurimath/math/function/csch.rb +1 -1
  81. data/lib/plurimath/math/function/ddot.rb +2 -1
  82. data/lib/plurimath/math/function/dot.rb +2 -1
  83. data/lib/plurimath/math/function/exp.rb +1 -1
  84. data/lib/plurimath/math/function/fenced.rb +5 -3
  85. data/lib/plurimath/math/function/floor.rb +3 -1
  86. data/lib/plurimath/math/function/font_style/bold.rb +1 -1
  87. data/lib/plurimath/math/function/font_style/double_struck.rb +1 -1
  88. data/lib/plurimath/math/function/font_style/fraktur.rb +1 -1
  89. data/lib/plurimath/math/function/font_style/italic.rb +1 -1
  90. data/lib/plurimath/math/function/font_style/monospace.rb +1 -1
  91. data/lib/plurimath/math/function/font_style/normal.rb +22 -1
  92. data/lib/plurimath/math/function/font_style/sans-serif.rb +1 -1
  93. data/lib/plurimath/math/function/font_style/script.rb +1 -1
  94. data/lib/plurimath/math/function/frac.rb +2 -1
  95. data/lib/plurimath/math/function/hat.rb +2 -1
  96. data/lib/plurimath/math/function/int.rb +3 -2
  97. data/lib/plurimath/math/function/lg.rb +1 -1
  98. data/lib/plurimath/math/function/linebreak.rb +2 -1
  99. data/lib/plurimath/math/function/ln.rb +1 -1
  100. data/lib/plurimath/math/function/log.rb +4 -1
  101. data/lib/plurimath/math/function/longdiv.rb +3 -0
  102. data/lib/plurimath/math/function/mpadded.rb +2 -1
  103. data/lib/plurimath/math/function/msgroup.rb +3 -0
  104. data/lib/plurimath/math/function/multiscript.rb +4 -0
  105. data/lib/plurimath/math/function/nary.rb +9 -3
  106. data/lib/plurimath/math/function/norm.rb +3 -1
  107. data/lib/plurimath/math/function/obrace.rb +2 -1
  108. data/lib/plurimath/math/function/oint.rb +3 -2
  109. data/lib/plurimath/math/function/overleftrightarrow.rb +2 -1
  110. data/lib/plurimath/math/function/overset.rb +2 -1
  111. data/lib/plurimath/math/function/power.rb +1 -1
  112. data/lib/plurimath/math/function/power_base.rb +1 -1
  113. data/lib/plurimath/math/function/prod.rb +3 -2
  114. data/lib/plurimath/math/function/sec.rb +1 -1
  115. data/lib/plurimath/math/function/sech.rb +1 -1
  116. data/lib/plurimath/math/function/semantics.rb +35 -0
  117. data/lib/plurimath/math/function/sin.rb +1 -1
  118. data/lib/plurimath/math/function/sinh.rb +1 -1
  119. data/lib/plurimath/math/function/sqrt.rb +3 -2
  120. data/lib/plurimath/math/function/sum.rb +3 -2
  121. data/lib/plurimath/math/function/table/align.rb +1 -1
  122. data/lib/plurimath/math/function/table/bmatrix.rb +1 -1
  123. data/lib/plurimath/math/function/table/cases.rb +4 -0
  124. data/lib/plurimath/math/function/table/multline.rb +1 -1
  125. data/lib/plurimath/math/function/table/pmatrix.rb +1 -1
  126. data/lib/plurimath/math/function/table/split.rb +1 -1
  127. data/lib/plurimath/math/function/table/vmatrix.rb +1 -1
  128. data/lib/plurimath/math/function/table.rb +19 -2
  129. data/lib/plurimath/math/function/tan.rb +1 -1
  130. data/lib/plurimath/math/function/tanh.rb +1 -1
  131. data/lib/plurimath/math/function/td.rb +4 -0
  132. data/lib/plurimath/math/function/ternary_function.rb +2 -2
  133. data/lib/plurimath/math/function/text.rb +3 -0
  134. data/lib/plurimath/math/function/tilde.rb +2 -1
  135. data/lib/plurimath/math/function/tr.rb +3 -0
  136. data/lib/plurimath/math/function/ubrace.rb +2 -1
  137. data/lib/plurimath/math/function/ul.rb +2 -1
  138. data/lib/plurimath/math/function/unary_function.rb +1 -1
  139. data/lib/plurimath/math/function/uncertainty.rb +26 -11
  140. data/lib/plurimath/math/function/underset.rb +2 -1
  141. data/lib/plurimath/math/function/unitsml.rb +18 -6
  142. data/lib/plurimath/math/function/vec.rb +2 -1
  143. data/lib/plurimath/math/number.rb +30 -12
  144. data/lib/plurimath/math/symbol_index.rb +10254 -0
  145. data/lib/plurimath/math/symbol_table.rb +89 -0
  146. data/lib/plurimath/math/symbols/paren.rb +7 -0
  147. data/lib/plurimath/math/symbols/symbol.rb +30 -3
  148. data/lib/plurimath/math/symbols.rb +81 -5
  149. data/lib/plurimath/math.rb +8 -0
  150. data/lib/plurimath/mathml/parser.rb +2 -0
  151. data/lib/plurimath/mathml/translator.rb +17 -3
  152. data/lib/plurimath/native_kernel.rb +64 -0
  153. data/lib/plurimath/omml/parser.rb +1 -0
  154. data/lib/plurimath/omml/translator.rb +2 -1
  155. data/lib/plurimath/pma.rb +19 -0
  156. data/lib/plurimath/unicode_math/constants.rb +0 -258
  157. data/lib/plurimath/unicode_math/mapper/capture_order.rb +142 -0
  158. data/lib/plurimath/unicode_math/mapper/rules.rb +4086 -0
  159. data/lib/plurimath/unicode_math/mapper.rb +146 -0
  160. data/lib/plurimath/unicode_math/parse.rb +54 -294
  161. data/lib/plurimath/unicode_math/parser.rb +71 -2
  162. data/lib/plurimath/unicode_math.rb +1 -2
  163. data/lib/plurimath/unitsml.rb +0 -1
  164. data/lib/plurimath/utility.rb +34 -12
  165. data/lib/plurimath/version.rb +1 -1
  166. data/lib/plurimath.rb +42 -3
  167. data/plurimath.gemspec +3 -1
  168. data/scripts/check_gum_references.rb +69 -0
  169. data/scripts/check_suite_budget.rb +329 -0
  170. data/scripts/docs/asciimath_tables.rb +363 -0
  171. data/scripts/docs/core_inventory.rb +432 -0
  172. data/scripts/docs/format_specs.rb +672 -0
  173. data/scripts/generate_symbol_index.rb +118 -0
  174. data/scripts/measure_require.rb +362 -0
  175. data/scripts/replay_asciimath_corpus.rb +7 -7
  176. data/scripts/replay_stage_roundtrips.rb +242 -0
  177. data/scripts/require_baseline.json +34 -0
  178. data/scripts/roundtrip_cases.rb +462 -0
  179. metadata +97 -16
  180. data/lib/plurimath/asciimath/transform.rb +0 -1395
  181. data/lib/plurimath/latex/transform.rb +0 -1006
  182. data/lib/plurimath/unicode_math/parsing_rules/absence_rules.rb +0 -150
  183. data/lib/plurimath/unicode_math/parsing_rules/common_rules.rb +0 -136
  184. data/lib/plurimath/unicode_math/parsing_rules/constants_rules.rb +0 -136
  185. data/lib/plurimath/unicode_math/parsing_rules/helper.rb +0 -13
  186. data/lib/plurimath/unicode_math/parsing_rules/masked.rb +0 -84
  187. data/lib/plurimath/unicode_math/parsing_rules/sub_sup.rb +0 -281
  188. data/lib/plurimath/unicode_math/parsing_rules.rb +0 -14
  189. data/lib/plurimath/unicode_math/transform.rb +0 -4058
@@ -0,0 +1,368 @@
1
+ = Uncertainty propagation and measurement statistics
2
+
3
+ `Plurimath::Math::Evaluation::Gum` accepts explicit estimates, component
4
+ variances and analytic sensitivity coefficients in one coherent unit system.
5
+ `analyze` derives exact first, second and third derivatives of an existing
6
+ Formula with polynomial/rational arithmetic and integer powers. It reuses
7
+ the existing expression parser. Unsupported function derivatives are refused;
8
+ there is no finite-difference Hessian fallback. Neither entrypoint infers
9
+ units or independence.
10
+
11
+ [source,ruby]
12
+ ----
13
+ gum = Plurimath::Math::Evaluation::Gum
14
+ component = gum.component(distribution: :rectangular, half_width: "0.3")
15
+ result = gum.propagate(estimate: "12.3", components: [component],
16
+ gradient: [1], independent: true, guard_digits: 30)
17
+ result[:variance] # => (3/100)
18
+ result[:standard_uncertainty] # BigDecimal, declared precision
19
+ ----
20
+
21
+ Inputs accept integers, rationals, decimal strings and finite BigDecimal
22
+ values. Binary Float input is refused. `type_a(observations)` reports count,
23
+ mean, extrema, sample variance, variance of the mean and degrees of freedom.
24
+ A rectangular, triangular or arcsine component takes a half-width. Curvilinear trapezoid additionally takes
25
+ `boundary_half_width: d`, with `0 < d < half_width`, giving variance
26
+ `half_width^2/3 + d^2/9` (JCGM 101 6.4.3.4); a normal
27
+ component takes a standard uncertainty. Student-t takes its scale and degrees
28
+ of freedom, giving variance `scale^2 * nu/(nu-2)`; `nu <= 2` is refused.
29
+
30
+ First-order propagation gives the sum of squared sensitivities times input
31
+ variances. Optional positive component degrees of freedom give the
32
+ Welch-Satterthwaite effective degrees of freedom. An omitted value denotes
33
+ infinite degrees of freedom; a returned nil means the denominator is zero.
34
+ This does not choose a coverage factor or assess LPU adequacy.
35
+
36
+ For `order: 2`, all components must explicitly declare `distribution: :normal`.
37
+ Supply a complete symmetric `hessian` matrix and `third` rank-three tensor,
38
+ plus `derivatives_complete: true`. The estimate includes half the diagonal
39
+ Hessian contraction. The variance includes both the Hessian-square and
40
+ first-times-third derivative terms in JCGM 100:2008 5.1.2 note. A Hessian
41
+ alone is insufficient: `f(x)=x+x^3` at zero has a zero Hessian and a nonzero
42
+ order-four variance correction. Every derivative entry, including zeros,
43
+ must be supplied. Unsupported joint dependence, nonnormal GUF2, incomplete
44
+ derivatives and negative approximated variance raise a named error.
45
+
46
+ [source,ruby]
47
+ ----
48
+ formula = Plurimath::Math.parse("x+x^3", :asciimath)
49
+ result = gum.analyze(formula, estimates: { x: 0 },
50
+ components: { x: { variance: "0.01", distribution: :normal } },
51
+ independent: true, order: 2, guard_digits: 40)
52
+ result[:variance] # => (53/5000), including the first-times-third term
53
+ ----
54
+
55
+ The estimate and component hashes must have identical ordered variable keys.
56
+ Results identify the engine version and method revision. They retain exact
57
+ rational variances and BigDecimal standard uncertainties; this is a Ruby API,
58
+ not the complete serialized cross-runtime evaluator contract.
59
+
60
+ == H.1 conventions and verification
61
+
62
+ The fixture records four distinct source conventions: rounded GUM 100 H.1
63
+ standard uncertainties, unrounded H.1 source components, JCGM 101 Table 10
64
+ PDF population moments, and GUM 5:2026 Table 8.1 PDF population moments.
65
+ These are different inputs and produce different uncertainties. The tests
66
+ use explicitly synthetic independent normal inputs with each variance set
67
+ to check the Taylor contraction; they refuse the actual nonnormal H.1 PDFs.
68
+ No assertion forces the original 34 nm result to equal the amended 36 nm
69
+ result within 0.5 nm. A special multi-affine moment identity does not remove
70
+ the general normality restriction.
71
+
72
+ Run `python3 spec/support/gum_h1_reference.py` to regenerate the exact
73
+ rational derivative fixtures and independently factored variance references.
74
+ The focused spec also checks a polynomial with nonzero third derivatives,
75
+ a quadratic with a nonzero mean correction and the refusal boundaries.
76
+
77
+ Sources: https://www.bipm.org/documents/20126/2071204/JCGM_100_2008_E.pdf[JCGM 100:2008],
78
+ https://www.bipm.org/documents/20126/2071204/JCGM_101_2008_E.pdf[JCGM 101:2008],
79
+ and the BIPM JCGM publications for GUM 100:2008/Amd.1:2026 and GUM 5:2026.
80
+
81
+ This entrypoint supplies numerical propagation, not a complete JCGM engine.
82
+ Unsupported function derivatives, automatic unit-aware GUM propagation,
83
+ correlated inputs, global risks and Ruby/TS wire conformance remain outside
84
+ this capability. An LPU/GUF2 result retains `adequacy: :not_assessed`; producing
85
+ a coverage factor alone does not validate the approximation.
86
+
87
+ == Quantity arithmetic
88
+
89
+ `Formula#evaluate_quantity(bindings)` is an explicit arithmetic entrypoint.
90
+ It needs UnitsML Quantity/conversion support (available in 0.6.14). Older
91
+ UnitsML versions retain the ordinary numeric evaluator; a quantity request
92
+ receives a named unsupported-expression error when that engine is absent.
93
+ Construct bindings with `Unitsml::Quantity.new(value: ..., unit: ...)`.
94
+ Numeric bindings and literals are dimensionless; integer division retains
95
+ rational magnitudes. Unit parsing, dimensions, composition, conversion and
96
+ scale legality stay in UnitsML. Addition and subtraction convert the right
97
+ operand into the left operand's unit before delegating the operation.
98
+
99
+ [source,ruby]
100
+ ----
101
+ require "unitsml"
102
+ formula = Plurimath::Math.parse("x+y", :asciimath)
103
+ outcome = formula.evaluate_quantity(
104
+ x: Unitsml::Quantity.new(value: 1, unit: "m"),
105
+ y: Unitsml::Quantity.new(value: 50, unit: "cm")
106
+ )
107
+ outcome.value.value # => (3/2)
108
+ outcome.value.norm_text # => "m"
109
+ ----
110
+
111
+ The supported expression subset is arithmetic, rational fractions, parentheses
112
+ and integer powers. Other functions raise an evaluator unsupported-expression
113
+ error. Dimension mismatches, conversion failures and invalid scale operations
114
+ preserve UnitsML's named error types. This does not attach units to GUM
115
+ sensitivities automatically; callers of Gum still supply one coherent system.
116
+
117
+ Quantity results expose `accuracy`; limited Float or BigDecimal sources remain
118
+ limited even when UnitsML conversion returns a Rational magnitude.
119
+
120
+ == Series and coverage factors
121
+
122
+ `Gum.series(observations, axis:, window:, guard_digits:)` reports exact mean,
123
+ extrema, count and sample variance, plus decimal strings for sample standard
124
+ deviation and standard uncertainty of the mean. For a matrix, axis 0 treats
125
+ rows as observations and axis 1 treats columns as observations. A window is
126
+ nil (all observations) or zero-based `[start, length]` on the observation
127
+ axis; out-of-range, ragged or insufficient samples are refused.
128
+
129
+ `Gum.coverage(standard_uncertainty:, probability:, degrees_of_freedom:,
130
+ guard_digits:)` returns a coverage factor and expanded uncertainty as decimal
131
+ strings. Nil degrees of freedom selects a normal distribution; finite values
132
+ select Student-t. The verified domain is central probability 0.5 through 0.999,
133
+ Student-t degrees of freedom 1 through 10000, and at most 8 output significant
134
+ digits. Other requests receive a typed refusal. Student-t factors come from
135
+ integrating the normalized density and bracketing its CDF, independently
136
+ checked against 80-digit incomplete-beta references. They are not interpolated
137
+ from a table.
138
+
139
+ Explicit guard-digit calculations select half-up decimal rounding and restore
140
+ the caller's decimal context. Statistical wire rounding uses integer/rational
141
+ arithmetic and does not depend on ambient BigDecimal limits or modes.
142
+
143
+ == Deterministic adaptive Monte Carlo
144
+
145
+ [source,ruby]
146
+ ----
147
+ result = gum.monte_carlo(formula,
148
+ inputs: { x: { distribution: :normal, location: "0", sd: "1" } },
149
+ independent: true, seeds: [12345,23456,34567,45678], probability: "0.95",
150
+ interval: :both, significant_digits: 2, guard_digits: 12,
151
+ max_samples: 200000
152
+ )
153
+ ----
154
+
155
+ The sampler uses the enhanced four-state Wichmann-Hill recurrence from
156
+ JCGM 101:2008 C.3.3.3. Four nonzero seeds below their respective moduli are
157
+ required; they, the final state, draw count, method revision and variable
158
+ order are included in the result. No process-global random source is used.
159
+ Normal and Student-t sampling follow C.4 and C.6. Rectangular, symmetric
160
+ triangular, arcsine and fixed-midpoint curvilinear trapezoid PDFs are also
161
+ supported. Every input must declare its PDF and parameters; Student-t `scale`
162
+ is not its standard deviation.
163
+
164
+ The existing Formula parser compiles exact polynomials about the exact PDF
165
+ centers. Large offset cancellation is simplified before sampling. The current
166
+ sampling domain has at most 128 intermediate terms and total degree 32;
167
+ nonconstant divisors are refused because finite output moments are not
168
+ established. Finite output variance is checked before sampling: a Student-t input needs
169
+ degrees of freedom greater than twice its polynomial degree. A linear
170
+ Student-t input with three degrees of freedom is supported; its square is
171
+ refused because that output has infinite variance. The batch standard
172
+ deviation has a finite second moment whenever output variance is finite;
173
+ no unnecessary fourth-moment condition is imposed.
174
+
175
+ The batch size, significant-digit tolerance and stopping statistics follow
176
+ 7.9.4 and equation 18. Both probabilistically symmetric and shortest intervals
177
+ use the one-based endpoint convention of 7.7.2. With `interval: :both`, every
178
+ endpoint is included in the stabilization test. Exhausting the explicit
179
+ sample cap raises `ConvergenceError`; it never reports an unstabilized
180
+ calculation as complete. This statistical stopping procedure is not a
181
+ mathematical guarantee of a particular realization's error.
182
+
183
+ Sampling and centered evaluation use declared binary64 arithmetic; the exact
184
+ polynomial coefficients and center expansion precede that computation.
185
+ Non-exact result fields are decimal strings with at most 12 significant
186
+ digits. `significant_digits` controls statistical stabilization independently
187
+ of the wire's `guard_digits`. Cross-runtime byte identity is not asserted.
188
+
189
+ The separate `GUM mathematical references` Actions job runs both actual
190
+ nonnormal H.1 PDF conventions at two meaningful uncertainty digits and both
191
+ interval kinds. Its artifact includes the actual sample counts, tolerance,
192
+ seed states and comparison with independently factored population moments.
193
+ The bounded local one-digit run is a coarser check, not a substitute for that
194
+ job. Reproduce the stronger check with:
195
+
196
+ [source,shell]
197
+ ----
198
+ bundle exec ruby scripts/check_gum_references.rb --output /tmp/gum-reference.json \
199
+ --significant-digits 2 --max-samples 2000000 \
200
+ spec/fixtures/evaluation/gum_h1_mcm.json
201
+ ----
202
+
203
+ == Normal conformity decisions
204
+
205
+ `Gum.conformity` implements the normal, measurement-only knowledge case of
206
+ JCGM 106:2012. Both `distribution: :normal` and
207
+ `knowledge: :measurement_only` are explicit. This identifies the posterior
208
+ estimate/uncertainty with the measurement estimate/uncertainty for the
209
+ capability index and guard geometry; informative priors are refused.
210
+
211
+ Supply `estimate:`, `standard_uncertainty:`, two `tolerance:` limits (nil for
212
+ an unbounded side), `rule:`, `coverage_factor:`, `guard_ratio:` and
213
+ `guard_digits:`. Rules are simple acceptance, guarded acceptance, guarded
214
+ rejection, and `iso14253_style` (the k=2,r=1 geometry described in JCGM 106).
215
+ The separately named `three_zone` policy reports conditional outcomes when
216
+ the expanded interval overlaps a tolerance boundary. It is not substituted
217
+ for a requested binary decision rule. Limits are closed, and boundary status
218
+ and signed residuals are explicit.
219
+
220
+ The returned specific consumer risk applies only to acceptance; specific
221
+ producer risk applies only to rejection. Conditional decisions report neither
222
+ as an actual decision risk. Global risks need a process/measurement joint PDF
223
+ and receive a typed refusal. Conformance probabilities use both normal tails;
224
+ probability fields declare 1 through 12 decimal places and their resolution.
225
+
226
+ A 2.3 percent one-sided tail ceiling must not be assumed for every two-sided
227
+ geometry. For example, with tolerance width 4u and w=2u, Cm=1 and the accepted
228
+ midpoint has nonconformance probability 2*Phi(-2), about 4.55 percent.
229
+ The engine returns the exact two-tail normal probability for the declared
230
+ geometry. A requested `consumer_risk_ceiling:` is refused if the guard band
231
+ does not establish it at the declared numerical resolution. The
232
+ `iso14253_style` name denotes the geometry documented in JCGM 106:2012 and does
233
+ not claim compliance with an unprovided later ISO edition.
234
+
235
+ Reference regeneration: `spec/support/gum_statistics_reference.py` uses
236
+ mpmath 1.3.0 at 80 decimal digits; `spec/support/wichmann_hill_reference.py` uses
237
+ the independent 32-bit recurrence and exact rational arithmetic. Runtime Ruby
238
+ uses different quadrature/recurrence paths. Normative publications remain at
239
+ their official source; no PDF is bundled with this implementation.
240
+
241
+ `Gum.validate_coverage` explicitly compares a proposed GUM interval against a
242
+ stabilized MCM interval at the same probability. It derives the target tolerance
243
+ from the proposed GUM standard uncertainty and meaningful digits, and requires
244
+ MCM to be at least five times tighter (JCGM 101 clauses 8.1/8.2). It returns
245
+ `validated` or `not_validated` for that specified probability and interval;
246
+ coarser, mismatched or incomplete MCM receives a typed refusal. This does not
247
+ turn `adequacy: :not_assessed` into an unconditional model-validity claim.
248
+
249
+
250
+ == Covariance, calibration and grouped observations
251
+
252
+ `Gum.type_a_covariance(paired_observations)` retains the sample covariance
253
+ and covariance of the mean of paired observations. `Gum.propagate_vector`
254
+ uses an explicit Jacobian and covariance matrix and returns the complete
255
+ output covariance, including cross-output terms. Covariance matrices must be
256
+ symmetric positive semidefinite; singular matrices are accepted without
257
+ adding diagonal noise.
258
+
259
+ `Gum.propagate_covariance` extends the scalar propagation interface with
260
+ `covariance:` and `joint_distribution:`. First-order propagation uses the
261
+ complete covariance matrix. Second-order propagation requires explicit
262
+ `:multivariate_normal` joint knowledge, normal component declarations, and
263
+ complete symmetric Hessian and third-derivative tensors. Normal marginal
264
+ PDFs and zero correlation alone do not establish joint normality. Correlated
265
+ Welch-Satterthwaite degrees of freedom are not inferred.
266
+
267
+ Student-t PDF shape and variance-estimate degrees of freedom are separate.
268
+ Use `pdf_degrees_of_freedom:` for the PDF and, when supported by the source,
269
+ `variance_degrees_of_freedom:` for the uncertainty estimate. The legacy
270
+ Student-t `degrees_of_freedom:` keyword remains a PDF-shape alias. Its
271
+ variance-estimate degrees default to `:unknown`, which propagates an unknown
272
+ effective-degrees status. For other distributions, nil explicitly denotes
273
+ infinite variance-estimate degrees; `:unknown` preserves missing information.
274
+
275
+ `Gum.linear_calibration` implements the unweighted GUM H.3 line fit. The
276
+ caller declares `abscissa_uncertainty: :negligible` and
277
+ `residual_model: :independent_common_variance`. Prediction distinguishes
278
+ `:mean_correction` from `:new_observation`; the latter includes residual
279
+ variance. Extrapolation is flagged. The engine does not infer linearity,
280
+ normality, or negligible temperature uncertainty.
281
+
282
+ `Gum.grouped_type_a` accepts balanced group means and sample variances
283
+ with `observations_per_group:`. It reports both mean squares, the F statistic
284
+ and its degrees of freedom. The caller chooses `:random_group_effect` or
285
+ `:no_group_effect`; no automatic F-test changes that choice. A negative
286
+ estimated random-group component requires an explicit constrained model and
287
+ is refused rather than silently clipped.
288
+
289
+ The independently regenerated Annex H fixture covers paired electrical
290
+ outputs (H.2), calibration (H.3), decay-corrected activity (H.4), balanced
291
+ observation summaries (H.5), and Rockwell hardness components (H.6). Exact input
292
+ profiles and numerical tolerances are in the focused specs. H.5 distinguishes
293
+ provided summaries from the publication's rounded intermediate values. H.2
294
+ checks both supplied raw observations and rounded uncertainty/correlation
295
+ summaries against independent calculations; neither reproduces every
296
+ published uncertainty to its last digit. Unrounded source observations or
297
+ the publication's calculation/rounding convention are needed to close that
298
+ separate boundary. Missing certificate or pooled-variance degrees of freedom
299
+ remain unknown. These examples do not establish general model adequacy.
300
+
301
+
302
+ == Implicit measurements and additional source profiles
303
+
304
+ `Gum.propagate_implicit` linearizes a caller-supplied root of `h(y,x)=0`.
305
+ Supply output estimates, `output_jacobian:`, `input_jacobian:`, input
306
+ `covariance:`, `residuals:`, `residual_tolerance:` and `guard_digits:`.
307
+ Exact pivoted elimination solves the sensitivity system, and the result
308
+ retains the complete output covariance. Singular output Jacobians and
309
+ residuals beyond the declared tolerance receive typed refusals. This is not
310
+ a root finder; the residual tolerance has the units of the supplied equations.
311
+ It does not establish the adequacy of the linearization.
312
+
313
+ The GUM5 profiles include all ten thermometer outputs in section13, with
314
+ shared calibration uncertainty; all six correlated Gaussian quadratic
315
+ comparison-loss moment cases in section16; and the linear-sum variances of
316
+ section6. The actual mass-calibration PDFs of section7 are used for LPU;
317
+ normal-only GUF2 is refused for that mixed-PDF profile. An independent exact
318
+ population-moment calculation uses reciprocal-uniform integrals. Its
319
+ reference-density half-width is 0.05 kg/m3, as specified in Table7.1.
320
+ MCM supports the mass model through exact rational compilation and an
321
+ explicit denominator-support certificate. Correlated normal MCM requires
322
+ `independent: false`, `joint_distribution: :multivariate_normal` and
323
+ `joint_covariance:` in the ordered input mapping. Marginal normal variances
324
+ must agree with the covariance diagonal. Exact LDL factorization supports
325
+ singular positive-semidefinite covariance without jitter; final factor roots
326
+ and samples use binary64. The result records the joint law, covariance and
327
+ factor policy.
328
+ Normal-equivalent local Taylor derivatives must not be interpreted as finite
329
+ population moments of reciprocals of unbounded Gaussian variables.
330
+
331
+ The GUM6:2020 section13.1.4 bromine profile uses the source's explicit normal
332
+ PDF example. It demonstrates vanishing first-order sensitivity, nonzero
333
+ quadratic variance, and the corrected mean. Neither unrequested truncation
334
+ nor a different physical PDF is inferred from the example. Source digests,
335
+ inputs, independent numerical reference generators and declared tolerances
336
+ are included in the fixtures and focused specs.
337
+
338
+
339
+ The rational sampler retains exact numerator/denominator polynomials and
340
+ centers the output before binary64 evaluation. Conservative exact interval
341
+ bounds must prove the denominator is separated from zero using explicitly
342
+ bounded rectangular input supports. Other denominator PDFs, zero-crossing
343
+ support and unsupported coefficient ranges receive typed refusals. A finite
344
+ normal-input reciprocal is not inferred from a small standard deviation.
345
+ Finite-output-variance checks use numerator polynomial degrees together with
346
+ the bounded reciprocal certificate. Result metadata identifies this backend
347
+ and records the exact denominator interval; it is distinct from the original
348
+ polynomial backend.
349
+
350
+ `spec/fixtures/evaluation/gum_mcm_profiles.json` supplies eleven explicit
351
+ source profiles: three linear sums, six correlated quadratic cases, the
352
+ actual mixed-PDF mass calibration, and the normal bromine example. The
353
+ mathematical-reference Actions job runs these at two meaningful uncertainty
354
+ digits and requires both interval kinds to stabilize. Independent population
355
+ means/uncertainties are checked within two predeclared adaptive tolerances.
356
+ This moment check does not establish population coverage of every returned
357
+ interval. The bounded local three-profile run uses one meaningful digit;
358
+ stronger full-profile execution is reported separately from Actions.
359
+
360
+
361
+ The extended reference job declares a maximum of eight million samples per
362
+ profile. Its first two-million-sample run did not stabilize the zero-mean,
363
+ correlation 0.9 quadratic case; that failure remains evidence of the resource
364
+ boundary. A convergence refusal includes the achieved sample count, numerical
365
+ tolerance, twice-standard-error diagnostics and PRNG state. The implementation
366
+ persists the original Welford recurrence in sample order, avoiding repeated
367
+ historical rescans while retaining the same binary64 prefix moments. Requested
368
+ stopping criteria and meaningful digits are unchanged.