v0.2 numerical API assessment (historical) · phit

Note

This record was written from 2026-10-12 to 2026-10-17, before the first tagged release. It describes the code and evidence as they were then, and is kept as history. The API overview and verification pages describe the current releases.

The distribution and statistical utility implementation includes probability evaluation, descriptive/draw kernels and explicitly seeded batch sampling. The native release gate passes on this Apple Silicon/macOS workstation with PHP 8.5.10 and matching headers: 68 Rust tests, 14 PHP suites and eleven executed examples passed, along with clippy, signatures, provenance and evidence-table checks. This is a source/readiness record; no tag, registry submission, binary publication or deployment was performed. Cargo/PIE version metadata still identifies the existing 0.1.0 baseline until the project’s separate release/versioning step.

Delivered scope

Area	Delivered evidence
Backend audit	Executable statrs 0.19 audit against R; saved findings; MIT cdflib chosen over GPL nmath ports
Probability kernels	All planned Tier 1/2 families, 13 parameterizations, seven operations, scalar/batch PHP APIs: 182 functions
Statistical utilities	Ten descriptive functions; corrected moments, type-7 quantiles and explicit weighted definitions
Posterior draws	Strict weighted moments, Cholesky covariance maps and affine transforms, with independent verification
Reference accuracy	R/SciPy/60-digit mpmath fixtures; native comparison report; no runtime reference dependency
PHP verification	8,618 distribution comparisons, 25 independent adjudications, 43 boundary conventions; 145 descriptive R quantities and missing/error checks
Examples	Executed t test, confidence interval, Poisson likelihood, normal tail/central probability, equivalent NB forms; draw moment transport
Performance	27 input cases over 1,000/100,000/one million values; PHP scalar/batch, Rust/R/SciPy, full-output consumption, raw times and peak RSS
Regression preservation	Seven fitters against rebuilt pre-v0.2 revision `6342562`; every compared quantity identical; observed median ratios 0.967×–1.024×
Contracts/provenance	Reflection-generated PHP stubs/signature snapshot, detailed family/utility contracts, hashes for all four distribution/descriptive fixtures, checked evidence tables
RNG	13 seeded batch functions, local ChaCha20 state, 25 independent Python/R cases, prefix/state/type checks and reproducible benchmarks
Estimator reuse	Assessed public kernel replacements; retained established OLS/probit paths to preserve existing regression behavior

The contracts, distribution guide, utility guide, verification record and benchmarks provide the definitions and limits.

Numerical findings and fixes

The saved native/mpmath errors are typically below 1e-13; the largest is about 8.34e-13 in a large-df chi-square log tail. Native tests keep the original operation-specific 1e-12 tolerances. R and SciPy have documented endpoint and tail differences, with an independent reference used only when the saved references justify it. In particular, SciPy’s large-df chi-square lower-tail error is visible in both the reference record and benchmarks. Unavailable high-precision values are recorded as null, and reduced subnormal precision is disclosed.

Additional verification fixed two arithmetic bugs: overflowing descriptive variance no longer becomes zero through max(NAN, 0), and finite large NB size/mean values whose sum overflows no longer become a false point mass. Negative descriptive weights are rejected before missing-value deletion. R reference values at ordinary scales remain within the established tolerances; existing regression APIs and numerical paths are preserved.

Reuse and RNG decisions

The executable reuse experiment found that the new Student-t quantile improves R agreement for the six tested OLS critical values, but changes their rounding. The public normal log-CDF differs at 17 saved points from the established probit calculation. This task also requires preserving regression behavior, so neither path is replaced in this release. A future refactor can use this evidence to make an explicit model compatibility decision.

Random sampling is implemented with dist_{family}_rng(n, seed, ...parameters). Each call owns a pinned ChaCha20 stream and transforms open-interval uniforms through the existing inverse CDF. The sampling contract defines seed ownership, count/type/range policies and reproducibility limits. Independent Python ChaCha/PCG/Open01 equations and base-R quantiles verify the stream and samples; benchmarks verify sampled points and full-vector moments before recording seeded-call timings. The earlier handoff recommendation to defer RNG has been superseded by this implementation.

Verification and maintenance

PHP=/path/to/matching/php PHP_CONFIG=/path/to/php-config ./scripts/check
python3 scripts/reference-manifest.py --check
python3 scripts/distribution-docs.py --check

The gate runs formatting, clippy with warnings denied, all Rust tests, the release extension build, reflected signature/default/stub checks, every PHP integration suite, examples and offline provenance/documentation checks. The benchmark and independent-reference generation commands are separate and documented alongside their reports. Quarto renders the new guides, contracts, comparison and benchmark pages into the local _site output without publishing them.

Release and platform limits

The new completion run verifies macOS arm64/PHP 8.5.10. Earlier packaging evidence in deployment covers Linux arm64 PHP 8.3/8.4/8.5 for the preceding source snapshot. That historical evidence does not establish that the latest hardening changes passed those environments. The configured remote amd64/PHP matrix and updated binary/container builds must run as part of the separate release process. Windows/ZTS remain outside the supported package matrix. Benchmarks do not establish performance bounds on other machines or all finite/extreme arguments.

Version/tag selection, Packagist registration and release/binary publication remain external release steps. No commit, push, PR or publication is part of this work.