feat!: Rename System::apply_mut to System::apply

The convention in Rust is to use `_mut` suffix for methods that can
modify `self` (e.g., by returning mutable reference to itself or its
field). There is not a "non-mut" alternative for applying a system in
Gomez now, so using just `apply` for the method name seems fine.

Author: pnevyk

benches/solvers.rs

@@ -249,7 +249,7 @@ where
             na::U1::name(),
         );
 
-        match self.f.apply_mut(&x, &mut fx) {
+        match self.f.apply(&x, &mut fx) {
             Ok(_) => GslStatus::ok(),
             Err(_) => GslStatus::err(GslError::BadFunc),
         }

examples/rosenbrock.rs

@@ -13,7 +13,7 @@ impl System for Rosenbrock {
     type Scalar = f64;
     type Dim = na::U2;
 
-    fn apply_mut<Sx, Sfx>(
+    fn apply<Sx, Sfx>(
         &self,
         x: &na::Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut na::Vector<Self::Scalar, Self::Dim, Sfx>,

src/analysis/initial.rs

@@ -59,7 +59,7 @@ where
         let scale = OVector::from_iterator_generic(f.dim(), U1::name(), scale_iter);
 
         // Compute F'(x) in the initial point.
-        f.apply_mut(x, fx)?;
+        f.apply(x, fx)?;
         let jac1 = Jacobian::new(f, x, &scale, fx)?;
 
         // Compute Newton step.
@@ -74,7 +74,7 @@ where
         *x += p;
 
         // Compute F'(x) after one Newton step.
-        f.apply_mut(x, fx)?;
+        f.apply(x, fx)?;
         let jac2 = Jacobian::new(f, x, &scale, fx)?;
 
         // Linear variables have no effect on the Jacobian matrix. They can be

src/core/solver.rs

@@ -61,7 +61,7 @@ use super::system::System;
 ///         });
 ///
 ///         // We must compute the residuals.
-///         f.apply_mut(x, fx)?;
+///         f.apply(x, fx)?;
 ///
 ///         Ok(())
 ///     }
@@ -81,7 +81,7 @@ pub trait Solver<F: System> {
     /// The value of `x` is the current values of variables. After the method
     /// returns, `x` should hold the variable values of the performed step and
     /// `fx` *must* contain residuals of that step as computed by
-    /// [`System::apply_mut`].
+    /// [`System::apply`].
     ///
     /// It is implementation error not to compute the residuals of the computed
     /// step.

src/core/system.rs

@@ -29,7 +29,7 @@ pub enum SystemError {
 ///
 /// A system is any type that implements [`System`] trait. There are two
 /// required associated types (scalar type and dimension type) and two required
-/// methods: [`apply_mut`](System::apply_mut) and [`dim`](System::dim).
+/// methods: [`apply`](System::apply) and [`dim`](System::dim).
 ///
 /// ```rust
 /// use gomez::nalgebra as na;
@@ -49,7 +49,7 @@ pub enum SystemError {
 ///     type Dim = na::U2;
 ///
 ///     // Apply trial values of variables to the system.
-///     fn apply_mut<Sx, Sfx>(
+///     fn apply<Sx, Sfx>(
 ///         &self,
 ///         x: &na::Vector<Self::Scalar, Self::Dim, Sx>,
 ///         fx: &mut na::Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -81,7 +81,7 @@ pub trait System {
     type Dim: Dim;
 
     /// Calculate the residuals of the system given values of the variables.
-    fn apply_mut<Sx, Sfx>(
+    fn apply<Sx, Sfx>(
         &self,
         x: &Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -104,7 +104,7 @@ pub trait System {
 /// Some extensions methods for the [`System`] that may be found useful.
 pub trait SystemExt: System {
     /// Calculate the residuals and return the squared norm of the residuals.
-    fn apply_mut_norm_squared<Sx, Sfx>(
+    fn apply_norm_squared<Sx, Sfx>(
         &self,
         x: &Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -115,7 +115,7 @@ pub trait SystemExt: System {
 }
 
 impl<F: System> SystemExt for F {
-    fn apply_mut_norm_squared<Sx, Sfx>(
+    fn apply_norm_squared<Sx, Sfx>(
         &self,
         x: &Vector<F::Scalar, F::Dim, Sx>,
         fx: &mut Vector<F::Scalar, F::Dim, Sfx>,
@@ -124,7 +124,7 @@ impl<F: System> SystemExt for F {
         Sx: Storage<Self::Scalar, Self::Dim>,
         Sfx: StorageMut<Self::Scalar, Self::Dim>,
     {
-        self.apply_mut(x, fx)?;
+        self.apply(x, fx)?;
         Ok(fx.norm_squared())
     }
 }
@@ -189,7 +189,7 @@ where
     type Scalar = F::Scalar;
     type Dim = F::Dim;
 
-    fn apply_mut<Sx, Sfx>(
+    fn apply<Sx, Sfx>(
         &self,
         x: &Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -201,7 +201,7 @@ where
         // TODO: RepulsiveSystem should adjust the residuals of the inner system
         // such that solvers tend to go away from the roots stored in the
         // archive.
-        self.f.apply_mut(x, fx)
+        self.f.apply(x, fx)
     }
 
     fn dim(&self) -> Self::Dim {

src/derivatives.rs

@@ -105,7 +105,7 @@ where
 
             // Update the point.
             x[j] = xj + step;
-            f.apply_mut(x, &mut col)?;
+            f.apply(x, &mut col)?;
 
             // Compute the derivative approximation: J[i, j] = (F(x + e_j * step_j) - F(x)) / step_j.
             col -= fx;
@@ -145,7 +145,7 @@ mod tests {
         let mut fx = dvector![0.0, 0.0];
 
         let func = ExtendedRosenbrock::new(2);
-        func.apply_mut(&x, &mut fx).unwrap();
+        func.apply(&x, &mut fx).unwrap();
         let jac = Jacobian::new(&func, &mut x, &scale, &fx);
 
         assert!(jac.is_ok());
@@ -162,7 +162,7 @@ mod tests {
         let mut fx = dvector![0.0, 0.0, 0.0, 0.0];
 
         let func = ExtendedPowell::new(4);
-        func.apply_mut(&x, &mut fx).unwrap();
+        func.apply(&x, &mut fx).unwrap();
         let jac = Jacobian::new(&func, &mut x, &scale, &fx);
 
         assert!(jac.is_ok());

src/lib.rs

@@ -83,7 +83,7 @@
 //!     type Dim = na::U2;
 //!
 //!     // Apply trial values of variables to the system.
-//!     fn apply_mut<Sx, Sfx>(
+//!     fn apply<Sx, Sfx>(
 //!         &self,
 //!         x: &na::Vector<Self::Scalar, Self::Dim, Sx>,
 //!         fx: &mut na::Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -130,7 +130,7 @@
 //! #     type Scalar = f64;
 //! #     type Dim = na::U2;
 //! #
-//! #     fn apply_mut<Sx, Sfx>(
+//! #     fn apply<Sx, Sfx>(
 //! #         &self,
 //! #         x: &na::Vector<Self::Scalar, Self::Dim, Sx>,
 //! #         fx: &mut na::Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -183,7 +183,7 @@
 //! #     type Scalar = f64;
 //! #     type Dim = na::U2;
 //! #
-//! #     fn apply_mut<Sx, Sfx>(
+//! #     fn apply<Sx, Sfx>(
 //! #         &self,
 //! #         x: &na::Vector<Self::Scalar, Self::Dim, Sx>,
 //! #         fx: &mut na::Vector<Self::Scalar, Self::Dim, Sfx>,

src/population.rs

@@ -212,7 +212,7 @@ where
     Sx: Storage<F::Scalar, F::Dim>,
     Sfx: StorageMut<F::Scalar, F::Dim>,
 {
-    f.apply_mut(x, fx)?;
+    f.apply(x, fx)?;
     Ok(fx.norm())
 }
 

src/solver/cuckoo.rs

@@ -314,7 +314,7 @@ where
 
         // Assign te best individual.
         x.copy_from(&population.iter_sorted().next().unwrap());
-        f.apply_mut(x, fx)?;
+        f.apply(x, fx)?;
 
         let report = population.report();
 

src/solver/nelder_mead.rs

@@ -219,13 +219,13 @@ where
         if simplex.is_empty() {
             // Simplex initialization.
             simplex.push(x.clone_owned());
-            errors.push(f.apply_mut_norm_squared(x, fx)?);
+            errors.push(f.apply_norm_squared(x, fx)?);
 
             for j in 0..n {
                 let mut xi = x.clone_owned();
                 xi[j] = dom.vars()[j].clamp(xi[j] + scale[j]);
 
-                errors.push(f.apply_mut_norm_squared(&xi, fx)?);
+                errors.push(f.apply_norm_squared(&xi, fx)?);
                 simplex.push(xi);
             }
 
@@ -268,7 +268,7 @@ where
         // Perform one of possible simplex transformations.
         reflection.on_line2_mut(centroid, &simplex[sort_perm[n]], reflection_coeff);
         let reflection_not_feasible = reflection.project(dom);
-        let reflection_error = f.apply_mut_norm_squared(reflection, fx)?;
+        let reflection_error = f.apply_norm_squared(reflection, fx)?;
 
         #[allow(clippy::suspicious_else_formatting)]
         let (transformation, not_feasible) = if errors[sort_perm[0]] <= reflection_error
@@ -284,7 +284,7 @@ where
             // farther along this direction.
             expansion.on_line2_mut(centroid, &simplex[sort_perm[n]], expansion_coeff);
             let expansion_not_feasible = expansion.project(dom);
-            let expansion_error = f.apply_mut_norm_squared(expansion, fx)?;
+            let expansion_error = f.apply_norm_squared(expansion, fx)?;
 
             if expansion_error < reflection_error {
                 // Expansion indeed help, replace the worst point.
@@ -309,7 +309,7 @@ where
                 // Try to perform outer contraction.
                 contraction.on_line2_mut(centroid, &simplex[sort_perm[n]], outer_contraction_coeff);
                 let contraction_not_feasible = contraction.project(dom);
-                let contraction_error = f.apply_mut_norm_squared(contraction, fx)?;
+                let contraction_error = f.apply_norm_squared(contraction, fx)?;
 
                 if contraction_error <= reflection_error {
                     // Use the contracted point instead of the reflected point
@@ -327,7 +327,7 @@ where
                 // Try to perform inner contraction.
                 contraction.on_line2_mut(centroid, &simplex[sort_perm[n]], inner_contraction_coeff);
                 let contraction_not_feasible = contraction.project(dom);
-                let contraction_error = f.apply_mut_norm_squared(contraction, fx)?;
+                let contraction_error = f.apply_norm_squared(contraction, fx)?;
 
                 if contraction_error <= errors[sort_perm[n]] {
                     // The contracted point is better than the worst point.
@@ -352,7 +352,7 @@ where
                     for i in 1..=n {
                         let xi = &mut simplex[sort_perm[i]];
                         xi.on_line_mut(contraction, shrink_coeff);
-                        errors[sort_perm[i]] = f.apply_mut_norm_squared(xi, fx)?;
+                        errors[sort_perm[i]] = f.apply_norm_squared(xi, fx)?;
                     }
 
                     (Transformation::Shrinkage, false)
@@ -377,7 +377,7 @@ where
 
         // Return the best simplex point.
         x.copy_from(&simplex[sort_perm[0]]);
-        f.apply_mut(x, fx)?;
+        f.apply(x, fx)?;
 
         if transformation == Transformation::Shrinkage || not_feasible {
             // Check whether the simplex collapsed or not. It can happen only

src/solver/trust_region.rs

@@ -241,7 +241,7 @@ where
         }
 
         // Compute F(x) and F'(x).
-        f.apply_mut(x, fx)?;
+        f.apply(x, fx)?;
         jac.compute(f, x, scale, fx)?;
 
         let fx_norm = fx.norm();
@@ -531,7 +531,7 @@ where
         }
 
         // Compute F(x').
-        let is_trial_valid = f.apply_mut(x_trial, fx_trial).is_ok();
+        let is_trial_valid = f.apply(x_trial, fx_trial).is_ok();
         let fx_trial_norm = fx_trial.norm();
 
         let gain_ratio = if is_trial_valid {

src/testing.rs

@@ -58,7 +58,7 @@ where
         Sx: Storage<Self::Scalar, Self::Dim>,
     {
         let mut fx = x.clone_owned();
-        if self.apply_mut(x, &mut fx).is_ok() {
+        if self.apply(x, &mut fx).is_ok() {
             fx.iter().all(|fxi| fxi.abs() <= eps)
         } else {
             false
@@ -116,7 +116,7 @@ impl System for ExtendedRosenbrock {
     type Scalar = f64;
     type Dim = Dynamic;
 
-    fn apply_mut<Sx, Sfx>(
+    fn apply<Sx, Sfx>(
         &self,
         x: &Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -222,7 +222,7 @@ impl System for ExtendedPowell {
     type Scalar = f64;
     type Dim = Dynamic;
 
-    fn apply_mut<Sx, Sfx>(
+    fn apply<Sx, Sfx>(
         &self,
         x: &Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -301,7 +301,7 @@ impl System for BullardBiegler {
     type Scalar = f64;
     type Dim = U2;
 
-    fn apply_mut<Sx, Sfx>(
+    fn apply<Sx, Sfx>(
         &self,
         x: &Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -371,7 +371,7 @@ impl System for Sphere {
     type Scalar = f64;
     type Dim = Dynamic;
 
-    fn apply_mut<Sx, Sfx>(
+    fn apply<Sx, Sfx>(
         &self,
         x: &Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -440,7 +440,7 @@ impl System for Brown {
     type Scalar = f64;
     type Dim = Dynamic;
 
-    fn apply_mut<Sx, Sfx>(
+    fn apply<Sx, Sfx>(
         &self,
         x: &Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut Vector<Self::Scalar, Self::Dim, Sfx>,
@@ -503,7 +503,7 @@ impl System for Exponential {
     type Scalar = f64;
     type Dim = Dynamic;
 
-    fn apply_mut<Sx, Sfx>(
+    fn apply<Sx, Sfx>(
         &self,
         x: &Vector<Self::Scalar, Self::Dim, Sx>,
         fx: &mut Vector<Self::Scalar, Self::Dim, Sfx>,