Struct varpro::model::SeparableModel

pub struct SeparableModel<ScalarType> where
    ScalarType: Scalar,  { /* fields omitted */ }

This structure represents a separable nonlinear model.

Introduction

A separable nonlinear model is a nonlinear, vector valued function function $\vec{f}(\vec{x},\vec{\alpha},\vec{c})$ which depends on

• an independent variable $\vec{x}$, e.g. a location, time, etc…
• the nonlinear model parameters $\vec{\alpha}$.
• and a number of linear parameters $\vec{c}$ The number of elements in $\vec{f}$ must be the same as in the independent variable $\vec{x}$.

Separable means that the nonlinear model function can be written as the linear combination of $N_{base}$ nonlinear base functions, i.e.

f(\vec{x},\vec{\alpha}) = \sum_{j=1}^M c_j \cdot \vec{f}_j(\vec{x},S_j(\vec{\alpha})),

where $\vec{c}=(c_1,\dots,\c_M)$ are the coefficients of the model basis functions and $S_j(\vec{\alpha})$ is a subset of the nonlinear model parameters that may be different for each model function. The basis functions should depend on the model parameters nonlinearly. Linear parameters should be in the coefficient vector $\vec{c}$ only.

Important Considerations for Basis Functions

We have already stated that the basis functions should depend on their parameter subset $S_j(\vec{\alpha})$ in a non-linear manner. Linear dependencies should be rewritten in such a way that we can stick them into the coefficient vector $\vec{c}$. It is not strictly necessary to do that, but it will only make the fitting process slower and less robust. The great strength of varpro comes from treating the linear and nonlinear parameters differently.

Another important thing is to ensure that the basis functions are not linearly dependent. That is, at least not for all possible choices of $\vec{alpha}$. It is OK if model functions become linearly dependent for some combinations of model parameters. See also LevMarProblemBuilder::epsilon.

Base Functions

It perfectly fine for a base function to depend on all or none of the model parameters or any subset of the model parameters.

Invariant Functions

We refer to functions $\vec{f}_j(\vec{x})$ that do not depend on the model parameters as invariant functions. We offer special methods to add invariant functions during the model building process.

Base Functions

The varpro library expresses base function signatures as $\vec{f}_j(\vec{x},p_1,...,p_{P_j}))$, where $p_1,...,p_{P_J}$ are the paramters that the basefunction with index $j$ actually depends on. These are not given as a vector, but as a (variadic) list of arguments. The parameters must be a subset of the model parameters. In order to add functions like this to a model, we must also provide all partial derivatives (for parameters that the function explicitly depends on).

Refer to the documentation of the SeparableModelBuilder to see how to construct a model with basis functions.

Usage

The is no reason to interface with the separable model directly. First, construct it using a SeparableModelBuilder and then pass the model to one of the problem builders (e.g. LevMarProblemBuilder) to use it for nonlinear least squares fitting.

Implementations

impl<ScalarType> SeparableModel<ScalarType> where
    ScalarType: Scalar, 

pub fn parameters(&self) -> &[String]

Get the parameters of the model

pub fn parameter_count(&self) -> usize

Get the number of nonlinear parameters of the model

pub fn basis_function_count(&self) -> usize

Get the number of basis functions of the model

impl<ScalarType> SeparableModel<ScalarType> where
    ScalarType: Scalar, 

pub fn eval(
    &self,
    location: &DVector<ScalarType>,
    parameters: &[ScalarType]
) -> Result<DMatrix<ScalarType>, ModelError>

Arguments

• location: the value of the independent location parameter $\vec{x}$
• parameters: the parameter vector $\vec{\alpha}$

Result

Evaluates the model in matrix from for the given nonlinear parameters. This produces a matrix where the columns of the matrix are given by the basis function, evaluated in the order that they were added to the model. Assume the model consists of $f_1(\vec{x},\vec{\alpha})$, $f_2(\vec{x},\vec{\alpha})$, and $f_3(\vec{x},\vec{\alpha})$ and the functions where added to the model builder in this particular order. Then the matrix is given as

  \mathbf{\Phi}(\vec{x},\vec{\alpha}) \coloneqq
  \begin{pmatrix}
  \vert & \vert & \vert \\
  f_1(\vec{x},\vec{\alpha}) & f_2(\vec{x},\vec{\alpha}) & f_3(\vec{x},\vec{\alpha}) \\
  \vert & \vert & \vert \\
  \end{pmatrix},

where, again, the function $f_j$ gives the column values for colum $j$ of $\mathbf{\Phi}(\vec{x},\vec{\alpha})$. Since model function is a linear combination of the functions $f_j$, the value of the modelfunction at these parameters can be obtained as the matrix vector product $\mathbf{\Phi}(\vec{x},\vec{\alpha}) \, \vec{c}$, where $\vec{c}$ is a vector of the linear coefficients.

Errors

An error result is returned when

• the parameters do not have the same length as the model parameters given when building the model
• the basis functions do not produce a vector of the same length as the location argument $\vec{x}$

pub fn eval_deriv<'a, 'b, 'c, 'd>(
    &'a self,
    location: &'b DVector<ScalarType>,
    parameters: &'c [ScalarType]
) -> DerivativeProxy<'d, ScalarType> where
    'a: 'd,
    'b: 'd,
    'c: 'd, 

Arguments

• location: the value of the independent location parameter $\vec{x}$
• parameters: the parameter vector $\vec{\alpha}$

Usage

This function returns a proxy for syntactic sugar. Use it directly to call get the derivative matrix of model as model.eval_deriv(&x,parameters).at(0). We can also access the derivative by name for convenience as model.eval_deriv(&x,parameters).at_param_name("tau"), which will produce the same result of the index based call if "tau" is the name of the first model parameter. NOTE: In code, the derivatives are indexed with index 0. The index is given by the order that the model parameters where given when building a model. Say our model was given model parameters &["tau","omega"], then parameter "tau" corresponds to index 0 and parameter "omega" to index 1. This means that the derivative $\partial/\partial\tau$ has index 0 and $\partial/\partial\omega$ has index 1.

Result

The function returns a matrix where the derivatives of the model functions are forming the columns of the matrix. Assume the model consists of $f_1(\vec{x},\vec{\alpha})$, $f_2(\vec{x},\vec{\alpha})$, and $f_3(\vec{x},\vec{\alpha})$ and the functions where added to the model builder in this particular order. Let the model parameters be denoted by $\vec{\alpha}=(\alpha_1,\alpha_2,...,\alpha_N)$, then this function returns the matrix

  \mathbf{D}_j(\vec{x},\vec{\alpha}) \coloneqq
  \begin{pmatrix}
  \vert & \vert & \vert \\
  \frac{\partial f_1(\vec{x},\vec{\alpha})}{\partial \alpha_j} & \frac{\partial f_2(\vec{x},\vec{\alpha})}{\partial \alpha_j} & \frac{\partial f_3(\vec{x},\vec{\alpha})}{\partial \alpha_j} \\
  \vert & \vert & \vert \\
  \end{pmatrix},

where in the code the index j of the derivative begins with 0 and goes to N-1.

Errors

An error result is returned when

• the parameters do not have the same length as the model parameters given when building the model
• the basis functions do not produce a vector of the same length as the location argument $\vec{x}$
• the given parameter index is out of bounds
• the given parameter name is not a parameter of the model.