Struct varpro::model::SeparableModel [−][src]
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,
[src]
ScalarType: Scalar,
pub fn parameters(&self) -> &[String]
[src]
Get the parameters of the model
pub fn parameter_count(&self) -> usize
[src]
Get the number of nonlinear parameters of the model
pub fn basis_function_count(&self) -> usize
[src]
Get the number of basis functions of the model
impl<ScalarType> SeparableModel<ScalarType> where
ScalarType: Scalar,
[src]
ScalarType: Scalar,
pub fn eval(
&self,
location: &DVector<ScalarType>,
parameters: &[ScalarType]
) -> Result<DMatrix<ScalarType>, ModelError>
[src]
&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,
[src]
&'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.
Auto Trait Implementations
impl<ScalarType> !RefUnwindSafe for SeparableModel<ScalarType>
impl<ScalarType> !Send for SeparableModel<ScalarType>
impl<ScalarType> !Sync for SeparableModel<ScalarType>
impl<ScalarType> Unpin for SeparableModel<ScalarType>
impl<ScalarType> !UnwindSafe for SeparableModel<ScalarType>
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> Same<T> for T
type Output = T
Should always be Self
impl<SS, SP> SupersetOf<SS> for SP where
SS: SubsetOf<SP>,
SS: SubsetOf<SP>,
pub fn to_subset(&self) -> Option<SS>
pub fn is_in_subset(&self) -> bool
pub fn to_subset_unchecked(&self) -> SS
pub fn from_subset(element: &SS) -> SP
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,