MOAB: Mesh Oriented datABase
(version 5.3.1)
|
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