MOAB: Mesh Oriented datABase  (version 5.2.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     diachin2@llnl.gov, djmelan@sandia.gov, mbrewer@sandia.gov,
00024     pknupp@sandia.gov, tleurent@mcs.anl.gov, tmunson@mcs.anl.gov
00025 
00026     (2006) kraftche@cae.wisc.edu
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, const Settings* settings,
00146                                                       PatchSet* user_set, MsqError& err ) = 0;
00147 
00148     /**\brief Evaluate objective function for specified patch.
00149      *
00150      * Either evaluate the objective function over the passed patch
00151      * or update the accumulated, global objective function value for
00152      * changes in the passed patch, depending on the value of the
00153      * EvalType.
00154      *\param type  Evaluation type.
00155      *\param pd    The patch.
00156      *\param value_out  The passed-back value of the objective fuction.
00157      *\param free  If true, incorporate the quality metric values only
00158      *             for those metric evaluations that depend on at least
00159      *             one free vertex
00160      *\return false if any QualityMetric evaluation returned false,
00161      *        true otherwise.
00162      */
00163     virtual bool evaluate( EvalType type, PatchData& pd, double& value_out, bool free, MsqError& err ) = 0;
00164 
00165     /**\brief Evaluate objective function and gradient for specified patch.
00166      *
00167      * Either evaluate the objective function over the passed patch
00168      * or update the accumulated, global objective function value for
00169      * changes in the passed patch, depending on the value of the
00170      * EvalType.
00171      *
00172      * The default implementation of this function will
00173      * use the value-only variation of the evaluate method and numerical
00174      * approximation to calculate gradients.  Whenever possible, objective
00175      * function implementations should provide more efficient analyical
00176      * gradient calculations.
00177      *
00178      *\param type  Evaluation type.
00179      *\param pd    The patch.
00180      *\param value_out  The passed-back value of the objective fuction.
00181      *\param grad_out The gradient of the OF wrt the coordinates of
00182      *             each *free* vertex in the patch.
00183      *\return false if any QualityMetric evaluation returned false,
00184      *        true otherwise.
00185      */
00186     virtual bool evaluate_with_gradient( EvalType type, PatchData& pd, double& value_out,
00187                                          std::vector< Vector3D >& grad_out, MsqError& err );
00188 
00189     /**\brief Evaluate objective function and diagonal blocks of Hessian for specified patch.
00190      *
00191      * Either evaluate the objective function over the passed patch
00192      * or update the accumulated, global objective function value for
00193      * changes in the passed patch, depending on the value of the
00194      * EvalType.
00195      *
00196      * The default implementation of this function evaluate the
00197      * entire Hessian and discard non-diagonal portions.  Concrete
00198      * objective functions should provide a more efficient implementation
00199      * that evaluates and accumulates only the required terms.
00200      *
00201      *\param type  Evaluation type.
00202      *\param pd    The patch.
00203      *\param value_out  The passed-back value of the objective fuction.
00204      *\param grad_out The gradient of the OF wrt the coordinates of
00205      *             each *free* vertex in the patch.
00206      *\param hess_diag_out The diagonal blocks of a Hessian.  I.e. Decompose
00207      *             the Hessian into 3x3 submatrices and return only the
00208      *             submatrices (blocks) along the diagonal.
00209      *\return false if any QualityMetric evaluation returned false,
00210      *        true otherwise.
00211      */
00212     virtual bool evaluate_with_Hessian_diagonal( EvalType type, PatchData& pd, double& value_out,
00213                                                  std::vector< Vector3D >& grad_out,
00214                                                  std::vector< SymMatrix3D >& hess_diag_out, MsqError& err );
00215 
00216     /**\brief Evaluate objective function and Hessian for specified patch.
00217      *
00218      * Either evaluate the objective function over the passed patch
00219      * or update the accumulated, global objective function value for
00220      * changes in the passed patch, depending on the value of the
00221      * EvalType.
00222      *
00223      * The default implementation of this function will fail.
00224      *
00225      *\param type  Evaluation type.
00226      *\param pd    The patch.
00227      *\param value_out  The passed-back value of the objective fuction.
00228      *\param grad_out The gradient of the OF wrt the coordinates of
00229      *             each *free* vertex in the patch.
00230      *\param Hessian_out The Hessian of the OF wrt the coordinates of
00231      *             each *free* vertex in the patch.
00232      *\return false if any QualityMetric evaluation returned false,
00233      *        true otherwise.
00234      */
00235     virtual bool evaluate_with_Hessian( EvalType type, PatchData& pd, double& value_out,
00236                                         std::vector< Vector3D >& grad_out, MsqHessian& Hessian_out, MsqError& err );
00237 
00238     /**\brief Create copy with same state
00239      *
00240      * Create a new instance of the objective function that
00241      * is a copy of the callee with the same accumulated
00242      * values, parameters, etc.
00243      */
00244     virtual ObjectiveFunction* clone() const = 0;
00245 
00246     /** Clear any values accumulated for BCD-related eval calls */
00247     virtual void clear() = 0;
00248 
00249     /** Get the minimum number of layers of adjacent elements required
00250      *  in a patch to evaluate the objective function for a single
00251      *  free vertex.
00252      */
00253     virtual int min_patch_layers() const = 0;
00254 
00255   protected:
00256     /**\brief Returns eps used in the numerical gradient calculation.
00257      *
00258      * Returns an appropiate value (eps) to use as a delta step for
00259      * MsqVertex vertex in dimension k (i.e. k=0 -> x, k=1 -> y, k=2 -> z).
00260      * The objective function value at the perturbed vertex position is given
00261      * in local_val.
00262      */
00263     double get_eps( PatchData& pd, EvalType eval_type, double& local_val, int k, size_t vertex_index, MsqError& err );
00264 
00265   private:
00266     /**\brief Compute numerical approx. of gradient for 1 vertex's coordinates.
00267      *
00268      * Compute the numerical approximation of the gradient of the objective
00269      * function for the coordinates of a single vertex given a patch for
00270      * which that vertex is the only free vertex.
00271      *\param type   Evaluation type.
00272      *\param pd     A patch containing a single free vertex and the
00273      *              adjacent elements necessary for complete evaluation
00274      *              of the dependence of the objective fuction on the
00275      *              coordinates of the free vertex.
00276      *\param flocal The objective function value for the unmodified
00277      *              subpatch.  (Output.)
00278      *\param grad   The gradient of the OF with respect to the coordinates
00279      *              of the free veretx.  (Output.)
00280      *\return       The result of calling the ObjectiveFunction::evaluate
00281      *              method.
00282      */
00283     bool compute_subpatch_numerical_gradient( EvalType type, EvalType get_eps_eval_type, PatchData& pd, double& flocal,
00284                                               Vector3D& grad, MsqError& err );
00285 
00286     bool compute_patch_numerical_gradient( EvalType type, EvalType get_eps_eval_type, PatchData& pd, double& flocal,
00287                                            std::vector< Vector3D >& grad, MsqError& err );
00288 };
00289 
00290 }  // namespace MBMesquite
00291 
00292 #endif  // ObjectiveFunction_hpp
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines