[Planeshifter]

resolves stdlib-js/metr-issue-tracker#1322

Description

What is the purpose of this pull request?

This pull request:

• adds a C implementation for @stdlib/math/base/special/kernel-betaincinv
• adds a native add-on binding, C benchmarks, C examples, native tests, and documentation for the C API
• extends scripts/evalpoly.js to generate the C polynomial evaluation functions (spliced into src/main.c between auto-generated markers), keeping the JS and C polynomial coefficients in sync from a single source

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

• [RFC]: Add C implementations to base special math functions (tracking issue) #649
• [RFC]: Add C implementation for @stdlib/math/base/special/betaincinv #6030 (a C implementation for math/base/special/betaincinv depends on this kernel)

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

Implementation notes:

• The implementation is a faithful port of the existing JavaScript implementation (Boost ibeta_inverse.hpp, t_distribution_inv.hpp, and roots.hpp), preserving branch structure, constants, and iteration behavior.
• As @stdlib/math/base/special/betainc does not yet have a C implementation, the two call sites in the driver use stdlib_base_kernel_betainc( x, a, b, true, false, &out, &deriv ) directly, mirroring what the JS betainc wrapper does.
• The JS implementation computes ldexp( 1.0, (2.0*53.0)/3.0 ); the JS ldexp truncates the fractional exponent, so the C port uses stdlib_base_ldexp( 1.0, 35 ) to match runtime behavior.
• The C API follows the multi-output pointer pattern of @stdlib/math/base/special/kernel-betainc: void stdlib_base_kernel_betaincinv( const double a, const double b, const double p, const double q, double *out1, double *out2 ).
• Native tests pass the full C++ (Boost) fixture set (2000 cases) within 16 ULP (empirical minimum, deterministic). Differential testing against the JS implementation over >150k random and edge-case inputs shows agreement, with residual-level analysis confirming remaining ULP spread is root-finder termination conditioning rather than porting divergence.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

This PR was written primarily by Claude Code under my direction, using a multi-agent workflow: the JS implementation and existing C ports (gammaincinv, kernel-betainc) were studied in detail, the port was generated to mirror the JS line-by-line, and the result was verified via fixture tests, large-scale differential testing against the JS implementation, and multiple independent adversarial review passes. All design decisions and validation results were reviewed by me.

---

@stdlib-js/reviewers

[stdlib-bot]

Coverage Report

No coverage information available.

[kgryte]

@anandkaranubc Would you mind doing a first review of this package? Cheers!

[anandkaranubc]

@anandkaranubc Would you mind doing a first review of this package? Cheers!

Of course, on it! Thanks!

[anandkaranubc]

The CI failure is in the downstream stats/base/dists/f/quantile tests, not in this package. The same issue would also show up in stats/base/dists/beta/quantile. Those fixture tolerances were set to the exact worst case of the old JS root-finder, with no headroom. The new root-finder in this PR lands a few ULP away on a handful of large-parameter entries, with no loss of accuracy. Updating those downstream tolerances is a separate change, so I'd prefer to handle it in a follow-up PR.