Merge pull request #32 from dcwuser/dcwuser/dataAdaptation

Dcwuser/data adaptation

Author: dcwuser

Examples/project.fragment.lock.json

@@ -5,13 +5,13 @@
       "type": "project",
       "framework": ".NETFramework,Version=v4.0",
       "compile": {
-        "bin/Release/Meta.Numerics.dll": {}
+        "bin/Debug/Meta.Numerics.dll": {}
       },
       "runtime": {
-        "bin/Release/Meta.Numerics.dll": {}
+        "bin/Debug/Meta.Numerics.dll": {}
       },
       "contentFiles": {
-        "bin/Release/Meta.Numerics.pdb": {
+        "bin/Debug/Meta.Numerics.pdb": {
           "buildAction": "None",
           "codeLanguage": "any",
           "copyToOutput": true

Numerics/Analysis/FunctionMath_Odes.cs

@@ -117,7 +117,7 @@ public static OdeResult IntegrateOde (Func<double, double, double> rhs, double x
         /// the common case where the independent variable is time, but the algorithm works whether the independent variable
         /// resents 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, MultiOdeSettings)"/>
+        /// <see cref="MultiFunctionMath.IntegrateOde(Func{double, IReadOnlyList{double}, IReadOnlyList{double}}, double, IReadOnlyList{double}, double, MultiOdeSettings)"/>
         /// 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

Numerics/Analysis/MultiFunctionMath_Extrema_ModelTrust.cs

@@ -744,19 +744,4 @@ public double FindMinimumSeperation () {
 
     }
 
-    // IList defines CopyTo. IReadOnlyList doesn't. So in order to switch from IList to IReadOnlyList,
-    // we define an extension method to implement it.
-
-    internal static class CopyHelper {
-
-        public static void CopyTo<T> (this IReadOnlyList<T> source, T[] target, int startIndex) {
-            Debug.Assert(source != null);
-            Debug.Assert(target != null);
-            Debug.Assert(startIndex >= 0);
-            for (int i = 0; i < source.Count; i++) {
-                target[startIndex + i] = source[i];
-            }
-        }
-
-    }
 }

Numerics/Analysis/MultiFunctionMath_Ode.cs

@@ -21,7 +21,7 @@ public static partial class MultiFunctionMath {
         /// <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, MultiOdeSettings)"/>.</para>
+        /// <see cref="IntegrateConservativeOde(Func{double, IReadOnlyList{double}, IReadOnlyList{double}}, double, IReadOnlyList{double}, IReadOnlyList{double}, double, MultiOdeSettings)"/>.</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>
@@ -32,7 +32,7 @@ public static partial class MultiFunctionMath {
         /// 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) {
+        public static MultiOdeResult IntegrateConservativeOde (Func<double, IReadOnlyList<double>, IReadOnlyList<double>> rhs, double x0, IReadOnlyList<double> y0, IReadOnlyList<double> yPrime0, double x1) {
             return (IntegrateConservativeOde(rhs, x0, y0, yPrime0, x1, new MultiOdeSettings()));
         }
 
@@ -55,7 +55,7 @@ public static MultiOdeResult IntegrateConservativeOde (Func<double, IList<double
         /// <remarks>
         /// <para>For information on conservative ODEs, see <see cref="FunctionMath.IntegrateConservativeOde(Func{double, double, double}, double, double, double, double, OdeSettings)"/>.</para>
         /// </remarks>
-        public static MultiOdeResult IntegrateConservativeOde (Func<double, IList<double>, IList<double>> rhs, double x0, IList<double> y0, IList<double> yPrime0, double x1, MultiOdeSettings settings) {
+        public static MultiOdeResult IntegrateConservativeOde (Func<double, IReadOnlyList<double>, IReadOnlyList<double>> rhs, double x0, IReadOnlyList<double> y0, IReadOnlyList<double> yPrime0, double x1, MultiOdeSettings settings) {
 
             if (rhs == null) throw new ArgumentNullException(nameof(rhs));
             if (y0 == null) throw new ArgumentNullException(nameof(y0));
@@ -86,12 +86,12 @@ public static MultiOdeResult IntegrateConservativeOde (Func<double, IList<double
         /// the maximum allowed number of <paramref name="rhs"/> evaluations.</exception>
         /// <remarks>
         /// <para>For information about integrating coupled ODEs, see
-        /// <see cref="IntegrateOde(Func{double, IList{double}, IList{double}}, double, IList{double}, double, MultiOdeSettings)"/>.</para>
+        /// <see cref="IntegrateOde(Func{double, IReadOnlyList{double}, IReadOnlyList{double}}, double, IReadOnlyList{double}, double, MultiOdeSettings)"/>.</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) {
+        public static MultiOdeResult IntegrateOde (Func<double, IReadOnlyList<double>, IReadOnlyList<double>> rhs, double x0, IReadOnlyList<double> y0, double x1) {
             return (IntegrateOde(rhs, x0, y0, x1, new MultiOdeSettings()));
         }
 
@@ -115,7 +115,7 @@ public static MultiOdeResult IntegrateOde (Func<double, IList<double>, IList<dou
         /// 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, MultiOdeSettings settings) {
+        public static MultiOdeResult IntegrateOde (Func<double, IReadOnlyList<double>, IReadOnlyList<double>> rhs, double x0, IReadOnlyList<double> y0, double x1, MultiOdeSettings settings) {
 
             if (rhs == null) throw new ArgumentNullException(nameof(rhs));
             if (y0 == null) throw new ArgumentNullException(nameof(y0));
@@ -134,22 +134,26 @@ public static MultiOdeResult IntegrateOde (Func<double, IList<double>, IList<dou
 
     internal abstract class MultiOdeEngine : OdeEngine {
 
-        public MultiOdeEngine (Func<double, IList<double>, IList<double>> rhs, double x, MultiOdeSettings settings) : base(x) {
+        public MultiOdeEngine (Func<double, IReadOnlyList<double>, IReadOnlyList<double>> rhs, double x, MultiOdeSettings settings) : base(x) {
             Debug.Assert(rhs != null);
             Debug.Assert(settings != null);
             this.rhs = rhs;
             this.settings = settings;
         }
 
-        private readonly Func<double, IList<double>, IList<double>> rhs;
+        private readonly Func<double, IReadOnlyList<double>, IReadOnlyList<double>> rhs;
 
         protected readonly MultiOdeSettings settings;
 
-        public IList<double> Evaluate (double x, IList<double> y) {
+        public IReadOnlyList<double> Evaluate (double x, IReadOnlyList<double> y) {
             if (count >= settings.EvaluationBudget) throw new NonconvergenceException();
             count++;
-            ReadOnlyCollection<double> yWrapper = new ReadOnlyCollection<double>(y);
-            IList<double> z = rhs(x, yWrapper);
+            // ReadOnlyCollection doesn't have a constructor that accepts IReadOnlyList.
+            // But being an IReadOnlyList doesn't protect us from be cast back to a mutable
+            // type, so for the moment this is actually not safe from poorly behaved
+            // rhs's. 
+            //ReadOnlyCollection<double> yWrapper = new ReadOnlyCollection<double>(y);
+            IReadOnlyList<double> z = rhs(x, y);
             if (z == null) throw new InvalidOperationException();
             return (z);
         }
@@ -173,7 +177,7 @@ protected override void AcceptStep () {
 
     internal class MultiBulrischStoerEngine : MultiOdeEngine, IBulrischStoerEngine {
 
-        public MultiBulrischStoerEngine (Func<double, IList<double>, IList<double>> rhs, double x, IList<double> y, MultiOdeSettings settings) : base(rhs, x, settings) {
+        public MultiBulrischStoerEngine (Func<double, IReadOnlyList<double>, IReadOnlyList<double>> rhs, double x, IReadOnlyList<double> y, MultiOdeSettings settings) : base(rhs, x, settings) {
 
             Debug.Assert(rhs != null);
             Debug.Assert(y != null);
@@ -218,7 +222,7 @@ private double[] TrialStep (int n) {
             double[] nY1 = new double[Y.Length];
             for (int i = 0; i < nY1.Length; i++) { nY0[i] = Y[i]; nY1[i] = Y[i] + h * YPrime[i]; }
 
-            IList<double> F;
+            IReadOnlyList<double> F;
             for (int k = 1; k < n; k++) {
                 F = Evaluate(X + k * h, nY1);
                 for (int i = 0; i < nY1.Length; i++) { double t = nY1[i]; nY1[i] = nY0[i] + 2.0 * h * F[i]; nY0[i] = t; }
@@ -279,7 +283,7 @@ public override MultiOdeResult GetResult () {
 
     internal class MultiStoermerEngine : MultiOdeEngine, IBulrischStoerEngine {
 
-        public MultiStoermerEngine (Func<double, IList<double>, IList<double>> rhs, double x, IList<double> y, IList<double> yPrime, MultiOdeSettings settings) : base(rhs, x, settings) {
+        public MultiStoermerEngine (Func<double, IReadOnlyList<double>, IReadOnlyList<double>> rhs, double x, IReadOnlyList<double> y, IReadOnlyList<double> yPrime, MultiOdeSettings settings) : base(rhs, x, settings) {
 
             Debug.Assert(rhs != null);
             Debug.Assert(y != null);
@@ -401,7 +405,7 @@ private void TrialStep (int n, out double[] Y1, out double[] YP1) {
 
             int d = Y.Length;
 
-            IList<double> F;
+            IReadOnlyList<double> F;
             Y1 = new double[d];
             double[] D1 = new double[d];
 

Numerics/Core/ComplexMath.cs

@@ -7,7 +7,7 @@
 namespace Meta.Numerics {
 
     /// <summary>
-    /// Provides simple functions of complex arguments. 
+    /// Contains methods that compute basic functions of complex arguments. 
     /// </summary>
     public static class ComplexMath {
 

Numerics/Core/Global.cs

@@ -1,4 +1,6 @@
 using System;
+using System.Diagnostics;
+using System.Collections.Generic;
 
 namespace Meta.Numerics {
 
@@ -23,6 +25,7 @@ public static void Swap<T> (ref T a, ref T b) {
         }
 
         // pre-calculate some often-used factors
+        // these are actually useless; the compiler pre-calculates them for us
 
         public const double TwoPI = 2.0 * Math.PI;
 
@@ -47,6 +50,17 @@ public static void Swap<T> (ref T a, ref T b) {
 
         public static readonly double LogTwo = Math.Log(2.0);
 
+        // IList defines CopyTo. IReadOnlyList doesn't. So in order to switch from IList to IReadOnlyList,
+        // we define an extension method to implement it.
+        public static void CopyTo<T> (this IReadOnlyList<T> source, T[] target, int startIndex) {
+            Debug.Assert(source != null);
+            Debug.Assert(target != null);
+            Debug.Assert(startIndex >= 0);
+            for (int i = 0; i < source.Count; i++) {
+                target[startIndex + i] = source[i];
+            }
+        }
+
     }
 
 }

Numerics/Core/UncertainMath.cs

@@ -4,7 +4,7 @@ namespace Meta.Numerics {
 
 
     /// <summary>
-    /// Contains methods for computing basic mathematical functions of uncertain values.
+    /// Contains methods that compute basic functions of uncertain values.
     /// </summary>
     /// <remarks><para>The methods in this static class perform the same basic mathematical operations as the methods of
     /// the <see cref="System.Math"/> class, accounting for the uncertainty in the inputs to produce a corresponding

Numerics/Data/ComputedList.cs

@@ -1,23 +1,21 @@
 using System;
 using System.Collections;
 using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
+using System.Diagnostics;
 
 namespace Meta.Numerics.Data
 {
 
     internal class ComputedList<T> : NamedList, IEnumerable, IEnumerable<T>, IReadOnlyList<T>
     {
         internal ComputedList (FrameView frame, string name, Func<FrameRow,T> function) : base(name) {
+            Debug.Assert(frame != null);
+            Debug.Assert(function != null);
             this.frame = frame;
-            this.name = name;
             this.function = function;
         }
 
         private readonly FrameView frame;
-        private readonly string name;
         private readonly Func<FrameRow, T> function;
 
         public T this[int index]

Numerics/Data/FrameColumn.cs

@@ -8,8 +8,12 @@ namespace Meta.Numerics.Data
 {
 
     /// <summary>
-    /// One column of a data frame.
+    /// Represents one column of a data frame.
     /// </summary>
+    /// <remarks>
+    /// <para>To obtained strongly typed values of the data in the column,
+    /// use the <see cref="As{T}" autoUpgrade="true"/> method.</para>
+    /// </remarks>
     public sealed class FrameColumn : IEnumerable {
 
         internal FrameColumn(FrameView frame, int c) {
@@ -61,14 +65,17 @@ public object this[int r] {
         }
 
         /// <summary>
-        /// Returns the column as a typed list.
+        /// Exposes the column as a list of uniform type.
         /// </summary>
         /// <typeparam name="T">The type of the list.</typeparam>
         /// <returns>An object that allows the column to be accessed as a typed list.</returns>
         /// <remarks>
         /// <para>This operation is both time and memory efficient. It does not convert every element
         /// into a new list, but instead simply instantiates a converter that implements the list
         /// operations directly against the already existing storage.</para>
+        /// <para>The type specified by <typeparamref name="T"/> need not be the same as the
+        /// underlying stored type of the column. As long as the exposed values can be cast or
+        /// converted to the specified type, the typed list returned will work as required.</para>
         /// </remarks>
         public IReadOnlyList<T> As<T> () {
             // If the requested column is of the requested type, expose it directly.

Numerics/Data/FrameColumnCollection.cs

@@ -7,7 +7,7 @@ namespace Meta.Numerics.Data
 {
 
     /// <summary>
-    /// A collection of data frame columns.
+    /// Represents a collection of columns of a data frame.
     /// </summary>
     public sealed class FrameColumnCollection : IReadOnlyCollection<FrameColumn>, IReadOnlyList<FrameColumn>, IEnumerable<FrameColumn> /*, IReadOnlyDictionary<string,FrameColumn> */
     {