Simbody  3.8
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.
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:
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)
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:
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_
Includes internal headers providing declarations for the basic SimTK Core classes,...
This is the header file that every Simmath compilation unit should include first.
#define SimTK_SIMMATH_EXPORT
Definition: SimTKmath/include/simmath/internal/common.h:64
This abstract class defines a function to be differentiated (repeatedly) by a Differentiator object.
Definition: Differentiator.h:152
Function & setEstimatedAccuracy(Real)
FunctionRep * rep
Definition: Differentiator.h:175
Derive a concrete class from this one if you have a scalar function of multiple variables that you wa...
Definition: Differentiator.h:208
GradientFunction(int ny=-1, Real acc=-1)
virtual ~GradientFunction()
Definition: Differentiator.h:214
virtual int f(const Vector &y, Real &fy) const =0
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 int f(const Vector &y, Vector &fy) const =0
virtual ~JacobianFunction()
Definition: Differentiator.h:233
JacobianFunction(int nf=-1, int ny=-1, Real acc=-1)
Derive a concrete class from this one if you have a scalar function of a single scalar variable that ...
Definition: Differentiator.h:189
virtual int f(Real x, Real &fx) const =0
virtual ~ScalarFunction()
Definition: Differentiator.h:195
Given a function f(y), where f, y or both can be vectors, calculate the derivative (gradient,...
Definition: Differentiator.h:77
void calcDerivative(Real y0, Real fy0, Real &dfdy, Method=UnspecifiedMethod) const
static bool isValidMethod(Method)
int getNumDifferentiations() const
Method getDefaultMethod() const
void calcGradient(const Vector &y0, Real fy0, Vector &gf, Method=UnspecifiedMethod) const
Method
Definition: Differentiator.h:92
Real calcDerivative(Real y0, Method=UnspecifiedMethod) const
int getNumDifferentiationFailures() const
int getNumCallsToUserFunction() const
Matrix calcJacobian(const Vector &y0, Method=UnspecifiedMethod) const
void calcJacobian(const Vector &y0, const Vector &fy0, Matrix &dfdy, Method=UnspecifiedMethod) const
Differentiator & setDefaultMethod(Method)
Differentiator(const Function &f, Method defaultMethod=UnspecifiedMethod)
Vector calcGradient(const Vector &y0, Method=UnspecifiedMethod) const
static int getMethodOrder(Method)
static const char * getMethodName(Method)
This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with o...
Definition: Assembler.h:37
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
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:607