[Rd] Query: Could documentation include modernized references?

[J C Nash]

Thanks Martin.

Following Duncan's advice as well as some textual input, I have put a proposed Rd file for
optim on a fork of the R code at
https://github.com/nashjc/r/blob/master/src/library/stats/man/optim.Rd

This has the diffs given below from the github master. The suggested changes
primarily point to a Task View, which I believe is a sensible approach.

I'll admit to being rather clumsy with git, and will be happy to receive advice
on how to proceed if more work needed on my part.

Cheers,

John Nash




--- optim.Rd	2022-03-24 19:02:04.000000000 -0400
+++ optim.Rd.20230324.txt	2023-03-29 09:23:28.373457291 -0400
@@ -15,6 +15,9 @@
    General-purpose optimization based on Nelder--Mead, quasi-Newton and
    conjugate-gradient algorithms. It includes an option for
    box-constrained optimization and simulated annealing.
+  These methods are quite old and better ones are known for many
+  problems.  See the Optimization and Mathematical Programming task
+  view (Schwendinger and Borchers, 2023) for a survey.
  }
  \usage{
  optim(par, fn, gr = NULL, \dots,
@@ -67,6 +70,8 @@
    Beale--Sorenson updates).  Conjugate gradient methods will generally
    be more fragile than the BFGS method, but as they do not store a
    matrix they may be successful in much larger optimization problems.
+  The \code{"CG"} method has known improvements that are discussed in
+  Schwendinger and Borchers (2023)."

    Method \code{"L-BFGS-B"} is that of Byrd \emph{et. al.} (1995) which
    allows \emph{box constraints}, that is each variable can be given a lower
@@ -230,8 +235,10 @@
  \source{
    The code for methods \code{"Nelder-Mead"}, \code{"BFGS"} and
    \code{"CG"} was based originally on Pascal code in Nash (1990) that was
-  translated by \code{p2c} and then hand-optimized.  Dr Nash has agreed
-  that the code can be made freely available.
+  translated by \code{p2c} and then hand-optimized.  Dr Nash has agreed
+  that the code can be made freely available, but recommends that the more
+  reliable \code{optimx::Rcgmin()} function should be used instead of
+  method \code{"CG"}.

    The code for method \code{"L-BFGS-B"} is based on Fortran code by Zhu,
    Byrd, Lu-Chen and Nocedal obtained from Netlib (file
@@ -269,6 +276,10 @@
    Nocedal, J. and Wright, S. J. (1999).
    \emph{Numerical Optimization}.
    Springer.
+	
+  Florian Schwendinger, Hans W. Borchers (2023). \emph{CRAN Task View:
+  Optimization and Mathematical Programming.} Version 2023-02-16.
+  URL https://CRAN.R-project.org/view=Optimization.	
  }

  \seealso{




On 2023-03-31 09:31, Martin Maechler wrote:
> 
> Thanks a lot, Duncan, for this (as usual from you) very precise
> and helpful information / explanations.
> 
> I am "happy"/willing to get involved a bit here, as I do want to
> spend some time re-reading about current state of (some, notably
> optim-related) optimizers.
> 
> (But I will be mostly offline for the next 60 hours or so.)
> 
> 
> Martin
> 
> --
> Martin Maechler
> ETH Zurich  and  R Core team