Simbody 3.7
Loading...
Searching...
No Matches
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
35namespace SimTK {
36
37
78public:
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);
100
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;
134private:
135 // opaque implementation for binary compatibility
136 DifferentiatorRep* rep;
137};
138
153public:
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;
170protected:
173
174 // opaque implementation for binary compatibility
175 FunctionRep* rep;
176
177private:
178 // suppress copy constructor and copy assignment
179 Function(const Function&) = delete;
180 Function& operator=(const Function&) = delete;
181
182friend class Differentiator;
183};
184
190public:
191 virtual int f(Real x, Real& fx) const=0;
192
193protected:
194 explicit ScalarFunction(Real acc=-1);
195 virtual ~ScalarFunction() { }
196
197private:
198 // suppress copy constructor and copy assignment
199 ScalarFunction(const Function&);
200 ScalarFunction& operator=(const Function&);
201};
202
209public:
210 virtual int f(const Vector& y, Real& fy) const=0;
211
212protected:
213 explicit GradientFunction(int ny=-1, Real acc=-1);
214 virtual ~GradientFunction() { }
215
216private:
217 // suppress copy constructor and copy assignment
219 GradientFunction& operator=(const GradientFunction&);
220};
221
228public:
229 virtual int f(const Vector& y, Vector& fy) const=0;
230
231protected:
232 explicit JacobianFunction(int nf=-1, int ny=-1, Real acc=-1);
233 virtual ~JacobianFunction() { }
234
235private:
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
FunctionRep * rep
Definition Differentiator.h:175
Function & setEstimatedAccuracy(Real)
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
static const char * getMethodName(Method)
void calcGradient(const Vector &y0, Real fy0, Vector &gf, Method=UnspecifiedMethod) const
Method
Definition Differentiator.h:92
Differentiator & setDefaultMethod(Method)
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(const Function &f, Method defaultMethod=UnspecifiedMethod)
Vector calcGradient(const Vector &y0, Method=UnspecifiedMethod) const
static int getMethodOrder(Method)
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