WASM: support_enumeration and vertex_enumeration hang in the browser — root cause is jitted generators (numba.np.linalg._LAPACK verified working)

[mmcky]

Note

Updated 2026-08-21. Second revision today, after the cross-issue consistency pass: vertex_enumeration joins the scope — _vertex_enumeration_gen is the package's only other @jit(nopython=True) generator, so it is expected to hang for the same reason (by mechanism; not yet observed in the browser) — and the status note, the Problem section, the acceptance criteria and a new Related section are updated accordingly, now that PR #938 has merged and ci/wasm/smoke_test.py exists on main. The former "Side benefit" section is removed because its premise was wrong: _indiff_mixed_action, which makes the _LAPACK call, is already cache=True, and the # cache=True raises _pickle.PicklingError comment on the generator is a 2016 leftover unrelated to _LAPACK (cache=True on the generator works natively on Numba 0.62.1; re-enabling it is a separate maintenance item). Two permalinks and the patch count are corrected in place, and a draft of the upstream report for criterion 3 is in the comment below.

Status update (2026-08-21). The _LAPACK question is answered: on the public numba-ecosystem JupyterLite demo (Numba 0.66.0 / NumPy 2.4.6 / SciPy 1.18.0 on Emscripten) both bare np.linalg.solve inside @njit and QuantEcon's _numba_linalg_solve return correct results (#927 (comment)). support_enumeration still never returns, and the culprit is Numba generator functions — a minimal @njit function with yield hangs on first call. support_enumeration_gen is exactly such a generator, so the blocker has moved from LAPACK to jitted generators. vertex_enumeration / vertex_enumeration_gen is affected by the same bug: _vertex_enumeration_gen (yield at L161) is the package's only other jitted generator, and the failure happens at generator creation, before its numba.typed.Dict use is ever reached — so both game_theory enumeration routines are blocked until the upstream export is fixed. Original issue text follows; the "If it fails" fallback-solver plan is no longer needed and the acceptance criteria have been revised at the bottom.

---

Part of #925 (Phase 1, gated on the Phase 0 findings in #928). This is the highest-risk unknown in the browser-compliance audit.

Problem

util/numba.py imports the private API from numba.np.linalg import _LAPACK and uses it in an @overload to bind LAPACK's xgesv (Fortran, reached through SciPy's cython_lapack capsules) as a raw function address callable from nopython code. In game_theory.support_enumeration, _indiff_mixed_action calls it from inside the jitted equilibrium search, reached from the jitted generator _support_enumeration_gen.

Natively, the bound address is a machine-code pointer. Under Emscripten it must be an index into the shared WebAssembly function table, resolved across dynamically loaded side modules (SciPy's extension modules on one side, Numba's freshly linked user module on the other), with a matching signature at the call_indirect site. The QuantStack engine was explicitly designed for cross-module symbol resolution, so this may just work — but none of the (now ten) emscripten-forge numba patches mention LAPACK or linalg, and the recipe's tests never exercise np.linalg inside a jitted function.

game_theory.vertex_enumeration never touches _LAPACK, but it is driven by a jitted generator of the same kind — _vertex_enumeration_gen, returned by vertex_enumeration_gen and consumed by vertex_enumeration — which is why it is in scope now that the hang is traced to generators rather than to the LAPACK binding.

How to test

The same _LAPACK mechanism backs Numba's own np.linalg.solve support, so the clean experiment (part of the Phase 0 smoke suite, #928) is: run np.linalg.solve inside a scratch @njit function in the browser. If that works, QuantEcon's helper almost certainly works too; if it fails, both fail together.

If it fails

In order of preference:

1. A pure-Numba LU solve with partial pivoting behind a sys.platform == "emscripten" gate. support_enumeration solves small dense (k+1)×(k+1) systems for support size k, so a hand-written nopython solver is entirely adequate there.
2. Report the gap upstream to the emscripten-forge / Numba WASM effort — Numba's own linalg support has the same dependency, and the authors are actively expanding coverage.

Related

• PR WASM: JupyterLite environment config and browser smoke suite #938 (merged 2026-08-21): ci/wasm/environment.yml, ci/wasm/smoke_test.py, ci/wasm/test_jupyterlite.py and the native ci_wasm_smoke.yml job are now on main. test_support_enumeration and test_vertex_enumeration in smoke_test.py are unguarded and will hang in the browser, and test_jupyterlite.py runs test_support_enumeration in its shared kernel; guarding them with something that does not execute the test, and adding the minimal generator test from criterion 2, is part of the WASM: add a WebAssembly/JupyterLite smoke-test job to CI #933 runner work.
• WASM: add a WebAssembly/JupyterLite smoke-test job to CI #933: browser runner job; carries the hang-guard and isolation-test notes for this issue.
• WASM: cache=True functions that link a cache-restored callee fail with "no compiled object yet" (simplex_grid → num_compositions_jit → comb_jit) #944: the sibling upstream blocker (cache=True callers of cache-restored functions fail with "no compiled object yet", reported upstream as Numba: RuntimeError: no compiled object yet emscripten-forge/recipes#6309). Different mechanism, same "wait for upstream" posture.
• WASM: browser support for QuantEcon.py (Numba + JupyterLite) — tracking issue #925 (umbrella) and WASM: JupyterLite proof-of-concept deployment and browser smoke suite #928 (Phase 0 results table, where the support_enumeration and bare-generator rows belong).

Acceptance criteria

• In-browser verdict recorded: np.linalg.solve inside @njit works on Emscripten (LAPACK binding resolves correctly)
• Minimal jitted-generator repro added to the smoke suite (ci/wasm/smoke_test.py, on main since PR WASM: JupyterLite environment config and browser smoke suite #938) so the mechanism is isolated the way the bare np.linalg.solve test isolates LAPACK
• Generator hang reported upstream to the emscripten-forge / Numba WASM effort with the minimal repro (draft report in the comment below)
• Decide whether support_enumeration and vertex_enumeration need an Emscripten-gated non-generator path, or whether we wait on the upstream fix
• In-browser tests cover support_enumeration and vertex_enumeration (test_support_enumeration and test_vertex_enumeration in ci/wasm/smoke_test.py, currently unguarded) so regressions are caught once they run

[kp992]

I tested the following snippet and it worked:

from numba import njit
import numpy as np
from quantecon.util.numba import _numba_linalg_solve

@njit
def test_qe_solve():
  A = np.asfortranarray(np.array([[3., 2.], [1., -1.]]))
  b = np.asfortranarray(np.array([2., 4.])) 
  r = _numba_linalg_solve(A, b)
  return r, b
  
r, sol = test_qe_solve()
print(r, sol)

and also:

from numba import njit
import numpy as np
  
@njit
def solve_test():
    A = np.array([[3.0, 2.0], [1.0, -1.0]])
    b = np.array([2.0, 4.0])
    return np.linalg.solve(A, b)
      
result = solve_test()
print(result)

[oyamad]

I too tested on the public demo https://notebook.link/@anutosh491/numba-ecosystem:

import sys, numba, numpy as np
print(sys.platform)          # must print: emscripten
print(numba.__version__, np.__version__)
import scipy; print(scipy.__version__)
import scipy.linalg.cython_lapack   # the thing _LAPACK binds to
print("scipy cython_lapack OK")

emscripten
0.66.0 2.4.6
1.18.0
scipy cython_lapack OK

Test	Result
test_qe_solve	✅ 0 [ 2. -2.] (correct)
solve_test	✅ 0 [ 2. -2.] (correct)
support_enumeration	❌ first call never returns

The last test (support_enumeration) seems due to an issue on jitted generators:

from numba import njit
@njit
def g(n):
    for i in range(n):
        yield i

g(3)

(No return; hung?)

Cc: @anutosh491

[oyamad]

Here's the diagnosis by Claude Code Fable 5:

---

The generator hang is a symbol-name mismatch in the emscripten-forge Numba port:

• The jitted generator wrapper imports numba_make_generator (lowercase).
• Native Numba bridges that name to the C function Numba_make_generator (capital N) through _dynfunc.c_helpers + ll.add_symbol + MCJIT.
• The Emscripten port resolves helper imports purely by dynamic-loader export name, and 0002-export-runtime-helpers-for-wasm.patch only exports the capital-N spelling.
• Since the wasm linker passes --allow-undefined, the failure only surfaces at the first call — generator creation — which kills the kernel, so the cell never returns.

Minimal repro (on https://notebook.link/@anutosh491/numba-ecosystem):

import ctypes
import numba._dynfunc as _dynfunc

lib = ctypes.CDLL(_dynfunc.__file__)
for name in ("Numba_make_generator", "numba_make_generator"):
    try:
        addr = ctypes.cast(getattr(lib, name), ctypes.c_void_p).value
        print(f"{name}: resolved at {addr}")
    except AttributeError:
        print(f"{name}: NOT FOUND")

Output:

Numba_make_generator: resolved at 78906
numba_make_generator: NOT FOUND

Cc @anutosh491

[anutosh491]

Hmm, let me try having a look and figuring if I can think of a fix for this. Thanks for the report ;)

[oyamad]

One more code script from Claude Code Fable 5:

# Run in a FRESH kernel, before compiling any generator
from numba.core.pythonapi import PythonAPI

_orig_get_function = PythonAPI._get_function

def _get_function(self, fnty, name):
    if name == "numba_make_generator":
        name = "Numba_make_generator"
    return _orig_get_function(self, fnty, name)

PythonAPI._get_function = _get_function

from numba import njit

@njit
def g2(n):
    for i in range(n):
        yield i

print(list(g2(3)))      # expect: [0, 1, 2]

Output:

[0, 1, 2]

---

Fix options suggested by Claude Code Fable 5:

• In 0002-export-runtime-helpers-for-wasm.patch, export a lowercase alias from _dynfunc.c (after the definition of Numba_make_generator):

  #ifdef __EMSCRIPTEN__
  __attribute__((visibility("default"), alias("Numba_make_generator")))
  PyObject *numba_make_generator(Py_ssize_t gen_state_size, void *initial_state,
                                 PyCFunctionWithKeywords nextfunc,
                                 gen_finalizer_t finalizer,
                                 EnvironmentObject *env);
  #endif

• Or have pythonapi.py declare Numba_make_generator when sys.platform == "emscripten" (the Python-level equivalent of the runtime patch above).

[mmcky]

Updated the title, added a status note at the top, and revised the acceptance criteria to reflect the finding above: _LAPACK / np.linalg.solve in @njit is verified working on Emscripten, and the remaining blocker for support_enumeration is the jitted-generator hang (support_enumeration_gen is a @njit generator). The fallback-solver plan is no longer needed. Next steps are a minimal generator repro in the smoke suite (via #933) and an upstream report.