Skip to content

feat: add math/base/special/binetf - #16636

Open
RonakChakrawati wants to merge 1 commit into
stdlib-js:developfrom
RonakChakrawati:feat/binetf
Open

RonakChakrawati wants to merge 1 commit into
stdlib-js:developfrom
RonakChakrawati:feat/binetf

Conversation

@RonakChakrawati

Copy link
Copy Markdown
Contributor

Resolves a part of #649.

Description

What is the purpose of this pull request?

This pull request:

  • adds math/base/special/binetf, a single-precision implementation of Binet's formula extended to real numbers, including a C implementation, native addon bindings, and a C header

  • adds tests with numpy-generated fixtures, plus C and JavaScript benchmarks and examples

  • adds documentation, TypeScript declarations, and REPL help

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

Reference Packages

Did the content of this pull request follow one or more existing packages? Answering is optional.

This pull request followed these packages:

  • math/base/special/binet for the algorithm and package structure

  • math/base/special/tanhf for single-precision conventions

What carried over from the reference(s)?

  • package structure, documentation layout, benchmark layout, test shape, and naming

  • the f32-wrapped evaluation strategy and float32 assertion helpers

  • benchmark input generation ahead of the timed loop

What differed, or what did you have to work out yourself?

  • the single-precision overflow threshold of the dominant term: 184.373779296875 is the smallest single-precision value at which powf(phi,absf(x)) exceeds FLT_MAX. Beyond it, the dominant term is evaluated in log space as expf(ln(phi)*absf(x) - ln(sqrt(5))), and for negative x the ln(absf(cospif(x))) correction is folded into the exponent so the result remains real-valued

  • the extension of Binet's formula to negative non-integer x via phi**x = cos(pi*x)*phi**absf(x), which keeps the result real for all inputs

  • the cancellation domain: near x = 0 and the negative half-integers the two terms of the formula nearly cancel, so no single-precision result is meaningful there. The fixture generator filters such points (|y|*sqrt(5)/(|t1|+|t2|) < 0.05 and |x| < 40), and tests assert absolute error instead

  • ULP tolerances were measured against regenerated fixtures rather than carried over from the double-precision package

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.

Fixtures in test/fixtures/python/ are generated by test/fixtures/python/runner.py using numpy. Inputs are float32 and expected values are computed in float64 before a single rounding, so the reference is not computed at the precision under test. The small_negative fixture contains 499 points because one sample was dropped by the cancellation filter. Relative tolerances are per-domain measured maxima scaled by at least 2x, up to 200 ULP in the log-space tail where the float32 rounding of ln(phi) is amplified by the magnitude of x. Regenerating the fixtures from the committed runner produces byte-identical output.

Checklist

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

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 drafted with Claude Code: the C and JavaScript implementations, the float32 test port, and the documentation were derived from math/base/special/binet. I built and ran the package myself, ran both test suites (5290 assertions each), verified the JavaScript and native addon outputs are bit-identical on a set of gate inputs including the overflow boundary, and confirmed the committed fixtures are byte-reproducible from the committed generator.


@stdlib-js/reviewers

- add single-precision implementation of Binet's formula extended to real numbers
- add C implementation, native addon bindings, and C header
- add tests, numpy-generated fixtures, benchmarks, and examples
- add documentation, TypeScript declarations, and REPL docs

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown_pkg_readmes
    status: passed
  - task: lint_markdown_docs
    status: na
  - task: lint_markdown
    status: na
  - task: lint_package_json
    status: passed
  - task: lint_repl_help
    status: passed
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: passed
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: passed
  - task: lint_python
    status: missing_dependencies
  - task: lint_r
    status: na
  - task: lint_c_src
    status: passed
  - task: lint_c_examples
    status: passed
  - task: lint_c_benchmarks
    status: passed
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: passed
  - task: lint_license_headers
    status: passed
---
@RonakChakrawati
RonakChakrawati requested a review from a team November 15, 2026 04:36
@stdlib-bot stdlib-bot added Math Issue or pull request specific to math functionality. Needs Review A pull request which needs code review. labels Nov 15, 2026
@stdlib-bot

Copy link
Copy Markdown
Contributor

Coverage Report

Package Statements Branches Functions Lines
math/base/special/binetf $\\color{green}282/282$
$\\color{green}+100.00\\%$
$\\color{green}15/15$
$\\color{green}+100.00\\%$
$\\color{green}2/2$
$\\color{green}+100.00\\%$
$\\color{green}282/282$
$\\color{green}+100.00\\%$

The above coverage report was generated for the changes in this PR.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Math Issue or pull request specific to math functionality. Needs Review A pull request which needs code review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants