Add a bracketed scalar rootfind node, kept internal for now

[MarcBerliner]

Adds an expression-tree node that solves residual == 0 for its unknown over a bracket, plus the native CasADi rootfinder plugin it runs on.

The solve runs inside the CasADi graph, not in Python: the node converts to a rootfinder using a "brent" plugin registered by pybammsolvers. An expression containing one costs no extra Python frames per evaluation, and survives codegen to C.

Brent needs only a sign change over the bracket, so it converges where a Newton iteration stalls or leaves the domain, and the answer cannot leave the bracket. Derivatives come from CasADi's implicit function theorem, exactly.

Deliberately not public

The node is pybamm._Brent, with no docs page and no changelog entry. It is reachable from the pybamm namespace the way _BaseAverage already is, and nothing about it is a commitment yet.

There are no in-tree consumers, and the constructor is going to change: the residual is currently a symbol the caller names and must keep unique by hand, and that wants to become a closed sub-expression with positional arguments — a shape the Rust tape backend in #5732 independently needs, and which Brent presently reconstructs by hand via casadi.symvar and a scoped cache. Cheaper to withhold the name now than to break it later. #5730 is the first real consumer; the public name can follow once it has proven the shape.

sto = pybamm._BrentUnknown("stoichiometry")
node = pybamm._Brent(param.n.prim.U(sto, T) - voltage, sto, (0, 1))

Building the plugin

It is built out of tree, so CMake supplies four things an in-tree CasADi plugin gets for free. brent.hpp opens with this list; briefly:

1. The internal headers. rootfinder_impl.hpp and five siblings are not installed by CasADi (INSTALL_INTERNAL_HEADERS is off by default) and are LGPL-3.0-or-later, so they are staged at configure time from the sdist rather than vendored into this BSD-3-Clause tree. -DCASADI_SOURCE_DIR=<tree> builds offline.
2. An ABI check. Those headers are not ABI-stable, so the linked CasADi's version is read from its own installed casadi/config.h — the one source present on every discovery path, including Windows/vcpkg and conda, which have no interpreter to ask. That version is also what selects the sdist, so the pin in pyproject.toml is the only one, and -DCASADI_INTERNAL_VERSION= is an override whose only job now is to fail loudly when it disagrees with the linked library. The staging directory is keyed on the version, so a bump cannot find the previous release's headers in place and skip restaging.
3. The compile flags CasADi itself used, from the same header. CASADI_WITH_THREADSAFE_SYMBOLICS adds a static mutex to Rootfinder, so guessing it would be an ABI break rather than a warning.
4. The stringified iteration. brent_impl.hpp is compiled and stringified into brent_impl_str, so codegen emits the same text this file compiles and the two paths cannot drift.

Not available on Windows

The CasADi wheel for Windows is built with MinGW — it ships libstdc++-6.dll and .dll.a import libraries, and its own config.h names the compiler as x86_64-w64-mingw32.shared.posix-g++. pybammsolvers is built with MSVC against vcpkg's CasADi. Brent subclasses casadi::Rootfinder, so the two cannot be linked across that ABI, and the plugin registered inside our extension is invisible to the CasADi Python calls: the process holds two copies with two plugin registries.

Converting a node to CasADi there raises a NotImplementedError naming the cause rather than CasADi's Plugin 'brent' is not found, evaluate() still works via SciPy, and both test modules skip on win32. Closing the gap means building the plugin as a separate MinGW DLL against the wheel's libcasadi.dll.a — a second toolchain in the Windows job — or landing it upstream in CasADi, which has no bracketed rootfinder of its own.

Notes

• The plugin caches its last solve, keyed on every input but the guess. Without it a Brent nested inside another re-solves on every enclosing iteration, which compounds per level. Covered on both the interpreted and the generated path. The cache scratch lives on the solver's memory object, which CasADi hands out per concurrent evaluation, so a threaded map over one Function does not share it.
• The bracket is tested by sign rather than by fa * fb <= 0, which underflows to zero for two residuals near the underflow limit and reads as a sign change.
• Exhausting max_iter is reported as a failure, not a root, on both the CasADi and the NumPy path. Likewise an empty bracket: the NumPy path used to swallow both into a quiet NaN, along with the tree probes the blanket except was meant to absorb.
• Nothing the conversion emits is named after the node's id. Ids are a per-process hash and the names reach fn.serialize(), the AOT compile cache key, so a model holding a rootfind used to miss the on-disk cache in every process: measured over three fresh interpreters, a Brent-free function keyed to 4da87061f2ba3c82 each time while one holding a Brent keyed to 5229b804…, 0d83e675…, 277998d7…. Now 3e26c07750303134 each time. The identity was never needed, since CasADi names generated code positionally and the conversion cache — keyed on the id, which is where identity belongs — already gives two Brents differing only in tolerance their own rootfinder. A test pins the key across processes.
• Also fixes an unrelated test bug found on the way: test_pybamm_import unloaded every pybamm module from sys.modules and never restored them, leaving a second set of classes behind so isinstance failed across the boundary for anything sharing an xdist worker afterwards.

Tests: 4207 unit, 82 pybammsolvers.

The composite electrode SOH solver built on this is #5730.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 91.37931% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.08%. Comparing base (3e8d682) to head (fa12f8d).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
...ackages/pybamm/src/pybamm/expression_tree/brent.py	91.76%	14 Missing ⚠️
...ybamm/src/pybamm/discretisations/discretisation.py	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5729      +/-   ##
==========================================
- Coverage   98.20%   98.08%   -0.13%     
==========================================
  Files         340      341       +1     
  Lines       32743    32916     +173     
==========================================
+ Hits        32156    32285     +129     
- Misses        587      631      +44     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[aabills]

I think in general this is a good idea but let's rename it to something more general than the particular numerical method we're using

[aabills]

Claude's suggestion which I like:

sto = pybamm.Unknown(name)
return pybamm.ImplicitFunction(U(sto, T, branch) - target, sto, (lo, hi))

One simple change, maybe we call it ImplicitUnknown?