Simbody  3.7
Differentiator.h
Go to the documentation of this file.
1 #ifndef SimTK_DIFFERENTIATOR_H_
2 #define SimTK_DIFFERENTIATOR_H_
3 
4 /* -------------------------------------------------------------------------- *
5  * Simbody(tm): SimTKmath *
6  * -------------------------------------------------------------------------- *
7  * This is part of the SimTK biosimulation toolkit originating from *
8  * Simbios, the NIH National Center for Physics-Based Simulation of *
9  * Biological Structures at Stanford, funded under the NIH Roadmap for *
10  * Medical Research, grant U54 GM072970. See https://simtk.org/home/simbody. *
11  * *
12  * Portions copyright (c) 2006-12 Stanford University and the Authors. *
13  * Authors: Michael Sherman *
14  * Contributors: *
15  * *
16  * Licensed under the Apache License, Version 2.0 (the "License"); you may *
17  * not use this file except in compliance with the License. You may obtain a *
18  * copy of the License at http://www.apache.org/licenses/LICENSE-2.0. *
19  * *
20  * Unless required by applicable law or agreed to in writing, software *
21  * distributed under the License is distributed on an "AS IS" BASIS, *
22  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
23  * See the License for the specific language governing permissions and *
24  * limitations under the License. *
25  * -------------------------------------------------------------------------- */
26 
32 #include "SimTKcommon.h"
34 
35 namespace SimTK {
36 
37 
78 public:
79  // This are local classes within Differentiator; defined below.
80  class ScalarFunction; // ordinary scalar function of a scalar
81  class GradientFunction; // scalar function of vector
82  class JacobianFunction; // vector function of vector
83  class Function; // abstraction of the above
84 
85  // These are the exceptions that can be thrown by this class.
86  class OpNotAllowedForFunctionOfThisShape;
87  class UserFunctionThrewAnException;
88  class UserFunctionReturnedNonzeroStatus;
89  class UnknownMethodSpecified;
90 
91 
92  enum Method {
93  UnspecifiedMethod=0,
94  ForwardDifference=1,
95  CentralDifference=2
96  };
97  static bool isValidMethod(Method);
98  static const char* getMethodName(Method);
99  static int getMethodOrder(Method);
100 
101  virtual ~Differentiator();
102  explicit Differentiator(const Function& f,
103  Method defaultMethod=UnspecifiedMethod);
104 
105  // You can change the default method; normally it is ForwardDifference.
106  // If you set it to 'UnspecifiedMethod' it goes back to the original default.
107  Differentiator& setDefaultMethod(Method);
108  Method getDefaultMethod() const;
109 
110  // These are the real routines, which are efficient and flexible
111  // but somewhat messy to use.
112  void calcDerivative(Real y0, Real fy0, Real& dfdy,
113  Method=UnspecifiedMethod) const;
114  void calcGradient (const Vector& y0, Real fy0, Vector& gf,
115  Method=UnspecifiedMethod) const;
116  void calcJacobian (const Vector& y0, const Vector& fy0, Matrix& dfdy,
117  Method=UnspecifiedMethod) const;
118 
119  // These provide a simpler though less efficient interface. They will
120  // do some heap allocation, and will make an initial unperturbed call
121  // to the user function.
122  Real calcDerivative(Real y0, Method=UnspecifiedMethod) const;
123  Vector calcGradient (const Vector& y0, Method=UnspecifiedMethod) const;
124  Matrix calcJacobian (const Vector& y0, Method=UnspecifiedMethod) const;
125 
126  // Statistics (mutable)
127  void resetAllStatistics(); // reset all stats to zero
128  int getNumDifferentiations() const; // total # calls of calcWhatever
129  int getNumDifferentiationFailures() const; // # of those that failed
130  int getNumCallsToUserFunction() const; // total # calls to user function
131 
132  // This is a local class.
133  class DifferentiatorRep;
134 private:
135  // opaque implementation for binary compatibility
136  DifferentiatorRep* rep;
137 };
138 
153 public:
154  Function& setNumFunctions(int);
155  Function& setNumParameters(int);
156  Function& setEstimatedAccuracy(Real);
157 
158  // These values are fixed after construction.
159  int getNumFunctions() const;
160  int getNumParameters() const;
161  Real getEstimatedAccuracy() const; // approx. "roundoff" in f calculation
162 
163  // Statistics (mutable)
164  void resetAllStatistics();
165  int getNumCalls() const; // # evaluations of this function since reset
166  int getNumFailures() const; // # of calls which failed
167 
168  // This is the declaration of a local class name.
169  class FunctionRep;
170 protected:
171  Function();
172  ~Function();
173 
174  // opaque implementation for binary compatibility
175  FunctionRep* rep;
176 
177 private:
178  // suppress copy constructor and copy assignment
179  Function(const Function&) = delete;
180  Function& operator=(const Function&) = delete;
181 
182 friend class Differentiator;
183 };
184 
190 public:
191  virtual int f(Real x, Real& fx) const=0;
192 
193 protected:
194  explicit ScalarFunction(Real acc=-1);
195  virtual ~ScalarFunction() { }
196 
197 private:
198  // suppress copy constructor and copy assignment
199  ScalarFunction(const Function&);
200  ScalarFunction& operator=(const Function&);
201 };
202 
209 public:
210  virtual int f(const Vector& y, Real& fy) const=0;
211 
212 protected:
213  explicit GradientFunction(int ny=-1, Real acc=-1);
214  virtual ~GradientFunction() { }
215 
216 private:
217  // suppress copy constructor and copy assignment
219  GradientFunction& operator=(const GradientFunction&);
220 };
221 
228 public:
229  virtual int f(const Vector& y, Vector& fy) const=0;
230 
231 protected:
232  explicit JacobianFunction(int nf=-1, int ny=-1, Real acc=-1);
233  virtual ~JacobianFunction() { }
234 
235 private:
236  // suppress copy constructor and copy assignment
238  JacobianFunction& operator=(const JacobianFunction&);
239 };
240 
241 } // namespace SimTK
242 
243 #endif // SimTK_DIFFERENTIATOR_H_
FunctionRep * rep
Definition: Differentiator.h:175
Given a function f(y), where f, y or both can be vectors, calculate the derivative (gradient...
Definition: Differentiator.h:77
Derive a concrete class from this one if you have a scalar function of a single scalar variable that ...
Definition: Differentiator.h:189
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
SimTK_Real Real
This is the default compiled-in floating point type for SimTK, either float or double.
Definition: SimTKcommon/include/SimTKcommon/internal/common.h:606
Includes internal headers providing declarations for the basic SimTK Core classes, including Simmatrix.
This abstract class defines a function to be differentiated (repeatedly) by a Differentiator object...
Definition: Differentiator.h:152
Method
Definition: Differentiator.h:92
virtual ~GradientFunction()
Definition: Differentiator.h:214
This is the header file that every Simmath compilation unit should include first. ...
virtual ~ScalarFunction()
Definition: Differentiator.h:195
Derive a concrete class from this one if you have a scalar function of multiple variables that you wa...
Definition: Differentiator.h:208
Function_< Real > Function
This typedef is used for the very common case that the return type of the Function object is Real...
Definition: Function.h:117
#define SimTK_SIMMATH_EXPORT
Definition: SimTKmath/include/simmath/internal/common.h:64
Derive a concrete class from this one if you have a set of functions (i.e., a vector-valued function)...
Definition: Differentiator.h:227
virtual ~JacobianFunction()
Definition: Differentiator.h:233