added Damped Sinusoid

Author: hexqnt

README.md

@@ -1,15 +1,29 @@
 # curve-fit
 
-`curve-fit` — учебное приложение для подбора параметров кривой по набору точек. Основаня цель приложения это наработка интуиции по модельным кривым.
+`curve-fit` — учебное приложение для подбора параметров кривой по набору точек.
+Главная цель проекта: нарабатывать интуицию о том, как ведут себя разные модели и оптимизаторы
+на реальных и синтетических данных.
+
+Проект не пытается быть “production-утилитой” для универсального фитинга: это песочница для экспериментов и обучения.
 
 [![CI](https://github.com/hexqnt/curve-fit/actions/workflows/ci.yml/badge.svg)](https://github.com/hexqnt/curve-fit/actions/workflows/ci.yml)
 
-![Alt text](images/curve-fit-screenshot.png "Optional title text")
+![curve-fit screenshot](images/curve-fit-screenshot.png)
+
+## Что внутри
+
+- Параметрические семейства:
+  - полиномы, экспоненциальные, сигмоиды, пиковые модели, степенные, двухэкспоненциальные и осциллирующие (затухающая синусоида),
+  - cплайны: линейный, монотонный кубический (PCHIP), натуральный кубический, Akima.
+- Несколько оптимизаторов и метрик лосса для сравнения динамики сходимости.
+- Диагностика итераций и визуализация результата в интерактивном UI.
+
+## Desktop vs Web
 
-Отличие десктопной версии от web-версии:
+Десктопная версия имеет:
 
 - чуть выше производительность
-- нет подвисания при обучении(фитинге кривой)
+- меньше риск подвисаний во время обучения (фитинга)
 
 ## Run Desktop
 
@@ -19,7 +33,7 @@ cargo run
 
 ## Run Web (wasm)
 
-1. Установить таргет:
+1. Установить target:
 
 ```bash
 rustup target add wasm32-unknown-unknown

src/app.rs

@@ -212,6 +212,7 @@ enum ModelChoice {
     Logistic,
     Gompertz,
     BiExponential,
+    DampedSinusoid,
     Lorentzian,
     NaturalLog,
     FourPl,
@@ -233,13 +234,14 @@ enum ModelChoice {
 }
 
 impl ModelChoice {
-    const ALL: [Self; 24] = [
+    const ALL: [Self; 25] = [
         Self::Polynomial,
         Self::Arrhenius,
         Self::Inverse,
         Self::Logistic,
         Self::Gompertz,
         Self::BiExponential,
+        Self::DampedSinusoid,
         Self::Lorentzian,
         Self::NaturalLog,
         Self::FourPl,
@@ -283,6 +285,7 @@ impl ResolvedModel {
             ModelChoice::Logistic => Self::Parametric(CurveFamily::Logistic),
             ModelChoice::Gompertz => Self::Parametric(CurveFamily::Gompertz),
             ModelChoice::BiExponential => Self::Parametric(CurveFamily::BiExponential),
+            ModelChoice::DampedSinusoid => Self::Parametric(CurveFamily::DampedSinusoid),
             ModelChoice::Lorentzian => Self::Parametric(CurveFamily::Lorentzian),
             ModelChoice::NaturalLog => Self::Parametric(CurveFamily::NaturalLog),
             ModelChoice::FourPl => Self::Parametric(CurveFamily::FourPl),
@@ -371,6 +374,7 @@ fn model_group(model: ModelChoice) -> ModelGroup {
         ModelChoice::Arrhenius
         | ModelChoice::Inverse
         | ModelChoice::BiExponential
+        | ModelChoice::DampedSinusoid
         | ModelChoice::NaturalLog
         | ModelChoice::MichaelisMenten
         | ModelChoice::ExponentialBasic

src/app/formula.rs

@@ -14,6 +14,7 @@ fn model_formula_full(model: ModelChoice, polynomial_degree: usize) -> String {
         ModelChoice::BiExponential => {
             r"y = a_{1}·exp(-k_{1}·x) + a_{2}·exp(-k_{2}·x) + c".to_string()
         }
+        ModelChoice::DampedSinusoid => r"y = A·exp(-k·x)·sin(\omega·x + \phi) + c".to_string(),
         ModelChoice::Lorentzian => r"y = C + \frac{A}{1 + (\frac{x - x_0}{gamma})^{2}}".to_string(),
         ModelChoice::NaturalLog => r"y = A·ln(\frac{x}{B})".to_string(),
         ModelChoice::FourPl => r"y = d + \frac{a - d}{1 + (\frac{x}{c})^{b}}".to_string(),
@@ -116,6 +117,9 @@ fn model_ml_note(language: UiLanguage, model: ModelChoice) -> &'static str {
         (UiLanguage::English, ModelChoice::BiExponential) => {
             "Two-timescale exponential model with strong parameter coupling."
         }
+        (UiLanguage::English, ModelChoice::DampedSinusoid) => {
+            "Oscillatory model with damping; often has many local minima."
+        }
         (UiLanguage::English, ModelChoice::Lorentzian) => "Peak-shaped model with heavy tails.",
         (UiLanguage::English, ModelChoice::NaturalLog) => {
             "Log transform response, useful for diminishing returns."
@@ -163,6 +167,9 @@ fn model_ml_note(language: UiLanguage, model: ModelChoice) -> &'static str {
         (UiLanguage::Russian, ModelChoice::BiExponential) => {
             "Двухэкспоненциальная модель с сильной связью параметров."
         }
+        (UiLanguage::Russian, ModelChoice::DampedSinusoid) => {
+            "Осциллирующая модель с затуханием и множеством локальных минимумов."
+        }
         (UiLanguage::Russian, ModelChoice::Lorentzian) => {
             "Пиковая модель с более тяжёлыми хвостами."
         }

src/app/i18n.rs

@@ -190,17 +190,17 @@ pub(super) fn param_init_method_disabled_label(
 ) -> &'static str {
     match (language, method) {
         (UiLanguage::English, ParamInitMethod::DataBased) => {
-            "Data-based (Polynomial/Logistic/Gompertz/Bi-Exponential/Gaussian/Exponential (Basic)/Power only)"
+            "Data-based (Polynomial/Logistic/Gompertz/Bi-Exponential/Damped Sinusoid/Gaussian/Exponential (Basic)/Power only)"
         }
         (UiLanguage::English, ParamInitMethod::Randomized) => {
-            "Randomized (Polynomial/Logistic/Gompertz/Bi-Exponential/Gaussian/Exponential (Basic)/Power only)"
+            "Randomized (Polynomial/Logistic/Gompertz/Bi-Exponential/Damped Sinusoid/Gaussian/Exponential (Basic)/Power only)"
         }
         (UiLanguage::English, ParamInitMethod::Default) => "Default",
         (UiLanguage::Russian, ParamInitMethod::DataBased) => {
-            "По данным (только Polynomial/Logistic/Gompertz/Bi-Exponential/Gaussian/Exponential (Basic)/Power)"
+            "По данным (только Polynomial/Logistic/Gompertz/Bi-Exponential/Damped Sinusoid/Gaussian/Exponential (Basic)/Power)"
         }
         (UiLanguage::Russian, ParamInitMethod::Randomized) => {
-            "Случайно (только Polynomial/Logistic/Gompertz/Bi-Exponential/Gaussian/Exponential (Basic)/Power)"
+            "Случайно (только Polynomial/Logistic/Gompertz/Bi-Exponential/Damped Sinusoid/Gaussian/Exponential (Basic)/Power)"
         }
         (UiLanguage::Russian, ParamInitMethod::Default) => "По умолчанию",
     }
@@ -214,6 +214,7 @@ pub(super) fn model_choice_label(language: UiLanguage, model: ModelChoice) -> &'
         (UiLanguage::English, ModelChoice::Logistic) => "Logistic",
         (UiLanguage::English, ModelChoice::Gompertz) => "Gompertz",
         (UiLanguage::English, ModelChoice::BiExponential) => "Bi-Exponential",
+        (UiLanguage::English, ModelChoice::DampedSinusoid) => "Damped Sinusoid",
         (UiLanguage::English, ModelChoice::Lorentzian) => "Lorentzian",
         (UiLanguage::English, ModelChoice::NaturalLog) => "Natural Log",
         (UiLanguage::English, ModelChoice::FourPl) => "4PL",
@@ -238,6 +239,7 @@ pub(super) fn model_choice_label(language: UiLanguage, model: ModelChoice) -> &'
         (UiLanguage::Russian, ModelChoice::Logistic) => "Логистическая",
         (UiLanguage::Russian, ModelChoice::Gompertz) => "Гомпертц",
         (UiLanguage::Russian, ModelChoice::BiExponential) => "Би-экспонента",
+        (UiLanguage::Russian, ModelChoice::DampedSinusoid) => "Затухающая синусоида",
         (UiLanguage::Russian, ModelChoice::Lorentzian) => "Лоренциан",
         (UiLanguage::Russian, ModelChoice::NaturalLog) => "Натуральный логарифм",
         (UiLanguage::Russian, ModelChoice::FourPl) => "4PL",
@@ -275,6 +277,7 @@ pub(super) fn family_label(language: UiLanguage, family: CurveFamily) -> &'stati
         (UiLanguage::English, CurveFamily::Logistic) => "Logistic",
         (UiLanguage::English, CurveFamily::Gompertz) => "Gompertz",
         (UiLanguage::English, CurveFamily::BiExponential) => "Bi-Exponential",
+        (UiLanguage::English, CurveFamily::DampedSinusoid) => "Damped Sinusoid",
         (UiLanguage::English, CurveFamily::Lorentzian) => "Lorentzian",
         (UiLanguage::English, CurveFamily::NaturalLog) => "Natural Log",
         (UiLanguage::English, CurveFamily::FourPl) => "4PL",
@@ -303,6 +306,7 @@ pub(super) fn family_label(language: UiLanguage, family: CurveFamily) -> &'stati
         (UiLanguage::Russian, CurveFamily::Logistic) => "Логистическая",
         (UiLanguage::Russian, CurveFamily::Gompertz) => "Гомпертц",
         (UiLanguage::Russian, CurveFamily::BiExponential) => "Би-экспонента",
+        (UiLanguage::Russian, CurveFamily::DampedSinusoid) => "Затухающая синусоида",
         (UiLanguage::Russian, CurveFamily::Lorentzian) => "Лоренциан",
         (UiLanguage::Russian, CurveFamily::NaturalLog) => "Натуральный логарифм",
         (UiLanguage::Russian, CurveFamily::FourPl) => "4PL",

src/app/normalization.rs

@@ -138,6 +138,19 @@ impl ParametricNormalization {
                         values[4] *= y_scale;
                     }
                 }
+                CurveFamily::DampedSinusoid => {
+                    if to_normalized {
+                        values[0] /= y_scale;
+                        values[1] *= x_scale;
+                        values[2] *= x_scale;
+                        values[4] /= y_scale;
+                    } else {
+                        values[0] *= y_scale;
+                        values[1] /= x_scale;
+                        values[2] /= x_scale;
+                        values[4] *= y_scale;
+                    }
+                }
                 CurveFamily::Lorentzian => {
                     if to_normalized {
                         values[0] /= y_scale;

src/app/param_init.rs

@@ -23,6 +23,7 @@ pub(super) fn is_advanced_param_init_supported(family: CurveFamily) -> bool {
             CurveFamily::Logistic
                 | CurveFamily::Gompertz
                 | CurveFamily::BiExponential
+                | CurveFamily::DampedSinusoid
                 | CurveFamily::Gaussian
                 | CurveFamily::ExponentialBasic
                 | CurveFamily::Power
@@ -44,6 +45,7 @@ pub(super) fn data_based_params_for_family(
         CurveFamily::Logistic => data_based_logistic_params(points),
         CurveFamily::Gompertz => data_based_gompertz_params(points),
         CurveFamily::BiExponential => data_based_bi_exponential_params(points),
+        CurveFamily::DampedSinusoid => data_based_damped_sinusoid_params(points),
         CurveFamily::Gaussian => data_based_gaussian_params(points),
         CurveFamily::ExponentialBasic => data_based_exponential_basic_params(points),
         CurveFamily::Power => data_based_power_params(points),
@@ -95,6 +97,34 @@ fn data_based_bi_exponential_params(points: &Points) -> Result<CurveParams, Stri
         .map_err(|error| error.to_string())
 }
 
+fn data_based_damped_sinusoid_params(points: &Points) -> Result<CurveParams, String> {
+    let sorted = sorted_by_x(points);
+    let first = sorted[0];
+    let last = sorted[sorted.len() - 1];
+    let x_span = (last.x() - first.x()).abs().max(PARAM_INIT_SPAN_EPS);
+    let (_, _, y_min, y_max, _) = point_extrema(points);
+    let center = mean_y(points);
+    let amplitude = ((y_max - y_min) * 0.5).abs().max(PARAM_INIT_SPAN_EPS);
+    let k = 0.5 / x_span;
+    let zero_crossings = count_centered_sign_changes(&sorted, center);
+    let omega = if zero_crossings > 0 {
+        std::f64::consts::PI * zero_crossings as f64 / x_span
+    } else {
+        std::f64::consts::TAU / x_span
+    };
+    let denom = (amplitude * (-k * first.x()).exp())
+        .abs()
+        .max(PARAM_INIT_SPAN_EPS);
+    let ratio = ((first.y() - center) / denom).clamp(-1.0, 1.0);
+    let phi = ratio.asin() - omega * first.x();
+
+    CurveParams::try_from_values(
+        CurveFamily::DampedSinusoid,
+        vec![amplitude, k, omega, phi, center],
+    )
+    .map_err(|error| error.to_string())
+}
+
 fn data_based_gaussian_params(points: &Points) -> Result<CurveParams, String> {
     let (x_min, x_max, _, y_max, x_at_y_max) = point_extrema(points);
     let x_span = (x_max - x_min).max(PARAM_INIT_SPAN_EPS);
@@ -225,3 +255,28 @@ fn y_at_x_bounds(points: &Points) -> (f64, f64) {
 
     (y_at_min_x, y_at_max_x)
 }
+
+fn mean_y(points: &Points) -> f64 {
+    points.as_slice().iter().map(|point| point.y()).sum::<f64>() / points.len() as f64
+}
+
+fn sorted_by_x(points: &Points) -> Vec<crate::domain::Point> {
+    let mut sorted = points.as_slice().to_vec();
+    sorted.sort_by(|left, right| left.x().total_cmp(&right.x()));
+    sorted
+}
+
+fn count_centered_sign_changes(sorted: &[crate::domain::Point], center: f64) -> usize {
+    let mut sign_changes = 0_usize;
+    let mut previous = sorted[0].y() - center;
+    for point in sorted.iter().skip(1) {
+        let current = point.y() - center;
+        if previous * current < 0.0 {
+            sign_changes += 1;
+        }
+        if current.abs() > PARAM_INIT_SPAN_EPS {
+            previous = current;
+        }
+    }
+    sign_changes
+}

src/app/tests.rs

@@ -631,6 +631,8 @@ fn param_init_method_support_matrix_is_correct() {
     assert!(ParamInitMethod::Default.is_supported_for_family(CurveFamily::Arrhenius));
     assert!(ParamInitMethod::DataBased.is_supported_for_family(CurveFamily::Linear));
     assert!(ParamInitMethod::Randomized.is_supported_for_family(CurveFamily::Power));
+    assert!(ParamInitMethod::DataBased.is_supported_for_family(CurveFamily::BiExponential));
+    assert!(ParamInitMethod::Randomized.is_supported_for_family(CurveFamily::DampedSinusoid));
 
     assert!(!ParamInitMethod::DataBased.is_supported_for_family(CurveFamily::Arrhenius));
     assert!(!ParamInitMethod::Randomized.is_supported_for_family(CurveFamily::FourPl));
@@ -660,6 +662,49 @@ fn data_based_power_initialization_rejects_non_positive_y() {
     assert!(error.contains("requires y > 0"));
 }
 
+#[test]
+fn data_based_bi_exponential_initialization_returns_finite_values() {
+    let points = points_from_pairs(&[
+        (0.0, 2.7),
+        (0.4, 2.1),
+        (0.9, 1.5),
+        (1.6, 1.0),
+        (2.3, 0.7),
+        (3.2, 0.5),
+    ]);
+    let params = data_based_params_for_family(CurveFamily::BiExponential, &points)
+        .expect("must initialize bi-exponential params");
+    let values = params.values();
+
+    assert_eq!(values.len(), CurveFamily::BiExponential.parameter_count());
+    assert!(values.iter().all(|value| value.is_finite()));
+    assert!(values[1] > 0.0, "k1 must be positive");
+    assert!(values[3] > 0.0, "k2 must be positive");
+}
+
+#[test]
+fn data_based_damped_sinusoid_initialization_returns_finite_values() {
+    let points = points_from_pairs(&[
+        (0.0, 0.6),
+        (0.5, 1.2),
+        (1.0, 0.3),
+        (1.5, -0.8),
+        (2.0, -0.5),
+        (2.5, 0.4),
+        (3.0, 0.7),
+        (3.5, 0.1),
+        (4.0, -0.4),
+    ]);
+    let params = data_based_params_for_family(CurveFamily::DampedSinusoid, &points)
+        .expect("must initialize damped sinusoid params");
+    let values = params.values();
+
+    assert_eq!(values.len(), CurveFamily::DampedSinusoid.parameter_count());
+    assert!(values.iter().all(|value| value.is_finite()));
+    assert!(values[1] > 0.0, "k must be positive");
+    assert!(values[2] > 0.0, "omega must be positive");
+}
+
 #[test]
 fn randomized_initialization_stays_within_expected_range() {
     let mut app = CurveFitApp::default();