This crate does not require nor std nor alloc ❤️

This is my take on a "convenient interface" for a brilliant levenberg_marquardt crate, aiming to be versatile, flexible and easy-to-understand.

Before you read further, consider giving levenberg_marquardt itself a look - it's interface is quite abstract, and you might come up with a more efficient use pattern for your problem.

As another shout out, see varpro crate, which does basically the same thing (provides a high-level interface to levenberg_marquardt), except it has some more special sauce your application might benefit from.

Motivation

I've identified following drawbacks in APIs of mentioned crates:

• levenberg_marquardt uses nalgebra and requires you to explicitly use it too. This can be quite confusing, especially if you are yet to read nalgebra's doc.
• Both levenberg_marquardt and varpro unify parameters and data into a single object. This makes sense for internal solving process, but there's no reason to leave it like that in a public API.
• varpro requires std (because reasons, I guess)
• levenberg_marquardt allows problem to return any sort of nalgebra matrix, abstracted over storage. varpro, on the other hand, is hard-coded to use Dyn-sized storages, meaning that for every single parameters get/set operation, new vector (on the heap!) is allocated. This might be less than ideal, especially if both parameter and point count happen to be statically known.
• varpro defines it's SeparableModel parameters as a nalgebra vector. This leaves your code prone to getting wrong parameter or non-existing parameter from the vector.

I've come up with the following design:

1. All models have statically-known parameter count. This allows get/set operations to use stack-allocated storage.
2. Model (parameters container) is separate from data. Combination into a single struct is not required to use to the public API.
3. (2) allows definition of an alternative model trait, with no nalgebra mentioned. Instead, it tangentially mentions generic_array (specifically, there's an Into<GenericArray> return bound), which I find easier to use.
4. (2) allows abstraction over data-providing type. Data provider is converted into nalgebra matrix internally.
5. This crate only heap-allocates in case there is an unknown data point count.
6. Model type is never erased, models expose relevant parameters as fields/methods. Makes impossible to ask for wrong/incorrect parameter, since all parameters are obtained via field access and function calls (instead of opaque nalgebra matrix element).
7. Crate provides a simple way to compose multiple models into a single, more complex one.

I find described API more intuitive and less error prone. Also it statically prevents some of the levenberg_marquardts termination reasons (User, NoParameters, NoResiduals, WrongDimensions).

With general idea outlined, here's an example:

Basic example

# use approx::assert_ulps_eq;
# use nacfahi::{models::basic::Linear, *};

// some data, presumably 2x + 1
let x = [1.0, 2.0, 3.0, 4.0, 5.0];
let y = [3.0, 5.0, 7.0, 9.0, 11.0];

// fitting model: a*x + b
let mut line = Linear { a: 0.0, b: 0.0 };

// do the fit!
let report = fit!(&mut line, x, y);

// check that approximation is successful
assert!(
    report.termination.was_successful(),
    "Approximation should be successful"
);

// check that model parameters have expected values
assert_ulps_eq!(line.a, 2.0);
assert_ulps_eq!(line.b, 1.0);

Looks simple enough? Consider reading the rest, then!

What's actually going on

There are a couple things to unpack here:

Data format

Input data can be any AsMatrixView trait implementor, and core Rust array happens to be one. See trait's documentation for details.

fit macro

That's a pure convenience macro expanding into a [function@fit] function call. For details, see [macro@fit!].

Fit models

Model generally refers to FitModel implementation, internally wired to levenberg_marquardt's LeastSquaresProblem trait.

Most of the public items in this crate are models representing various common fitting functions or meta operations.

Additionally, FitModel is implemented for &mut FitModel - this is actually utilized in the above example to keep ownership of the model after the fit.

Also, core Rust arrays implement FitModel, as a sum of it's element models. So [Exponent; 2] would fit with a sum of two independent Exponent models, and [Gaussian; 5] would fit with 5 Gaussian independent models.

To reiterate: these models contain multiple independent instances of the same model type that are added up.

Basic Models

Basic models are representations of elementary functions. You can fit them directly (as does the example above), or compose more complex models with them (see below).

Basic models are located in models::basic module, see it's items for details.

Utility models

Utility models are models containing other models, implementing some sort of additional functionality, like range filtering or mapping.

See models::utility items for details. Here are some examples:

• Ranged has a second field range defining x variable range the model will be nonzero in. Sharp turns can be emulated with this model, for example here is an exponential "ramp", dropping after 0.0:

# use core::ops::RangeTo;
# use nacfahi::{models::{basic::Exponent, utility::Ranged}, *};
// (see `utility_models` integration test for details)
type ExpRamp<Scalar> = Ranged<Exponent<Scalar>, RangeTo<Scalar>>;

// for example, this model equals 0 at x > 0:
let _ramp = Ranged {
    inner: Exponent { a: 0.0, b: 0.0 },
    range: ..0.0,
};

• ModelMap (UNTESTED!) is supposed to additionally map the model, allowing fits in mapped spaces. For example, while fitting to a single exponent, you might want to use LnMap to do a linear fit:

# use nacfahi::{models::{basic::Exponent, utility::{model_map, LnMap}}, fit};
# use num_traits::Float;
# use approx::assert_ulps_eq;
# 
// some exponential data
let expected_a = 3.0;
let expected_b = 0.5;
let x = [0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0];
let y = x.map(|x| expected_a * (x * expected_b).exp());
let linear_y = y.map(f64::ln);

// exponential model
let mut expo_model = Exponent { a: 1.0, b: 0.0 };
// expolinear (exponential mapped to linear)
let mut expolinear = model_map(&mut expo_model, LnMap);

// fit!
let report = fit!(&mut expolinear, x, linear_y);

# assert!(
#     report.termination.was_successful(),
#     "Fit should be successful {report:?}"
# );
# assert_ulps_eq!(expo_model.a, expected_a);
# assert_ulps_eq!(expo_model.b, expected_b);

Note: this functionality is largely unfinished, and probably should not be used yet

• Composition (UNTESTED!) is supposed to allow model composition. This is similar to ModelMap, except "the map" here has it's own parameters and fitting process fits them as well. Here's an example of gaussian-over-exponential model (whatever that would mean):

/* no example hewe, sowwy :( */

Note: this functionality is largely unfinished, and probably should not be used yet

Custom models

What if you need a model consisting of linear, exponential and three gaussian peaks? Even [Box<dyn FitModel>; 5] won't work, since FitModel is not object-safe...

Well, FitModel is fully public, and you are free to implement it yourself! In this case, it's a bunch of annoying boilerplate though:

# use generic_array::sequence::{Concat, Split};
# use nacfahi::{models::{FitModel, basic::{Exponent, Gaussian, Linear}}};
#
struct CustomModel {
    linear: Linear<f64>,
    exponent: Exponent<f64>,
    peaks: [Gaussian<f64>; 3],
}

impl FitModel for CustomModel {
    type Scalar = f64;
    type ParamCount = typenum::U13; // <-- oh, and you also need to manually compute total parameter count

    fn evaluate(&self, x: &f64) -> f64 {
        self.linear.evaluate(x) + self.exponent.evaluate(x) + self.peaks.evaluate(x)
    }

    fn jacobian(&self, x: &f64) -> impl Into<generic_array::GenericArray<f64, Self::ParamCount>> {
        let linear = self.linear.jacobian(x).into();
        let exponent = self.exponent.jacobian(x).into();
        let peaks = self.peaks.jacobian(x).into();
        linear.concat(exponent).concat(peaks)
    }

    fn set_params(&mut self, new_params: generic_array::GenericArray<f64, Self::ParamCount>) {
        let (linear, rest) = new_params.split();
        let (exponent, peaks) = rest.split();

        self.linear.set_params(linear);
        self.exponent.set_params(exponent);
        self.peaks.set_params(peaks);
    }

    fn get_params(&self) -> impl Into<generic_array::GenericArray<f64, Self::ParamCount>> {
        let linear = self.linear.get_params().into();
        let exponent = self.exponent.get_params().into();
        let peaks = self.peaks.get_params().into();
        linear.concat(exponent).concat(peaks)
    }
}

Good news is - there's a derive macro for that!

# use nacfahi::{models::{FitModel, FitModelSum, basic::{Constant, Exponent, Gaussian}}, *};
# use static_assertions::assert_impl_all;
# 
#[derive(FitModelSum)]
#[scalar_type(f64)]
struct ConstExponent {
    linear: Constant<f64>,
    exponent: Exponent<f64>,
    peaks: [Gaussian<f64>; 3],
}
# 
# assert_impl_all!(ConstExponent: FitModel<Scalar = f64>);

And it does exactly all of the above, except you can do some stuff that is hard to implement manually.

See FitModelSum for usage details and more examples.

In case you happened to cargo-expand it - I've spent yes time implementing this

Why the name?

Actual intended name is nacfa'i, which is a lojban predicate for "x1 is solved to find x2".

(I am not proficient in lojban at all, pwease don't huwt mw :3