path: root/thirdparty/linux/include/coin/coin/IpAlgBuilder.hpp

// Copyright (C) 2004, 2007 International Business Machines and others.
// All Rights Reserved.
// This code is published under the Eclipse Public License.
//
// $Id: IpAlgBuilder.hpp 2666 2016-07-20 16:02:55Z stefan $
//
// Authors:  Carl Laird, Andreas Waechter     IBM    2004-09-29

#ifndef __IPALGBUILDER_HPP__
#define __IPALGBUILDER_HPP__

#include "IpIpoptAlg.hpp"
#include "IpReferenced.hpp"
#include "IpAugSystemSolver.hpp"
#include "IpPDSystemSolver.hpp"

namespace Ipopt
{

  // forward declarations
  class IterationOutput;
  class HessianUpdater;
  class ConvergenceCheck;
  class SearchDirectionCalculator;
  class EqMultiplierCalculator;
  class IterateInitializer;
  class LineSearch;
  class MuUpdate;

  /** Builder for creating a complete IpoptAlg object.  This object
   *  contains all subelements (such as line search objects etc).  How
   *  the resulting IpoptAlg object is built can be influenced by the
   *  options.
   *
   *  More advanced customization can be achieved by subclassing this
   *  class and overloading the virtual methods that build the
   *  individual parts. The advantage of doing this is that it allows
   *  one to reuse the extensive amount of options processing that
   *  takes place, for instance, when generating the symmetric linear
   *  system solver. Another method for customizing the algorithm is
   *  using the optional custom_solver argument, which allows the
   *  expert user to provide a specialized linear solver for the
   *  augmented system (e.g., type GenAugSystemSolver), possibly for
   *  user-defined matrix objects. The optional custom_solver constructor
   *  argument is likely obsolete, however, as more control over this
   *  this process can be achieved by implementing a subclass of this
   *  AlgBuilder (e.g., by overloading the AugSystemSolverFactory method).
   */
  class AlgorithmBuilder : public ReferencedObject
  {
  public:
    /**@name Constructors/Destructors */
    //@{
    /** Constructor */
    AlgorithmBuilder(SmartPtr<AugSystemSolver> custom_solver=NULL);

    /** Destructor */
    virtual ~AlgorithmBuilder()
    {}

    //@}

    /** Methods for IpoptTypeInfo */
    //@{
    /** register the options used by the algorithm builder */
    static void RegisterOptions(SmartPtr<RegisteredOptions> roptions);
    //@}

    /** @name Convenience methods for building solvers without having
     *  to duplicate the significant amount of preprocessor flag and
     *  option checking that takes place. These solvers are used to
     *  create a number of core algorithm components across the
     *  different Build* methods, but depending on what options are
     *  chosen, the first method requiring the solver to be used can
     *  vary. Therefore, each of the Factory methods below is paired
     *  with a Getter method, which is called by all parts of this
     *  algorithm builder to ensure the Factory is only called once. */
    //@{

    /** Create a solver that can be used to solve a symmetric linear
     *  system.
     *  Dependencies: None
     */
    virtual SmartPtr<SymLinearSolver>
        SymLinearSolverFactory(const Journalist& jnlst,
                               const OptionsList& options,
                               const std::string& prefix);

    /** Get the symmetric linear system solver for this
     *  algorithm. This method will call the SymLinearSolverFactory
     *  exactly once (the first time it is used), and store its
     *  instance on SymSolver_ for use in subsequent calls.
     */
    SmartPtr<SymLinearSolver> GetSymLinearSolver(const Journalist& jnlst,
                                                 const OptionsList& options,
                                                 const std::string& prefix);

    /** Create a solver that can be used to solve an
     *  augmented system.
     *  Dependencies:
     *     -> GetSymLinearSolver()
     *         -> SymLinearSolverFactory()
     *     -> custom_solver_
     */
    virtual SmartPtr<AugSystemSolver>
        AugSystemSolverFactory(const Journalist& jnlst,
                               const OptionsList& options,
                               const std::string& prefix);

    /** Get the augmented system solver for this algorithm. This
     *  method will call the AugSystemSolverFactory exactly once (the
     *  first time it is used), and store its instance on AugSolver_
     *  for use in subsequent calls.
     */
    SmartPtr<AugSystemSolver> GetAugSystemSolver(const Journalist& jnlst,
                                                 const OptionsList& options,
                                                 const std::string& prefix);

    /** Create a solver that can be used to solve a
     *  primal-dual system.
     *  Dependencies:
     *     -> GetAugSystemSolver()
     *         -> AugSystemSolverFactory()
     *             -> GetSymLinearSolver()
     *                 -> SymLinearSolverFactory()
     *             -> custom_solver_
     */
    virtual SmartPtr<PDSystemSolver>
        PDSystemSolverFactory(const Journalist& jnlst,
                              const OptionsList& options,
                              const std::string& prefix);

    /** Get the primal-dual system solver for this algorithm. This
     *  method will call the PDSystemSolverFactory exactly once (the
     *  first time it is used), and store its instance on PDSolver_
     *  for use in subsequent calls.
     */
    SmartPtr<PDSystemSolver> GetPDSystemSolver(const Journalist& jnlst,
                                               const OptionsList& options,
                                               const std::string& prefix);
    //@}

    /** @name Methods to build parts of the algorithm */
    //@{
    /** Allocates memory for the IpoptNLP, IpoptData, and
     *  IpoptCalculatedQuanties arguments.
     *  Dependencies: None
     */
    virtual void BuildIpoptObjects(const Journalist& jnlst,
                                   const OptionsList& options,
                                   const std::string& prefix,
                                   const SmartPtr<NLP>& nlp,
                                   SmartPtr<IpoptNLP>& ip_nlp,
                                   SmartPtr<IpoptData>& ip_data,
                                   SmartPtr<IpoptCalculatedQuantities>& ip_cq);

    /** Creates an instance of the IpoptAlgorithm class by building
     *  each of its required constructor arguments piece-by-piece. The
     *  default algorithm can be customized by overloading this method
     *  or by overloading one or more of the Build* methods called in
     *  this method's default implementation. Additional control can
     *  be achieved by overloading any of the *SolverFactory methods.
     *  This method will call (in this order):
     *     -> BuildIterationOutput()
     *     -> BuildHessianUpdater()
     *     -> BuildConvergenceCheck()
     *     -> BuildSearchDirectionCalculator()
     *     -> BuildEqMultiplierCalculator()
     *     -> BuildIterateInitializer()
     *     -> BuildLineSearch()
     *     -> BuildMuUpdate()
     */
    virtual SmartPtr<IpoptAlgorithm> BuildBasicAlgorithm(const Journalist& jnlst,
        const OptionsList& options,
        const std::string& prefix);

    /** Creates an instance of the IterationOutput class. This method
     *  is called in the default implementation of
     *  BuildBasicAlgorithm. It can be overloaded to customize that
     *  portion the default algorithm.
     *  Dependencies: None
     */
    virtual SmartPtr<IterationOutput>
        BuildIterationOutput(const Journalist& jnlst,
                             const OptionsList& options,
                             const std::string& prefix);

    /** Creates an instance of the HessianUpdater class. This method
     *  is called in the default implementation of
     *  BuildBasicAlgorithm.  It can be overloaded to customize that
     *  portion the default algorithm.
     *  Dependencies: None
     */
    virtual SmartPtr<HessianUpdater>
        BuildHessianUpdater(const Journalist& jnlst,
                            const OptionsList& options,
                            const std::string& prefix);

    /** Creates an instance of the ConvergenceCheck class. This method
     *  is called in the default implementation of
     *  BuildBasicAlgorithm.  It can be overloaded to customize that
     *  portion the default algorithm.
     *  Dependencies: None
     */
    virtual SmartPtr<ConvergenceCheck>
        BuildConvergenceCheck(const Journalist& jnlst,
                              const OptionsList& options,
                              const std::string& prefix);

    /** Creates an instance of the SearchDirectionCalculator
     *  class. This method is called in the default implementation of
     *  BuildBasicAlgorithm.  It can be overloaded to customize that
     *  portion the default algorithm.
     *  Dependencies:
     *     -> GetPDSystemSolver()
     *         -> PDSystemSolverFactory()
     *             -> GetAugSystemSolver()
     *                 -> AugSystemSolverFactory()
     *                     -> GetSymLinearSolver()
     *                         -> SymLinearSolverFactory()
     *                     -> custom_solver_
     */
     virtual SmartPtr<SearchDirectionCalculator>
        BuildSearchDirectionCalculator(const Journalist& jnlst,
                                       const OptionsList& options,
                                       const std::string& prefix);

    /** Creates an instance of the EqMultiplierCalculator class. This
     *  method is called in the default implementation of
     *  BuildBasicAlgorithm.  It can be overloaded to customize that
     *  portion the default algorithm.
     *  Dependencies:
     *     -> GetAugSystemSolver()
     *         -> AugSystemSolverFactory()
     *             -> GetSymLinearSolver()
     *                 -> SymLinearSolverFactory()
     *             -> custom_solver_
     */
    virtual SmartPtr<EqMultiplierCalculator>
        BuildEqMultiplierCalculator(const Journalist& jnlst,
                                    const OptionsList& options,
                                    const std::string& prefix);

    /** Creates an instance of the IterateInitializer class. This
     *  method is called in the default implementation of
     *  BuildBasicAlgorithm.  It can be overloaded to customize that
     *  portion the default algorithm.
     *  Dependencies:
     *     -> EqMultCalculator_
     *     -> GetAugSystemSolver()
     *         -> AugSystemSolverFactory()
     *             -> GetSymLinearSolver()
     *                 -> SymLinearSolverFactory()
     *             -> custom_solver_
     */
    virtual SmartPtr<IterateInitializer>
        BuildIterateInitializer(const Journalist& jnlst,
                                const OptionsList& options,
                                const std::string& prefix);

    /** Creates an instance of the LineSearch class. This method is
     *  called in the default implementation of BuildBasicAlgorithm.
     *  It can be overloaded to customize that portion the default
     *  algorithm.
     *  Dependencies:
     *     -> EqMultCalculator_
     *     -> ConvCheck_
     *     -> GetAugSystemSolver()
     *         -> AugSystemSolverFactory()
     *             -> GetSymLinearSolver()
     *                 -> SymLinearSolverFactory()
     *             -> custom_solver_
     *     -> GetPDSystemSolver()
     *         -> PDSystemSolverFactory()
     *             -> GetAugSystemSolver()
     *                 -> AugSystemSolverFactory()
     *                     -> GetSymLinearSolver()
     *                         -> SymLinearSolverFactory()
     *                     -> custom_solver_
     */
    virtual SmartPtr<LineSearch> BuildLineSearch(const Journalist& jnlst,
                                                 const OptionsList& options,
                                                 const std::string& prefix);

    /** Creates an instance of the MuUpdate class. This method is
     *  called in the default implementation of BuildBasicAlgorithm.
     *  It can be overloaded to customize that portion the default
     *  algorithm.
     *  Dependencies:
     *     -> LineSearch_
     *         -> EqMultCalculator_
     *         -> ConvCheck_
     *     -> GetPDSystemSolver()
     *         -> PDSystemSolverFactory()
     *             -> GetAugSystemSolver()
     *                 -> AugSystemSolverFactory()
     *                     -> GetSymLinearSolver()
     *                         -> SymLinearSolverFactory()
     *                     -> custom_solver_
     */
    virtual SmartPtr<MuUpdate> BuildMuUpdate(const Journalist& jnlst,
                                             const OptionsList& options,
                                             const std::string& prefix);
    //@}

  private:
    /**@name Default Compiler Generated Methods
     * (Hidden to avoid implicit creation/calling).
     * These methods are not implemented and 
     * we do not want the compiler to implement
     * them for us, so we declare them private
     * and do not define them. This ensures that
     * they will not be implicitly created/called. */
    //@{
    /** Default Constructor */
    //AlgorithmBuilder();

    /** Copy Constructor */
    AlgorithmBuilder(const AlgorithmBuilder&);

    /** Overloaded Equals Operator */
    void operator=(const AlgorithmBuilder&);
    //@}

    /** @name IpoptAlgorithm constructor arguments.
     *  These components are built in separate Build
     *  methods in the order defined by BuildBasicAlgorithm.
     *  A single core component may require one or more
     *  other core components in its constructor, so the
     *  this class holds pointers to each component for use
     *  between the separate Build methods. */
    //@{
    SmartPtr<IterationOutput> IterOutput_;
    SmartPtr<HessianUpdater> HessUpdater_;
    SmartPtr<ConvergenceCheck> ConvCheck_;
    SmartPtr<SearchDirectionCalculator> SearchDirCalc_;
    SmartPtr<EqMultiplierCalculator> EqMultCalculator_;
    SmartPtr<IterateInitializer> IterInitializer_;
    SmartPtr<LineSearch> LineSearch_;
    SmartPtr<MuUpdate> MuUpdate_;
    //@}

    /** @name Commonly used solver components
     *  for building core algorithm components. Each
     *  of these members is paired with a Factory/Getter
     *  method. */
    //@{
    SmartPtr<SymLinearSolver> SymSolver_;
    SmartPtr<AugSystemSolver> AugSolver_;
    SmartPtr<PDSystemSolver> PDSolver_;
    //@}

    /** Optional pointer to AugSystemSolver.  If this is set in the
     *  contructor, we will use this to solve the linear systems. */
    SmartPtr<AugSystemSolver> custom_solver_;

  };
} // namespace Ipopt

#endif