mc-integrate — Monte Carlo Numerical Integrator

Productized callable Monte Carlo integrator with a deterministic LCG core and an optional ANU quantum RNG seed. Estimates Catalan G, Apéry ζ(3), Euler–Mascheroni γ, and π⁵×6 (BT-209 m_p/m_e identity reference) with explicit abs/rel error gates and a Welch–t indistinguishability test for cross-RNG comparison. Pure-stdlib hexa; zero runtime deps.

Mirrors: canonical at https://github.com/need-singularity/mc-integrate; HF Hub mirror at https://huggingface.co/need-singularity/mc-integrate (infrastructure repo, not a trained model — the model-type repo carries the integrator as a code+manifest distribution). Updates pushed to GitHub main are auto-mirrored to HF within ~2-3 min via .github/workflows/sync-to-hf.yml (GitHub Actions, $0 on public-repo free tier; HF_TOKEN secret required — USER_ACTION pending).

Provenance: extracted 2026-05-04 from nexus/modules/mc_integrate/ (nexus extraction audit rank 8, score 8 — dual-home blocker resolved Phase 1 via 4-tier ANU resolution; Phase 2 standalone enables multiverse_nav rank-9 unblock).

---

What is mc-integrate?

mc-integrate is a small, sharp-edged numerical integrator you wire into any problem that benefits from Monte Carlo (high-dimensional integrals, Bayesian posterior estimates, partition-function sampling). It exposes two functions:

• estimate_constant(name, n_samples, rng) — estimate one of four named mathematical constants whose analytical value is known. The result includes abs/rel error and a discrete gate ∈ {PASS, NEAR, FAIL} so you get a yes/no signal without writing your own threshold logic.
• compare_rng(name, n_samples, n_trials, rng_a, rng_b) — Welch–t indistinguishability test: are two RNG backends statistically equivalent on this integrand? Uses df-aware critical-t lookup at α=0.05 two-tailed (NIST/SEMATECH §1.3.6.7.2 + Bevington & Robinson Table C.2; linear interp for non-integer df) plus a Wilson–Hilferty p-value approximation.

Named constants

Name	Analytical value	Integrand
catalan	0.91596559417721901505	∫₀¹ arctan(u)/u du
zeta3	1.20205690315959428540	∫∫∫ 1/(1 - uvw) over [0,1]³
euler_gamma	0.57721566490153286061	-∫₀¹ ln(-ln(u)) du (ε=1e-5 tail trim)
pi5_times_n6	1836.1181087117…	(π via 4×quarter-disc indicator)⁵ × 6

Acceptance gates (verbatim)

• PASS if abs_err < 1e-3
• NEAR if abs_err < 5e-3
• FAIL otherwise

LCG core

s_{n+1} = (1664525 · s_n + 1013904223) mod (2³¹ − 1)

(Numerical Recipes constants; 2³¹ − 1 is the eighth Mersenne prime, keeping the stream period prime-floored.)

---

Installation

Via hx (recommended, once registry-published)

hx install mc-integrate          # pulls latest from registry
hx install mc-integrate@1.0.0    # pin
mc-integrate --version           # → 1.0.0

Via git clone (works today)

git clone https://github.com/need-singularity/mc-integrate.git ~/.mc-integrate
export MC_INTEGRATE_ROOT=~/.mc-integrate
export PATH="$MC_INTEGRATE_ROOT/cli:$PATH"

hexa run $MC_INTEGRATE_ROOT/cli/mc-integrate.hexa self-test

Dependencies

Zero runtime deps. Pure hexa-lang stdlib. No Python aux, no native bridges, no required network.

mc-integrate cooperates with two optional sister packages when they are installed (auto-detected at runtime; absence falls back gracefully):

• sim-universe — provides modules/godel_q/anu_source.hexa, the live ANU vacuum-fluctuation REST endpoint shim. Preferred when present (tier 3 of the resolution chain). Repo: https://github.com/need-singularity/sim-universe.
• qmirror — provides cli/qmirror.hexa qrng (alternative quantum entropy source; not currently wired as a backend because qmirror's qrng subcmd emits a selftest verdict rather than raw hex bytes — see Caveats §1). Repo: https://github.com/need-singularity/qmirror.

When both are absent, mc-integrate falls back to urandom, which is the same behavior as the upstream nexus origin.

---

Quick Start

1. Run the self-test

mc-integrate self-test

Output: catalan PASS gate + zeta3 + euler_gamma path checks + Welch-t falsifiers F2/F3/F4/F5 + critical-t table G1/G2/G3 + p-value G4/G5/G6, ending with __MC_INTEGRATE_STANDALONE__ PASS version=1.0.0.

2. Estimate a constant

mc-integrate estimate --constant catalan -N 100000 --rng urandom
mc-integrate estimate --constant zeta3   -N 1000000 --rng anu
mc-integrate estimate --constant pi5_times_n6 -N 50000 --json

Result includes value, abs_err, rel_err, runtime_s, gate, samples, rng_used (which records the actual RNG that bootstrapped — may differ from the requested --rng if a fallback fired).

3. Compare two RNG backends

mc-integrate compare --compare catalan -N 50000 --trials 6

Produces Welch–t mean/std for each backend, t-statistic, df, df-aware t_crit(α=0.05), Wilson–Hilferty p-value, and a boolean indistinguishable verdict.

4. Use as a library (hexa)

import "mc_integrate"

let r = mc_integrate.estimate_constant("zeta3", 1000000, "urandom")
println("ζ(3) ≈ " + str(r["value"]) + " (gate=" + r["gate"] + ")")

let cmp = mc_integrate.compare_rng("catalan", 10000, 6, "anu", "urandom")
if cmp["indistinguishable"] {
    println("anu and urandom are statistically equivalent on Catalan G.")
}

5. Status / 4-tier ANU probe

mc-integrate status

Shows the ANU resolution chain — useful when debugging "why did --rng anu silently fall back?" questions.

---

Architecture

Two variants, one surface

estimate_constant(name, n_samples, rng="anu")    estimate_constant(..., rng="urandom")
        │                                                       │
        ▼                                                       ▼
   _bootstrap_seed("anu")                              _bootstrap_seed("urandom")
        │                                                       │
        ▼                                                       │
   _resolve_anu_source()  →  4-tier chain                       │
        │                                                       │
        ├─ tier 1: $MC_INTEGRATE_ANU_SOURCE                     │
        ├─ tier 2: $ANU_SOURCE_HEXA                             │
        ├─ tier 3: ~/core/sim-universe/.../anu_source.hexa      │
        └─ tier 4: ~/core/nexus/.../anu_source.hexa             │
            │                                                   │
            └─ all-absent → fall through to urandom ────────────┤
                                                                ▼
                                                        head -c 16 /dev/urandom
                                                                │
                                                                ▼
                                                  (LCG seeded; integrate)

Cross-link to sister packages

Package	Provides	mc-integrate uses for
sim-universe	anu_source.hexa (ANU vacuum-fluctuation)	optional preferred ANU seed (tier 3)
qmirror	cli/qmirror.hexa qrng subcmd	not currently wired (see Caveats §1)
qrng	(in-development standalone)	future preferred backend if it ships hex

---

Self-test

$ mc-integrate self-test
=== mc-integrate self-test (standalone v1.0.0) ===
  module: /Users/ghost/core/mc-integrate/mc_integrate/module/mc_integrate.hexa
  hexa  : /Users/ghost/core/hexa-lang/hexa
=== mc_integrate --self-test ===
  catalan estimate    : 0.916xxx
  ...
  G6 biased-p<0.001    : ... → PASS
__MC_INTEGRATE__ PASS constant=catalan abs_err=… gate=PASS
__MC_INTEGRATE_COMPARE__ PASS t_stat=… df=10 verdict=significant
__MC_INTEGRATE_COMPARE_CRITVAL__ PASS t_crit_df10=2.228 t_crit_df_inf=1.96 p_value_impl=yes
__MC_INTEGRATE_STANDALONE__ PASS version=1.0.0

---

License

Apache-2.0 — see LICENSE.

---

Caveats

raw#10 honest C3 — explicit limitations (these are NOT bugs; they are the edges where this tool stops being honest):

1. qmirror cli does not currently emit raw hex bytes. cli/qmirror.hexa qrng prints a SELFTEST verdict (__QMIRROR_QRNG__ PASS) rather than raw entropy. Phase 1 decouple therefore uses a 4-tier file-path resolution for the ANU source, NOT a qmirror cli shellout. If qmirror later adds a qrng --emit-hex mode (or the standalone qrng package ships a CLI), mc-integrate could switch to a cli shellout backend; until then it transitively reads anu_source.hexa via the resolution chain.

2. Dual-mirror sync USER_ACTION pending. The GitHub Actions workflow sync-to-hf.yml requires the HF_TOKEN repository secret to be set at https://github.com/need-singularity/mc-integrate/settings/secrets/actions. Until then GH→HF mirror runs will fail loudly at the "Verify HF_TOKEN secret is present" step (loud-fail gate; no silent skip).

3. MC convergence not validated for arbitrary integrands. Only the four named constants (catalan, zeta3, euler_gamma, pi5_times_n6) have analytical-error gates. The public API does NOT expose a generic estimate(integrand, dim, ...) because hexa's lack of first-class closure-as-arg ergonomics blocks the upstream Python signature; the planned future surface for closure-passing is registry-side, not core.

4. multiverse_nav unblock not auto-tested. The phase 2 nexus extraction audit identifies multiverse_nav (rank 9) as transitively blocked by mc_integrate's dual-home dependency. Phase 1 + Phase 2 declare the dual-home blocker resolved (sim-universe coupling deleted at the import surface), but this PR does NOT auto-run a multiverse_nav rebuild + smoke. The user-review consumer-refactor step (nexus/cli/mc.hexa 4-tier shellout + cmd_mc dispatch + hexa.toml dep + install.hexa) is staged but not committed.

5. License audit deferred. Apache-2.0 is declared in LICENSE and hexa.toml. Downstream provenance is traced (LCG = Numerical Recipes; Welch-t = NIST/SEMATECH §1.3.6.7.2; critical-t table = Bevington & Robinson Table C.2; Wilson–Hilferty t→z = standard textbook approx) but no formal patent / SPDX audit has been performed. If you redistribute commercially, do your own diligence.

---

Provenance

Field	Value
Extracted from	nexus/modules/mc_integrate/ @ 2026-05-04
Upstream origin	n6-architecture/experiments/anu_mc_verification/anu_mc_verify.hexa (productized .hexa 2026-04-27, HEXA-ONLY)
Decouple cycle	mc_integrate_decouple_2026_05_04
Extraction audit	rank 8, score 8 — dual-home blocker (resolved)
Sister packages	qmirror v2.0.0, sim-universe v1.0.0, hexa-bio v1.0.0, honesty-monitor v1.0.0, anima-agent v1.0.0
Ecosystem registry	hexa-lang/tool/pkg/registry.tsv (entry index pending)

---

Contributing

Issues and PRs welcome at https://github.com/need-singularity/mc-integrate. Please run hexa run cli/mc-integrate.hexa self-test before submitting.