added documentation

Math/NumberTheory/Moduli/SquareRoots.hs

@@ -1,4 +1,14 @@
-module Math.NumberTheory.Moduli.SquareRoots (sqrts) where
+-- |
+-- Module:      Math.NumberTheory.Moduli.SquareRoots
+-- Copyright:   (c) 2015 by Dr. Lars Brünjes
+-- Licence:     MIT
+-- Maintainer:  Dr. Lars Brünjes <[email protected]>
+-- Stability:   Provisional
+-- Portability: portable
+--
+-- This module provides a function to find all square roots of a number modulo another number.
+module Math.NumberTheory.Moduli.SquareRoots (
+    sqrts ) where
 
 import Data.List (sort)
 import Math.NumberTheory.Primes.Factorisation (factorise)
@@ -31,6 +41,8 @@ sqrtsPP a (p, e)
     where
         m = p ^ e
 
+-- |@sqrts a m@ finds all square roots of @a@ modulo @m@,
+--  where @a@ is an arbitrary integer and @m@ is a positive integer.
 sqrts :: Integer -> Integer -> [Integer]
 sqrts a m
     | a <  0       = error $ "a must not be negative, but a == " ++ show a ++ " < 0."

Math/NumberTheory/Pell.hs

@@ -1,4 +1,21 @@
-module Math.NumberTheory.Pell ( solve, getReps, getMinimalReps, equivalent, mul, solvePlusOne ) where
+-- |
+-- Module:      Math.NumberTheory.Pell
+-- Copyright:   (c) 2015 by Dr. Lars Brünjes
+-- Licence:     MIT
+-- Maintainer:  Dr. Lars Brünjes <[email protected]>
+-- Stability:   Provisional
+-- Portability: portable
+--
+-- This module provides a function to solve generalized Pell Equations, 
+-- using the "LMM Algorithm" described by John P. Robertson in
+-- <http://http://www.jpr2718.org/pell.pdf>.
+-- A /generalized Pell Equation/ is a diophantine equation of the form
+-- @x^2 - dy^2 = n@, where @d@ is a positive integer which is not a square
+-- and where @n@ is a non-zero integer.
+-- We are looking for solutions @(x,y)@, where @x@ and @y@ are non-negative integers.
+module Math.NumberTheory.Pell ( 
+    Solution,
+    solve ) where
 
 import Control.Arrow ((***))
 import Data.List (sort, nub)
@@ -31,6 +48,9 @@ getRS d m z =
             [] -> Nothing
             (rs : _) -> Just rs
 
+-- |Represents a solution to a generalized Pell Equation.
+-- The first component is the value of x,
+-- the second component that of y.
 type Solution = (Integer, Integer)
 
 solvePlusOne :: Integer -> Solution
@@ -78,6 +98,10 @@ getMinimalReps d n = ((r, s), map toMinimal reps) where
     ((r, s), reps) = getReps d n
     toMinimal (x, y) = minimum $ map (abs *** abs) $ filter (\(x', y') -> x' * y' >= 0) [(x, y), mul d (r, s) (x, y), mul d (r, -s) (x, y)]
 
+-- |@solve d n@ calculates all non-negative integer solutions of the generalized Pell Equation
+-- x^2 - @d@y^2 = @n@, 
+-- where @d@ must be a positive integer which is not a square,
+-- and @n@ must be a non-zero integer.
 solve :: Integer -> Integer -> [Solution]
 solve d n 
     | d <= 0     = error $ "D must be positive, but D == " ++ show d ++ "."
@@ -89,7 +113,3 @@ solve d n
                         go xys' = normalize xys' ++ go (step xys')
                         normalize = sort . nub
                         step = map (mul d (r, s))
-
-equivalent :: Integer -> Integer -> (Integer, Integer) -> (Integer, Integer) -> Bool
-equivalent d n (x, y) (r, s) = nDivides (x * r - d * y * s) && nDivides (x * s - y * r) where
-    nDivides z = (z `mod` n) == 0

pell.cabal

@@ -4,17 +4,17 @@
 name:                pell
 version:             0.1.0.0
 synopsis:            Package to solve the Generalized Pell Equation.
--- description:         
+description:         Finds all solutions of the generalized Pell Equation.   
 homepage:            https://github.com/brunjlar/pell
 license:             MIT
 license-file:        LICENSE
-author:              Dr. Lars Bruenjes
+author:              Lars Bruenjes
 maintainer:          [email protected]
--- copyright:           
-category:            Math
+copyright:           (c) 2015 by Dr. Lars Brünjes 
+category:            Math, Algorithms, Number Theory
 build-type:          Simple
 extra-source-files:  README.md
-cabal-version:       >=1.22.2.0
+cabal-version:       >=1.20.0
 
 library
   exposed-modules:     Math.NumberTheory.Pell, Math.NumberTheory.Moduli.SquareRoots
@@ -41,6 +41,15 @@ Test-Suite test-pell
                        containers, 
                        QuickCheck >= 2.8, 
                        primes, 
-                       Cabal >= 1.22.2, 
+                       Cabal >= 1.20.0,
                        cabal-test-quickcheck
   default-language:    Haskell2010
+
+source-repository head
+  type:                git
+  location:            https://github.com/brunjlar/pell
+
+source-repository this
+  type:                git
+  location:            https://github.com/brunjlar/pell
+  tag:                 0.1.0.0