source: branches/3087_Ceres_Integration/HeuristicLab.ExtLibs/HeuristicLab.NativeInterpreter/0.1/HeuristicLab.NativeInterpreter-0.1/CeresTypes.cs @ 18007

namespace HeuristicLab.NativeInterpreter {
  public class CeresTypes {
    // Ceres Solver - A fast non-linear least squares minimizer
    // Copyright 2019 Google Inc. All rights reserved.
    // http://ceres-solver.org/
    //
    // Redistribution and use in source and binary forms, with or without
    // modification, are permitted provided that the following conditions are met:
    //
    // * Redistributions of source code must retain the above copyright notice,
    //   this list of conditions and the following disclaimer.
    // * Redistributions in binary form must reproduce the above copyright notice,
    //   this list of conditions and the following disclaimer in the documentation
    //   and/or other materials provided with the distribution.
    // * Neither the name of Google Inc. nor the names of its contributors may be
    //   used to endorse or promote products derived from this software without
    //   specific prior written permission.
    //
    // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
    // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    // POSSIBILITY OF SUCH DAMAGE.
    //
    // Author: sameeragarwal@google.com (Sameer Agarwal)
    // 
    // Wrapped for access from C# by Gabriel Kronberger

    public enum LinearSolver : int {
      // These solvers are for general rectangular systems formed from the
      // normal equations A'A x = A'b. They are direct solvers and do not
      // assume any special problem structure.

      // Solve the normal equations using a dense Cholesky solver; based
      // on Eigen.
      DENSE_NORMAL_CHOLESKY,

      // Solve the normal equations using a dense QR solver; based on
      // Eigen.
      DENSE_QR,

      // Solve the normal equations using a sparse cholesky solver; requires
      // SuiteSparse or CXSparse.
      SPARSE_NORMAL_CHOLESKY,

      // Specialized solvers, specific to problems with a generalized
      // bi-partitite structure.

      // Solves the reduced linear system using a dense Cholesky solver;
      // based on Eigen.
      DENSE_SCHUR,

      // Solves the reduced linear system using a sparse Cholesky solver;
      // based on CHOLMOD.
      SPARSE_SCHUR,

      // Solves the reduced linear system using Conjugate Gradients, based
      // on a new Ceres implementation.  Suitable for large scale
      // problems.
      ITERATIVE_SCHUR,

      // Conjugate gradients on the normal equations.
      CGNR
    };

    public enum Preconditioner {
      // Trivial preconditioner - the identity matrix.
      IDENTITY,

      // Block diagonal of the Gauss-Newton Hessian.
      JACOBI,

      // Note: The following three preconditioners can only be used with
      // the ITERATIVE_SCHUR solver. They are well suited for Structure
      // from Motion problems.

      // Block diagonal of the Schur complement. This preconditioner may
      // only be used with the ITERATIVE_SCHUR solver.
      SCHUR_JACOBI,

      // Visibility clustering based preconditioners.
      //
      // The following two preconditioners use the visibility structure of
      // the scene to determine the sparsity structure of the
      // preconditioner. This is done using a clustering algorithm. The
      // available visibility clustering algorithms are described below.
      CLUSTER_JACOBI,
      CLUSTER_TRIDIAGONAL,

      // Subset preconditioner is a general purpose preconditioner
      // linear least squares problems. Given a set of residual blocks,
      // it uses the corresponding subset of the rows of the Jacobian to
      // construct a preconditioner.
      //
      // Suppose the Jacobian J has been horizontally partitioned as
      //
      // J = [P]
      //     [Q]
      //
      // Where, Q is the set of rows corresponding to the residual
      // blocks in residual_blocks_for_subset_preconditioner.
      //
      // The preconditioner is the inverse of the matrix Q'Q.
      //
      // Obviously, the efficacy of the preconditioner depends on how
      // well the matrix Q approximates J'J, or how well the chosen
      // residual blocks approximate the non-linear least squares
      // problem.
      SUBSET,
    };

    public enum Minimizer : int {
      LINE_SEARCH,
      TRUST_REGION,
    };

    public enum LineSearchDirection : int {
      // Negative of the gradient.
      STEEPEST_DESCENT,

      // A generalization of the Conjugate Gradient method to non-linear
      // functions. The generalization can be performed in a number of
      // different ways, resulting in a variety of search directions. The
      // precise choice of the non-linear conjugate gradient algorithm
      // used is determined by NonlinerConjuateGradientType.
      NONLINEAR_CONJUGATE_GRADIENT,

      // BFGS, and it's limited memory approximation L-BFGS, are quasi-Newton
      // algorithms that approximate the Hessian matrix by iteratively refining
      // an initial estimate with rank-one updates using the gradient at each
      // iteration. They are a generalisation of the Secant method and satisfy
      // the Secant equation.  The Secant equation has an infinium of solutions
      // in multiple dimensions, as there are N*(N+1)/2 degrees of freedom in a
      // symmetric matrix but only N conditions are specified by the Secant
      // equation. The requirement that the Hessian approximation be positive
      // definite imposes another N additional constraints, but that still leaves
      // remaining degrees-of-freedom.  (L)BFGS methods uniquely determine the
      // approximate Hessian by imposing the additional constraints that the
      // approximation at the next iteration must be the 'closest' to the current
      // approximation (the nature of how this proximity is measured is actually
      // the defining difference between a family of quasi-Newton methods including
      // (L)BFGS & DFP). (L)BFGS is currently regarded as being the best known
      // general quasi-Newton method.
      //
      // The principal difference between BFGS and L-BFGS is that whilst BFGS
      // maintains a full, dense approximation to the (inverse) Hessian, L-BFGS
      // maintains only a window of the last M observations of the parameters and
      // gradients. Using this observation history, the calculation of the next
      // search direction can be computed without requiring the construction of the
      // full dense inverse Hessian approximation. This is particularly important
      // for problems with a large number of parameters, where storage of an N-by-N
      // matrix in memory would be prohibitive.
      //
      // For more details on BFGS see:
      //
      // Broyden, C.G., "The Convergence of a Class of Double-rank Minimization
      // Algorithms,"; J. Inst. Maths. Applics., Vol. 6, pp 76-90, 1970.
      //
      // Fletcher, R., "A New Approach to Variable Metric Algorithms,"
      // Computer Journal, Vol. 13, pp 317-322, 1970.
      //
      // Goldfarb, D., "A Family of Variable Metric Updates Derived by Variational
      // Means," Mathematics of Computing, Vol. 24, pp 23-26, 1970.
      //
      // Shanno, D.F., "Conditioning of Quasi-Newton Methods for Function
      // Minimization," Mathematics of Computing, Vol. 24, pp 647-656, 1970.
      //
      // For more details on L-BFGS see:
      //
      // Nocedal, J. (1980). "Updating Quasi-Newton Matrices with Limited
      // Storage". Mathematics of Computation 35 (151): 773-782.
      //
      // Byrd, R. H.; Nocedal, J.; Schnabel, R. B. (1994).
      // "Representations of Quasi-Newton Matrices and their use in
      // Limited Memory Methods". Mathematical Programming 63 (4):
      // 129-156.
      //
      // A general reference for both methods:
      //
      // Nocedal J., Wright S., Numerical Optimization, 2nd Ed. Springer, 1999.
      LBFGS,
      BFGS,
    };

    // Nonlinear conjugate gradient methods are a generalization of the
    // method of Conjugate Gradients for linear systems. The
    // generalization can be carried out in a number of different ways
    // leading to number of different rules for computing the search
    // direction. Ceres provides a number of different variants. For more
    // details see Numerical Optimization by Nocedal & Wright.
    public enum NonlinearConjugateGradientType {
      FLETCHER_REEVES,
      POLAK_RIBIERE,
      HESTENES_STIEFEL,
    };

    public enum LineSearch {
      // Backtracking line search with polynomial interpolation or
      // bisection.
      ARMIJO,
      WOLFE,
    };

    // Ceres supports different strategies for computing the trust region
    // step.
    public enum TrustRegionStrategy : int {
      // The default trust region strategy is to use the step computation
      // used in the Levenberg-Marquardt algorithm. For more details see
      // levenberg_marquardt_strategy.h
      LEVENBERG_MARQUARDT,

      // Powell's dogleg algorithm interpolates between the Cauchy point
      // and the Gauss-Newton step. It is particularly useful if the
      // LEVENBERG_MARQUARDT algorithm is making a large number of
      // unsuccessful steps. For more details see dogleg_strategy.h.
      //
      // NOTES:
      //
      // 1. This strategy has not been experimented with or tested as
      // extensively as LEVENBERG_MARQUARDT, and therefore it should be
      // considered EXPERIMENTAL for now.
      //
      // 2. For now this strategy should only be used with exact
      // factorization based linear solvers, i.e., SPARSE_SCHUR,
      // DENSE_SCHUR, DENSE_QR and SPARSE_NORMAL_CHOLESKY.
      DOGLEG
    };

    // Ceres supports two different dogleg strategies.
    // The "traditional" dogleg method by Powell and the
    // "subspace" method described in
    // R. H. Byrd, R. B. Schnabel, and G. A. Shultz,
    // "Approximate solution of the trust region problem by minimization
    //  over two-dimensional subspaces", Mathematical Programming,
    // 40 (1988), pp. 247--263
    public enum DogLeg {
      // The traditional approach constructs a dogleg path
      // consisting of two line segments and finds the furthest
      // point on that path that is still inside the trust region.
      TRADITIONAL_DOGLEG,

      // The subspace approach finds the exact minimum of the model
      // constrained to the subspace spanned by the dogleg path.
      SUBSPACE_DOGLEG
    };

  }
}