001    package numal.lowprecision;
002    
003    /** Methods for computing the residual vector of a function, its jacobian matrix and several
004      * options accessor methods which control the behavior of {@link AnalyticProblems#marquardt}
005      * to evaluate the properties of a given function f(x[i],par) with n parameters par over a set
006      * of point {x[i],y[i]) where i=1 to m.
007      */
008    public interface Function {
009    
010      /** Get the analytic values of the function for the given set of parameters and for all abcissa.
011       *
012       * @param m number of sample points used in the fitting
013       * @param parameter an array of function parameters
014       * @return the value of this function for all abcissa and parameters
015       */
016      public float[] getAnalyticValues(int m, float parameter[]);
017    
018      /** Get residual vector rv[i] = f(x[i],par) - y[i]. POSTCONDITION: parameter array must not be altered.
019       *  
020       * @param m number of sample points used in the fitting
021       * @param n number of parameters, must be less than or equal to m
022       * @param parameter <b>input</b>: current values of parameters (shouldn't be altered by funct)
023       * @param rv <b>output</b>: residual vector obtained with current value of parameters; i.e  f(x[i],par) - y[i]
024       * @return true when successful, false if current estimates of parameters lie outside a feasible region (invoker can avoid residual vector calculations on values which may make no sense or even cause overflow)
025       */
026      public boolean computeResidualVector(int m, int n, float parameter[], float rv[]);
027      
028      /** Get the partial derivatives jac[i][j] = drv[i]/dpar[j], obtained with the current values
029       * of the parameters. The precision of this method in computing the elements of jac must be at
030       * least the precision defined by in[3] and in[4] of {@link AnalyticProblems#marquardt}.
031       * POSTCONDITION: parameter array must not be altered.
032       *
033       * @param m number of sample points used in the fitting
034       * @param n number of parameters, must be less than or equal to the number of sample points
035       * @param parameter <b>input</b>: current values of parameters
036       * @param rv <b>output</b>: residual vector obtained with current value of parameters; i.e  f(x[i],parameter) - y[i]
037       * @param jac <b>output</b>: partial derivatives drv[i]/dparameter[j], obtained with the current values of the parameters
038       */
039      public void computeJacobian(int m, int n, float parameter[], float rv[], float jac[][]);
040      
041      /** Maximum allowed number of invocations of {@link Function#computeResidualVector} */
042      public int getInvocations();          // in[5]
043    
044      /** Machine precision */
045      public float getMachinePrecision();   // in[0]
046    
047      /** Relative tolerance for the difference between the Euclidian norm of the ultimate and
048       *  penultimate residual vector (value of epsilon_re) (see absoluteTolerance) */
049      public float getRelativeTolerance();  // in[3]
050    
051      /** Absolute tolerance for the difference between the Euclidian norm of the ultimate and
052       *  penultimate residual vector (value of epsilon_a) the process is terminated if the improvement
053       *  of the sum of the squares is less than relativeTolerance*(sum of the squares)+absoluteTolerance*absoluteTolerance */
054      public float getAbsoluteTolerance();  // in[4]
055      
056      /** Starting value used for the relation between the gradient and the Gauss-Newton direction (value of &xi;);
057       *  if the problem is well conditioned then a suitable value for startingValue will be 0.01;
058       *  if the problem is ill conditioned then startingValue should be greater, but the value of startingValue must
059       *  satisfy : machinePrecision &lt; startingValue &le; 1 / machinePrecision */
060      public float getStartingValue();      // in[6]
061    
062    }