PyDSTool provides a thin wrapper around the SciPy versions of the Levenberg-Marquardt least squares optimizer and the one-parameter BoundMin bounded minimizer, under a unifying class type ParamEst, which is implemented in PyDSTool/Toolbox/ParamEst.py. This class provides basic features such as a default residual function that is compatible with PyDSTool Model objects, easing the changing of model parameter values, computation of trajectories, and setting of additional parameters for each call to the function.
The user begins by creating and initializing a ParamEst class instance with a Model system, the number of free parameters in the model to be fitted, the dependent variables names to use, and the residual function to use. Either integration initial conditions or model parameters can be used as the free parameters.
Residual functions must have a signature of the form (s, p, tmesh [, <optional additional argument sequence>]). The first argument s refers to the ParamEst class instance initialized by the user, which provides the function access to the model and other user-specified settings. The p argument will be an array of new parameter values, given in the same order as s.freeParNames.
An explicit Jacobian defined in a model system (such as that calculated using the Symbolic toolbox differentiation functions) will automatically be used by the class.
Once the ParamEst object has been created, its run method can be called in order to execute the actual optimization algorithm. Arguments to this call allow additional arguments to be sent to the residual function, and algorithmic tolerances to be set. By default, the ParamEst class calls the optimizers with their 'full output' options set, and stores the results in the dictionary s.pestResult, as well as returning a copy of that dictionary. Note that this dictionary will be overwritten on the next call to run.
One benefit of organizing a parameter estimation problem inside a class such as ParamEst is that it gives the residual function greater power to store state inside its associated class instance.
For further information see examples in PyDSTool/tests such as pest_test1.py for initialization of ParamEst class instances, overriding of default residual functions, and running of the optimizers.
This works in an N-dimensional parameter space on an n-dimensional model trajectory. This sub-class wraps the leastsq function from scipy.minpack. This algorithm is inherently unconstrained, but can be adapted to incorporate soft constraints in the residual function (see the provided example scripts).
The class attribute _memory, which is pre-declared and provided as a memory for the residual functions between calls. It is declared to be the array zeros(self._tmesh_len*self._depvar_len, dtype=float64), to provide temporary storage while building the return array of residuals (see residual_fn_LMpest_default_Ndim for an example).
This works only in a one-dimensional parameter space for a one-dimensional model trajectory. This sub-class wraps fminbound from scipy.optimize. It minimizes subject to bound constraints.
You can fit user-defined qualitative "features" of a trajectory to those of experimental data or to predefined ideals using conventional optimization algorithms, such as least squares. This approach is under development but appears to work well in instances where standard approaches for which the fitting problem is ill-conditioned by virtue of having a "fitness landscape" that is too flat or too irregular near typical initial conditions.
A robust way to fit trajectory extrema in a given coordinate is to define events in the test model to find them accurately. The tools provided here assume that you have added appropriate events to your model to do this. This is described further in the following docstring for the example residual function residual_fn_LMpest_extrema(s, p, tmesh) exported from ParamEst.py:
s.testModel given to the ParamEst object at creation. This generator should contain separate events for detecting maxima and minima in each coordinate being fitted (e.g. zero crossing of first derivative of a coordinate, in appropriate direction). For a coordinate named 'x' these events are expected to have the names 'min_ev_x' and 'max_ev_x'. num_expected_mins and num_expected_maxs is per variable.
In addition to parameter estimation, one may use an algorithm to systematically alter a model in order to achieve a fit of its performance to given criteria. This may be called model estimation, a.k.a. model inference. To support this, a number of tools are provided for manipulating model descriptions (using ModelSpec), via a class of model Transforms. One may also take advantage of a library (class ModelLibrary) of model description primitives, from which to base a systematic search of a "model space" suitable to the model estimation problem.
A ModelManager instance is a repository for all models related by a class of transformations. In order to build model instantiations that are ready to simulate, the GDescriptor and MDescriptor classes are used to hold all the specific details of how to instantiate a model once it is mathematically specified. Upon demand, these are then fed by the model manager into a ModelConstructor object to build a new model. The model manager is also the access point for creating transformations of a model into another.