MOAB: Mesh Oriented datABase  (version 5.4.1)
ObjectiveFunction.hpp
Go to the documentation of this file.
00001 /* *****************************************************************
00002     MESQUITE -- The Mesh Quality Improvement Toolkit
00003 
00004     Copyright 2004 Sandia Corporation and Argonne National
00005     Laboratory.  Under the terms of Contract DE-AC04-94AL85000
00006     with Sandia Corporation, the U.S. Government retains certain
00007     rights in this software.
00008 
00009     This library is free software; you can redistribute it and/or
00010     modify it under the terms of the GNU Lesser General Public
00011     License as published by the Free Software Foundation; either
00012     version 2.1 of the License, or (at your option) any later version.
00013 
00014     This library is distributed in the hope that it will be useful,
00015     but WITHOUT ANY WARRANTY; without even the implied warranty of
00016     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00017     Lesser General Public License for more details.
00018 
00019     You should have received a copy of the GNU Lesser General Public License
00020     (lgpl.txt) along with this library; if not, write to the Free Software
00021     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00022 
00023     [email protected], [email protected], [email protected],
00024     [email protected], [email protected], [email protected]
00025 
00026     (2006) [email protected]
00027 
00028   ***************************************************************** */
00029 // -*- Mode : c++; tab-width: 3; c-tab-always-indent: t; indent-tabs-mode: nil; c-basic-offset: 3
00030 // -*-
00031 
00032 /*! \file ObjectiveFunction.hpp
00033 
00034 Header file for the MBMesquite::ObjectiveFunction class
00035 
00036   \author Michael Brewer
00037   \author Thomas Leurent
00038   \date   2002-05-23
00039   \author Jason Kraftcheck
00040   \date   2006-04
00041  */
00042 
00043 #ifndef OBJECTIVE_FUNCTION_HPP
00044 #define OBJECTIVE_FUNCTION_HPP
00045 
00046 #include "Mesquite.hpp"
00047 
00048 #include <list>
00049 #include <vector>
00050 #include <cstddef>
00051 
00052 namespace MBMesquite
00053 {
00054 class PatchData;
00055 class MsqHessian;
00056 class QualityMetric;
00057 class MsqVertex;
00058 class MsqError;
00059 class Vector3D;
00060 class SymMatrix3D;
00061 class Mesh;
00062 class MeshDomain;
00063 class PatchSet;
00064 class Settings;
00065 class MeshDomainAssoc;
00066 
00067 /*! \class ObjectiveFunction
00068      \brief Base class for concrete Objective Functions
00069      ObjectiveFunction contains a pointer to a QualityMetric.  If
00070      the ObjectiveFunction is associated with more than one
00071      QualityMetric (i.e., the Objective is a composite, and the
00072      composed ObjectiveFunctions are associated with different
00073      QualityMetrics), then the QualityMetric pointer is set
00074      to NULL..
00075     */
00076 class MESQUITE_EXPORT ObjectiveFunction
00077 {
00078   public:
00079     enum EvalType
00080     {
00081         /** Do not modify or use any accumulated value in the
00082          *  calculation of the objective function value.
00083          *  Evaluate the objective function only over the passed
00084          *  patch.  Used for NASH-type solutions.
00085          */
00086         CALCULATE,
00087         /** Incorporate the evaluation of the passed patch into
00088          *  the accumulated global objective function value.  This
00089          *  EvalType is used by the default initialize implemenation,
00090          *  and need not be considered by ObjectiveFunction
00091          *  implementations that provide their own implementation of
00092          *  the initialize method.
00093          */
00094         ACCUMULATE,
00095         /** Save the evaluation over the passed patch such that it
00096          *  can later be removed from the accumulated global objective
00097          *  function value.  Assume that the current accumulated
00098          *  value already includes the evaluation of this patch. Do
00099          *  *not* modify any accumulated, global value.
00100          */
00101         SAVE,
00102         /** Assume that the patch passed to this call is a modified
00103          *  version of the patch previously passed with either the
00104          *  SAVE or UPDATE EvalType specified.  Update the accumulated
00105          *  global value accordingly (remove previously saved local
00106          *  data from accumulated value, and incorporate evaluation
00107          *  over this patch into the accumulated value.)  Save the
00108          *  necessary data such that the results of incorporaring
00109          *  the evaluation of this patch into the accumulated global
00110          *  value can be removed upon a subsequent call with this
00111          *  EvalType.
00112          */
00113         UPDATE,
00114         /** For this EvalType, the passed back results should be the
00115          *  same as for the UPDATE EvalType, but any accumulated data
00116          *  or data corresponding to the previous local values should
00117          *  *not* be modified.
00118          */
00119         TEMPORARY
00120     };
00121 
00122     // virtual destructor ensures use of polymorphism during destruction
00123     virtual ~ObjectiveFunction();
00124 
00125     //!\brief Called at start of instruction queue processing
00126     //!
00127     //! Do any preliminary global initialization, consistency checking,
00128     //! etc.  This function is pure-virtual (abstract) in this class
00129     //! because every practical OF implementation at this time should
00130     //! have an implementation that at least recursively calls the same
00131     //! function on the underlying QualityMetric or ObjectiveFunction(s).
00132     virtual void initialize_queue( MeshDomainAssoc* mesh_and_domain, const Settings* settings, MsqError& err ) = 0;
00133 
00134     /**\brief Initial accumulated value for block coordinate descent algorithms
00135      *
00136      * Set accumulated value of objective function to the value for the
00137      * entire, unmodified mesh.  This is the initial state for a block
00138      * coordinate descent algorithm.  The ObjectiveFunction will asked
00139      * to add or remove values for a specific patch of the mesh during
00140      * the optimization.
00141      *\param mesh  The Mesh
00142      *\param domain The MeshDomain
00143      *\param user_set User-defined patch set - not relevant for most OF templates.
00144      */
00145     virtual bool initialize_block_coordinate_descent( MeshDomainAssoc* mesh_and_domain,
00146                                                       const Settings* settings,
00147                                                       PatchSet* user_set,
00148                                                       MsqError& err ) = 0;
00149 
00150     /**\brief Evaluate objective function for specified patch.
00151      *
00152      * Either evaluate the objective function over the passed patch
00153      * or update the accumulated, global objective function value for
00154      * changes in the passed patch, depending on the value of the
00155      * EvalType.
00156      *\param type  Evaluation type.
00157      *\param pd    The patch.
00158      *\param value_out  The passed-back value of the objective fuction.
00159      *\param free  If true, incorporate the quality metric values only
00160      *             for those metric evaluations that depend on at least
00161      *             one free vertex
00162      *\return false if any QualityMetric evaluation returned false,
00163      *        true otherwise.
00164      */
00165     virtual bool evaluate( EvalType type, PatchData& pd, double& value_out, bool free, MsqError& err ) = 0;
00166 
00167     /**\brief Evaluate objective function and gradient for specified patch.
00168      *
00169      * Either evaluate the objective function over the passed patch
00170      * or update the accumulated, global objective function value for
00171      * changes in the passed patch, depending on the value of the
00172      * EvalType.
00173      *
00174      * The default implementation of this function will
00175      * use the value-only variation of the evaluate method and numerical
00176      * approximation to calculate gradients.  Whenever possible, objective
00177      * function implementations should provide more efficient analyical
00178      * gradient calculations.
00179      *
00180      *\param type  Evaluation type.
00181      *\param pd    The patch.
00182      *\param value_out  The passed-back value of the objective fuction.
00183      *\param grad_out The gradient of the OF wrt the coordinates of
00184      *             each *free* vertex in the patch.
00185      *\return false if any QualityMetric evaluation returned false,
00186      *        true otherwise.
00187      */
00188     virtual bool evaluate_with_gradient( EvalType type,
00189                                          PatchData& pd,
00190                                          double& value_out,
00191                                          std::vector< Vector3D >& grad_out,
00192                                          MsqError& err );
00193 
00194     /**\brief Evaluate objective function and diagonal blocks of Hessian for specified patch.
00195      *
00196      * Either evaluate the objective function over the passed patch
00197      * or update the accumulated, global objective function value for
00198      * changes in the passed patch, depending on the value of the
00199      * EvalType.
00200      *
00201      * The default implementation of this function evaluate the
00202      * entire Hessian and discard non-diagonal portions.  Concrete
00203      * objective functions should provide a more efficient implementation
00204      * that evaluates and accumulates only the required terms.
00205      *
00206      *\param type  Evaluation type.
00207      *\param pd    The patch.
00208      *\param value_out  The passed-back value of the objective fuction.
00209      *\param grad_out The gradient of the OF wrt the coordinates of
00210      *             each *free* vertex in the patch.
00211      *\param hess_diag_out The diagonal blocks of a Hessian.  I.e. Decompose
00212      *             the Hessian into 3x3 submatrices and return only the
00213      *             submatrices (blocks) along the diagonal.
00214      *\return false if any QualityMetric evaluation returned false,
00215      *        true otherwise.
00216      */
00217     virtual bool evaluate_with_Hessian_diagonal( EvalType type,
00218                                                  PatchData& pd,
00219                                                  double& value_out,
00220                                                  std::vector< Vector3D >& grad_out,
00221                                                  std::vector< SymMatrix3D >& hess_diag_out,
00222                                                  MsqError& err );
00223 
00224     /**\brief Evaluate objective function and Hessian for specified patch.
00225      *
00226      * Either evaluate the objective function over the passed patch
00227      * or update the accumulated, global objective function value for
00228      * changes in the passed patch, depending on the value of the
00229      * EvalType.
00230      *
00231      * The default implementation of this function will fail.
00232      *
00233      *\param type  Evaluation type.
00234      *\param pd    The patch.
00235      *\param value_out  The passed-back value of the objective fuction.
00236      *\param grad_out The gradient of the OF wrt the coordinates of
00237      *             each *free* vertex in the patch.
00238      *\param Hessian_out The Hessian of the OF wrt the coordinates of
00239      *             each *free* vertex in the patch.
00240      *\return false if any QualityMetric evaluation returned false,
00241      *        true otherwise.
00242      */
00243     virtual bool evaluate_with_Hessian( EvalType type,
00244                                         PatchData& pd,
00245                                         double& value_out,
00246                                         std::vector< Vector3D >& grad_out,
00247                                         MsqHessian& Hessian_out,
00248                                         MsqError& err );
00249 
00250     /**\brief Create copy with same state
00251      *
00252      * Create a new instance of the objective function that
00253      * is a copy of the callee with the same accumulated
00254      * values, parameters, etc.
00255      */
00256     virtual ObjectiveFunction* clone() const = 0;
00257 
00258     /** Clear any values accumulated for BCD-related eval calls */
00259     virtual void clear() = 0;
00260 
00261     /** Get the minimum number of layers of adjacent elements required
00262      *  in a patch to evaluate the objective function for a single
00263      *  free vertex.
00264      */
00265     virtual int min_patch_layers() const = 0;
00266 
00267   protected:
00268     /**\brief Returns eps used in the numerical gradient calculation.
00269      *
00270      * Returns an appropiate value (eps) to use as a delta step for
00271      * MsqVertex vertex in dimension k (i.e. k=0 -> x, k=1 -> y, k=2 -> z).
00272      * The objective function value at the perturbed vertex position is given
00273      * in local_val.
00274      */
00275     double get_eps( PatchData& pd, EvalType eval_type, double& local_val, int k, size_t vertex_index, MsqError& err );
00276 
00277   private:
00278     /**\brief Compute numerical approx. of gradient for 1 vertex's coordinates.
00279      *
00280      * Compute the numerical approximation of the gradient of the objective
00281      * function for the coordinates of a single vertex given a patch for
00282      * which that vertex is the only free vertex.
00283      *\param type   Evaluation type.
00284      *\param pd     A patch containing a single free vertex and the
00285      *              adjacent elements necessary for complete evaluation
00286      *              of the dependence of the objective fuction on the
00287      *              coordinates of the free vertex.
00288      *\param flocal The objective function value for the unmodified
00289      *              subpatch.  (Output.)
00290      *\param grad   The gradient of the OF with respect to the coordinates
00291      *              of the free veretx.  (Output.)
00292      *\return       The result of calling the ObjectiveFunction::evaluate
00293      *              method.
00294      */
00295     bool compute_subpatch_numerical_gradient( EvalType type,
00296                                               EvalType get_eps_eval_type,
00297                                               PatchData& pd,
00298                                               double& flocal,
00299                                               Vector3D& grad,
00300                                               MsqError& err );
00301 
00302     bool compute_patch_numerical_gradient( EvalType type,
00303                                            EvalType get_eps_eval_type,
00304                                            PatchData& pd,
00305                                            double& flocal,
00306                                            std::vector< Vector3D >& grad,
00307                                            MsqError& err );
00308 };
00309 
00310 }  // namespace MBMesquite
00311 
00312 #endif  // ObjectiveFunction_hpp
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines