CL_fsolveb

Description

• Solves fct(x) = 0 by the secant method or variants.

  The function fct must have the following interface:

  y = fct(x, ind, args)

  where x is a vector of size (1xP), ind is a vector of indices of the same size as x, and args is a variable of any type (with a constant value). ind contains the indices currently evalued (corresponding to the values in x).

  An interval (x1, x2) containing the solution must be known (x1 may not be smaller than x2).

  The solution is found if the 2 following conditions are met (if they are applicable): |y| is less than ytol and |dx| is less than dxtol where y=fct(x), and dx is the change in the value of x in the last iteration. If ytol or dxtol are not specified, the corresponding condition is automatically met. If none of them is specified, ytol is set to 0, and dxtol is not set.

  Variants of algorithm are possible by using the meth parameter:

  - meth = "s" : usual secant method.

  - meth = "d" : dichotomy.

  - meth = "ds" : dichotomy + secant method at each iteration. Convergence may be faster but at the price of one additional function call per iteration.

  - meth = "s2" : variant of secant method. The algorithm makes the size of the current interval shrink as much as possible at each iteration (so that it may not necessarily contain the solution). This method can be faster than the other ones, but the convergence is not guaranteed.

  The values y1=fct(x1) and y2=fct(x2) may be given. If not, they are automatically computed by the algorithm.

  The output argument info contains additional information:

  info = 0: OK

  info = 1: fct(x1) and fct(x2) have the same sign or x1 == x2 (for some indices). The corresponding results are set to %nan.

  info = 2: No convergence (for some indices). The corresponding results are set to %nan.

  info = 3: Corresponds to: info == 1 & info == 2.

• Notes :

  - if x1, x2, y1, or y2 contains %nan (for some indices), the corresponding outputs are set to %nan.

  - if fct returns %nan (for some indices), the corresponding outputs are set to %nan.

  - fct should be continuous and monotonous in [x1, x2].

Parameters

fct:

(function) Function with interface: y = f(x, ind, args)

x1, x2:

Interval containing the solution. (1xN)

args:

(optional, any type) Argument passed to "fct" function. Default is [].

ytol:

(optional) Tolerance on fct(x). (1x1)

dxtol:

(optional) Tolerance on change in x. (1x1)

meth:

(optional) Option of algorithm ("s", "d", "ds", "s2"). Default is "s".

y1:

(optional) Value of fct at x1. (1xN)

y2:

(optional) Value of fct at x2. (1xN)

x:

value such that fct(x) = 0. (1xN)

y:

Exact value of fct at x. (1xN)

info:

(integer) Additional information. 0 means "OK".

Authors

• CNES - DCT/SB

Examples

// Example 1: Solves: sin(x) = 0.1 function [y]=fct(x, ind, args) y = sin(x) - 0.1; endfunction [x, y] = CL_fsolveb(fct, -1, 1); // Example 2: Solves: sin(x) = [0.1, 0.2, 0.3, 0.4, 0.5] clear fct; function [y]=fct(x, ind, args) y = sin(x) - args(ind); endfunction n = 5; args = (1:n) / 10; x1 = -1 * ones(1,n); x2 = 1 * ones(1,n); [x, y, info] = CL_fsolveb(fct, x1, x2, args, ytol=1.e-12);