*Last updated: 2023-03-16.*
# tf_quant_finance.math.root_search.newton_root
View source
Finds roots of a scalar function using Newton's method.
```python
tf_quant_finance.math.root_search.newton_root(
value_and_grad_func, initial_values, max_iterations=20, tolerance=2e-07,
relative_tolerance=None, dtype=None, name='root_finder'
)
```
This method uses Newton's algorithm to find values `x` such that `f(x)=0` for
some real-valued differentiable function `f`. Given an initial value `x_0` the
values are iteratively updated as:
`x_{n+1} = x_n - f(x_n) / f'(x_n),`
for further details on Newton's method, see [1]. The implementation accepts
array-like arguments and assumes that each cell corresponds to an independent
scalar model.
#### Examples
```python
# Set up the problem of finding the square roots of three numbers.
constants = np.array([4.0, 9.0, 16.0])
initial_values = np.ones(len(constants))
def objective_and_gradient(values):
objective = values**2 - constants
gradient = 2.0 * values
return objective, gradient
# Obtain and evaluate a tensor containing the roots.
roots = tff.math.root_search.newton_root(objective_and_gradient,
initial_values)
print(root_values) # Expected output: [ 2. 3. 4.]
print(converged) # Expected output: [ True True True]
print(failed) # Expected output: [False False False]
```
#### References
[1] Luenberger, D.G., 1984. 'Linear and Nonlinear Programming'. Reading, MA:
Addison-Wesley.
#### Args:
* `value_and_grad_func`: A python callable that takes a `Tensor` of the same
shape and dtype as the `initial_values` and which returns a two-`tuple` of
`Tensors`, namely the objective function and the gradient evaluated at the
passed parameters.
* `initial_values`: A real `Tensor` of any shape. The initial values of the
parameters to use (`x_0` in the notation above).
* `max_iterations`: positive `int`. The maximum number of
iterations of Newton's method.
Default value: 20.
* `tolerance`: positive scalar `Tensor`. The absolute tolerance for the root
search. Search is judged to have converged if
`|f(x_n) - f(x_n-1)|` < |x_n| * `relative_tolerance` + `tolerance`
(using the notation above), or if `x_n` becomes `nan`. When an element is
judged to have converged it will no longer be updated. If all elements
converge before `max_iterations` is reached then the root finder will
return early. If None, it would be set according to the `dtype`,
which is 4 * np.finfo(dtype.as_numpy_dtype(0)).eps.
Default value: 2e-7.
* `relative_tolerance`: positive `double`, default 0. See the document for
`tolerance`.
Default value: None.
* `dtype`: optional `tf.DType`. If supplied the `initial_values` will be coerced
to this data type.
Default value: None.
* `name`: `str`, to be prefixed to the name of
TensorFlow ops created by this function.
Default value: 'root_finder'.
#### Returns:
A three tuple of `Tensor`s, each the same shape as `initial_values`. It
contains the found roots (same dtype as `initial_values`), a boolean
`Tensor` indicating whether the corresponding root results in an objective
function value less than the tolerance, and a boolean `Tensor` which is true
where the corresponding 'root' is not finite.