Brun, docs, license

* added Documnter.jl docs
* added Brun lattice reduction. The comment on commit b767593
  saying Brun was added then was incorrect
* Added the sizereduction function
* added functions returning lattic metrics for a matrix:
   orthogonalityFactor, hermiteFactor, seysenCond
* adde isLLLreduced, issizereduced
* updated license to match standard MIT form

LICENSE.md

@@ -1,24 +1,21 @@
-The LLLplus.jl package is licensed under the MIT License. The package
-consists of the contents of the /src and other files in this
-repository. 
+MIT License
 
-> Copyright (c) 2019: Christian Peel
->
-> Permission is hereby granted, free of charge, to any person obtaining
-> a copy of this software and associated documentation files (the
-> "Software"), to deal in the Software without restriction, including
-> without limitation the rights to use, copy, modify, merge, publish,
-> distribute, sublicense, and/or sell copies of the Software, and to
-> permit persons to whom the Software is furnished to do so, subject to
-> the following conditions:
->
-> The above copyright notice and this permission notice shall be
-> included in all copies or substantial portions of the Software.
->
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-> EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-> MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-> IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-> CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-> TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-> SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2019: Christian Peel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Project.toml

@@ -2,7 +2,7 @@ name = "LLLplus"
 uuid = "142c1900-a1c3-58ae-a66d-b187f9ca6423"
 keywords = ["lattice reduction", "LLL", "Seysen", "closest vector problem"]
 authors = ["Christian Peel <[email protected]>"]
-version = "1.1.0"
+version = "1.2.0"
 
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"

README.md

@@ -1,40 +1,41 @@
 # LLLplus.jl
 
 [![Build Status](https://travis-ci.org/christianpeel/LLLplus.jl.svg?branch=master)](https://travis-ci.org/christianpeel/LLLplus.jl)
-<!---
-[![LLLplus](http://pkg.julialang.org/badges/LLLplus_release.svg)](http://pkg.julialang.org/?pkg=LLLplus&ver=0.7)
--->
 
-Lattice reduction and related lattice tools are used in 
+Lattice reduction and related lattice tools are used in
 cryptography, digital communication, and integer programming.  LLLplus
-includes Lenstra-Lenstra-Lovacsz (LLL) lattice reduction, Seysen
-lattice reduction, VBLAST matrix decomposition, and a closest vector
-problem (CVP) solver.
+includes Lenstra-Lenstra-Lovacsz (LLL), Brun,
+and Seysen lattice reduction; VBLAST matrix decomposition; and a closest vector
+problem (CVP) solver. The historical and practical prominence of the
+LLL technique in lattice tools is the reason for its use in the
+name "LLLplus".
 
 [LLL](https://en.wikipedia.org/wiki/Lenstra%E2%80%93Lenstra%E2%80%93Lov%C3%A1sz_lattice_basis_reduction_algorithm)
 [1] 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.  LLL reduction is
 often used as an approximate solution to the
 [shortest vector problem](https://en.wikipedia.org/wiki/Lattice_problem#Shortest_vector_problem_.28SVP.29)
-(SVP).  We also include Gauss/Lagrange 2-dimensional lattice reduction
-as a learning tool, and Seysen [2] lattice reduction which
-simultaneously reduces a basis `B` and its dual `inv(B)'`. The LLL and
-Seysen algorithms are based on [3]. The
+(SVP).  We also include Gauss/Lagrange, Brun [2] and Seysen [3]
+lattice reduction techniques. The LLL, Brun, and
+Seysen algorithms are based on [4]. The
 [CVP](https://en.wikipedia.org/wiki/Lattice_problem#Closest_vector_problem_.28CVP.29)
-solver is based on [4] and can handle lattices and bounded integer
+solver is based on [5] and can handle lattices and bounded integer
 constellations.
-<!-- Many GPS researchers refer to the CVP as the "integer least squares" -->
-<!-- problem, while digital communication researchers often call it the -->
-<!-- [sphere-decoder](https://en.wikipedia.org/wiki/Lattice_problem#Sphere_decoding). -->
 
 We also include code to do a
 [Vertical-Bell Laboratories Layered Space-Time](https://en.wikipedia.org/wiki/Bell_Laboratories_Layered_Space-Time)
-(V-BLAST) [5] matrix decomposition which is used in digital
-communications. The LLL,
-Seysen, V-BLAST, and CVP functions are used to solve (exactly or
-approximately) CVP problems in encoding and decoding multi-terminal
-signals.
+(V-BLAST) [6] matrix decomposition which is used in digital
+communications. The LLL, Brun, Seysen, V-BLAST, and CVP functions are
+used to solve (exactly or approximately) CVP problems in encoding and
+decoding multi-terminal signals.
+
+Another important application of is in cryptanalysis: attacking the
+security of security systems. As an example of the sort of tools that
+are used in cryptanalysis, see the `subsetsum`
+function.  Another important application is in integer programming,
+where the LLL algorithm has been shown to solve the integer
+programming feasibility problem; see `integerfeasibility`.
 
 ### Examples
 
@@ -45,7 +46,7 @@ package on random lattices.
 Pkg.add("LLLplus")
 using LLLplus
 
-# Time LLL, VBLAST decomposition of a complex matrix with randn entries 
+# Time LLL, VBLAST decomposition of a complex matrix with randn entries
 N = 1000;
 H = randn(N,N) + im*randn(N,N);
 println("Testing LLL on $(N)x$(N) complex matrix...")
@@ -66,7 +67,7 @@ println("Testing Seysen on same $(N)x$(N) matrix...")
 
 ### Execution Time results
 
-On this page we give a few performance results obtained from the
+The following performance results are obtained from the
 following command in the top-level LLLplus directory:
 `julia -e 'include("benchmark/perftest.jl")'`
 In the tests we time execution of the lattice-reduction functions,
@@ -83,67 +84,70 @@ emulate unit-variance Gaussian-distributed values.
 
 ![Time vs matrix size](benchmark/perfVsNfloat64.png)
 
-Though the focus of the package is on floating-point, 
+Though the focus of the package is on floating-point,
 all the modules can handle a variety of data types. In the next figure
 we show execution time for several datatypes (Int32, Int64,
-Int128, Float32, Float64, DoublFloat, BitInt, and BigFloat) which are used to
+Int128, Float32, Float64, DoubleFloat, BitInt, and BigFloat) which are used to
 generate 40 128x128 matrices, over which execution time for the lattice
 reduction techniques is averaged.  The vertical axis is a logarithmic
 representation of execution time as in the previous
 figure.
 
 ![Time vs data type](benchmark/perfVsDataType.png)
 
-The algorithm pseudocode in the monograph [6] and the survey paper [3]
+The algorithm pseudocode in the monograph [7] and the survey paper [4]
 were very helpful in writing the lattice reduction tools in LLLplus
-and are a good resource for further study.
-
-LLLplus does not pretend to be a tool for number-theory work. For
-that, see the [Nemo.jl](https://github.com/wbhart/Nemo.jl) package
-which uses the [FLINT](http://flintlib.org/) C library to do LLL
+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
+[fplll](https://github.com/fplll/fplll). Also, for many
+number-theoretic problems the
+[Nemo.jl](https://github.com/wbhart/Nemo.jl) package is appropriate;
+it uses the [FLINT](http://flintlib.org/) C library to do LLL
 reduction on Nemo-specific data types.
+Finally, LLLplus should have version number of about 0.2.0 rather
+than 1.2.0; please treat the package as experimental.
 
 ### Future
 
 Possible improvements include:
-* Add Block-Korkin-Zolotarev lattice redution, with improvements
-  as in [7], code for Babai's simple CVP approximation [8], and
-  Brun's integer relation decomposition.
+* Add Block-Korkin-Zolotarev lattice reduction, with improvements
+  as in [8], code for Babai's CVP approximation [9], and explicit CVP
+  approximations using LLL, Brun, Seysen, and VBLAST.
 * The [SVP](http://www.latticechallenge.org/svp-challenge/) Challenge
   and the
   [Ideal](http://www.latticechallenge.org/ideallattice-challenge/)
-  Lattice challenge have code to generate lattices for the respective
-  contests which could be used or duplicated to make challenging
-  performance tests. The main
-  [Lattice](http://www.latticechallenge.org/) Challenge also lists
-  references which could be used to replicate tests.
+  Lattice challenge have code to generate lattices
+  which could be used to make challenging performance tests.
 * Compare with the [fplll](https://github.com/fplll/fplll) library,
   the [Number Theory Library](http://www.shoup.net/ntl/), and
   NEMO/FLINT. 
-<!-- * Make additions to -->
-<!--   [ArbFloats](https://github.com/JuliaArbTypes/ArbFloats.jl) and -->
-<!--   [IntervalArithmetic](https://github.com/eeshan9815/IntervalArithmetic.jl) -->
-<!--   to enable them to work. -->
+
+
 
 ### References
 
-[1] A. K. Lenstra; H. W. Lenstra Jr.; L. Lovász, ["Factoring polynomials with rational coefficients"](http://ftp.cs.elte.hu/~lovasz/scans/lll.pdf). Mathematische Annalen 261, 1982
+[1] A. K. Lenstra; H. W. Lenstra Jr.; L. Lovász, ["Factoring polynomials with rational coefficients"](http://ftp.cs.elte.hu/~lovasz/scans/lll.pdf). Mathematische Annalen 261, 1982.
+
+[2] V. Brun,
+["En generalisation av kjedebrøken I,"](https://archive.org/stream/skrifterutgitavv201chri#page/300/mode/2up)
+Skr. Vidensk. Selsk. Kristiana, Mat. Nat. Klasse, 1919.
 
-[2] M. Seysen, ["Simultaneous reduction of a lattice basis and its reciprocal basis"](http://link.springer.com/article/10.1007%2FBF01202355) Combinatorica, 1993.
+[3] M. Seysen, ["Simultaneous reduction of a lattice basis and its reciprocal basis"](http://link.springer.com/article/10.1007%2FBF01202355) Combinatorica, 1993.
 
-[3] D. Wuebben, D. Seethaler, J. Jalden, and G. Matz, ["Lattice Reduction - A Survey with Applications in Wireless Communications"](http://www.ant.uni-bremen.de/sixcms/media.php/102/10740/SPM_2011_Wuebben.pdf). IEEE Signal Processing Magazine, 2011.
+[4] D. Wuebben, D. Seethaler, J. Jalden, and G. Matz, ["Lattice Reduction - A Survey with Applications in Wireless Communications"](http://www.ant.uni-bremen.de/sixcms/media.php/102/10740/SPM_2011_Wuebben.pdf). IEEE Signal Processing Magazine, 2011.
 
-[4] A. Ghasemmehdi, E. Agrell, ["Faster Recursions in Sphere Decoding"](https://publications.lib.chalmers.se/records/fulltext/local_141586.pdf) IEEE
+[5] A. Ghasemmehdi, E. Agrell, ["Faster Recursions in Sphere Decoding"](https://publications.lib.chalmers.se/records/fulltext/local_141586.pdf) IEEE
 Transactions on Information Theory, vol 57, issue 6 , June 2011.
 
-[5] P. W. Wolniansky, G. J. Foschini, G. D. Golden, R. A. Valenzuela, ["V-BLAST: An Architecture for Realizing Very High Data Rates Over the Rich-Scattering Wireless Channel"](http://ieeexplore.ieee.org/xpl/login.jsp?tp=&arnumber=738086). Proc. URSI
+[6] P. W. Wolniansky, G. J. Foschini, G. D. Golden, R. A. Valenzuela, ["V-BLAST: An Architecture for Realizing Very High Data Rates Over the Rich-Scattering Wireless Channel"](http://ieeexplore.ieee.org/xpl/login.jsp?tp=&arnumber=738086). Proc. URSI
 ISSSE: 295–300, 1998. 
 
-[6] M. R. Bremner, ["Lattice Basis Reduction: An Introduction to the LLL
+[7] M. R. Bremner, ["Lattice Basis Reduction: An Introduction to the LLL
  Algorithm and Its Applications"](https://www.amazon.com/Lattice-Basis-Reduction-Introduction-Applications/dp/1439807027) CRC Press, 2012.
 
-[7] Y. Chen, P. Q. Nguyen, ["BKZ 2.0: Better Lattice Security Estimates"](http://www.iacr.org/archive/asiacrypt2011/70730001/70730001.pdf). Proc. ASIACRYPT 2011.
+[8] Y. Chen, P. Q. Nguyen, ["BKZ 2.0: Better Lattice Security Estimates"](http://www.iacr.org/archive/asiacrypt2011/70730001/70730001.pdf). Proc. ASIACRYPT 2011.
 
-[8] L. Babai, ["On Lovász’ lattice reduction and the nearest lattice point problem"](https://link.springer.com/article/10.1007/BF02579403),
+[9] L. Babai, ["On Lovász’ lattice reduction and the nearest lattice point problem"](https://link.springer.com/article/10.1007/BF02579403),
 Combinatorica, 1986.
 

docs/make.jl

@@ -0,0 +1,9 @@
+using LLLplus, Documenter, MacroTools
+
+makedocs(
+         sitename="LLLplus.jl",
+         pages = [
+                  "Home" => "index.md",
+                  "Functions" => "functions.md"],
+         format = Documenter.HTML(prettyurls = haskey(ENV, "CI")))
+

docs/src/functions.md

@@ -0,0 +1,25 @@
+# Functions
+
+
+```@meta
+DocTestSetup = quote
+    using LLLplus
+    using LinearAlgebra
+end
+```
+```@docs
+    lll
+    cvp
+    svp
+    gauss
+    seysen
+    vblast
+    subsetsum
+    integerfeasibility
+    hard_sphere
+    issizereduced
+    islllreduced
+    orthogonalitydefect
+    hermitefactor
+    seysencond
+```