1 // Ceres Solver - A fast non-linear least squares minimizer 2 // Copyright 2010, 2011, 2012 Google Inc. All rights reserved. 3 // http://code.google.com/p/ceres-solver/ 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions are met: 7 // 8 // * Redistributions of source code must retain the above copyright notice, 9 // this list of conditions and the following disclaimer. 10 // * Redistributions in binary form must reproduce the above copyright notice, 11 // this list of conditions and the following disclaimer in the documentation 12 // and/or other materials provided with the distribution. 13 // * Neither the name of Google Inc. nor the names of its contributors may be 14 // used to endorse or promote products derived from this software without 15 // specific prior written permission. 16 // 17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 18 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 21 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27 // POSSIBILITY OF SUCH DAMAGE. 28 // 29 // Author: keir@google.com (Keir Mierle) 30 31 #ifndef CERES_INTERNAL_PROGRAM_H_ 32 #define CERES_INTERNAL_PROGRAM_H_ 33 34 #include <string> 35 #include <vector> 36 #include "ceres/internal/port.h" 37 38 namespace ceres { 39 namespace internal { 40 41 class ParameterBlock; 42 class ProblemImpl; 43 class ResidualBlock; 44 45 // A nonlinear least squares optimization problem. This is different from the 46 // similarly-named "Problem" object, which offers a mutation interface for 47 // adding and modifying parameters and residuals. The Program contains the core 48 // part of the Problem, which is the parameters and the residuals, stored in a 49 // particular ordering. The ordering is critical, since it defines the mapping 50 // between (residual, parameter) pairs and a position in the jacobian of the 51 // objective function. Various parts of Ceres transform one Program into 52 // another; for example, the first stage of solving involves stripping all 53 // constant parameters and residuals. This is in contrast with Problem, which is 54 // not built for transformation. 55 class Program { 56 public: 57 Program(); 58 explicit Program(const Program& program); 59 60 // The ordered parameter and residual blocks for the program. 61 const vector<ParameterBlock*>& parameter_blocks() const; 62 const vector<ResidualBlock*>& residual_blocks() const; 63 vector<ParameterBlock*>* mutable_parameter_blocks(); 64 vector<ResidualBlock*>* mutable_residual_blocks(); 65 66 // Serialize to/from the program and update states. 67 // 68 // NOTE: Setting the state of a parameter block can trigger the 69 // computation of the Jacobian of its local parameterization. If 70 // this computation fails for some reason, then this method returns 71 // false and the state of the parameter blocks cannot be trusted. 72 bool StateVectorToParameterBlocks(const double *state); 73 void ParameterBlocksToStateVector(double *state) const; 74 75 // Copy internal state to the user's parameters. 76 void CopyParameterBlockStateToUserState(); 77 78 // Set the parameter block pointers to the user pointers. Since this 79 // runs parameter block set state internally, which may call local 80 // parameterizations, this can fail. False is returned on failure. 81 bool SetParameterBlockStatePtrsToUserStatePtrs(); 82 83 // Update a state vector for the program given a delta. 84 bool Plus(const double* state, 85 const double* delta, 86 double* state_plus_delta) const; 87 88 // Set the parameter indices and offsets. This permits mapping backward 89 // from a ParameterBlock* to an index in the parameter_blocks() vector. For 90 // any parameter block p, after calling SetParameterOffsetsAndIndex(), it 91 // is true that 92 // 93 // parameter_blocks()[p->index()] == p 94 // 95 // If a parameter appears in a residual but not in the parameter block, then 96 // it will have an index of -1. 97 // 98 // This also updates p->state_offset() and p->delta_offset(), which are the 99 // position of the parameter in the state and delta vector respectively. 100 void SetParameterOffsetsAndIndex(); 101 102 // See problem.h for what these do. 103 int NumParameterBlocks() const; 104 int NumParameters() const; 105 int NumEffectiveParameters() const; 106 int NumResidualBlocks() const; 107 int NumResiduals() const; 108 109 int MaxScratchDoublesNeededForEvaluate() const; 110 int MaxDerivativesPerResidualBlock() const; 111 int MaxParametersPerResidualBlock() const; 112 int MaxResidualsPerResidualBlock() const; 113 114 // A human-readable dump of the parameter blocks for debugging. 115 // TODO(keir): If necessary, also dump the residual blocks. 116 string ToString() const; 117 118 private: 119 // The Program does not own the ParameterBlock or ResidualBlock objects. 120 vector<ParameterBlock*> parameter_blocks_; 121 vector<ResidualBlock*> residual_blocks_; 122 123 friend class ProblemImpl; 124 }; 125 126 } // namespace internal 127 } // namespace ceres 128 129 #endif // CERES_INTERNAL_PROGRAM_H_ 130