# HG changeset patch
# User Arun Giridhar <arungiridhar@gmail.com>
# Date 1665100326 14400
# Node ID e5e35410da904d263b5c6f742e246ab05c7ac20e
# Parent  24247d13a44b6c50ed6a9d43a5af02195061ef1c
doc: Documented undocumented outputs for lsqnonneg and pqpnonneg

lsqnonneg.m: Edited docstring to describe what the output lambda was,
previously not documented.  In the course of testing, an error was
found for an (unlikely) edge case.  Marked that with FIXME for now.

pqpnonneg.m: Same as above.

diff -r 24247d13a44b -r e5e35410da90 scripts/optimization/lsqnonneg.m
--- a/scripts/optimization/lsqnonneg.m	Sun Oct 02 09:00:05 2022 -0400
+++ b/scripts/optimization/lsqnonneg.m	Thu Oct 06 19:52:06 2022 -0400
@@ -69,8 +69,10 @@
 ## @end itemize
 ##
 ## @item lambda
-## @c FIXME: Something is output from the function, but what is it?
-## Undocumented output
+## Conjugate gradient at the converged point.  Zero elements are usually
+## abutting coordinate planes.  Negative elements are stable to small
+## perturbations.
+##
 ## @end table
 ## @seealso{pqpnonneg, lscov, optimset}
 ## @end deftypefn
@@ -219,6 +221,11 @@
   if (isargout (6))
     lambda = zeros (size (x));
     lambda(p) = w;
+    ## FIXME: The above line errors when the solution is NOT constrained
+    ## by non-negativity!  That case happens when the lsqnonneg solution
+    ## is the same as the fminunc solution.  Ideally the user would not
+    ## be using lsqnonneg if nonnegativity constraints are not active, but we
+    ## should handle that more gracefully.
   endif
 
 endfunction
diff -r 24247d13a44b -r e5e35410da90 scripts/optimization/pqpnonneg.m
--- a/scripts/optimization/pqpnonneg.m	Sun Oct 02 09:00:05 2022 -0400
+++ b/scripts/optimization/pqpnonneg.m	Thu Oct 06 19:52:06 2022 -0400
@@ -71,8 +71,10 @@
 ## @end itemize
 ##
 ## @item lambda
-## @c FIXME: Something is output from the function, but what is it?
-## Undocumented output
+## Conjugate gradient at the converged point.  Zero elements are usually
+## abutting coordinate planes.  Negative elements are stable to small
+## perturbations.
+##
 ## @end table
 ## @seealso{lsqnonneg, qp, optimset}
 ## @end deftypefn
@@ -223,6 +225,11 @@
   if (isargout (5))
     lambda = zeros (size (x));
     lambda(p) = w;
+    ## FIXME: The above line errors when the solution is NOT constrained
+    ## by non-negativity!  That case happens when the lsqnonneg solution
+    ## is the same as the fminunc solution.  Ideally the user would not
+    ## be using lsqnonneg if nonnegativity constraints are not active, but we
+    ## should handle that more gracefully.
   endif
 
 endfunction