Skip to content

Correct TOMS 748 root bracketing docs#1418

Draft
mpwaser wants to merge 1 commit into
boostorg:developfrom
mpwaser:fix/toms-748-doc-bracket-root
Draft

Correct TOMS 748 root bracketing docs#1418
mpwaser wants to merge 1 commit into
boostorg:developfrom
mpwaser:fix/toms-748-doc-bracket-root

Conversation

@mpwaser

@mpwaser mpwaser commented Jul 9, 2026

Copy link
Copy Markdown

Fixes #1166.

Summary

This is a documentation-only update for the TOMS 748 root-finding docs.

The parameter description now says that the initial bounds must bracket at
least one root, rather than a single root. The f(a) * f(b) < 0 precondition
remains documented immediately below that text.

Rationale

  • TOMS Algorithm 748 is described as enclosing a zero of a continuous function
    (Alefeld, Potra, and Shi, ACM TOMS 21(3), 1995, DOI:
    10.1145/210089.210111).
  • Boost.Math's implementation enforces a sign-changing bracket, not uniqueness:
    toms748_solve rejects same-sign endpoint values, and detail::bracket
    updates the interval by comparing endpoint signs.
  • With continuous f, the endpoint sign change guarantees at least one
    sign-changing root in the interval. If all roots in the interval are simple
    crossings, this implies an odd number of roots, but additional
    even-multiplicity roots may also lie in the same bounds, so uniqueness is not
    required.

Changes

  • update the Quickbook source in doc/roots/roots_without_derivatives.qbk
  • update the corresponding pregenerated HTML page under doc/html

Validation

  • inspected the issue discussion and existing TOMS 748 precondition wording
  • inspected include/boost/math/tools/toms748_solve.hpp
  • compiled and ran a local smoke test showing:
    • a sign-changing interval containing two distinct roots, one crossing root
      and one even-multiplicity root, is accepted
    • an interval containing two simple roots but no endpoint sign change is
      rejected
  • checked Boost.Math and Boost superproject contribution/template files; no PR
    template is present in the repo or organization-level .github repo
  • checked official Boost requirements/submission guidance and Math README docs
    build instructions
  • bootstrapped b2 and initialized the required Boost documentation tool
    submodules/dependencies
  • ran ../../../b2 -q --user-config=<repo>/user-config.jam from libs/math/doc
  • ran git diff --check

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation bug for TOMS 748

1 participant