Forward sensitivities need a C compiler on the user's machine, and neither the installation page nor the sensitivities guide says so: on a wheel install with no `cc`, a run with sensitivity_params raises CodegenToolchainError where a plain run works

Open Beginner friendly
  • Is something wrong?
#1,690 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
91/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
documentation

Research direction

Read docs/installation.md beside the wheel installation table and docs/user-guide/sensitivities.md at the guide’s start; compare their guidance with docs/user-guide/codegen.md. Add the runtime C compiler requirement for forward sensitivities in the installation and sensitivities pages, and clarify what needs the JIT in the capabilities() text. Done when those entry points explain the requirement and fix consistently.

Written by the indexing model from the issue text.

Description

documentation

A forward-sensitivity run always compiles its right-hand side, so it needs a C compiler where the user runs it. Consider a wheel install on a host with no cc and an empty codegen cache. A plain ODE run of A -> 0 works. The same run with sensitivity_params=["k"] raises CodegenToolchainError. The message is clear and names the fix. However, a user learns of the requirement from that error, and not from the page they installed from or the guide they are following.

Found for the tracking issue #1689. Checked on 2026-11-12 on macOS arm64, in a new Python 3.13 environment holding only bngsim 0.17.1 from PyPI and what it brings (numpy 2.5.4, python-libsbml 5.21.2, sympy 1.14.0, mpmath 1.3.0). Not checked on Linux or Windows.

Repro (python repro.py)

"""Forward sensitivities on a wheel install with no C compiler on PATH and an empty codegen cache."""
import os
import tempfile
from pathlib import Path

tmp = Path(tempfile.mkdtemp())
(tmp / "bin").mkdir()
os.environ["PATH"] = str(tmp / "bin")  # an empty directory: no cc
os.environ.pop("CC", None)
os.environ["BNGSIM_CODEGEN_CACHE_DIR"] = str(tmp / "cache")  # empty, as on a new machine

import bngsim  # noqa: E402

net = tmp / "decay.net"
net.write_text(
    "begin parameters\n 1 k 1\nend parameters\n"
    "begin species\n 1 A() 100\nend species\n"
    "begin reactions\n 1 1 0 k\nend reactions\n"
    "begin groups\n 1 Atot 1\nend groups\n",
    encoding="utf-8",
)
print("bngsim", bngsim.__version__, "| HAS_MIR:", bngsim.HAS_MIR)

model = bngsim.Model.from_net(str(net))
r = bngsim.Simulator(model, method="ode").run(t_span=(0, 1), n_points=3)
print("plain run:      A(1) =", round(float(r.species[-1, 0]), 4), "(exact 36.7879)")

model = bngsim.Model.from_net(str(net))
try:
    sim = bngsim.Simulator(model, method="ode", sensitivity_params=["k"])
    r = sim.run(t_span=(0, 1), n_points=3)
    print("sensitivity run: dA/dk(1) =", round(float(r.sensitivities[-1, 0, 0]), 4), "(exact -36.7879)")
except Exception as e:  # noqa: BLE001
    print("sensitivity run:", type(e).__name__)
    print("  ", str(e)[:230], "...")

Output

bngsim 0.17.1 | HAS_MIR: False
plain run:      A(1) = 36.7879 (exact 36.7879)
sensitivity run: CodegenToolchainError
   Failed to build the analytical sensitivity RHS required for forward sensitivity (CodegenToolchainError: C compiler not found: 'cc' is not an executable on PATH. Install Xcode Command Line Tools (macOS), gcc (Linux), or Visual Stud ...

Two controls. With cc on PATH (remove the line that sets PATH), the last line is sensitivity run: dA/dk(1) = -36.7879 (exact -36.7879). With no cc and the default cache, after a run that compiled this model, the script prints the same: a compiled library in the cache is reused without a compiler.

What the docs say

  • README.md, under Highlights: "Forward sensitivities need a codegen backend: cc, or the opt-in MIR JIT in a source build".
  • docs/user-guide/codegen.md: "A forward-sensitivity run always compiles", and that a missing compiler raises CodegenToolchainError. Its cluster note says that compute nodes often have no compiler on PATH.
  • docs/installation.md, docs/quickstart.md, docs/index.md and docs/user-guide/sensitivities.md do not mention a compiler at run time. The only compiler on the installation page is the C++17 one for a source build.
  • capabilities()["missing"]["mir"] says of the in-process JIT: "Nothing needs it: codegen compiles its generated C with a system compiler". On a host with no compiler, forward sensitivities do need it, and no published wheel carries it (HAS_MIR is False).

Reach

A user of a wheel on a machine with no compiler: stock Windows, a slim container image, or a cluster compute node. On Windows the message names Visual Studio Build Tools as the fix; we did not try that. A plain ODE run is not affected: without a compiler, a model at or above the codegen threshold (256 species, by the README) runs on the interpreted right-hand side.

A possible fix

It may be best to state the requirement in two places: the installation page, beside the table of wheels, and the top of the sensitivities guide. The capabilities() text could say what does need the JIT. Shipping the JIT in the wheels would remove the requirement, but it is marked a prototype (#1490 concerns its refresh).

Not covered by

#1491 (which wheels are built) and #1490 (the vendored JIT's version).

Dominant language
Python
Stars
3
Forks
5
Avg merge
1d 1h
Merged PRs (30d)
361

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from lanl/bngsim

All issues in lanl/bngsim

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.