diff --git a/MathNet.Numerics.sln b/MathNet.Numerics.sln index 3a37d94b..815226fe 100644 --- a/MathNet.Numerics.sln +++ b/MathNet.Numerics.sln @@ -43,13 +43,14 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{039229DA-A docs\content\CSV.fsx = docs\content\CSV.fsx docs\content\DescriptiveStatistics.fsx = docs\content\DescriptiveStatistics.fsx docs\content\Distance.fsx = docs\content\Distance.fsx + docs\content\Euclid.fsx = docs\content\Euclid.fsx docs\content\Functions.fsx = docs\content\Functions.fsx docs\content\Generate.fsx = docs\content\Generate.fsx docs\content\index.fsx = docs\content\index.fsx docs\content\IntegralTransforms.fsx = docs\content\IntegralTransforms.fsx docs\content\Integration.fsx = docs\content\Integration.fsx docs\content\Interpolation.fsx = docs\content\Interpolation.fsx - docs\content\RandomAndDistributions.fsx = docs\content\RandomAndDistributions.fsx + docs\content\Random.fsx = docs\content\Random.fsx docs\tools\templates\template.cshtml = docs\tools\templates\template.cshtml EndProjectSection EndProject diff --git a/docs/content/Euclid.fsx b/docs/content/Euclid.fsx new file mode 100644 index 00000000..eeacc8f0 --- /dev/null +++ b/docs/content/Euclid.fsx @@ -0,0 +1,109 @@ +(*** hide ***) +#I "../../out/lib/net40" +#r "MathNet.Numerics.dll" +#r "MathNet.Numerics.FSharp.dll" + +(** +Euclid & Number Theory +====================== + +The static `Euclid` class in the `MathNet.Numerics` namespace provides routines related +to the domain of integers. + + +Remainder vs. Canonical Modulus +------------------------------- + +Remainder and modulus are closely related operations with a long tradition of confusing +on with the other. The % operator in most computer languages implements one of the two, +but some even leave which one as an implementation detail (e.g. C-1990). + +*Warning: In C#, like most languages, % is the remainder operator, not the modulus!* + + +#### Remainder + +The **remainder** is the amount left over after performing the devision of a dividend +by a divisor, $\frac{dividend}{divisor}$, which do not divide evenly, that is, +where the result of the division cannot be expressed as an integer. It is thus natural +that the **remainder has the sign of the dividend**. + +In C# and F#, the remainder is available as `%` operator, in VB as `Mod`. +Alternatively you can use the Reminder function: + + [lang=csharp] + Euclid.Remainder( 5, 3); // = 2, such that 5 = 1*3 + 2 + Euclid.Remainder(-5, 3); // = -2, such that -5 = -1*3 - 2 + Euclid.Remainder( 5, -3); // = 2, such that 5 = -1*-3 + 2 + Euclid.Remainder(-5, -3); // = -2, such that -5 = 1*-3 - 2 + + +#### Modulus + +On the other hand, in modular arithmetic numbers "wrap around" upon reaching a certain +value n, or when crossing zero. Two real numbers are said to be *congruent modulo n* +when their difference is an integer multiple of n. The modulo operator normalizes the dividend +to the fundamental or smallest values congruent modulo n, where n is the divisor, and thus +to the interval from 0 to n (including 0 but excluding n, possibly negative). It is thus natural that +the **modulus always has the sign of the divisor**. + + [lang=csharp] + Euclid.Modulus( 5, 3); // = 2, congruent modulo 3 by 5 - 1*3 + Euclid.Modulus(-5, 3); // = 1, congruent modulo 3 by -5 + 2*3 + Euclid.Modulus( 5, -3); // = -1, congruent modulo -3 by 5 + 2*-3 + Euclid.Modulus(-5, -3); // = -2, congruent modulo -3 by -5 - 1*-3 + +A typical case where the modulus appears in daily life is when grouping students into 3 groups +by letting them line up and count through as 0 1 2 0 1 2 0 1 2 etc. This way, each student will +end up in the group of their order within the line modulus 3. + + +Integer Properties +------------------ + +#### Even or Odd? + +Very simple question yet still somewhat error-prone to implement such that it works correctly +for both positive and negative integers: is a number even or odd? + +* `IsEven(number)` +* `IsOdd(number)` + + +#### Powers of two and Squares + +Powers of two are prevalent in computer engineering. For performance reasons it is often preferable +to align data in blocks where the size is a power of two, i.e. $2^k$. The `CeilingToPowerOfTwo` function +helps in such situations by finding the smallest perfect power of two larger than or equal to +the provided argument. There is also `IsPowerOfTwo` to determine whether a number is such a power of two, +and `PowerOfTwo` to compute it efficiently. + +When switching the operands of $2^k$ we get the square $k^2$. `IsPerfectSquare` determines whether +the integer argument is a perfect square, i.e. a square of an integer. + + +Euclid's Algorithm +------------------ + +#### Greatest Common Divisor + +The `GreatestCommonDivisor` evaluates the **GCD** of either two integers or a full list or array of them +using Euclid's algorithm. An extended version also returns how exactly the GCD can be composed from two +integer arguments. + + [lang=csharp] + Euclid.GreatestCommonDivisor(10, 15, 45); // 5 + + long x, y; + Euclid.ExtendedGreatestCommonDivisor(45, 18, out x, out y) // 9 + // -> x=1, y=-2, hence 9 == 1*45 + -2*18 + + +#### Least Common Multiple + +Closely related to the GCD, `LeastCommonMultiple` returns the **LCM** of two or more integers. + + [lang=csharp] + Euclid.LeastCommonMultiple(3, 5, 6); // 30 + +*) diff --git a/docs/tools/templates/template.cshtml b/docs/tools/templates/template.cshtml index 00220c20..3c3d7c65 100644 --- a/docs/tools/templates/template.cshtml +++ b/docs/tools/templates/template.cshtml @@ -57,7 +57,7 @@
  • Arbitrary Precision Numbers
  • Complex Numbers
  • Matrices and Vectors
  • -
  • Euclid & Number Theory
  • +
  • Euclid & Number Theory
  • Combinatorics