Inverse of a monotone function.

DESCRIPTION:

Inverse of a monotone function, solve f(x)=y.

USAGE:

inverseFunction(f, v, initial=0:1, f.initial, 
                tol=.Machine$double.eps^0.25, 
                maxiter=10, domain=c( - Inf, Inf), ...) 

REQUIRED ARGUMENTS:

f
a real-valued monotone function, for which the first argument may be vector-valued. There may be additional arguments.
v
real-valued scalar or vector; solve f(x)=v.

OPTIONAL ARGUMENTS:

initial
initial guesses for x. The length of initial must be at least two, and need not be the same length as v. It is helpful if the range of these values contains the solution(s).
f.initial
the value of f(initial), if known.
tol
approximate numerical tolerance for solutions. The actual tolerance is based on tol and includes a term that scales with the size of the solution: each returned value falls within
tol + 4*.Machine$double.eps*abs(x)
of the exact solution, where "x" takes on values closer and closer to the exact solution as the method converges. This is the same tolerance used by the function and by the Fortran routine root1d, which is called by and this function.
maxiter
maximum number of iterations used to find an interval that bounds all solutions.
domain
if known, the domain of f, e.g. domain=c(0, Inf).
...
additional arguments for f.

VALUE:

vector of values of x for which f(x, ...) = v.

DETAILS:

This function first finds a bounding interval, evaluates f at additional intermediate points, then uses a monotone spline function to obtain initial guesses and bounding intervals for the solution for each value of v. Then, for each value of v, use Brent's safeguarded polynomial interpolation procedure for solving a univariate nonlinear equation, based on the Fortran function zeroin from NETLIB (Dongarra and Grosse 1987).

The initial values must fall within the domain of the function.

If the initial values do not bound the solutions, the function may attempt values of x outside the domain while finding a bounding region; if f then returns NA the function keeps track of information about the domain, and continues attempting to bound the solutions using other values of x.

Users can accumulate information through attributes of the function value. If the attributes includes additional arguments of f, the next function call uses the new values of those arguments.

The function f must be monotone. If necessary, you may restrict consideration to an interval using the domain argument, chosen so that the function is monotone over the domain, see example below.

This function calls Fortran routine root1d, which stores information internally. This function may not call uniroot or vice versa, and neither function may be called recursively.

REFERENCES:

Brent, R. (1973), Algorithms for Minimization without Derivatives, Prentice-Hall, Englewood Cliffs, NJ, USA.

Dongarra, J. J., and Grosse, E. (1987), "Distribution of mathematical software via electronic mail," Communications of the ACM 30, pp. 403-407.

SEE ALSO:

, .

EXAMPLES:

inverseFunction(exp, 1:3) 
inverseFunction(log, 1:3, 1:2) 
inverseFunction(logb, 1:3, 1:2, base=2) 
inverseFunction(function(x) x^3+x+1, 1:3) 
 
# inverseFunction(sin, .99)  # This fails because sin is not monotone 
inverseFunction(sin, .99, domain=c(-pi/2, pi/2)) # monotone on this domain