[R] nls convergence problem

[Earl F. Glynn]

I'm having problems getting nls to agree that convergence has occurred in a 
toy problem.

nls.out never gets defined when there is an error in nls.  Reaching the 
maximum number of iterations is alway an error, so nls.out never gets 
defined when the maximum number of iterations is reched.

>From ?nls.control:
  tol: A positive numeric value specifying the tolerance level for
          the relative offset convergence criterion.

>From some S-Plus documentation I found online via Google:
http://www.uni-muenster.de/ZIV/Mitarbeiter/BennoSueselbeck/s-html/helpfiles/nls.control.html

tolerance:
tolerance for the relative offset convergence criterion in the algorithm. 
Default 0.001. Note that the convergence test used in nls() is strictly 
relative. Therefore if the solution to a problem turned out to be a perfect 
fit (unlikely except in artificial examples), convergence is not guaranteed 
to be recognized by the algorithm.


Here's my toy problem:
> ?nls.control
> ?nls
> # Method 2
> X <- 0:15
> Y <- 9.452 * exp(-0.109*X) + 5.111   # Toy problem
>
> nls.out <- nls(Y ~ a*exp(b*X)+c,
+                start=list(a=6,b=-0.5,c=1),
+                control=nls.control(maxiter=15, tol=0.01),  # nothing makes 
sense here
+                trace=TRUE)
1016.507 :   6.0 -0.5  1.0
143.5807 :   6.1680290 -0.1506021  4.4013020
7.306365 :   9.10093164 -0.09114858  5.44620298
0.0342703 :   9.2801070 -0.1109063  5.2795803
3.001985e-05 :   9.4506654 -0.1089749  5.1122982
1.918531e-14 :   9.452 -0.109  5.111
6.894644e-28 :   9.452 -0.109  5.111
2.208811e-29 :   9.452 -0.109  5.111
7.888609e-30 :   9.452 -0.109  5.111
7.888609e-30 :   9.452 -0.109  5.111
7.099748e-30 :   9.452 -0.109  5.111
3.155444e-30 :   9.452 -0.109  5.111
3.155444e-30 :   9.452 -0.109  5.111
3.155444e-30 :   9.452 -0.109  5.111
3.155444e-30 :   9.452 -0.109  5.111
3.155444e-30 :   9.452 -0.109  5.111
Error in nls(Y ~ a * exp(b * X) + c, start = list(a = 6, b = -0.5, c = 1), 
:
        number of iterations exceeded maximum of 15

There is near-perfect convergence after 12 iterations, but I cannot figure 
out a way for R to recognize it.

What does "relative offset convergence criterion" mean?  How can nls.control 
be used to say this problem has converged, and have nls exit without an 
error?

Should the R documentation be modified to explain what "relative offset 
convergence criterion" means?  Should the R documentation be expanded to 
include the comment from the S-Plus: "Therefore if the solution to a problem 
turned out to be a perfect fit (unlikely except in artificial examples), 
convergence is not guaranteed to be recognized by the algorithm".  If this 
is true, this seems like a suboptimal design.

Thanks for any insight about this.

efg

Earl F. Glynn
Scientific Programmer
Stowers Institute for Medical Research