BaseOptimizer.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.math3.optim;

  19. import org.apache.commons.math3.util.Incrementor;
  20. import org.apache.commons.math3.exception.TooManyEvaluationsException;
  21. import org.apache.commons.math3.exception.TooManyIterationsException;

  23. /**
  24.  * Base class for implementing optimizers.
  25.  * It contains the boiler-plate code for counting the number of evaluations
  26.  * of the objective function and the number of iterations of the algorithm,
  27.  * and storing the convergence checker.
  28.  * <em>It is not a "user" class.</em>
  29.  *
  30.  * @param <PAIR> Type of the point/value pair returned by the optimization
  31.  * algorithm.
  32.  *
  33.  * @since 3.1
  34.  */
  35. public abstract class BaseOptimizer<PAIR> {
  36.     /** Evaluations counter. */
  37.     protected final Incrementor evaluations;
  38.     /** Iterations counter. */
  39.     protected final Incrementor iterations;
  40.     /** Convergence checker. */
  41.     private final ConvergenceChecker<PAIR> checker;

  43.     /**
  44.      * @param checker Convergence checker.
  45.      */
  46.     protected BaseOptimizer(ConvergenceChecker<PAIR> checker) {
  47.         this(checker, 0, Integer.MAX_VALUE);
  48.     }

  50.     /**
  51.      * @param checker Convergence checker.
  52.      * @param maxEval Maximum number of objective function evaluations.
  53.      * @param maxIter Maximum number of algorithm iterations.
  54.      */
  55.     protected BaseOptimizer(ConvergenceChecker<PAIR> checker,
  56.                             int maxEval,
  57.                             int maxIter) {
  58.         this.checker = checker;

  60.         evaluations = new Incrementor(maxEval, new MaxEvalCallback());
  61.         iterations = new Incrementor(maxIter, new MaxIterCallback());
  62.     }

  64.     /**
  65.      * Gets the maximal number of function evaluations.
  66.      *
  67.      * @return the maximal number of function evaluations.
  68.      */
  69.     public int getMaxEvaluations() {
  70.         return evaluations.getMaximalCount();
  71.     }

  73.     /**
  74.      * Gets the number of evaluations of the objective function.
  75.      * The number of evaluations corresponds to the last call to the
  76.      * {@code optimize} method. It is 0 if the method has not been
  77.      * called yet.
  78.      *
  79.      * @return the number of evaluations of the objective function.
  80.      */
  81.     public int getEvaluations() {
  82.         return evaluations.getCount();
  83.     }

  85.     /**
  86.      * Gets the maximal number of iterations.
  87.      *
  88.      * @return the maximal number of iterations.
  89.      */
  90.     public int getMaxIterations() {
  91.         return iterations.getMaximalCount();
  92.     }

  94.     /**
  95.      * Gets the number of iterations performed by the algorithm.
  96.      * The number iterations corresponds to the last call to the
  97.      * {@code optimize} method. It is 0 if the method has not been
  98.      * called yet.
  99.      *
  100.      * @return the number of evaluations of the objective function.
  101.      */
  102.     public int getIterations() {
  103.         return iterations.getCount();
  104.     }

  106.     /**
  107.      * Gets the convergence checker.
  108.      *
  109.      * @return the object used to check for convergence.
  110.      */
  111.     public ConvergenceChecker<PAIR> getConvergenceChecker() {
  112.         return checker;
  113.     }

  115.     /**
  116.      * Stores data and performs the optimization.
  117.      * <p>
  118.      * The list of parameters is open-ended so that sub-classes can extend it
  119.      * with arguments specific to their concrete implementations.
  120.      * <p>
  121.      * When the method is called multiple times, instance data is overwritten
  122.      * only when actually present in the list of arguments: when not specified,
  123.      * data set in a previous call is retained (and thus is optional in
  124.      * subsequent calls).
  125.      * <p>
  126.      * Important note: Subclasses <em>must</em> override
  127.      * {@link #parseOptimizationData(OptimizationData[])} if they need to register
  128.      * their own options; but then, they <em>must</em> also call
  129.      * {@code super.parseOptimizationData(optData)} within that method.
  130.      *
  131.      * @param optData Optimization data.
  132.      * This method will register the following data:
  133.      * <ul>
  134.      *  <li>{@link MaxEval}</li>
  135.      *  <li>{@link MaxIter}</li>
  136.      * </ul>
  137.      * @return a point/value pair that satisfies the convergence criteria.
  138.      * @throws TooManyEvaluationsException if the maximal number of
  139.      * evaluations is exceeded.
  140.      * @throws TooManyIterationsException if the maximal number of
  141.      * iterations is exceeded.
  142.      */
  143.     public PAIR optimize(OptimizationData... optData)
  144.         throws TooManyEvaluationsException,
  145.                TooManyIterationsException {
  146.         // Parse options.
  147.         parseOptimizationData(optData);

  149.         // Reset counters.
  150.         evaluations.resetCount();
  151.         iterations.resetCount();
  152.         // Perform optimization.
  153.         return doOptimize();
  154.     }

  156.     /**
  157.      * Performs the optimization.
  158.      *
  159.      * @return a point/value pair that satisfies the convergence criteria.
  160.      * @throws TooManyEvaluationsException if the maximal number of
  161.      * evaluations is exceeded.
  162.      * @throws TooManyIterationsException if the maximal number of
  163.      * iterations is exceeded.
  164.      */
  165.     public PAIR optimize()
  166.         throws TooManyEvaluationsException,
  167.                TooManyIterationsException {
  168.         // Reset counters.
  169.         evaluations.resetCount();
  170.         iterations.resetCount();
  171.         // Perform optimization.
  172.         return doOptimize();
  173.     }

  175.     /**
  176.      * Performs the bulk of the optimization algorithm.
  177.      *
  178.      * @return the point/value pair giving the optimal value of the
  179.      * objective function.
  180.      */
  181.     protected abstract PAIR doOptimize();

  183.     /**
  184.      * Increment the evaluation count.
  185.      *
  186.      * @throws TooManyEvaluationsException if the allowed evaluations
  187.      * have been exhausted.
  188.      */
  189.     protected void incrementEvaluationCount()
  190.         throws TooManyEvaluationsException {
  191.         evaluations.incrementCount();
  192.     }

  194.     /**
  195.      * Increment the iteration count.
  196.      *
  197.      * @throws TooManyIterationsException if the allowed iterations
  198.      * have been exhausted.
  199.      */
  200.     protected void incrementIterationCount()
  201.         throws TooManyIterationsException {
  202.         iterations.incrementCount();
  203.     }

  205.     /**
  206.      * Scans the list of (required and optional) optimization data that
  207.      * characterize the problem.
  208.      *
  209.      * @param optData Optimization data.
  210.      * The following data will be looked for:
  211.      * <ul>
  212.      *  <li>{@link MaxEval}</li>
  213.      *  <li>{@link MaxIter}</li>
  214.      * </ul>
  215.      */
  216.     protected void parseOptimizationData(OptimizationData... optData) {
  217.         // The existing values (as set by the previous call) are reused if
  218.         // not provided in the argument list.
  219.         for (OptimizationData data : optData) {
  220.             if (data instanceof MaxEval) {
  221.                 evaluations.setMaximalCount(((MaxEval) data).getMaxEval());
  222.                 continue;
  223.             }
  224.             if (data instanceof MaxIter) {
  225.                 iterations.setMaximalCount(((MaxIter) data).getMaxIter());
  226.                 continue;
  227.             }
  228.         }
  229.     }

  231.     /**
  232.      * Defines the action to perform when reaching the maximum number
  233.      * of evaluations.
  234.      */
  235.     private static class MaxEvalCallback
  236.         implements  Incrementor.MaxCountExceededCallback {
  237.         /**
  238.          * {@inheritDoc}
  239.          * @throws TooManyEvaluationsException
  240.          */
  241.         public void trigger(int max) {
  242.             throw new TooManyEvaluationsException(max);
  243.         }
  244.     }

  246.     /**
  247.      * Defines the action to perform when reaching the maximum number
  248.      * of evaluations.
  249.      */
  250.     private static class MaxIterCallback
  251.         implements Incrementor.MaxCountExceededCallback {
  252.         /**
  253.          * {@inheritDoc}
  254.          * @throws TooManyIterationsException
  255.          */
  256.         public void trigger(int max) {
  257.             throw new TooManyIterationsException(max);
  258.         }
  259.     }
  260. }
Created with JaCoCo 0.7.2.201409121644