diff --git a/Examples/Program.cs b/Examples/Program.cs index be3c6ba..4f5ad9c 100644 --- a/Examples/Program.cs +++ b/Examples/Program.cs @@ -20,59 +20,8 @@ private static MethodInfo[] GetExampleMethods () { return(methods); } - private static double EllipticPi(double n, double k) { - - if (n > 1.0) throw new ArgumentOutOfRangeException(nameof(n)); - if (k < 1.0 || k > 1.0) throw new ArgumentOutOfRangeException(nameof(k)); - - if (n == 1.0 || k == 1.0) return Double.PositiveInfinity; - - // DLMF 19.8 describes how to compute \Pi(n, k) via AGM plus some auxiluary - // calculations. Here a and g, along with p, converge to AGM(1,k') in the - // usual way; the sum of auxiluary variables q computed along the way gives \Pi(n, k). - // This method appears to have been derived by Carlson in "Three Improvements in - // Reduction and Computation of Elliptic Integrals", Journal of Research of the - // National Institute of Standards and Technology, 2002 Sep-Oct 107(5): 413-418 - // (https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4861378/) - // as a specialization of his method to calcuate R_J. - - double a = 1.0; - double g = Math.Sqrt((1.0 - k) * (1.0 + k)); - double n1 = 1.0 - n; - double pSquared = n1; - double p = Math.Sqrt(pSquared); - double q = 1.0; - double s = q; - - for (int i = 1; i < 100; i++) { - - double s_old = s; - double ag = a * g; - double e = (pSquared - ag) / (pSquared + ag); - q = 0.5 * q * e; - s += q; - - double p_old = p; - p = (pSquared + ag ) / (2.0 * p); - - if (p == p_old && s == s_old) { - return Math.PI / 4.0 / p * (2.0 + n / n1 * s); - } - - pSquared = p * p; - a = 0.5 * (a + g); - g = Math.Sqrt(ag); - - } - - throw new Exception(); - - } - - static void Main(string[] args) { - double e3 = EllipticPi(-0.25,0.99); MethodInfo[] methods = GetExampleMethods(); Dictionary index = new Dictionary(); @@ -81,6 +30,7 @@ static void Main(string[] args) } if (args.Length == 0) { + Console.WriteLine("The following examples are defined:"); foreach(string key in index.Keys) { Console.WriteLine(key); } diff --git a/Numerics/Core/Interval.cs b/Numerics/Core/Interval.cs index 5c11232..d14472c 100644 --- a/Numerics/Core/Interval.cs +++ b/Numerics/Core/Interval.cs @@ -39,6 +39,46 @@ public double RightEndpoint { } } + /// + /// Determines whether a given point is contained in the closed interval. + /// + /// The point. + /// if is contained in the closed interval [a,b], + /// otherwise . + public bool Contains (double x) { + return (x >= a) && (x <= b); + } + + /// + /// Determines whether a given point is contained in the closed or open interval. + /// + /// The point. + /// Specifier of whether the interval should be considered closed or open. + /// if is contained in the interval as specified, + /// otherwise + public bool Contains (double x, IntervalType type) { + if (type == IntervalType.Closed) { + return (x >= a) && (x <= b); + } else { + return (x > a) && (x < b); + } + } + + /// + /// Determines whether a given point is contained in the interval, with the left and right endpoints + /// separately specififed as closed or open. + /// + /// The point. + /// Specifier of whether the interval should be considered as including its left endpoint. + /// Specifier of whether the interval should be considered as including its right endpoint. + /// if is contained in the interval as specified, + /// otherwise + public bool Contains (double x, IntervalType leftEndpointType, IntervalType rightEndpointType) { + bool leftSatisfied = leftEndpointType == IntervalType.Closed ? x >= a : x > a; + bool rightSatisfied = rightEndpointType == IntervalType.Closed ? x <= b : x < b; + return leftSatisfied && rightSatisfied; + } + /// /// Determines whether the argument lies in the open interval. /// @@ -70,7 +110,7 @@ public double Width { /// public double Midpoint { get { - return ((a + b) / 2.0); + return 0.5 * (a + b); } } @@ -214,4 +254,20 @@ internal IEnumerable GetContainedIntegers () { } + /// + /// Indicates whether an interval should be considered closed or open. + /// + public enum IntervalType { + + /// + /// Endpoints should be considered within the interval. + /// + Closed, + + /// + /// Endpoints should be considered outside the interval. + /// + Open + } + } diff --git a/Numerics/Core/MoreMath.cs b/Numerics/Core/MoreMath.cs index bc425c2..10c6f2c 100644 --- a/Numerics/Core/MoreMath.cs +++ b/Numerics/Core/MoreMath.cs @@ -140,7 +140,7 @@ public static double Hypot (double x, double y) { // Beebe, "Computation of expm1(x) = exp(x) - 1", 2002 (http://www.math.utah.edu/~beebe/reports/expm1.pdf) // makes some good points about e^x - 1. // * He shows that the point e^x = 1/2 and e^x = 3/2 are the relevent limits where Math.Exp(x) - 1.0 - // looses a one bit of accuracy. + // looses one bit of accuracy. // * He measures that the maximum number of terms in the Taylor series required in this region is 17. // * He measures that the RMS error of the Taylor series in this region is ~0.8 bits and it's maximum // relative error is ~ 2.7 bits. @@ -177,9 +177,9 @@ private static double ReducedExpm1Series (double x) { /// The value of ex-1. /// /// If x is close to 0, then ex is close to 1, and computing ex-1 by - /// Math.Exp(x) - 1.0 will be subject to severe loss of significance due to cancelation. - /// This method maintains full precision for all values of x by switching to a series expansion for values of - /// x near zero. + /// Math.Exp(x) - 1.0 will be subject to severe loss of significance due to cancelation. + /// This method maintains full precision for all values of x by switching to a series expansion + /// when x is near zero. /// public static double ExpMinusOne (double x) { if ((expm1SeriesLowerLimit < x) && (x < expm1SeriesUpperLimit)) { diff --git a/Numerics/Extended/AdvancedDoubleDoubleMath.cs b/Numerics/Extended/AdvancedDoubleDoubleMath.cs index bcb4e04..4a3de7a 100644 --- a/Numerics/Extended/AdvancedDoubleDoubleMath.cs +++ b/Numerics/Extended/AdvancedDoubleDoubleMath.cs @@ -10,20 +10,21 @@ namespace Meta.Numerics.Extended { /// -based functions, you must ensure that the arguments you provide are also more /// accurate than . Because decimal numbers expressed in code are automatically /// intrepreted by the compiler as , it's easier than you might think do this wrong. - /// For example, invoking Gamma(0.2) will not compute Γ(1/5) to + /// For example, invoking Gamma(0.2) will not compute Γ(1/5) to /// precision. The reason is that 0.2 is intrepreted by the compiler as a , and there /// is no value that is precisely 1/5. Instead, 0.2 parsed as a , /// is stored as 3602879701896397 X 2-54 = 0.20000000000000001110223024625157... This equals - /// 0.2 within the 16 decimal-place accuracy of , but clearly not within the 32 + /// 0.2 to within the 16 decimal-place accuracy of , but clearly not to within the 32 /// decimal-place accuracy of . /// There are a number of ways to ensure that you are providing an argument to accuracy. - /// One possibility is to use the text parser, for example by invoking new DoubleDouble("0.2"). - /// Another is to produce tha argument as the result of calculation from exact integers, e.g. DoubleDouble.One / 5 or - /// ((DoubleDouble) 1) / 5. + /// One possibility is to use the text parser, for example by invoking new DoubleDouble("0.2"). + /// Another is to produce tha argument as the result of calculation from exact integers, (DoubleDouble) 1 / 5, which works + /// because 1 and 5 (like all integers within range) are represented exactly and the because of the cast the division operation + /// is . /// (The stored value in these cases is again not precisely 1/5, but is equal within the accuracy of .) /// Finally, if you know that the argument you want is precisely represetable as a , you can safely /// use the compiler's parser. For example, invoking Gamma(0.25) does compute Γ(1/4) to - /// to accuracy, because 1/4 is exactly representable via . + /// precision, because 1/4 is exactly representable by . /// public static partial class AdvancedDoubleDoubleMath { diff --git a/Numerics/Extended/AdvancedDoubleDoubleMath_Gamma.cs b/Numerics/Extended/AdvancedDoubleDoubleMath_Gamma.cs index 01182b1..d0da0b3 100644 --- a/Numerics/Extended/AdvancedDoubleDoubleMath_Gamma.cs +++ b/Numerics/Extended/AdvancedDoubleDoubleMath_Gamma.cs @@ -17,10 +17,12 @@ namespace Meta.Numerics.Extended { public static partial class AdvancedDoubleDoubleMath { /// - /// Computes the logarithm of the Gamma function double double precision. + /// Computes the logarithm of the Gamma function with double double precision. /// /// The argument, which must be non-negative. - /// The value of Gamma(x). + /// The value of ln(Γ(x)). + /// is less than zero. + /// public static DoubleDouble LogGamma (DoubleDouble x) { if (x < DoubleDouble.Zero) { diff --git a/Numerics/Extended/DoubleDouble.cs b/Numerics/Extended/DoubleDouble.cs index 8200e34..831d2f2 100644 --- a/Numerics/Extended/DoubleDouble.cs +++ b/Numerics/Extended/DoubleDouble.cs @@ -9,16 +9,38 @@ namespace Meta.Numerics.Extended { /// Represents a floating point number with quadruple precision. /// /// - /// The double double format uses two values to effectively - /// double the precision with which a number can be stored and manipulated as compared to - /// to the structure, i.e. to approximately 31 decimal digits of accuracy. + /// The structure uses two values to achieve + /// twice the precision with which a floating point number can be stored and manipulated as compared to + /// to the structure, approximately 31 decimal digits. /// Of all the extended precision floating point systems, double double is the /// fastest when implemented in software. A typical floating point operation using - /// s is just 3-4 times slower than on s. + /// s is just 3-4 times slower than using s. /// To instantiate a , you can use , /// or , or the constructor /// to parse the text representation of the decimal value you want. If the value you want can be represented as a - /// or or other built in type, you can cast that value to a . + /// or or other built in numeric type, you can cast that value to a . + /// When casting a to a , there is a gotcha that you must be careful + /// to avoid. Suppose you write DoubleDouble x = 0.2 or DoubleDouble x = 1.0 / 5.0. You might think that this produces the + /// representation of 1/5, but you would be wrong. The problem is that the compiler intreprets 0.2 or 1.0/5.0 + /// as s, and 1/5th is not exactly representable as a double, since it is not a rational number with a power-of-two denominator. + /// Double's best attempt at 1/5th is 3602879701896397 X 2^-54 = 0.20000000000000001110223024625157..., which + /// is accurate to 16 decimal digits, but not to 32. Therefore when it is cast to a it is much + /// farther away from 1/5th than can achieve. To obtain 1/5th to the accuracy of a , + /// you must write DoubleDouble x = new DoubleDouble("0.2") or DoubleDouble x = (DoubleDouble) 1 / 5. (The latter works + /// because 1 and 5 are exactly representable and the division is performed as division. All integers in range, + /// indeed all rational numbers with in-range numerators and power-of-two denominators, are exactly representable. So, for example, + /// DoubleDouble x = 0.25 does work as expected, because 1/4 is exactly representable. But to avoid the gotcha + /// it's best to simply train yourself to avoid assigning variables from factional values.) + /// Many of the mathematical functions which are implemented for arguments by static methods of the class + /// are implemented for arguments by static methods of the type itself, + /// for example and . + /// Some of the advanced functions which are implemented for arguments by static methods of the class + /// are implemented for arguments by static methods of the class. + /// + /// You may wonder why is not simply named "Quad". The reason is that "Quad" would propertly refer to an + /// implementation of the IEEE 754 quadruple-precision binary floating + /// point format, which would have not only the extended presion of , but also an extended range (up to 104932). + /// /// public struct DoubleDouble : IEquatable, IComparable { diff --git a/Numerics/Extended/Int128.cs b/Numerics/Extended/Int128.cs index 24d861f..d7ac43a 100644 --- a/Numerics/Extended/Int128.cs +++ b/Numerics/Extended/Int128.cs @@ -6,24 +6,62 @@ namespace Meta.Numerics.Extended { /// - /// Represents a signed integer with a 128 big register width. + /// Represents a signed integer with a 128 bit register width. /// /// - /// To instantiate a 128-bit signed integer, you can use the or - /// methods to parse a decimal string representation. If the value you want is representable by a built-in integer type (e.g. ), you can - /// simply assign a -typed variable from a built-in integer type. - /// If you know that the numbers you need fit in a 128 bit register, arithmetic with is typically faster than with . - /// Addition and subtraction are about four times faster, multiplication is about twice as fast, and division is about equally fast. + /// The built-in integer types short, int, and long are fixed-width registers with the characteristics shown below. is + /// a 128-bit signed integer register with analogous behavior and greatly extended range. + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + ///
TypeC# NameWidthMaxValue
short16b (2B)~32 X 103
int32b (4B)~2.1 X 109
long64b (8B)~9.2 X 1018
128b (16B)~1.7 X 1038
+ /// To instantiate a 128-bit signed integer, you can use the constructor , or the parsing methods + /// or to parse a decimal representation provided as a string. The parsing then occurs at run-time. + /// If the value you want is representable by a built-in integer type (e.g. ), you can + /// simply assign a variable from a built-in integer type. This is particularly useful in source code, since the compiler will parse fixed + /// values of these types at compile-time. + /// If you know that the numbers you need to work with all fit in a 128 bit register, arithmetic with is typically significantly faster than with . + /// Addition and subtraction are about six times faster, multiplication is about twice as fast, and division is about 50% faster. (Meta.Numerics itself uses + /// internally in the implementation of some discrete distributions that require very large integers.) + /// Operations that overflow and underflow behave like they do for the native unsigned integer types, with results equal to the lower 128 bits of the + /// full result, or wrapping around from to . /// Explicit casts between and the built-in integer types behave like unchecked explicit casts between the built-in integer types: /// the low-order bits of the binary representation are preserved and the high-order bits are, if necessary, discarded. This preserves values that are representable /// by the target type, but values that are not representable by the target type may be transformed in ways that, while correct in terms of the bit-level rules, - /// are unexpected in terms of numerical values. This is different than the behavior of , which performs casts as if checked, throwing - /// an exception if the value is not representable in the target type. If you want checked behavior, your code must explicitly check whether the value is in - /// the range of the target before casting. - /// The signed 128-bit integer type does not support bit-wise logical and shift operations, but the unsigned 128-bit integer type + /// are unexpected in terms of numerical values. While this is like the behavior of the built-in integer types, it is different than the behavior of , + /// which performs casts as if checked, throwing an exception if the value is not representable in the target type. If you want checked behavior, your code must explicitly + /// check whether the value is in the range of the target before casting. + /// does not support bit-wise logical and shift operations, but the unsigned 128-bit integer type /// does. If you want to perform bit-wise operations on 128-bit registers, use . /// - [CLSCompliant(false)] public struct Int128 : IEquatable, IComparable { /// @@ -60,11 +98,16 @@ private Int128 (UInt128 u) { /// /// The maximum value of the signed 128-bit integer. /// + /// This has the value 170,141,183,460,469,231,731,687,303,715,884,105,728, or about 1.7 X 1038. public static readonly Int128 MaxValue = new Int128(ulong.MaxValue >> 1, ulong.MaxValue); /// /// The minimum value of the signed 128-bit integer. /// + /// This has the value -170,141,183,460,469,231,731,687,303,715,884,105,729, or about -1.7 X 1038. + /// As is true for the native signed integer registers and any signed integer register that uses two's complement representation + /// of negative numbers, this is one larger in absolute value than , so the corresponding + /// positive value is not within the representable range of the type. public static readonly Int128 MinValue = new Int128(1UL << 63, 0UL); // Equality @@ -249,9 +292,9 @@ public static explicit operator long (Int128 s) { } /// - /// Converts an aribitrary-sized big integer into a 128-bit integer. + /// Converts an arbitrary-size big integer into a 128-bit integer. /// - /// Te big integer to be converted. + /// The big integer to convert. /// The 128-bit integer with the same lower 128 bits. public static explicit operator Int128 (BigInteger b) { UInt128 u = (UInt128) b; @@ -261,7 +304,7 @@ public static explicit operator Int128 (BigInteger b) { /// /// Converts a floating-point value into a 128-bit integer. /// - /// A floating-point number. + /// The floating-point number to convert. /// The lower 128 bits of the integer part of the floating-point number. /// is NaN, or infinite. public static explicit operator Int128 (double x) { @@ -476,7 +519,8 @@ public static Int128 DivRem (Int128 x, Int128 y, out Int128 r) { /// Because is one unit smaller in absolute value than , this /// method throws an when passed . Built in types such as /// have analogous behavior. All other values are supported. - /// was . + /// was , which has no corresponding positive + /// value in the range of the type. public static Int128 Abs (Int128 x) { UInt128 xu = x.u; if (xu.IsNegative) { diff --git a/Numerics/Extended/UInt128.cs b/Numerics/Extended/UInt128.cs index 2641004..d5edcda 100644 --- a/Numerics/Extended/UInt128.cs +++ b/Numerics/Extended/UInt128.cs @@ -12,13 +12,56 @@ namespace Meta.Numerics.Extended /// Represents a 128-bit unsigned integer. /// /// - /// The range of this structure is integer values from 0 to approximately 3.4 X 1038. - /// If you know that the integers you need to work with fit within this range, operations using - /// this structure will be faster than using . - /// (Addition and subtraction are about 4x faster. Multiplication is about 2x faster. - /// Division, unfortunately, isn't any faster.) - /// This structure behaves like a 128-bit fixed-width register analogous to - /// the native 64-bit () and 32-bit () registers. + /// The built-in unsigned integer types ushort, uint, and ulong are fixed-width registers with the characteristics shown below. is + /// a 128-bit unsigned integer register with analogous behavior and greatly extended range. + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + /// + ///
TypeC# NameWidthMaxValue
ushort16b (2B)~65 X 103
uint32b (4B)~4.2 X 109
ulong64b (8B)~18 X 1018
128b (16B)~3.4 X 1038
+ /// To instantiate a 128-bit unsigned integer, you can use the constructor , or the parsing methods + /// or to parse a decimal representation provided as a string. The parsing then occurs at run-time. + /// If the value you want is representable by a built-in unsigned integer type (e.g. ), you can + /// simply assign a variable from a built-in integer type. This is particularly useful in source code, since the compiler will parse fixed + /// values of these types at compile-time. + /// Operations that overflow and underflow behave like they do for the native unsigned integer types, with results modulo 2128, or wrapping around + /// from to . + /// Explicit casts between and the built-in integer types behave like unchecked explicit casts between the built-in integer types: + /// the low-order bits of the binary representation are preserved and the high-order bits are, if necessary, discarded. This preserves values that are representable + /// by the target type, but values that are not representable by the target type may be transformed in ways that, while correct in terms of the bit-level rules, + /// are unexpected in terms of numerical values. While this is like the behavior of the built-in integer types, it is different than the behavior of , + /// which performs casts as if checked, throwing an exception if the value is not representable in the target type. If you want checked behavior, your code must explicitly + /// check whether the value is in the range of the target before casting. + /// If you know that the numbers you need to work with all fit in a 128 bit unsigned register, arithmetic with is typically significantly faster than with . + /// Addition and subtraction are about six times faster, multiplication is about twice as fast, and division is about 50% faster. + /// also supports bitwise logical and shift operations. /// [CLSCompliant(false)] public struct UInt128 : IEquatable, IComparable { diff --git a/Numerics/Functions/AdvancedMath.cs b/Numerics/Functions/AdvancedMath.cs index 1be3718..a7feb47 100644 --- a/Numerics/Functions/AdvancedMath.cs +++ b/Numerics/Functions/AdvancedMath.cs @@ -5,6 +5,14 @@ namespace Meta.Numerics.Functions { /// /// Contains methods that compute advanced functions with real arguments. /// + /// + /// This static class provides an enormous number of advanced functions. + /// If you need to compute one of these functions with a complex + /// argument, see . + /// If you need to compute one of these functions with extended precision, + /// see . + /// Functions to evaluate orthogonal polynomials can be found in . + /// public static partial class AdvancedMath { // Members are defined in other files diff --git a/Numerics/Functions/AdvancedMath_Riemann.cs b/Numerics/Functions/AdvancedMath_Riemann.cs index a2d1707..8d29682 100644 --- a/Numerics/Functions/AdvancedMath_Riemann.cs +++ b/Numerics/Functions/AdvancedMath_Riemann.cs @@ -154,11 +154,13 @@ public static partial class AdvancedComplexMath { /// /// As the imaginary part of the argument increases, the computation of the zeta function becomes slower and more difficult. /// The computation time is approximately proportional to the imaginary part of z. The result also slowly looses accuracy for arguments with - /// very large imaginary parts; for arguments with z.Im of order 10^d, approximately the last d digits of the result are suspect. - /// The image below shows the complex Γ function near the origin using domain coloring. You can see the first non-trivial + /// very large imaginary parts; for arguments with z.Im of order 10^D, approximately the last D digits of the result are suspect. + /// The image below shows the complex ζ function near the origin using domain coloring. You can see the first non-trivial /// zeros at (1/2, ±14.13...) as well as the trivial zeros along the negative real axis. /// /// + /// + /// public static Complex RiemannZeta (Complex z) { // Use conjugation and reflection symmetry to move to the first quadrant. diff --git a/Numerics/Functions/NamespaceDoc.cs b/Numerics/Functions/NamespaceDoc.cs index 34a357e..c6aa0fb 100644 --- a/Numerics/Functions/NamespaceDoc.cs +++ b/Numerics/Functions/NamespaceDoc.cs @@ -6,13 +6,17 @@ namespace Meta.Numerics.Functions { /// Contains types that compute advanced functions. /// /// - /// This namespace contains types for computing nearly 100 advanced functions. - /// The functions are organized into several static classes. + /// This namespace contains types for computing more than 100 advanced functions. + /// Most of the functions are organized into several static classes. /// contains functions of integers such as . - /// contains functions of real variances, from relatively well-known functions - /// like and + /// contains functions of real numbers, from relatively well-known functions + /// like and , /// to relatively obscure functions like . - /// Complex variants of these functions are defined in . + /// Complex variants of some these functions are provided by . + /// The namesace also contains a handfull of types representing specialized mathematical + /// objects such as s and s. Functions on these + /// objects are defined on the types themselves or on additional static class collections + /// such as . /// [CompilerGenerated] internal class NamespaceDoc { diff --git a/Numerics/Functions/Permutation.cs b/Numerics/Functions/Permutation.cs index 8f2b069..c069dca 100644 --- a/Numerics/Functions/Permutation.cs +++ b/Numerics/Functions/Permutation.cs @@ -272,6 +272,17 @@ public override int GetHashCode () { /// /// Represents a permutation. /// + /// + /// A permutation of dimension D is a re-ordering a set of D distinguishable objects. The most obvious + /// application of permutations in programming is to re-order the elements of an ordered set, but the applications + /// in applied and theoretical mathematics are vast. + /// You can instantiate a new permutation from its map or cycle notation using the or + /// methods. You can enumerate all permutations of a given dimension using the method, or get a random one of a given dimension + /// using . + /// Once you have a permutation instance in hand, you can examine its properties (e.g. and ), + /// obtain its inverse (using ), or combine it with another perumtation using group multiplication (). + /// You can also apply it (in-place!) to any using . + /// /// public sealed class Permutation : IEquatable, IFormattable { @@ -381,18 +392,20 @@ public string ToString (string format, IFormatProvider formatProvider) { /// The corresponding permutation. /// /// This method is able to parse both map representations and cycle representations of permutations. - /// A map representation of an n-dimensional permutation is a space-separated list of all integers between 0 and n-1, - /// enclosed in square brackets. Each number indicates the index of the location to which the object that appears at - /// that location is mapped by the permutation. For example, [2 1 0] denotes the permutation that moves the object - /// at index 0 to index 2, does not move the object at index 1, and moves the object at index 2 to index 0. Note - /// that the numbers in the map representation are the same as the numbers on the second line of Cauchy's two-line - /// notation. - /// A cycle representation of an n-dimensional representation is a space-separated list of all integers between 0 and n-1, - /// grouped into cycles by parenthesis. Each cycle indicates that the element at the location with the first index in the cycle is moved to + /// A map representation of an n-dimensional permutation is a space-separated list of all integers between 0 and n-1 (inclusive), + /// enclosed in square brackets. The number at (zero-based) position k indicates the index of the position to which the object + /// which was originally at position k is mapped by the permutation. + /// For example, [2 1 0] denotes the permutation that moves the object + /// at index 0 to index 2, leaves the object at index 1 at index 1, and moves the object at index 2 to index 0. + /// Therefore the numbers in the map representation are the same as the numbers on the second line of + /// Cauchy's two-line notation. + /// A cycle representation of an n-dimensional representation is a space-separated list of all integers between 0 and n-1 (inclusive), + /// grouped into cycles by non-nested parenthesis. Each cycle indicates that the element at the location with the first index in the cycle is moved to /// the location with the second index in the cycle, the element at the location with the second index in the cycle is moved /// to the location with the third index in the cycle, and so on, until the element at the location with the last index - /// is moved to the location with the first index. Thus (0 2)(1) indicates that the elements at locations 0 and 2 change - /// places and the element at location 1 is left there. So (0 2)(1) and [2 1 0] represent the same permutation. + /// is moved to the location with the first index. Thus (0 2)(1) indicates that the elements at locations 0 and 2 change + /// places and the element at location 1 is left alone. So (0 2)(1) and [2 1 0] represent the same permutation. + /// Both map and cycle notation are in common use and each makes manifest different aspects of a permutation. /// /// is null. /// is not a valid text representation of a permutation. @@ -487,6 +500,10 @@ private void ComputeMap () { /// /// The type of the list. /// The list. + /// + /// Usefully for large arrays, the appliation is in-place, i.e. rather than allocate a second array and copy the elements to their target locations in the new array, + /// the elements are moved within the single array provided, using an algorithm which ensures that no element is lost via uncontrolled overwriting. + /// public void Apply (IList x) { if (x == null) throw new ArgumentNullException(nameof(x)); if (x.Count != this.Dimension) throw new DimensionMismatchException(); @@ -534,6 +551,8 @@ public Permutation Inverse () { /// the returned value will overflow. /// Note that the word order is also used to refer to the number of distinct permutations of a given dimension. That "order" is a property /// of the permutation group. This "order" is a property of each permutation. + /// In no circumstances does "order" refer to the number of elements on which a permutation operates; that is the + /// of the permutation. /// public long Order { get { diff --git a/Numerics/Matrices/NamespaceDoc.cs b/Numerics/Matrices/NamespaceDoc.cs new file mode 100644 index 0000000..1df640b --- /dev/null +++ b/Numerics/Matrices/NamespaceDoc.cs @@ -0,0 +1,33 @@ +using System.Collections.Generic; +using System.Runtime.CompilerServices; + +namespace Meta.Numerics.Matrices { + + + /// + /// Contains types that store and operate on matrices. + /// + /// + /// You can create matrices of real values using the and + /// classes, and vectors of real values using the and classes. + /// Operator overloads are defined that allow you to perform allowed arithmetic operations, such as adding + /// two vectors or matrices, or multiplying a vector by a scalar, vector, or matrix. Each type defines + /// methods corresponding to common linear algebra operations, such as inversion (), + /// finding eigenvalues and eigenvectors ( and ), + /// and decompositions ( and ). + /// The fastest way to solve a linear system A x = b is to form the of A + /// and call with the right-hand-side b. + /// There are several additional matrix containers that support smaller storage requirements and faster operations for + /// matrices with particular structures, such as , , + /// , and . + /// Where possible, we quickly return new matrix objects that implement a new view of existing stored values, + /// without copying or otherwise disturbing the original values. Examples include and . + /// For read-only purposes, this is much faster and requires less memory that computing and storing new values. The returned matrix objects are, + /// however, necessarily read-only. Whether an matrix object is read-only can be determined from . If + /// you want to modify a read-only matrix object, simply make a copy using the object's Copy method (e.g. or + /// ). + /// + [CompilerGenerated] + internal class NamespaceDoc { + } +} diff --git a/Numerics/Numerics.csproj b/Numerics/Numerics.csproj index 4fab0b3..bb49f59 100644 --- a/Numerics/Numerics.csproj +++ b/Numerics/Numerics.csproj @@ -4,7 +4,7 @@ netstandard1.1 Meta.Numerics Meta.Numerics - 4.1.2-alpha + 4.1.3-alpha Copyright © David Wright 2008-2020 David Wright Meta Numerics diff --git a/Numerics/Statistics/Distributions/BernoulliDistribution.cs b/Numerics/Statistics/Distributions/BernoulliDistribution.cs index 3bdcb6f..affc0d3 100644 --- a/Numerics/Statistics/Distributions/BernoulliDistribution.cs +++ b/Numerics/Statistics/Distributions/BernoulliDistribution.cs @@ -15,6 +15,7 @@ namespace Meta.Numerics.Statistics.Distributions { /// does not vanish. /// When multiple, independent Bernoulli trials are conducted, the binomial distribution () /// describes the probability of obtaining any particular number of successes. + /// /// /// /// diff --git a/Numerics/Statistics/Distributions/BetaDistribution.cs b/Numerics/Statistics/Distributions/BetaDistribution.cs index 1268f20..85a8383 100644 --- a/Numerics/Statistics/Distributions/BetaDistribution.cs +++ b/Numerics/Statistics/Distributions/BetaDistribution.cs @@ -15,18 +15,23 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// The beta distribution is defined on the interval [0,1]. Depending on its two shape parameters, it can take on a /// variety of forms on this interval. - /// If the two shape parameters are equal, the distribution is symmetric. If the first shape parameter is less than one, - /// the distribution has a singularity at its left endpoint. If the first shape parameter is greater than one, the distribution - /// goes to zero at its left endpoint. The second shape parameter similarly governs the distribution's behavior at its right - /// endpoint. + /// The left shape parameter α controls the shape of the distribution near the left endpoint x = 0. + /// The right shapre paramater β controls the shape of the distribution near the right endpoint x = 1. + /// If a shape parameter is less than one, the distribution is singular on that side. If a shape parameter is greater + /// than one, the distribution does to zero on that side. If a shape parameter is equal to one, the distribution + /// goes to a constant on that side. + /// If the two shape parameters are equal, the distribution is symmetric. /// When both shape parameters are one, the beta distribution reduces to a standard uniform distribution. - /// + /// /// Beta distributions describe the maximum and minimum values obtained from multiple, independent draws from a standard /// uniform distribution. For n draws, the maximum value is distributed as B(n,1). - /// + /// /// Similarly, the minimum value is distributed as B(1,n). + /// + /// In fact, the ith order statistic (ith smallest value) in n draws from a uniform distribution + /// is distributed as B(i, n - i + 1). /// Because of the wide variety of shapes it can take, the beta distribution is sometimes - /// used as an ad hoc model to describe any distribution observed on a finite interval. + /// used as an ad hoc model to fit distributions observed on a finite interval. /// /// /// diff --git a/Numerics/Statistics/Distributions/BinomialDistribution.cs b/Numerics/Statistics/Distributions/BinomialDistribution.cs index 4bc65c5..c96cc7b 100644 --- a/Numerics/Statistics/Distributions/BinomialDistribution.cs +++ b/Numerics/Statistics/Distributions/BinomialDistribution.cs @@ -12,8 +12,9 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// The binomial distribution gives the probability of obtaining k successes /// in n independent Bernoulli trials in which the probability of success in each trial is p. - /// For a single trial, the binomial distribution reduces to a Bernoulli distribution (). - /// The test statistic for a sign test () is distributed according to the Bernoulli distribution. + /// + /// Therefore, for a single trial, the binomial distribution reduces to a Bernoulli distribution (). + /// The test statistic for a sign test () is distributed according to the Binomial distribution. /// /// /// diff --git a/Numerics/Statistics/Distributions/CauchyDistribution.cs b/Numerics/Statistics/Distributions/CauchyDistribution.cs index e7e422a..37370a1 100644 --- a/Numerics/Statistics/Distributions/CauchyDistribution.cs +++ b/Numerics/Statistics/Distributions/CauchyDistribution.cs @@ -12,10 +12,14 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// In physical applications, the Cauchy distribution is usually called a Lorentz distribution. It models /// the shape of a spectral line. + /// The ratio of two normally distributed quantities has a Cauchy distribution. + /// /// The Cauchy distribution has "fat tails". In fact, it falls off at the minimum possible rate consistent - /// with having a convergent integral. For this same reason, none of its moments (above the zeroth) are defined. + /// with having a convergent probability integral. For this same reason, none of its moments (above the zeroth) + /// are defined. /// /// + /// public sealed class CauchyDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/ChiDistribution.cs b/Numerics/Statistics/Distributions/ChiDistribution.cs index 5968d9b..c63accf 100644 --- a/Numerics/Statistics/Distributions/ChiDistribution.cs +++ b/Numerics/Statistics/Distributions/ChiDistribution.cs @@ -13,12 +13,16 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// /// The χ distribution is the distribution of the magnitude of a ν-dimensional vector whose individual components are - /// normally distribution. - /// Since the distribution of the same sum of squares without taking the square root is called the ν2 distribution, - /// (), this distribution is called the ν distribution. + /// normally distributed. + /// + /// Since the distribution of the same sum of squares without taking the square root is called the χ2 distribution, + /// (), this distribution is called the χ distribution. + /// The particular case with ν = 2 is the . /// /// + /// /// + /// public sealed class ChiDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/ChiSquaredDistribution.cs b/Numerics/Statistics/Distributions/ChiSquaredDistribution.cs index a458a28..c9bd682 100644 --- a/Numerics/Statistics/Distributions/ChiSquaredDistribution.cs +++ b/Numerics/Statistics/Distributions/ChiSquaredDistribution.cs @@ -11,19 +11,21 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// /// A chi squared distribution is an asymmetrical distribution ranging from zero to infinity with a peak near its - /// number of degrees of freedom ν. It is a one-parameter distribution determined entirely by the parameter nu. + /// number of degrees of freedom ν. It is a one-parameter distribution determined entirely by the parameter ν. /// /// The figure above shows the χ2 distribution for ν = 6, as well as the normal distribution /// with equal mean and variance for reference. /// The sum of the squares of ν independent standard-normal distributed variables is distributed as χ2 /// with ν degrees of freedom. - /// + /// /// The χ2 distribution appears in least-squares fitting as the distribution of the sum-of-squared-deviations /// under the null hypothesis that the model explains the data. For example, the goodness-of-fit statistic returned by the /// model our model fitting methods (, , /// , and others) follows a χ2 distribution. /// + /// /// + /// public sealed class ChiSquaredDistribution : ContinuousDistribution { // internally, we use our Gamma distribution machinery to do our heavy lifting diff --git a/Numerics/Statistics/Distributions/ExponentialDistribution.cs b/Numerics/Statistics/Distributions/ExponentialDistribution.cs index 1353a83..18b66d8 100644 --- a/Numerics/Statistics/Distributions/ExponentialDistribution.cs +++ b/Numerics/Statistics/Distributions/ExponentialDistribution.cs @@ -17,12 +17,14 @@ namespace Meta.Numerics.Statistics.Distributions { /// An exponential distribution with mean one is called a standard exponential distribution. Any exponential distribution /// can be converted to a standard exponential by re-parameterizing the data into "fractions of the mean," /// i.e. z = x / μ. + /// /// Processes resulting in events that are exponentially distributed in time are said to be "ageless" because the hazard function /// of the exponential distribution is constant. The Weibull distribution () is a generalization - /// of the exponential distribution which the hazard function changes (typically by increasing) with time. + /// of the exponential distribution for which the hazard function changes (usually by increasing) with time. /// /// /// + /// public sealed class ExponentialDistribution : ContinuousDistribution { private readonly double mu; diff --git a/Numerics/Statistics/Distributions/FrechetDistribution.cs b/Numerics/Statistics/Distributions/FrechetDistribution.cs index 3cd225e..103209c 100644 --- a/Numerics/Statistics/Distributions/FrechetDistribution.cs +++ b/Numerics/Statistics/Distributions/FrechetDistribution.cs @@ -7,6 +7,10 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// Represents a Fréchet distribution. /// + /// + /// The Fréchet distribution is also called the inverse Weibull distribution. + /// + /// public sealed class FrechetDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/GammaDistribution.cs b/Numerics/Statistics/Distributions/GammaDistribution.cs index cd62ba5..875a3bb 100644 --- a/Numerics/Statistics/Distributions/GammaDistribution.cs +++ b/Numerics/Statistics/Distributions/GammaDistribution.cs @@ -17,6 +17,7 @@ namespace Meta.Numerics.Statistics.Distributions { /// the shape parameter is one, the Gamma distribution reduces to the exponential distribution. /// /// + /// public sealed class GammaDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/GeometricDistribution.cs b/Numerics/Statistics/Distributions/GeometricDistribution.cs index feb274e..4bafad5 100644 --- a/Numerics/Statistics/Distributions/GeometricDistribution.cs +++ b/Numerics/Statistics/Distributions/GeometricDistribution.cs @@ -10,6 +10,8 @@ namespace Meta.Numerics.Statistics.Distributions { /// The probability of obtaining each integer value in a geometric distribution is lower than the probability of obtaining /// the previous value by a constant factor. The probability thus decreases geometricly with the value, giving the distribution its name. /// + /// + /// public sealed class GeometricDistribution : DiscreteDistribution { /// diff --git a/Numerics/Statistics/Distributions/LaplaceDistribution.cs b/Numerics/Statistics/Distributions/LaplaceDistribution.cs index 3eaefe2..eb19fbc 100644 --- a/Numerics/Statistics/Distributions/LaplaceDistribution.cs +++ b/Numerics/Statistics/Distributions/LaplaceDistribution.cs @@ -8,11 +8,12 @@ namespace Meta.Numerics.Statistics.Distributions { /// Represents a Laplace distribution. /// /// - /// A Laplace distribution is a symmetric variant of the . + /// A Laplace distribution, also called the double exponential distribution, is a symmetric variant of the . /// Instead of putting all events to the right of the origin, it puts events on both sides of /// its central location with equally, with a probability density falling off exponentially on each side. /// /// + /// public sealed class LaplaceDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/LogisticDistribution.cs b/Numerics/Statistics/Distributions/LogisticDistribution.cs index a503259..c4fe32e 100644 --- a/Numerics/Statistics/Distributions/LogisticDistribution.cs +++ b/Numerics/Statistics/Distributions/LogisticDistribution.cs @@ -10,12 +10,13 @@ namespace Meta.Numerics.Statistics.Distributions { /// Represents a logistic distribution. /// /// - /// Like the normal distribution, the logistic distribution is a symmetric, unimodal distribution + /// Like the normal distribution, the logistic distribution is a bell-shaped (symmetric, unimodal) distribution /// distribution with exponentially supressed tails. /// A logistic distribution with mean zero and standard deviation one is called a standard logistic distribution. Any logistic distribution /// can be converted to a standard logistic distribution by reparameterzing into z = (x-m)/s. /// /// + /// public sealed class LogisticDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/LognormalDistribution.cs b/Numerics/Statistics/Distributions/LognormalDistribution.cs index 10652e9..3367d0b 100644 --- a/Numerics/Statistics/Distributions/LognormalDistribution.cs +++ b/Numerics/Statistics/Distributions/LognormalDistribution.cs @@ -15,10 +15,11 @@ namespace Meta.Numerics.Statistics.Distributions { /// The logarithm of a log-normal distributed variable is distributed normally. /// /// The log-normal distribution is commonly used in financial engineering as a model of stock prices. - /// If the rate of return on an asset is distributed normally, then its price will be distributed log-normally. + /// If the rate of return on an asset is distributed normally, then its price at a given time will be distributed log-normally. /// /// /// + /// public sealed class LognormalDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/MomentMath.cs b/Numerics/Statistics/Distributions/MomentMath.cs index f334a61..c336860 100644 --- a/Numerics/Statistics/Distributions/MomentMath.cs +++ b/Numerics/Statistics/Distributions/MomentMath.cs @@ -9,6 +9,15 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// Contains methods for converting between different kinds of moments. /// + /// + /// Distributions can be described by by sets of various moments. Raw moments + /// and central moments are encountered most commonly, but cumulants (also + /// called semi-invariants) and factorial moments are also seen. Given any + /// set of one kind of moment for a distribution up to a given order + /// (e.g. the 1st, 2nd, and 3rd central moments), the methods of this + /// class return the values of other kinds of moments, up to the same order + /// (e.g. the 1st, 2nd, and 3rd raw moments). + /// public static class MomentMath { /// @@ -16,6 +25,9 @@ public static class MomentMath { /// /// A set of raw moments. /// The corresponding set of central moments. + /// The computation of central moments from raw moments is often subject + /// to significant cancellation errors, so you should be wary of the higher + /// digits of central moments returned by this method. /// is null. /// The zeroth raw moment is not one. public static double[] RawToCentral (double[] M) { @@ -250,6 +262,9 @@ internal static double CumulantToMoment (double[] K, int r, bool central) { /// /// A set of raw moments. /// The corresponding set of cumulants. + /// The computation of cumulants from raw moments is often subject + /// to significant cancellation errors, so you should be wary of the higher + /// digits of cumulants returned by this method. /// is null. /// The zeroth raw moment is not one. public static double[] RawToCumulant (double[] M) { diff --git a/Numerics/Statistics/Distributions/NamespaceDoc.cs b/Numerics/Statistics/Distributions/NamespaceDoc.cs new file mode 100644 index 0000000..ad4b8c1 --- /dev/null +++ b/Numerics/Statistics/Distributions/NamespaceDoc.cs @@ -0,0 +1,40 @@ +using System.Runtime.CompilerServices; + +namespace Meta.Numerics.Statistics.Distributions { + + /// + /// Contains types that describe probability distributions. + /// + /// + /// Distributions are assignments of a probability-weight to each of the elements in a set. Most commonly, + /// those sets are subsets of the integers or real numbers. + /// Distribution on the integers inherit from the abstract class. For any discrete + /// distribution, you can determine its range (called ), the + /// probability weight of each value (using ), + /// and many other properties. You can generate pseduo-random integers distributed according to a + /// discrete distribution (using ). + /// Many discrete distributions are defined, including and + /// . + /// Distributions on the real numbers inherit from the abstract class. For + /// any continuous distribution, you can determine its range (called ), + /// the probability density at each value (using ), + /// the cumulative distribution function (using ), + /// and many other properties. You can generate pseudo-random floating-point values distributed according to + /// a continuous distribution (using ). + /// Many continuous distributions are defined, including , + /// , , and . + /// All one-dimensional distibutions, continuous and discrete, inherit from the abstract class. + /// Using the properties and methods of this class, you can determine raw moments () + /// such as the , central moments () + /// such as the , or cumulants (). + /// Many distributions also offer methods that allow you to find the parameters that best fit a given set of data points + /// and measure the quality of the fit. + /// You can add your own continous and discrete distributions by inheriting from or + /// and implementing only a few abstract methods. All the remaining properties and methods + /// are then automatically determined for your distribution. + /// + /// + [CompilerGenerated] + internal class NamespaceDoc { + } +} diff --git a/Numerics/Statistics/Distributions/NormalDistribution.cs b/Numerics/Statistics/Distributions/NormalDistribution.cs index 729e505..743d8e2 100644 --- a/Numerics/Statistics/Distributions/NormalDistribution.cs +++ b/Numerics/Statistics/Distributions/NormalDistribution.cs @@ -17,14 +17,16 @@ namespace Meta.Numerics.Statistics.Distributions { /// A normal distribution with mean zero and standard deviation one is called a standard normal distribution. Any normal distribution /// can be converted to a standard normal distribution by re-parameterizing the data in terms of "standard deviations from the mean", /// i.e. z = (x - μ) / σ. + /// /// Normal distribution appear in many contexts. In practical work, the normal distribution is often used as a crude /// model for the distribution of any continuous parameter that tends to cluster near its average, for example human height /// and weight. In more refined theoretical work, the normal distribution often emerges as a limiting distribution. For example, /// it can be shown that, if a large number of errors affect a measurement, then for nearly any underlying distribution - /// of error terms, the distribution of total error tends to a normal distribution. - /// The normal distribution is sometimes called a Gaussian, after the mathematician Friedrich Gauss. + /// of error terms, the distribution of total error tends toward a normal distribution. + /// The normal distribution is often called a Gaussian, after the mathematician Friedrich Gauss. /// /// + /// public sealed class NormalDistribution : ContinuousDistribution { private readonly double mu, sigma; diff --git a/Numerics/Statistics/Distributions/ParetoDistribution.cs b/Numerics/Statistics/Distributions/ParetoDistribution.cs index 5e265d5..a1fe171 100644 --- a/Numerics/Statistics/Distributions/ParetoDistribution.cs +++ b/Numerics/Statistics/Distributions/ParetoDistribution.cs @@ -9,6 +9,7 @@ namespace Meta.Numerics.Statistics.Distributions { /// Represents a Pareto or power law distribution. /// /// + /// public sealed class ParetoDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/PoissonDistribution.cs b/Numerics/Statistics/Distributions/PoissonDistribution.cs index 87d89c2..3752bce 100644 --- a/Numerics/Statistics/Distributions/PoissonDistribution.cs +++ b/Numerics/Statistics/Distributions/PoissonDistribution.cs @@ -9,6 +9,19 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// Represented a Poisson distribution. /// + /// + /// If events occur independely at uniformly distributed random times, + /// the Poisson distribution gives the probabability distribution of the number of + /// events than occur in a given time interval. If on average μ events occur + /// in the time interval the number of actual events that occur is Poisson distributed + /// with parameter μ. + /// The Poisson distribution has the unusual property that the distribution + /// of a sum of Poisson distributed values itself has a poisson distribution, + /// with a mean equal to the sum of the means of the contributing addends. + /// + /// + /// + /// public sealed class PoissonDistribution : DiscreteDistribution { /// diff --git a/Numerics/Statistics/Distributions/RayleighDistribution.cs b/Numerics/Statistics/Distributions/RayleighDistribution.cs index a735ec8..fd16606 100644 --- a/Numerics/Statistics/Distributions/RayleighDistribution.cs +++ b/Numerics/Statistics/Distributions/RayleighDistribution.cs @@ -14,6 +14,7 @@ namespace Meta.Numerics.Statistics.Distributions { /// A standard Rayleigh distribution is equivalent to a with ν = 2. /// /// + /// public sealed class RayleighDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/StudentDistribution.cs b/Numerics/Statistics/Distributions/StudentDistribution.cs index 6b1e26b..24eb836 100644 --- a/Numerics/Statistics/Distributions/StudentDistribution.cs +++ b/Numerics/Statistics/Distributions/StudentDistribution.cs @@ -7,14 +7,22 @@ namespace Meta.Numerics.Statistics.Distributions { /// - /// Represents the distribution of Student't t statistic. + /// Represents the distribution of Student's t statistic. /// /// The mean of n independent standard-normal distributed variables, divided by their root mean square, /// is distributed according a Student distribution with n degrees of freedom. Since this is the form of the expression /// for the mean of a sample divided by its standard deviation, the Student distribution expresses the distribution of - /// sample means arround the population mean, for a normally distributed population. + /// sample means arround the population mean, for a normally distributed population. + /// The origin of the name Student distribution is a nice bit of statistical trivia. William Gosset published a + /// paper describing the distribution and its statistical applications in 1908. His employer, the Guiness Brewery, + /// did not want other brewers to be tipped off to its application to comparing small samples of beer, so they asked + /// him to publish under a pseudonym. He published the paper under the name "Student" and the distribution has been + /// known by that name since. + /// + /// /// /// + /// public sealed class StudentDistribution : ContinuousDistribution { private double nu; diff --git a/Numerics/Statistics/Distributions/UniformDistribution.cs b/Numerics/Statistics/Distributions/UniformDistribution.cs index 1e5ed64..705384b 100644 --- a/Numerics/Statistics/Distributions/UniformDistribution.cs +++ b/Numerics/Statistics/Distributions/UniformDistribution.cs @@ -10,6 +10,7 @@ namespace Meta.Numerics.Statistics.Distributions { /// Represents a uniform distribution over an interval. /// /// + /// public sealed class UniformDistribution : ContinuousDistribution { private readonly Interval range; diff --git a/Numerics/Statistics/Distributions/WaldDistribution.cs b/Numerics/Statistics/Distributions/WaldDistribution.cs index 1c9d4c2..f49f1e7 100644 --- a/Numerics/Statistics/Distributions/WaldDistribution.cs +++ b/Numerics/Statistics/Distributions/WaldDistribution.cs @@ -8,19 +8,20 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// Represents a Wald (Inverse Gaussian) distribution. /// - /// + /// /// The Wald distribution, also called the inverse Gaussian distribution, is the distribution of first - /// passage times for a random walk. - /// The Wald distribution is often called the inverse Gaussian distribution, but it is not the - /// distribution of 1/x when x is Gaussian-distributed. - /// If a system exhibits one-dimensional Brownian motion with mean displacement mu t and variance - /// sigma t-squared. - /// This can be phrased in terms of the Gambler's ruin problem: given an initial endowment x, a gambler - /// repeatedly plays a game in which he wins 1 dollar with probability p and looses one dollar with probability - /// q = 1 - p. If q > p, he will eventually loose all his endowment. What is the probability distribution that - /// he will do so after exactly t games? - /// + /// passage times for Brownian motion. + /// In Brownian motion, a particle moves randomly so that its position at any given time is distributed + /// normally with a mean that increases linearly and a standard deviation that increases + /// with the square root of time. The first passage time is the earliest time that its position reaches + /// a given level. This first passage time is Wald distributed with mean and shape parameters related to + /// the drift, noise, and threshold. + /// + /// This may appear a very obscure an technical relationship, but it turns out to have myriad + /// applications: to stock prices, ballot counting, neurological response times, and earthquake prediction. + /// /// + /// public sealed class WaldDistribution : ContinuousDistribution { /// diff --git a/Numerics/Statistics/Distributions/WeibullDistribution.cs b/Numerics/Statistics/Distributions/WeibullDistribution.cs index 44d7054..16a45d2 100644 --- a/Numerics/Statistics/Distributions/WeibullDistribution.cs +++ b/Numerics/Statistics/Distributions/WeibullDistribution.cs @@ -13,9 +13,12 @@ namespace Meta.Numerics.Statistics.Distributions { /// /// /// The Weibull distribution is a generalized form of the exponential distribution, - /// for which the decay probability is not constant, but instead increases or decreases - /// with time. When the shape parameter is one, the Weibull distribution reduces to the - /// exponential distribution. + /// for which the hazard function is not constant, but instead increases (for shape parameter k > 1) + /// or decreases (for shape parameter k < 1) with x. When the shape parameter is one, the Weibull + /// distribution reduces to the exponential distribution. + /// In fact, any Weibull distribution can be transformed into a standard exponential distribtuion + /// by a change of variables. + /// /// The Weibull distribution is commonly used in engineering applications to /// model the time-to-failure of industrial components. /// diff --git a/Test/AdvancedMathTest_Bessel.cs b/Test/AdvancedMathTest_Bessel.cs index 5167440..4a9f2ef 100644 --- a/Test/AdvancedMathTest_Bessel.cs +++ b/Test/AdvancedMathTest_Bessel.cs @@ -38,13 +38,7 @@ public void IntegerBesselNegativeArgument () { foreach (int n in TestUtilities.GenerateIntegerValues(1, 1000, 4)) { foreach (double x in TestUtilities.GenerateRealValues(1.0E-4, 1.0E6, 8)) { int s = (n % 2 == 0) ? +1 : -1; - Console.WriteLine($"{n} {x} {s}"); - double f1 = AdvancedMath.BesselJ(n, -x); - double f2 = AdvancedMath.BesselJ(n, x); - Console.WriteLine($" {f1} {f2}"); - Console.WriteLine($" {new DoubleInfo(AdvancedMath.BesselJ(n, -x))} {new DoubleInfo(s * AdvancedMath.BesselJ(n, x))}"); - Console.WriteLine($" {AdvancedMath.BesselJ(n, -x) == s * AdvancedMath.BesselJ(n, -x)}"); - Assert.IsTrue(AdvancedMath.BesselJ(n, -x) == s * AdvancedMath.BesselJ(n, -x)); + Assert.IsTrue(AdvancedMath.BesselJ(n, -x) == s * AdvancedMath.BesselJ(n, x)); } } } diff --git a/Test/DistributionTest.cs b/Test/DistributionTest.cs index cf3ae3d..984e081 100644 --- a/Test/DistributionTest.cs +++ b/Test/DistributionTest.cs @@ -48,6 +48,7 @@ private static List CreateDistributions () { new ChiDistribution(1), new ChiDistribution(4), new RayleighDistribution(3.0), new FrechetDistribution(2.9, 4.0), + new NoncentralChiSquaredDistribution(2, 1.5), new TestDistribution() }); diff --git a/Test/IntervalTest.cs b/Test/IntervalTest.cs index 8a92f0f..93155da 100644 --- a/Test/IntervalTest.cs +++ b/Test/IntervalTest.cs @@ -9,56 +9,9 @@ namespace Test { ///This is a test class for IntervalTest and is intended ///to contain all IntervalTest Unit Tests /// - [TestClass()] + [TestClass] public class IntervalTest { - - private TestContext testContextInstance; - - /// - ///Gets or sets the test context which provides - ///information about and functionality for the current test run. - /// - public TestContext TestContext { - get { - return testContextInstance; - } - set { - testContextInstance = value; - } - } - - #region Additional test attributes - // - //You can use the following additional attributes as you write your tests: - // - //Use ClassInitialize to run code before running the first test in the class - //[ClassInitialize()] - //public static void MyClassInitialize(TestContext testContext) - //{ - //} - // - //Use ClassCleanup to run code after all tests in a class have run - //[ClassCleanup()] - //public static void MyClassCleanup() - //{ - //} - // - //Use TestInitialize to run code before running each test - //[TestInitialize()] - //public void MyTestInitialize() - //{ - //} - // - //Use TestCleanup to run code after each test has run - //[TestCleanup()] - //public void MyTestCleanup() - //{ - //} - // - #endregion - - private double a = -3.1; private double b = -2.0; private double c = 2.7; @@ -72,7 +25,7 @@ public void IntervalZeroWidth () { Assert.IsTrue(aa.Midpoint == a); } - [TestMethod()] + [TestMethod] public void IntervalWidth () { Interval ab = Interval.FromEndpoints(a, b); Assert.IsTrue(ab.Width == Math.Abs(a - b)); @@ -85,25 +38,11 @@ public void IntervalEndpoints () { Assert.IsTrue(ab.RightEndpoint == b); } - [TestMethod()] - public void ToTest () { - Interval ab = Interval.FromEndpoints(a, b); - Assert.AreEqual(ab.RightEndpoint, b); - } - [TestMethod] public void IntervalMidpoint () { Interval ab = Interval.FromEndpoints(a, b); Assert.IsTrue(ab.Midpoint == (a + b) / 2.0); - } - - /// - ///A test for From - /// - [TestMethod()] - public void FromTest () { - Interval ab = Interval.FromEndpoints(a, b); - Assert.AreEqual(ab.LeftEndpoint, a); + Assert.IsTrue(ab.Contains(ab.Midpoint)); } [TestMethod] @@ -115,6 +54,17 @@ public void IntervalOpenContains () { Assert.IsFalse(ac.OpenContains(d)); } + [TestMethod] + public void IntervalContainsEndpoints () { + Interval ab = Interval.FromEndpoints(a, b); + Assert.IsTrue(ab.Contains(a, IntervalType.Closed)); + Assert.IsFalse(ab.Contains(a, IntervalType.Open)); + Assert.IsTrue(ab.Contains(a, IntervalType.Closed, IntervalType.Open)); + Assert.IsTrue(ab.Contains(b, IntervalType.Closed)); + Assert.IsFalse(ab.Contains(b, IntervalType.Open)); + Assert.IsFalse(ab.Contains(b, IntervalType.Closed, IntervalType.Open)); + } + [TestMethod] public void IntervalFromMidpointAndWidth () { double m = 1.0; @@ -147,5 +97,15 @@ public void IntervalClosedContains () { Assert.IsFalse(ac.ClosedContains(d)); } + [TestMethod] + public void IntervalEquality () { + Interval ab = Interval.FromEndpoints(a, b); + Interval ac = Interval.FromEndpoints(a, c); + Assert.IsTrue(ab.Equals(ab)); + Assert.IsTrue(ab.Equals((object) ab)); + Assert.IsFalse(ab.Equals(ac)); + Assert.IsFalse(ab.Equals((object) ac)); + } + } }