Updated API documentation and added remaining unit tests from the DAM…

…TP test report.

README.rdoc

@@ -33,7 +33,7 @@ Implement the interface explicitly or anonymously. The _Compute_ method exhibits
 where _n_ is the number of variables, _m_ is the number of constraints, _x_ is the variable array, and _con_ is the array of calculated constraints 
 function values. The method should return the value of the objective function.
 
-To minimize the objective function subject to constraints, call the static _Cobyla.FindMinimum_ methods:
+To minimize the objective function subject to constraints, call the static _Cobyla.FindMinimum_ method:
 
     CobylaExitStatus FindMinimum(Calcfc calcfc, int n, int m, double[] x, 
                       double rhobeg, double rhoend, int iprint, int maxfun);
@@ -43,6 +43,8 @@ specifies the level of output to the console, and _maxfun_ is the maximum allowe
 optimal obtained variable values. The method returns final optimization status, which is one of normal termination, maximum iterations 
 reached or diverging rounding errors.
 
+For usage examples with anonymous interface implementations, please review the _CobylaTest.java_ file in the _test_ folder.
+
 ==The MIT License
 
 Copyright (c) 2012 Anders Gustafsson, Cureos AB.
@@ -61,4 +63,5 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ==Revision history
 
+* May 2, 2012: Reference to usage examples.
 * May 1, 2012: Initial document.

src/com/cureos/numerics/Calcfc.java

@@ -1,13 +1,42 @@
 /*
- * To change this template, choose Tools | Templates
- * and open the template in the editor.
+ * jcobyla
+ * 
+ * The MIT License
+ *
+ * Copyright (c) 2012 Anders Gustafsson, Cureos AB.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files 
+ * (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, 
+ * publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 
+ * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * 
+ * Remarks:
+ * 
+ * The original Fortran 77 version of this code was by Michael Powell (M.J.D.Powell @ damtp.cam.ac.uk)
+ * The Fortran 90 version was by Alan Miller (Alan.Miller @ vic.cmis.csiro.au). Latest revision - 30 October 1998
  */
 package com.cureos.numerics;
 
 /**
- *
- * @author anders
+ * Interface for calculation of objective function and constraints in COBYLA2 optimization.
+ * 
+ * @author Anders Gustafsson, Cureos AB.
  */
 public interface Calcfc {
+    /**
+     * The objective and constraints function evaluation method used in COBYLA2 minimization.
+     * @param n Number of variables.
+     * @param m Number of constraints.
+     * @param x Variable values to be employed in function and constraints calculation.
+     * @param con Calculated function values of the constraints.
+     * @return Calculated objective function value.
+     */
     double Compute(int n, int m, double[] x, double[] con);
 }

src/com/cureos/numerics/Cobyla.java

@@ -25,21 +25,38 @@
 package com.cureos.numerics;
 
 /**
- *
- * @author anders
+ * Constrained Optimization BY Linear Approximation in Java.
+ * 
+ * COBYLA2 is an implementation of Powell’s nonlinear derivative–free constrained optimization that uses 
+ * a linear approximation approach. The algorithm is a sequential trust–region algorithm that employs linear
+ * approximations to the objective and constraint functions, where the approximations are formed by linear
+ * interpolation at n + 1 points in the space of the variables and tries to maintain a regular–shaped simplex 
+ * over iterations.
+ * 
+ * It solves nonsmooth NLP with a moderate number of variables (about 100). Inequality constraints only.
+ * 
+ * The initial point X is taken as one vertex of the initial simplex with zero being another, so, X should
+ * not be entered as the zero vector.
+ * 
+ * @author Anders Gustafsson, Cureos AB.
  */
 public class Cobyla
 {    
     /**
-     *
-     * @param calcfc the value of calcfc
-     * @param n the value of n
-     * @param m the value of m
-     * @param x the value of x
-     * @param rhobeg the value of rhobeg
-     * @param rhoend the value of rhoend
-     * @param iprint the value of iprint
-     * @param maxfun the value of maxfun
+     * Minimizes the objective function F with respect to a set of inequality constraints CON,
+     * and returns the optimal variable array. F and CON may be non-linear, and should preferably be smooth.
+     * 
+     * @param calcfc Interface implementation for calculating objective function and constraints.
+     * @param n Number of variables.
+     * @param m Number of constraints.
+     * @param x On input initial values of the variables (zero-based array). On output
+     * optimal values of the variables obtained in the COBYLA minimization.
+     * @param rhobeg Initial size of the simplex.
+     * @param rhoend Final value of the simplex.
+     * @param iprint Print level, 0 <= iprint <= 3, where 0 provides no output and
+     * 3 provides full output to the console.
+     * @param maxfun Maximum number of function evaluations before terminating.
+     * @return Exit status of the COBYLA2 optimization.
      */
     public static CobylaExitStatus FindMinimum(final Calcfc calcfc, int n, int m, double[] x, double rhobeg, double rhoend, int iprint, int maxfun)
     {
@@ -97,13 +114,21 @@ public static CobylaExitStatus FindMinimum(final Calcfc calcfc, int n, int m, do
         int mpp = m + 2;
 
         // Internal base-1 X array
-        double[] xio = new double[n + 1];
-        System.arraycopy(x, 0, xio, 1, n);
+        double[] iox = new double[n + 1];
+        System.arraycopy(x, 0, iox, 1, n);
 
         // Internal representation of the objective and constraints calculation method, 
         // accounting for that X and CON arrays in the cobylb method are base-1 arrays.
         Calcfc fcalcfc = new Calcfc()
         {
+            /**
+             *
+             * @param n the value of n
+             * @param m the value of m
+             * @param x the value of x
+             * @param con the value of con
+             * @return the double
+             */
             @Override
             public double Compute(int n, int m, double[] x, double[] con)
             {
@@ -116,8 +141,8 @@ public double Compute(int n, int m, double[] x, double[] con)
             }
         };                
 
-        CobylaExitStatus status = cobylb(fcalcfc, n, m, mpp, xio, rhobeg, rhoend, iprint, maxfun);
-        System.arraycopy(xio, 1, x, 0, n);
+        CobylaExitStatus status = cobylb(fcalcfc, n, m, mpp, iox, rhobeg, rhoend, iprint, maxfun);
+        System.arraycopy(iox, 1, x, 0, n);
 
         return status;
     }

src/com/cureos/numerics/CobylaExitStatus.java

@@ -1,15 +1,47 @@
 /*
- * To change this template, choose Tools | Templates
- * and open the template in the editor.
+ * jcobyla
+ * 
+ * The MIT License
+ *
+ * Copyright (c) 2012 Anders Gustafsson, Cureos AB.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files 
+ * (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, 
+ * publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE 
+ * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * 
+ * Remarks:
+ * 
+ * The original Fortran 77 version of this code was by Michael Powell (M.J.D.Powell @ damtp.cam.ac.uk)
+ * The Fortran 90 version was by Alan Miller (Alan.Miller @ vic.cmis.csiro.au). Latest revision - 30 October 1998
  */
 package com.cureos.numerics;
 
 /**
- *
- * @author anders
+ * Enumeration of exit statuses associated with COBYLA2 optimization.
+ * 
+ * @author Anders Gustafsson, Cureos AB.
  */
 public enum CobylaExitStatus {
+    /**
+     * Optimization successfully completed.
+     */
     Normal,
+
+    /**
+     * Maximum number of iterations (function/constraints evaluations) reached during optimization.
+     */
     MaxIterationsReached,
+
+    /**
+     * Size of rounding error is becoming damaging, terminating prematurely.
+     */
     DivergingRoundingErrors
 }