bisection_method#

sionna.phy.utils.bisection_method(f: Callable, left: torch.Tensor, right: torch.Tensor, regula_falsi: bool = False, expand_to_left: bool = True, expand_to_right: bool = True, step_expand: float = 2.0, eps_x: float = 1e-05, eps_y: float = 0.0001, max_n_iter: int = 100, return_brackets: bool = False, precision: str | None = None, **kwargs) → torch.Tensor | Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor][source]#

Implements the classic bisection method for estimating the root of batches of decreasing univariate functions

Parameters:

  • f (Callable) – Generic function handle that takes batched inputs and returns batched outputs. Applies a different decreasing univariate function to each of its inputs. Must accept input batches of the same shape as left and right.

  • left (torch.Tensor) – […], torch.float. Left end point of the initial search interval, for each batch. The root is guessed to be contained within [left, right].

  • right (torch.Tensor) – […], torch.float. Right end point of the initial search interval, for each batch.

  • regula_falsi (bool) – If True, then the regula falsi method is employed to determine the next root guess. This guess is computed as the x-intercept of the line passing through the two points formed by the function evaluated at the current search interval endpoints. Else, the next root guess is computed as the middle point of the current search interval. Defaults to False.

  • expand_to_left (bool) – If True and f(left) is negative, then left is decreased by a geometric progression of step_expand until f becomes positive, for each batch. If False, then left is not decreased. Defaults to True.

  • expand_to_right (bool) – If True and f(left) is positive, then right is increased by a geometric progression of step_expand until f becomes negative, for each batch. If False, then right is not increased. Defaults to True.

  • step_expand (float) – See expand_to_left and expand_to_right. Defaults to 2.0.

  • eps_x (float) – Convergence criterion. Search terminates after max_n_iter iterations or if, for each batch, either the search interval length is smaller than eps_x or the function absolute value is smaller than eps_y. Defaults to 1e-5.

  • eps_y (float) – Convergence criterion. See eps_x. Defaults to 1e-4.

  • max_n_iter (int) – Maximum number of iterations. Defaults to 100.

  • return_brackets (bool) – If True, the final values of search interval left and right end point are returned. Defaults to False.

  • precision (str | None) – Precision used for internal calculations and outputs. If set to None, precision is used.

  • kwargs – Additional arguments for function f.

Outputs:

  • x_opt – […], torch.float. Estimated roots of the input batch of functions f.

  • f_opt – […], torch.float. Value of function f evaluated at x_opt.

  • left – […], torch.float. Final value of left end points of the search intervals. Only returned if return_brackets is True.

  • right – […], torch.float. Final value of right end points of the search intervals. Only returned if return_brackets is True.

Examples

import torch
from sionna.phy.utils import bisection_method

# Define a decreasing univariate function of x
def f(x, a):
    return - torch.pow(x - a, 3)

# Initial search interval
left, right = 0., 2.
# Input parameter for function a
a = 3

# Perform bisection method
x_opt, _ = bisection_method(f, left, right, eps_x=1e-4, eps_y=0, a=a)
print(x_opt.numpy())
# 2.9999084
On this page

This Page