updated README and doc strings

Project.toml

@@ -2,7 +2,7 @@ name = "LLLplus"
 uuid = "142c1900-a1c3-58ae-a66d-b187f9ca6423"
 keywords = ["lattice reduction", "lattice basis reduction", "SVP", "shortest vector problem", "CVP", "closest vector problem", "LLL", "Lenstra-Lenstra-Lovász", "Seysen", "Brun", "VBLAST", "subset-sum problem", "Lagarias-Odlyzko", "Bailey–Borwein–Plouffe formula"]
 license = "MIT"
-version = "1.3.0"
+version = "1.3.1"
 
 [deps]
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"

README.md

@@ -3,45 +3,27 @@
 [![Build Status](https://travis-ci.org/christianpeel/LLLplus.jl.svg?branch=master)](https://travis-ci.org/christianpeel/LLLplus.jl)
 [![](https://img.shields.io/badge/docs-devel-blue.svg)](https://christianpeel.github.io/LLLplus.jl/dev)
 
-LLLplus provides
+LLLplus provides lattice tools such as
 [Lenstra-Lenstra-Lovász](https://en.wikipedia.org/wiki/Lenstra%E2%80%93Lenstra%E2%80%93Lov%C3%A1sz_lattice_basis_reduction_algorithm)
-(LLL) lattice reduction, solvers for the
-[shortest vector problem](https://en.wikipedia.org/wiki/Lattice_problem#Shortest_vector_problem_(SVP))
-(SVP) and the [closest vector problem](https://en.wikipedia.org/wiki/Lattice_problem#Closest_vector_problem_.28CVP.29)
-(CVP), and related algorithms. These tools are
-used in cryptography, digital communication, and integer programming.
+(LLL) lattice reduction. This class of tools are of practical and
+theoretical use in cryptography, digital communication, and integer programming.
 This package is experimental and not a robust tool; use at your own
 risk :-)
 
-LLL lattice reduction is a powerful tool that is widely used in
-cryptanalysis, in cryptographic system design, in digital
-communications, and to solve other integer problems. The historical
-and practical prominence of the LLL technique in lattice tools is the
-reason for its use in the name "LLLplus". LLL reduction is often used
-as an approximate solution to the SVP.  We also include
-[Brun](https://archive.org/stream/skrifterutgitavv201chri#page/300/mode/2up)
-integer relations,
-[Seysen](http://link.springer.com/article/10.1007%2FBF01202355)
-lattice reduction, and
+LLLplus provides functions for LLL,
+[Seysen](http://link.springer.com/article/10.1007%2FBF01202355), and
 [Hermite-Korkine-Zolotarev](http://www.cas.mcmaster.ca/~qiao/publications/ZQW11.pdf)
-lattice reduction techniques.
-
-One application of lattice tools is in cryptanalysis; as an demo of a
-cryptanalytic attack, see the `subsetsum` function.  The LLL algorithm
-has been shown to solve many integer programming feasibility problems;
-see `integerfeasibility` for a demo. Lattice tools are often used to
-study and solve Diophantine problems; for example in "simultaneous
-diophantine approximation" a vector of real numbers are approximated
-by rationals with a common deonminator. For a demo function, see
-`rationalapprox`.  The
-[MUMIMO.jl](https://github.com/christianpeel/MUMIMO.jl) package
-demostrates how the `cvp`, `lll`, `brun`, `seysen`, and
-[`vblast`](https://en.wikipedia.org/wiki/Bell_Laboratories_Layered_Space-Time)
-functions can be used to solve (exactly or approximately) CVP problems
-and thereby decode multi-antenna signals.
-Finally, to see how the LLL can be used to find spigot formulas for
-irrationals, see `spigotBBP`.
-
+lattice reduction
+techniques. [Brun](https://archive.org/stream/skrifterutgitavv201chri#page/300/mode/2up)
+integer relations is included in the form of lattice
+reduction. Solvers for the [shortest
+vector](https://en.wikipedia.org/wiki/Lattice_problem#Shortest_vector_problem_(SVP))
+and the [closest
+vector](https://en.wikipedia.org/wiki/Lattice_problem#Closest_vector_problem_.28CVP.29)
+problems are also included; for more see the help text for the `lll`,
+`seysen`, `hkz`, `brun`, `svp`, and `cvp` functions. Several toy (demo)
+functions are also included; see the  `subsetsum`,
+`integerfeasibility`, `rationalapprox`, and  `spigotBBP` functions.
 
 <details>
    <summary><b>Examples</b> (click for details)</summary>
@@ -136,9 +118,11 @@ figure. This figure was generated using code in `test/perftest.jl`.
    <summary><b>Notes</b> (click for details)</summary>
 <p>
 
-The algorithm pseudocode in a [survey paper by Wuebben](http://www.ant.uni-bremen.de/sixcms/media.php/102/10740/SPM_2011_Wuebben.pdf) and the
+The 2020 [Simons Institute lattice](https://simons.berkeley.edu/programs/lattices2020)
+workshop, a
+[survey paper by Wuebben](http://www.ant.uni-bremen.de/sixcms/media.php/102/10740/SPM_2011_Wuebben.pdf), and the
 [monograph by Bremner](https://www.amazon.com/Lattice-Basis-Reduction-Introduction-Applications/dp/1439807027) 
-were helpful in writing the lattice reduction tools in LLLplus
+were helpful in writing the tools in LLLplus
 and are a good resource for further study. If you are trying to break
 one of the [Lattice Challenge](http://www.latticechallenge.org)
 records or are looking for robust, well-proven lattice tools, look at

docs/src/index.md

@@ -4,44 +4,28 @@
 CurrentModule = LLLplus
 ```
 
-LLLplus provides
+LLLplus provides lattice tools such as
 [Lenstra-Lenstra-Lovász](https://en.wikipedia.org/wiki/Lenstra%E2%80%93Lenstra%E2%80%93Lov%C3%A1sz_lattice_basis_reduction_algorithm)
-(LLL) lattice reduction, solvers for the
-[shortest vector problem](https://en.wikipedia.org/wiki/Lattice_problem#Shortest_vector_problem_(SVP))
-(SVP) and the [closest vector problem](https://en.wikipedia.org/wiki/Lattice_problem#Closest_vector_problem_.28CVP.29)
-(CVP), and related algorithms. These tools are
-used in cryptography, digital communication, and integer programming.
+(LLL) lattice reduction. This class of tools are of practical and
+theoretical use in cryptography, digital communication, and integer programming.
 This package is experimental and not a robust tool; use at your own
 risk :-)
 
-LLL lattice reduction is a powerful tool that is widely used in
-cryptanalysis, in cryptographic system design, in digital
-communications, and to solve other integer problems. The historical
-and practical prominence of the LLL technique in lattice tools is the
-reason for its use in the name "LLLplus". LLL reduction is often used
-as an approximate solution to the SVP.  We also include
-[Brun](https://archive.org/stream/skrifterutgitavv201chri#page/300/mode/2up)
-integer relations,
-[Seysen](http://link.springer.com/article/10.1007%2FBF01202355)
-lattice reduction, and
+LLLplus provides functions for LLL,
+[Seysen](http://link.springer.com/article/10.1007%2FBF01202355), and
 [Hermite-Korkine-Zolotarev](http://www.cas.mcmaster.ca/~qiao/publications/ZQW11.pdf)
-lattice reduction techniques.
-
-One application of lattice tools is in cryptanalysis; as an demo of a
-cryptanalytic attack, see the `subsetsum` function.  The LLL algorithm
-has been shown to solve many integer programming feasibility problems;
-see `integerfeasibility` for a demo. Lattice tools are often used to
-study and solve Diophantine problems; for example in "simultaneous
-diophantine approximation" a vector of real numbers are approximated
-by rationals with a common deonminator. For a demo function, see
-`rationalapprox`.  The
-[MUMIMO.jl](https://github.com/christianpeel/MUMIMO.jl) package
-demostrates how the `cvp`, `lll`, `brun`, `seysen`, and
-[`vblast`](https://en.wikipedia.org/wiki/Bell_Laboratories_Layered_Space-Time)
-functions can be used to solve (exactly or approximately) CVP problems
-and thereby decode multi-antenna signals.
-Finally, to see how the LLL can be used to find spigot formulas for
-irrationals, see `spigotBBP`.
+lattice reduction
+techniques. [Brun](https://archive.org/stream/skrifterutgitavv201chri#page/300/mode/2up)
+integer relations is included in the form of lattice
+reduction. Solvers for the [shortest
+vector](https://en.wikipedia.org/wiki/Lattice_problem#Shortest_vector_problem_(SVP))
+and the [closest
+vector](https://en.wikipedia.org/wiki/Lattice_problem#Closest_vector_problem_.28CVP.29)
+problems are also included; for more see the help text for the `lll`,
+`seysen`, `hkz`, `brun`, `svp`, and `cvp` functions. Several toy (demo)
+functions are also included; see the  `subsetsum`,
+`integerfeasibility`, `rationalapprox`, and  `spigotBBP` functions.
+
 
 ### Examples
 
@@ -125,9 +109,11 @@ figure. This figure was generated using code in `test/perftest.jl`.
 
 ### Notes
 
-The algorithm pseudocode in a [survey paper by Wuebben](http://www.ant.uni-bremen.de/sixcms/media.php/102/10740/SPM_2011_Wuebben.pdf) and the
+The 2020 [Simons Institute lattice](https://simons.berkeley.edu/programs/lattices2020)
+workshop, a
+[survey paper by Wuebben](http://www.ant.uni-bremen.de/sixcms/media.php/102/10740/SPM_2011_Wuebben.pdf), and the
 [monograph by Bremner](https://www.amazon.com/Lattice-Basis-Reduction-Introduction-Applications/dp/1439807027) 
-were helpful in writing the lattice reduction tools in LLLplus
+were helpful in writing the tools in LLLplus
 and are a good resource for further study. If you are trying to break
 one of the [Lattice Challenge](http://www.latticechallenge.org)
 records or are looking for robust, well-proven lattice tools, look at

src/cvp.jl

@@ -1,10 +1,10 @@
 """
     x=cvp(y,R)
 
-Solve the problem `argmin_x ||z-Hx||` for integer x using the technique from
-the paper below, where H=QR and y=Q'*z. The input vector `y` is of length `n`,
-with `H` of dimension `n` by `n`, and the returned vector `x` of length
-`n`.
+Solve the problem `argmin_x ||y-Rx||` for integer x using the technique from
+the paper below. The input vector `y` is of length `n`, with upper
+triangular `R` of dimension `n` by `n`, and the returned vector `x` of
+length `n`.
 
     x=cvp(y,R,infinite=Val(true),Umax=-1,Umax=-Umin,nxMax=Int(ceil(log2(n)*1e6)))
 
@@ -292,5 +292,3 @@ function decodeSVPAgrell(H::AbstractArray{Td,2}) where {Td<:Number}
         @goto LOOP
     end
 end
-
-

src/hard_sphere.jl

@@ -67,11 +67,15 @@ hard_sphere(x...) = hardsphere(x...)
 """
     xh = algIIsmart(yp,R,Qc)
 
-Find the closest xh for yp=R*xh + w, where w is some unknown noise and x(i)
-is from the range [0,...,Qc(i)-1]. This implements the "Alg II-smart"
-hard-decision sphere decoder as in Damen, El Gamal, and Caire, Trans It
-03. This function is not exported from LLLplus at present and may disappear
-in the future. 
+Find the minimizing xh = argmin_x ||yp- R*x||, where `yp` is a length N
+vector, `R` is NxM, `xh` will be a length M vector, and x(i) is
+from the range [0,...,Qc(i)-1]. R is assumed to be upper triangular.
+
+This implements the "Alg II-smart" hard-decision sphere decoder as in "On
+Maximum-Likelihood Detection and the Search for the Closest Lattice Point,"
+M. O. Damen, H. El Gamal, and G. Caire, Transactions Information Theory,
+v49, Oct 2003. This function is not exported from LLLplus at present and may
+disappear in the future.
 
 # Examples:
 ```jldoctest

src/hkz.jl

@@ -2,9 +2,9 @@
     B,T=hkz(H)
 
 Do Hermite-Korkine-Zolotarev (HKZ) reduction of the basis `H`, returning
-the reduced basis `B` and the unimodular rotation `T`. HKZ reduction is
-sometimes called "Hermite-Korkine-Zolotareff" or "Korkine-Zolotareff"
-reduction.
+the reduced basis `B` and the unimodular rotation `T` such that B = H*T.
+HKZ reduction is sometimes called "Hermite-Korkine-Zolotareff" or
+"Korkine-Zolotareff" reduction.
 
 Based on "Practical HKZ and Minkowski Lattice Reduction Algorithms" by Wen
 Zhang, Sanzheng Qiao, and Yimin Wei, 17 Aug. 2011.

test/perftest.jl

@@ -13,7 +13,7 @@ include("lrtest.jl")
 # getIntType is used to indicate what type we want the unimodular integer
 # matrix to have. We need to add methods of getIntType to handle the
 # DoubleFloats and Quadmath, since they are external packages that LLLplus
-# doesn't know about. So yes, we do a bit of type piracy.
+# doesn't know about. If this is type piracy, I think it's acceptable.
 import LLLplus.getIntType
 getIntType(Td::Type{Tr}) where {Tr<:Float128} = Int128
 getIntType(Td::Type{Tr}) where {Tr<:Double64} = Int128