documentation improvements

Author: geo-ant

src/lib.rs

@@ -12,6 +12,18 @@
 //! sides has been added to this library. This is a powerful technique for suitable
 //! problems and is explained at the end of this introductory chapter.
 //!
+//! ## Parallel Computations
+//!
+//! Since version 0.11.0, support for parallelizing some of the more expensive
+//! computations has been added. See the
+//! [`LevMarProblemBuilder::new_parallel`](crate::solvers::levmar::LevMarProblemBuilder::new_parallel) and
+//! [`LevMarProblemBuilder::mrhs_parallel`](crate::solvers::levmar::LevMarProblemBuilder::mrhs_parallel)
+//! builder functions. **Attention** Using multithreaded calculations might actually
+//! slow down the overall computations, so definitely make sure to compare it
+//! to the single-threaded case by **measuring**. For suitable problems it might
+//! give you a speedup in the double digit percentages, but for unsuitable ones
+//! it will slow the computations down much more than that.
+//!
 //! ## Overview
 //!
 //! Many nonlinear models consist of a mixture of both truly nonlinear and _linear_ model
@@ -387,7 +399,10 @@
 //! \end{matrix}\right)
 //! ```
 //!
-//! The order of the vectors in the matrix doesn't matter.
+//! The order of the vectors in the matrix doesn't matter, but it will determine
+//! the order of the linear coefficients, see
+//! [`LevMarProblemBuilder::mrhs`](crate::solvers::levmar::LevMarProblemBuilder::mrhs)
+//! for a more detailed explanation.
 //!
 //! ## Example
 //! ```no_run

src/solvers/levmar/builder.rs

@@ -180,11 +180,36 @@ where
     /// fit. This uses single threaded calculations.
     ///
     /// That means the observations are expected to be a matrix, where the
-    /// columns correspond to the individual observations. The nonlinear
-    /// parameters will be optimized across all the observations, but the
-    /// linear coefficients are calculated for each observation individually.
-    /// Hence, they also become a matrix where the columns correspond to the
-    /// linear coefficients of the observation in the same column.
+    /// columns correspond to the individual observations.
+    ///
+    /// For a set of observations `$\vec{y}_1,\dots,\vec{y}_S$` (column vectors) we
+    /// now have to pass a _matrix_ `$Y$` of observations, rather than a single
+    /// vector to the builder. As explained above, the resulting matrix would look
+    /// like this.
+    ///
+    /// ```math
+    /// \boldsymbol{Y}=\left(\begin{matrix}
+    ///  \vert &  & \vert \\
+    ///  \vec{y}_1 &  \dots & \vec{y}_S \\
+    ///  \vert &  & \vert \\
+    /// \end{matrix}\right)
+    /// ```
+    ///
+    /// The nonlinear parameters will be optimized across all the observations
+    /// globally, but the best linear coefficients are calculated for each observation
+    /// individually. Hence, the latter also become a matrix `$C$`, where the columns
+    /// correspond to the linear coefficients of the observation in the same column.
+    ///
+    /// ```math
+    /// \boldsymbol{C}=\left(\begin{matrix}
+    ///  \vert &  & \vert \\
+    ///  \vec{c}_1 &  \dots & \vec{c}_S \\
+    ///  \vert &  & \vert \\
+    /// \end{matrix}\right)
+    /// ```
+    ///
+    /// The (column) vector of linear coefficients `$\vec{c}_j$` is for the observation
+    /// `$\vec{y}_j$` in the same column.
     pub fn mrhs(model: Model) -> Self {
         Self {
             Y: None,
@@ -205,16 +230,12 @@ where
 {
     /// Create a new builder based on the given model
     /// for a problem with **multiple right hand sides** and perform a global
-    /// fit. This tries to increase the speed by using multithreaded calculations.
+    /// fit, see also [`LevMarProblemBuilder::mrhs`](crate::solvers::levmar::LevMarProblemBuilder::mrhs)
+    /// for an explanation how to order the observations into a matrix.
+    ///
+    /// This approach tries to increase the speed by using multithreaded calculations.
     /// **Attention**: using multithreading might actually be slower,
     /// so always try it for your usecase and measure!
-    ///
-    /// That means the observations are expected to be a matrix, where the
-    /// columns correspond to the individual observations. The nonlinear
-    /// parameters will be optimized across all the observations, but the
-    /// linear coefficients are calculated for each observation individually.
-    /// Hence, they also become a matrix where the columns correspond to the
-    /// linear coefficients of the observation in the same column.
     pub fn mrhs_parallel(model: Model) -> Self {
         Self {
             Y: None,