feat: add optimize/base/brentq

lib/node_modules/@stdlib/optimize/base/brentq/README.md

@@ -0,0 +1,117 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2026 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# brentq
+
+> Find a zero of a continuous function using Brent's method.
+
+<section class="intro">
+
+Finds a zero of a continuous function $f$ on the interval $\lbrack a, b \rbrack$ where the sign of $f(a)$ and $f(b)$ must be opposite.
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var brentq = require( '@stdlib/optimize/base/brentq' );
+```
+
+#### brentq( f, a, b, maxIter, xtol, rtol, args )
+
+Finds a zero of a continuous function `f` on the interval `[a, b]`.
+
+```javascript
+function f( x ) {
+    return ( x * x ) - 1.0;
+}
+
+var out = brentq( f, 0.0, 2.0, 100, 2.0e-12, 8.88e-16, [] );
+var root = out.root;
+// returns 1.0
+```
+
+The function returns a solution object with the following properties:
+
+-   **root**: the root.
+-   **iterations**: number of iterations.
+-   **function_calls**: number of function calls.
+-   **converged**: boolean indicating if convergence was reached.
+-   **flag**: convergence condition message.
+-   **method**: method name.
+
+The function has the following parameters:
+
+-   **f**: objective function `f(x, ...args)`.
+-   **a**: lower bound.
+-   **b**: upper bound.
+-   **maxIter**: maximum number of iterations.
+-   **xtol**: absolute tolerance.
+-   **rtol**: relative tolerance.
+-   **args**: array of arguments to be passed to `f`.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var sin = require( '@stdlib/math/base/special/sin' );
+var brentq = require( '@stdlib/optimize/base/brentq' );
+
+function f( x ) {
+    return sin( x );
+}
+
+var out = brentq( f, 3.0, 3.2, 100, 2e-12, 8.88e-16, [] );
+var root = out.root;
+
+console.log( root );
+// => 3.141592653589793
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/optimize/base/brentq/benchmark/benchmark.js

@@ -0,0 +1,52 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var pkg = require( './../package.json' ).name;
+var brentq = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var root;
+	var i;
+
+	function f( x ) {
+		return ( x * x ) - 1.0;
+	}
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		root = brentq( f, 0.0, 2.0, 100, 2e-12, 8.88e-16, [] );
+		if ( isnan( root ) ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( isnan( root ) ) {
+		b.fail( 'should not return NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

lib/node_modules/@stdlib/optimize/base/brentq/docs/repl.txt

@@ -0,0 +1,43 @@
+
+{{alias}}( f, a, b, maxIter, xtol, rtol, args )
+    Finds a zero of a continuous function `f` on the interval `[a, b]`.
+
+    Parameters
+    ----------
+    f: Function
+        Objective function.
+
+    a: number
+        Lower bound.
+
+    b: number
+        Upper bound.
+
+    maxIter: integer
+        Maximum number of iterations.
+
+    xtol: number
+        Absolute tolerance.
+
+    rtol: number
+        Relative tolerance.
+
+    args: Array
+        Callback function arguments.
+
+    Returns
+    -------
+    results: Object
+        Solution object.
+
+    Examples
+    --------
+    > function f( x ) { return x*x - 1.0; };
+    > var out = {{alias}}( f, 0.0, 2.0, 100, 2e-12, 8.88e-16, [] );
+    > out.root
+    1.0
+
+    See Also
+    --------
+
+

lib/node_modules/@stdlib/optimize/base/brentq/docs/types/index.d.ts

@@ -0,0 +1,87 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2026 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+// TypeScript Version: 4.1
+
+/**
+* Callback function.
+*
+* @param x - input value
+* @param args - callback function arguments
+* @returns function value
+*/
+type Callback = ( x: number, ...args: Array<any> ) => number;
+
+/**
+* Solution object.
+*/
+interface Results {
+	/**
+	* The root.
+	*/
+	root: number;
+
+	/**
+	* Number of iterations.
+	*/
+	iterations: number;
+
+	/**
+	* Number of function calls.
+	*/
+	function_calls: number;
+
+	/**
+	* Boolean indicating if convergence was reached.
+	*/
+	converged: boolean;
+
+	/**
+	* Convergence condition message.
+	*/
+	flag: string;
+
+	/**
+	* Method name.
+	*/
+	method: string;
+}
+
+/**
+* Finds a zero of a continuous function `f` on the interval `[a, b]`.
+*
+* @param f - objective function
+* @param a - lower bound
+* @param b - upper bound
+* @param maxIter - maximum number of iterations
+* @param xtol - absolute tolerance
+* @param rtol - relative tolerance
+* @param args - callback function arguments
+* @returns solution object
+*
+* @example
+* function f( x ) {
+*     return x * x - 1.0;
+* }
+* var out = brentq( f, 0.0, 2.0, 100, 2e-12, 8.88e-16, [] );
+* var root = out.root;
+* // returns 1.0
+*/
+declare function brentq( f: Callback, a: number, b: number, maxIter: number, xtol: number, rtol: number, args: Array<any> ): Results;
+
+export = brentq;