multiroot {rootSolve}R Documentation

Solves for n roots of n (nonlinear) equations

Description

Given a vector of n variables, and a set of n (nonlinear) equations in these variables,

estimates the root of the equations, i.e. the variable values where all function values = 0.

Assumes a full Jacobian matrix, uses the Newton-Raphson method

Usage

multiroot(f, start, maxiter=100, 
  rtol=1e-6, atol=1e-8, ctol=1e-8, 
  useFortran=TRUE, positive=FALSE, ...)

Arguments

f function for which the root is sought; it must return a vector with as many values as the length of start
start vector containing initial guesses for the unknown x; if start has a name attribute, the names will be used to label the output vector.
maxiter maximal number of iterations allowed
rtol relative error tolerance, either a scalar or a vector, one value for each element in the unknown x
atol absolute error tolerance, either a scalar or a vector, one value for each element in x
ctol a scalar. If between two iterations, the maximal change in the variable values is less than this amount, then it is assumed that the root is found
useFortran logical, if FALSE, then an R -implementation of the Newton-Raphson method is used - see details
positive if TRUE, the unknowns y are forced to be non-negative numbers
... additional arguments passed to function f

Details

start gives the initial guess for each variable; different initial guesses may return different roots.

The input parameters rtol, and atol determine the error control performed by the solver.

The solver will control the vector e of estimated local errors in f, according to an inequality of the form max-norm of ( e/ewt ) <= 1, where ewt is a vector of positive error weights. The values of rtol and atol should all be non-negative.

The form of ewt is:

rtol * abs(x) + atol

where multiplication of two vectors is element-by-element.

In addition, the solver will stop if between two iterations, the maximal change in the values of x is less than ctol.

There is no checking whether the requested precision exceeds the capabilities of the machine.

Value

a list containing:

root the location (x-values) of the root
f.root the value of the function evaluated at the root
iter the number of iterations used
estim.precis the estimated precision for root. It is defined as the mean of the absolute function values (mean(abs(f.root)))

Note

The Fortran implementation of the Newton-Raphson method function (the default) is generally faster than the R implementation.

multiroot makes use of function steady. Technically, multiroot is just a wrapper around function steady.

The R implementation has been included for didactic purposes.

It is NOT guaranteed that the method will converge to the root.

Author(s)

Karline Soetaert <k.soetaert@nioo.knaw.nl>

See Also

steady, steady.1D, and steady.band, the root solvers for a system of ordinary differential equations. Here variables are state-variables and the function estimates the rate of change.

Examples

# example 1  
# 2 simultaneous equations
model <- function(x) c(F1=x[1]^2+ x[2]^2 -1,F2=x[1]^2- x[2]^2 +0.5)

(ss<-multiroot(f=model,start=c(1,1)))

# example 2
# 3 equations, two solutions
model <- function(x) c(F1= x[1] + x[2] + x[3]^2 - 12,
                       F2= x[1]^2 - x[2] + x[3] - 2,
                       F3= 2 * x[1] - x[2]^2 + x[3] - 1 )

# first solution
(ss<-multiroot(model,c(1,1,1),useFortran=FALSE))
(ss<-multiroot(f=model,start=c(1,1,1)))

# second solution; use different start values
(ss<-multiroot(model,c(0,0,0)))
model(ss$root)

# example 3: find a matrix
f2<-function(x)
 {
 X<-matrix(nr=5,x)
 X %*% X %*% X -matrix(nr=5,data=1:25,byrow=TRUE)
 }
x<-multiroot(f2, start= 1:25 )$root
X<-matrix(nr=5,x)

X%*%X%*%X

[Package rootSolve version 1.3 Index]