Documentation and code clean-up. We are very close to the next dot-release.

Author: dcwuser

Numerics/Analysis/FunctionMath_Odes.cs

@@ -23,13 +23,11 @@ public static partial class FunctionMath {
         /// <exception cref="ArgumentNullException">The <paramref name="rhs"/> is null.</exception>
         /// <exception cref="NonconvergenceException">The ODE could not be integrated to the required precision before exhausting the maximum allowed number of <paramref name="rhs"/> evaluations.</exception>
         /// <remarks>
-        /// <para>A conservative ordinary differential equation has the form</para>
-        /// <img src="../images/ConservativeODE.png" />
-        /// <para>where the right-hand-side depends only on x and y, not on the derivative y'. ODEs of this form are called conservative because
-        /// they exhibit conserved quantities: combinations of y and y' that maintain the same value as the system evolves. Many forms of
-        /// Newtonian equations of motion, for example, are conservative ODEs, with conserved quantities such as energy, momentum, and
-        /// angular momentum. Our specialized conservative ODE integrator is not only more efficient for conservative ODEs, but does a
-        /// better job of maintaining the conserved quantities.</para>
+        /// <para>For information on integrating conservative ODEs, see
+        /// <see cref="IntegrateConservativeOde(Func{double, double, double}, double, double, double, double, OdeEvaluationSettings)"/>.</para>
+        /// <para>This overload uses default values for precision and evaluation budget. It targets a relative precision of
+        /// about 10<sup>-12</sup> and an absolute precision of about 10<sup>-24</sup> with an evaluation budget of about 8000.
+        /// </para>
         /// </remarks>
         public static OdeResult IntegrateConservativeOde (Func<double, double, double> rhs, double x0, double y0, double yPrime0, double x1) {
             return (IntegrateConservativeOde(rhs, x0, y0, yPrime0, x1, new OdeEvaluationSettings()));
@@ -83,22 +81,9 @@ public static OdeResult IntegrateConservativeOde (Func<double, double, double> r
         /// <exception cref="ArgumentNullException">The <paramref name="rhs"/> is null.</exception>
         /// <exception cref="NonconvergenceException">The ODE could not be integrated to the required precision before exhausting the maximum allowed number of <paramref name="rhs"/> evaluations.</exception>
         /// <remarks>
-        /// <para>An ordinary differential equation (ODE) has the form:</para>
-        /// <img src="../images/ODE.png" />
-        /// <para>The function specifying the derivative as a function of x and y is called the right-hand-side (RHS).</para>
-        /// <para>The integration of an ODE consists of specifying the value of y at some initial x and computing its value
-        /// at a different x in accordance with the differential equation. The terms "initial" and "final" are derived from
-        /// the common case where the indepdent variable is time, but the technique applies whether the independent variable
-        /// repsents a time, a location, or a completely non-physical quantity, as long as the problem has form of an ODE.</para>
-        /// <para>ODEs involving multi-dimensional, coupled dependent variables can be integrated using the
-        /// <see cref="MultiFunctionMath.IntegrateOde(Func{double, IList{double}, IList{double}}, double, IList{double}, double)"/>
-        /// method. Higher order ODEs can be integrated by representing them as coupled ODEs in which the zeroth component
-        /// is the desired y, the first component is y', the second component is y'', etc. So-called conservative second order
-        /// ODEs should be integrated using the <see cref="FunctionMath.IntegrateConservativeOde(Func{double, double, double}, double, double, double, double)"/>
-        /// method. If your ODE's RHS depends only on x, the problem reduces to a simple integral, which can be solved more rapidly and
-        /// accurately using the <see cref="FunctionMath.Integrate(Func{double, double}, Interval)"/> method. Analytic techniques can
-        /// also be used to reduce several other kinds of ODEs to simple integrals or lower-order ODEs.</para>
-        /// <para>This overload using default values for precision and evaluation budget. It targets a relative precision of
+        /// <para>For information on integrating ODEs, see
+        /// <see cref="IntegrateOde(Func{double, double, double}, double, double, double, OdeEvaluationSettings)"/>.</para>
+        /// <para>This overload uses default values for precision and evaluation budget. It targets a relative precision of
         /// about 10<sup>-12</sup> and an absolute precision of about 10<sup>-24</sup> with an evaluation budget of about 8000.
         /// </para>
         /// </remarks>
@@ -126,18 +111,18 @@ public static OdeResult IntegrateOde (Func<double, double, double> rhs, double x
         /// <para>The integration of an ODE consists of specifying the value of y at some initial x and computing its value
         /// at a different x in accordance with the differential equation. The terms "initial" and "final" are derived from
         /// the common case where the indepdent variable is time, but the technique applies whether the independent variable
-        /// repsents a time, a location, or a completely non-physical quantity, as long as the problem has form of an ODE.</para>
-        /// <para>ODEs involving multi-dimensional, coupled dependent variables can be integrated using the
-        /// <see cref="MultiFunctionMath.IntegrateOde(Func{double, IList{double}, IList{double}}, double, IList{double}, double)"/>
+        /// repsents a time, a location, or a completely non-physical quantity, as long as the problem has the form of an ODE.</para>
+        /// <para>ODEs involving multiple, coupled dependent variables can be integrated using the
+        /// <see cref="MultiFunctionMath.IntegrateOde(Func{double, IList{double}, IList{double}}, double, IList{double}, double, MultiOdeEvaluationSettings)"/>
         /// method. Higher order ODEs can be integrated by representing them as coupled ODEs in which the zeroth component
         /// is the desired y, the first component is y', the second component is y'', etc. So-called conservative second order
-        /// ODEs should be integrated using the <see cref="FunctionMath.IntegrateConservativeOde(Func{double, double, double}, double, double, double, double)"/>
+        /// ODEs should be integrated using the
+        /// <see cref="FunctionMath.IntegrateConservativeOde(Func{double, double, double}, double, double, double, double, OdeEvaluationSettings)"/>
         /// method. If your ODE's RHS depends only on x, the problem reduces to a simple integral, which can be solved more rapidly and
-        /// accurately using the <see cref="FunctionMath.Integrate(Func{double, double}, Interval)"/> method. Analytic techniques can
-        /// also be used to reduce several other kinds of ODEs to simple integrals or lower-order ODEs.</para>
+        /// accurately using the <see cref="FunctionMath.Integrate(Func{double, double}, Interval, EvaluationSettings)"/> method.
+        /// Analytic techniques can also be used to reduce several other kinds of ODEs to simple integrals or lower-order ODEs.</para>
         /// </remarks>
         /// <seealso href="https://en.wikipedia.org/wiki/Ordinary_differential_equation"/>
-
         public static OdeResult IntegrateOde (Func<double, double, double> rhs, double x0, double y0, double x1, OdeEvaluationSettings settings) {
 
             if (rhs == null) throw new ArgumentNullException(nameof(rhs));

Numerics/Analysis/MultiFunctionMath_Ode.cs

@@ -19,6 +19,19 @@ public static partial class MultiFunctionMath {
         /// <param name="yPrime0">The intial values of the functions' derivatives.</param>
         /// <param name="x1">The final value of the independent variable.</param>
         /// <returns>The solution, including the final value of the functions and their derivatives.</returns>
+        /// <remarks>
+        /// <para>For information on integrating coupled, conservative ODEs, see
+        /// <see cref="IntegrateConservativeOde(Func{double, IList{double}, IList{double}}, double, IList{double}, IList{double}, double, MultiOdeEvaluationSettings)"/>.</para>
+        /// <para>This overload uses default settings for precision and evaluation budget. It targets a relative precision of
+        /// about 10<sup>-12</sup> and an absolute precision of about 10<sup>-24</sup> with an evaluation budget of about 8000.
+        /// </para>
+        /// </remarks>
+        /// <exception cref="ArgumentNullException"><paramref name="rhs"/>, <paramref name="y0"/>, or <paramref name="yPrime0"/>
+        /// is <see langword="null"/>.</exception>
+        /// <exception cref="DimensionMismatchException"><paramref name="y0"/> and <paramref name="yPrime0"/> do not have the same
+        /// dimension.</exception>
+        /// <exception cref="NonconvergenceException">The ODE could not be integrated to the required precision before exhausting
+        /// the maximum allowed number of <paramref name="rhs"/>evaluations.</exception>
         public static MultiOdeResult IntegrateConservativeOde (Func<double, IList<double>, IList<double>> rhs, double x0, IList<double> y0, IList<double> yPrime0, double x1) {
             return (IntegrateConservativeOde(rhs, x0, y0, yPrime0, x1, new MultiOdeEvaluationSettings()));
         }
@@ -33,6 +46,15 @@ public static MultiOdeResult IntegrateConservativeOde (Func<double, IList<double
         /// <param name="x1">The final value of the independent variable.</param>
         /// <param name="settings">The settings to use when solving the problem.</param>
         /// <returns>The solution, including the final value of the functions and their derivatives.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="rhs"/>, <paramref name="y0"/>, <paramref name="yPrime0"/>,
+        /// or <paramref name="settings"/> is <see langword="null"/>.</exception>
+        /// <exception cref="DimensionMismatchException"><paramref name="y0"/> and <paramref name="yPrime0"/> do not have the same
+        /// dimension.</exception>
+        /// <exception cref="NonconvergenceException">The ODE could not be integrated to the required precision before exhausting
+        /// the maximum allowed number of <paramref name="rhs"/>evaluations.</exception>
+        /// <remarks>
+        /// <para>For information on conservative ODEs, see <see cref="FunctionMath.IntegrateConservativeOde(Func{double, double, double}, double, double, double, double, OdeEvaluationSettings)"/>.</para>
+        /// </remarks>
         public static MultiOdeResult IntegrateConservativeOde (Func<double, IList<double>, IList<double>> rhs, double x0, IList<double> y0, IList<double> yPrime0, double x1, MultiOdeEvaluationSettings settings) {
 
             if (rhs == null) throw new ArgumentNullException(nameof(rhs));
@@ -63,8 +85,11 @@ public static MultiOdeResult IntegrateConservativeOde (Func<double, IList<double
         /// <exception cref="NonconvergenceException">The ODE could not be integrated to the required precision before exhausting
         /// the maximum allowed number of <paramref name="rhs"/> evaluations.</exception>
         /// <remarks>
-        /// <para>The default settings for ODE integration are a relative precision of about 10<sup>-12</sup>, an absolute precision
-        /// of about 10<sup>-24</sup>, and a maximum of about 8000 right-hand-side evaluations.</para>
+        /// <para>For infomration about integrating coupled ODEs, see
+        /// <see cref="IntegrateOde(Func{double, IList{double}, IList{double}}, double, IList{double}, double, MultiOdeEvaluationSettings)"/>.</para>
+        /// <para>This overload uses default settings for precision and evaluation budget. It targets a relative precision of
+        /// about 10<sup>-12</sup> and an absolute precision of about 10<sup>-24</sup> with an evaluation budget of about 8000.
+        /// </para>
         /// </remarks>
         public static MultiOdeResult IntegrateOde (Func<double, IList<double>, IList<double>> rhs, double x0, IList<double> y0, double x1) {
             return (IntegrateOde(rhs, x0, y0, x1, new MultiOdeEvaluationSettings()));
@@ -86,8 +111,8 @@ public static MultiOdeResult IntegrateOde (Func<double, IList<double>, IList<dou
         /// the maximum allowed number of <paramref name="rhs"/>evaluations.</exception>
         /// <remarks>
         /// <para>This method integrates a set of coupled ordinary differential equations. The dependent variable y is a vector
-        /// with an arbitrary number of components, and the right-hand-side is a vector-valued function that gives the derivative
-        /// of each component, and may depend on the values of all the components as well as the independent variable.
+        /// with any number of components, and the right-hand-side is a vector-valued function that gives the derivative
+        /// of each component. Each component's derivative may depend itself and any other components, as well as on the independent variable.
         /// The independent variable x still takes only a single real value.</para>
         /// </remarks>
         public static MultiOdeResult IntegrateOde (Func<double, IList<double>, IList<double>> rhs, double x0, IList<double> y0, double x1, MultiOdeEvaluationSettings settings) {

Numerics/Analysis/MultiOdeEvaluationSettings.cs

@@ -4,12 +4,12 @@
 namespace Meta.Numerics.Analysis {
 
     /// <summary>
-    /// Contains settings used to solve a multi-dimensional ordinary differential equation.
+    /// Contains settings used to solve a set of coupled ordinary differential equations.
     /// </summary>
     public class MultiOdeEvaluationSettings : EvaluationSettings {
 
         /// <summary>
-        /// Initializes a new instance of evaluation settings for multiple ODEs.
+        /// Initializes a new instance of evaluation settings for coupled ODEs.
         /// </summary>
         public MultiOdeEvaluationSettings () : base(null) { }
 
@@ -18,11 +18,9 @@ public MultiOdeEvaluationSettings () : base(null) { }
         /// Gets or sets the handler that is called to report on progress toward the solution.
         /// </summary>
         /// <remarks>
-        /// <para>
-        /// For each successful step, this delegate is called to report the solution at the
-        /// new abcissa. If you have the listener record these results, we can interpolate
-        /// in order to approximate the solution at intermediate points.
-        /// </para>
+        /// <para>As the ODE is integrated, the specified handler is called for each integration
+        /// step. This allows the handler to monitor progress toward the solution and to
+        /// obtain intermediate values via interpolation.</para>
         /// </remarks>
         public Action<MultiOdeResult> Listener { get; set; }