Various optimizations, README update

Author: scheinerman

Project.toml

@@ -1,7 +1,7 @@
 name = "Mods"
 uuid = "7475f97c-0381-53b1-977b-4c60186c8d62"
 author = ["Edward Scheinerman <[email protected]>"]
-version = "2.2.3"
+version = "2.2.4"
 
 [compat]
 julia = "1"

README.md

@@ -2,57 +2,6 @@
 
 Modular arithmetic for Julia.
 
-## New in Version 2
-
-
-
-With this new version the modulus of a `Mod` number must be of type `Int`.
-If a `Mod` number is constructed with any other typeof `Integer`, the 
-constructor will (try to) convert it to type `Int`.
-
-The old style `Mod{N,T}(v)` no longer works. 
-
-### Why this change?
-
-There were various issues in the earlier version of `Mods` that are 
-resolved by requiring `N` to be of type `Int`.
-
-* Previously `Mod` numbers created with different sorts of integer parameters would 
-be different. So if `N = 17` and `M = 0x11`, then `Mod{N}(1)` would not be interoperable with `Mod{M}(1).`
-
-* The internal storage of the value of the `Mod` numbers could be  different. 
-For example, `Mod{17}(-1)` would store the
-value internally as `-1` whereas `Mod{17}(16)` would store the value as `16`.
-
-* Finally, if the modulus were a large `Int128` number, then arithmetic 
-operations could silently fail. 
-
-We believe that the dominant use case for this module will be with moduli between 
-`2` and `2^63-1` and so we do not expect this change to affect
-users. Further, since `Mod` numbers that required `Int128` moduli were 
-likely to give incorrect results, version 1 of this module was buggy.
-
-Users who require *smaller* integer (e.g., `Int8`) types should use the latest version 1 of `Mods`.
-
-> **NEW!** For small moduli (between 2 and 255) see the [MiniMods](https://github.com/scheinerman/MiniMods.jl) module.
-
-In addition, some functionality has been moved to the `extras` folder. 
-See the `README` there. 
-
-### New in 2.2.3
-
-The values of `Mod` numbers are held in 64-bit integers. If the moduli and values are 
-large enough, integer arithmetic might overflow and yield incorrect results. To deal
-with this, integer values are expanded to 128 bits in order to ensure correctness,
-and then reduced by the modulus.
-
-In prior versions, we always expanded values to 128 bits before arithmetic. 
-
-Starting in version 2.2.3, expansion to 128 bits only happens for moduli above 
-`typemax(Int32)` which equals `2^31 - 1 = 2,147,483,647`. This results in a 
-roughly 4 or 5 times speedup compared to prior versions.
-
-
 
 ## Quick Overview
 This module supports modular values and arithmetic. The moduli are integers (at least 2)
@@ -247,7 +196,11 @@ julia> value(a)
 8
 ```
 
+## Limitations
 
+The modulus and value of a `Mod` number are of type `Int` (or `Complex{Int}` for `GaussMod` numbers). This implies that the largest possible modulus is `typemax(Int)` which equals `2^63-1`
+(assuming a 64-bit system).
+ 
 ### Overflow safety
 
 Integer operations on 64-bit numbers can give results requiring more than
@@ -270,6 +223,14 @@ julia> Mod{N}(a) * Mod{N}(a)    # but this is correct!
 Mod{1000000000000000000}(0)
 ```
 
+This safety comes at a cost. If the modulus is large then operations may
+require enlarging the values to 128-bits before reducing mod `N`. For multipication, 
+this widening occurs when the modulus exceeds `2^32-1`; for addition, widening occurs
+when the modulus exceeds `2^62-1`.
+
+
+
+
 ## Extras
 
 ### Zeros and ones
@@ -432,4 +393,54 @@ GaussMod{13}(2 + 8im) + GaussMod{13}(11 + 2im)*x + GaussMod{13}(8 + 2im)*x^2 + G
 ```
 
 
+## Version 2 vs Version 1 of `Mods`
+
+
+
+In version 2 the modulus of a `Mod` number must be of type `Int`.
+If a `Mod` number is constructed with any other typeof `Integer`, the 
+constructor will (try to) convert it to type `Int`.
+
+The old style `Mod{N,T}(v)` no longer works. 
+
+### Why this change?
+
+There were various issues in the earlier version of `Mods` that are 
+resolved by requiring `N` to be of type `Int`.
+
+* Previously `Mod` numbers created with different sorts of integer parameters would 
+be different. So if `N = 17` and `M = 0x11`, then `Mod{N}(1)` would not be interoperable with `Mod{M}(1).`
+
+* The internal storage of the value of the `Mod` numbers could be  different. 
+For example, `Mod{17}(-1)` would store the
+value internally as `-1` whereas `Mod{17}(16)` would store the value as `16`.
+
+* Finally, if the modulus were a large `Int128` number, then arithmetic 
+operations could silently fail. 
+
+We believe that the dominant use case for this module will be with moduli between 
+`2` and `2^63-1` and so we do not expect this change to affect
+users. Further, since `Mod` numbers that required `Int128` moduli were 
+likely to give incorrect results, version 1 of this module was buggy.
+
+
+In addition, some functionality has been moved to the `extras` folder. 
+See the `README` there. In particular, the `CRT` function is no longer part of the `Mods`
+module but resides in `extras/CRT.jl`.
+
+
+### Different modulus types
+
+Since moduli are of type `Int`, a `Mod` numbers uses 8 bytes (and a `GaussMod` uses 16 bytes). A 
+large matrix of `Mod` numbers could unnecessarily use a lot of memory, especially if the moduli
+are small.
+
+Some solutions to this problem:
 
+* Use the latest Version 1 of `Mods`.
+* Create a cloned copy of the `Mods` package and edit this line in the file `Mods.jl`:
+```julia
+const value_type = Int                # storage type for the value in a Mod
+``` 
+to set `value_type` to a smaller type of integer (say, `Int16`).
+* For very small moduli (between 2 and 255) see the [MiniMods](https://github.com/scheinerman/MiniMods.jl) module.

src/Mods.jl

@@ -14,6 +14,14 @@ CZQ = Union{Complex{<:Integer},Integer,Complex{<:Rational},Rational}
 
 abstract type AbstractMod <: Number end
 
+
+const value_type = Int                # storage type for the value in a Mod
+
+const max_mod = typemax(value_type)   # maximum modulus allowed
+const max_mul = isqrt(max_mod)        # maximum before widening may be necessary for multiplication
+const max_add = max_mod ÷ 2           # maximum before widening may be necessary for addition
+
+
 include("constructors.jl")
 include("basic_functions.jl")
 include("promotion.jl")

src/arithmetic.jl

@@ -2,10 +2,11 @@
 # (+)(a::GaussMod{N}, b::GaussMod{N}) where {N} = Mod{N}(widen(a.val) + widen(b.val))
 
 function (+)(a::Mod{N}, b::Mod{N}) where {N}
-    N <= typemax(Int32) ? Mod{N}(a.val + b.val) : Mod{N}(widen(a.val) + widen(b.val))
+    N <= max_add ? Mod{N}(a.val + b.val) : Mod{N}(widen(a.val) + widen(b.val))
 end
+
 function (+)(a::GaussMod{N}, b::GaussMod{N}) where {N}
-    N <= typemax(Int32) ? Mod{N}((a.val) + (b.val)) :
+    N <= max_add ? Mod{N}((a.val) + (b.val)) :
     GaussMod{N}(widen(a.val) + widen(b.val))
 end
 
@@ -21,10 +22,10 @@ end
 
 
 function (*)(a::Mod{N}, b::Mod{N}) where {N}
-    N <= typemax(Int32) ? Mod{N}(a.val * b.val) : Mod{N}(widemul(a.val, b.val))
+    N <= max_mul ? Mod{N}(a.val * b.val) : Mod{N}(widemul(a.val, b.val))
 end
 function (*)(a::GaussMod{N}, b::GaussMod{N}) where {N}
-    N <= typemax(Int32) ? GaussMod{N}(a.val * b.val) : GaussMod{N}(widemul(a.val, b.val))
+    N <= max_mul ? GaussMod{N}(a.val * b.val) : GaussMod{N}(widemul(a.val, b.val))
 end
 
 """

src/basic_functions.jl

@@ -1,14 +1,14 @@
 value(a::AbstractMod) = a.val
-modulus(a::Mod{N}) where N = N 
-modulus(a::GaussMod{N}) where N = N
+modulus(a::Mod{N}) where {N} = N
+modulus(a::GaussMod{N}) where {N} = N
 
 abs(a::AbstractMod) = abs(value(a))
 conj(x::Mod{N}) where {N} = x
-conj(x::GaussMod{N}) where N = GaussMod{N}(value(x)')
+conj(x::GaussMod{N}) where {N} = GaussMod{N}(value(x)')
 
 # real & imaginary parts
-real(x::GaussMod{N}) where N = Mod{N}(real(value(x)))
-imag(x::GaussMod{N}) where N = Mod{N}(imag(value(x)))
+real(x::GaussMod{N}) where {N} = Mod{N}(real(value(x)))
+imag(x::GaussMod{N}) where {N} = Mod{N}(imag(value(x)))
 
 
 function hash(x::AbstractMod, h::UInt64 = UInt64(0))

src/constructors.jl

@@ -1,10 +1,10 @@
 
 struct Mod{N} <: AbstractMod
-    val::Int
+    val::value_type
     function Mod{N}(x::T) where {N,T<:Integer}
         @assert N isa Integer && N > 1 "Modulus must be an integer greater than 1"
-        @assert N <= typemax(Int) "modulus is too large"
-        new{Int(N)}(mod(x, N))
+        @assert N <= max_mod "modulus is too large"
+        new{value_type(N)}(mod(x, N))
     end
 end
 
@@ -25,10 +25,10 @@ mod(z::Complex{<:Integer}, n::Integer) = Complex(mod(real(z), n), mod(imag(z), n
 
 
 struct GaussMod{N} <: AbstractMod
-    val::Complex{Int}
+    val::Complex{value_type}
     function GaussMod{N}(x::Complex{T}) where {N,T<:Integer}
         @assert N isa Integer && N > 1 "Modulus must be an integer greater than 1"
-        @assert N <= typemax(Int) "modulus is too large"
+        @assert N <= max_mod "modulus is too large"
         new{Int(N)}(mod(x, N))
     end
 end