Struct varpro::solvers::levmar::LevMarProblemBuilder

pub struct LevMarProblemBuilder<'a, ScalarType> where
    ScalarType: Scalar + ComplexField,
    ScalarType::RealField: Float + Mul<ScalarType, Output = ScalarType>,  { /* fields omitted */ }

A builder structure to create a LevMarProblem, which can be used for fitting a separable model to data.

Example

The following code shows how to create an unweighted least squares problem to fit the separable model $\vec{f}(\vec{x},\vec{\alpha},\vec{c})$ given by model to data $\vec{y}$ (given as y) using the independent variable $\vec{x}$ (given as x). Furthermore we need an initial guess params for the nonlinear model parameters $\vec{\alpha}$

  let problem = LevMarProblemBuilder::new()
                .x(x)
                .y(y)
                .model(model)
                .initial_guess(params)
                .build()
                .unwrap();

Building a Model

A new builder is constructed with the new method. It must be filled with content using the methods described in the following. After all mandatory fields have been filled, the build method can be called. This returns a Result type that contains the finished model iff all mandatory fields have been set with valid values. Otherwise it contains an error variant.

Mandatory Building Blocks

The following methods must be called before building a problem with the builder.

• x to set the values of the independent variable $\vec{x}$
• y to set the values of the independent variable $\vec{y}$
• model to set the model function
• initial_guess provide an initial guess

Additional Building blocks

The other methods of the builder allow to manipulate further aspects, like adding weights to the data. The methods are marked as Optional.

Implementations

impl<'a, ScalarType> LevMarProblemBuilder<'a, ScalarType> where
    ScalarType: Scalar + ComplexField + Zero,
    ScalarType::RealField: Float + Mul<ScalarType, Output = ScalarType>, 

pub fn new() -> Self

Create a new builder with empty fields and unit weights

pub fn x<VectorType>(self, xvec: VectorType) -> Self where
    DVector<ScalarType>: From<VectorType>, 

Mandatory: Set the value of the independent variable $\vec{x}$ of the problem. The length of $\vec{x}$ and the data $\vec{y}$ must be the same.

pub fn y<VectorType>(self, yvec: VectorType) -> Self where
    DVector<ScalarType>: From<VectorType>, 

Mandatory: Set the data which we want to fit: $\vec{y}=\vec{y}(\vec{x})$. The length of $\vec{x}$ and the data $\vec{y}$ must be the same.

pub fn model(self, model: &'a SeparableModel<ScalarType>) -> Self

Mandatory: Set the actual model used for fitting

pub fn initial_guess(self, params: &[ScalarType]) -> Self

Mandatory: provide initial guess for the parameters. The number of values in the initial guess must match the number of model parameters

pub fn epsilon(self, eps: ScalarType::RealField) -> Self

Optional This value is relevant for the solver, because it uses singular value decomposition internally. This method sets a value \epsilon for which smaller (i.e. absolute - wise) singular values are considered zero. In essence this gives a truncation of the SVD. This might be helpful if two basis functions become linear dependent when the nonlinear model parameters align in an unfortunate way. In this case a higher epsilon might increase the robustness of the fitting process.

If this value is not given, it will be set to machine epsilon.

The given epsilon is automatically converted to a non-negative number.

pub fn weights<VectorType>(self, weights: VectorType) -> Self where
    DVector<ScalarType>: From<VectorType>, 

Optional Add diagonal weights to the problem (meaning data points are statistically independent). If this is not given, the problem is unweighted, i.e. each data point has unit weight.

Note The weighted residual is calculated as $||W(\vec{y}-\vec{f}(\vec{\alpha})||^2$, so to make weights that have a statistical meaning, the diagonal elements of the weight matrix should be set to w_{jj} = 1/\sigma_j where $\sigma_j$ is the (estimated) standard deviation associated with data point $y_j$.

pub fn build(self) -> Result<LevMarProblem<'a, ScalarType>, LevMarBuilderError>

build the least squares problem from the builder.

Prerequisites

• All mandatory parameters have been set (see individual builder methods for details)
• $\vec{x}$ and $\vec{y}$ have the same number of elements
• $\vec{x}$ and $\vec{y}$ have a nonzero number of elements
• the length of the initial guesses vector is the same as the number of model parameters

Returns

If all prerequisites are fulfilled, returns a LevMarProblem with the given content and the parameters set to the initial guess. Otherwise returns an error variant.

Trait Implementations

impl<'a, ScalarType: Clone> Clone for LevMarProblemBuilder<'a, ScalarType> where
    ScalarType: Scalar + ComplexField,
    ScalarType::RealField: Float + Mul<ScalarType, Output = ScalarType>,
    ScalarType::RealField: Clone, 

fn clone(&self) -> LevMarProblemBuilder<'a, ScalarType>

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, ScalarType> Default for LevMarProblemBuilder<'a, ScalarType> where
    ScalarType: Scalar + ComplexField + Zero,
    ScalarType::RealField: Float + Mul<ScalarType, Output = ScalarType>, 

Same as Self::new().

fn default() -> Self

Returns the “default value” for a type.