- Improved docs, prime_mem_fill/1 is det.

jp-diegidio · Aug 28, 2016 · 7cc6875 · 7cc6875
1 parent 41af743
commit 7cc6875
Show file tree

Hide file tree

Showing 19 changed files with 185 additions and 151 deletions.
diff --git a/Code/nan_numerics_prime.pl b/Code/nan_numerics_prime.pl
@@ -22,13 +22,14 @@
 */
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-% (SWI-Prolog 7.3.24)
+% (SWI-Prolog 7.3.25)
 
 % TODO: Implement prime counting/n-th prime functions.
 % TODO: Implement probabilitic test error estimates?
-% TODO: Implement option for num. of probabilistic iterations?
 % TODO: Implement deterministic tests (elliptic curves)?
-% TODO: Improve compatibility with other Prolog systems?
+% TODO: Implement dynamic wheel with option for level?
+% TODO: Implement option for num. of probabilistic iterations?
+% TODO: Improve compatibility with other Prolog systems.
 
 :- module(prime,
 	[	prime_test/1,			% +N:posint
@@ -62,46 +63,59 @@
 
 /** <module> A simple prime number library
 
-The module =prime= provides predicates to test (positive integer) numbers
-for primality, find divisors and factor numbers, generate prime numbers in
-some interval, find consecutive prime numbers, and save/load all prime
-numbers up to some value to/from a file or stream.
+=|library(nan_numerics_prime)|=
+
+Module =prime= provides predicates to test (positive integer) numbers for
+primality, find divisors and factor numbers, generate prime numbers in some
+interval, find consecutive prime numbers, and save/load all prime numbers
+up to some value to/from a file or stream.
+
+All predicates in module =prime= are _safe_, i.e. validate input arguments
+and ensure steadfastness.  For maximum performance, user code can directly
+call the _unsafe_ =public= (not exported) predicates in module =prime_lgc=.
 
 Implements a variant of the *Miller-Rabin* primality test that is
 _deterministic_ for numbers up to =3317044064679887385961980=, otherwise
-it is _probabilistic_ with the number of iterations fixed at =20=.  For
-better performance, leverages a prime wheel of level =4= and memoization.
+it is _probabilistic_ with the number of iterations fixed at =20=.
 
-All predicates in this module are _safe_, i.e. validate input arguments and
-ensure steadfastness.  For maximum performance, user code can directly call
-the _unsafe_ =public= (not exported) predicates in sub-module =prime_lgc=.
+For better performance, leverages a prime wheel of level =4=, i.e.
+generated by the first =4= consecutive prime numbers, and the memoization
+of pairs of consecutive prime numbers.
 
 *NOTE*: Since the primality test in use is _probabilistic_ in general, this
 module is not suitable for cryptographic applications.
 
-Example:
+This library was developed and tested with:
+SWI-Prolog 7.3.25 - http://www.swi-prolog.org/
 
-	==
-	?- pack_install(nan_numerics_prime).
-	true.
-	
-	?- use_module(library(nan_numerics_prime)).
-	true.
+Usage example:
+
+    ==
+    ?- pack_install(nan_numerics_prime).
+    true.
+    
+    ?- use_module(library(nan_numerics_prime)).
+    true.
 
-	?- time(prime_right(1234567891012345678901234567890123456789011111,P)).
-	% 1,205 inferences, 0.000 CPU in 0.000 seconds (?% CPU, Infinite Lips)
-	P = 1234567891012345678901234567890123456789011139.
-	==
+    ?- time(prime_right(1234567891012345678901234567890123456789011111, P)).
+    % 1,205 inferences, 0.000 CPU in 0.000 seconds (?% CPU, Infinite Lips)
+    P = 1234567891012345678901234567890123456789011139.
+
+    ?- time(prime_lgc:right_(1234567891012345678901234567890123456789011111, P)).
+    % 1,197 inferences, 0.000 CPU in 0.000 seconds (?% CPU, Infinite Lips)
+    P = 1234567891012345678901234567890123456789011139.
+    ==
 
 @author		Julio P. Di Egidio
-@version	1.2.1-beta
+@version	1.2.2-beta
 @copyright	2016 Julio P. Di Egidio
 @license	GNU GPLv3
 @tbd		Implement prime counting/n-th prime functions.
 @tbd		Implement probabilitic test error estimates?
-@tbd		Implement option for num. of probabilistic iterations?
 @tbd		Implement deterministic tests (elliptic curves)?
-@tbd		Improve compatibility with other Prolog systems?
+@tbd		Implement dynamic wheel with option for level?
+@tbd		Implement option for num. of probabilistic iterations?
+@tbd		Improve compatibility with other Prolog systems.
 */
 
 :- use_module(nan_numerics_prime_lgc).
@@ -268,7 +282,7 @@
 %	@error	syntax_error(invalid_format)	Input format is invalid.
 %	@error	syntax_error(invalid_start)		Input values must start at =2=.
 %	@error	syntax_error(invalid_value)		Input values must be =posint=.
-%	@error	syntax_error(invalid_consec)	Input values must be consecutive.
+%	@error	syntax_error(invalid_consec)	Input values must be consecutive primes.
 %	@error	Errors from system:open/4.
 %	@error	Errors from system:read/2.
 %	@tbd	Improve parse errors?
@@ -398,20 +412,19 @@
 
 %!	prime_mem_clear is det.
 %
-%	Clears the memoization table.
+%	Clears all memoization.
 
 prime_mem_clear :-
 	prime_mem:clear_.
 
-%!	prime_mem_fill(+Sup:posint) is semidet.
+%!	prime_mem_fill(+Sup:posint) is det.
 %
-%	Fills the memoization table with all prime numbers less than or equal
-%	to Sup.
+%	Ensures that all pairs of consecutive prime numbers less than or equal
+%	to Sup have been memoized.
 
 prime_mem_fill(Sup) :-
 	must_be(posint, Sup),
-	Sup >= 2,
-	forall(prime_lgc:gen_(2, Sup, _), true).
+	ignore(forall(prime_lgc:gen_(2, Sup, _), true)).
 
 %!	prime_mem_count(-Count:nonneg) is det.
 %
@@ -424,22 +437,22 @@
 %!	prime_det_max(-Max:posint) is det.
 %
 %	Max is the maximum number for which the primality test is still
-%	deterministic.
+%	_deterministic_.
 
 prime_det_max(Max) :-
 	prime_prb:det_max_(Max_), Max = Max_.
 
 %!	prime_prb_mul(-Mul:posint) is det.
 %
-%	Mul is the number of iterations for the probabilistic primality test.
+%	Mul is the number of iterations for the _probabilistic_ primality test.
 
 prime_prb_mul(Mul) :-
 	prime_prb:prb_mul_(Mul_), Mul = Mul_.
 
 %!	prime_whl_lev(-Lev:posint) is det.
 %
-%	Lev is the level of the wheel, i.e. the number of its generating prime
-%	numbers.
+%	Lev is the number of consecutive prime numbers starting from =2= that
+%	generate the underlying prime wheel.
 
 prime_whl_lev(Lev) :-
 	prime_whl:lev_(Lev_), Lev = Lev_.

diff --git a/Code/nan_numerics_prime_lgc.pl b/Code/nan_numerics_prime_lgc.pl
@@ -22,7 +22,7 @@
 */
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-% (SWI-Prolog 7.3.24)
+% (SWI-Prolog 7.3.25)
 
 :- module(prime_lgc, []).
 
@@ -48,21 +48,20 @@
 
 /** <module> A simple prime number library :: logic
 
-The module =prime_lgc= provides low-level _unsafe_ =public= (not exported)
-predicates to test (positive integer) numbers for primality, find divisors
-and factor numbers, generate prime numbers in some interval, and find
-consecutive prime numbers.
+To allow for maximum performance, module =prime_lgc= provides _unsafe_
+=public= (not exported) predicates that user code can call directly instead
+of calling the _safe_ predicates exported by module =prime=.
 
-For maximum performance, user code can directly call the predicates in this
-module instead of the _safe_ predicates exported by module =prime=.
+For info on the implementation, see library(nan_numerics_prime).
 
 *NOTE*: Predicates in this module are _unsafe_, i.e. do not validate input
 arguments and are not steadfast.
 
 @author		Julio P. Di Egidio
-@version	1.2.1-beta
+@version	1.2.2-beta
 @copyright	2016 Julio P. Di Egidio
 @license	GNU GPLv3
+@see		library(nan_numerics_prime)
 @tbd		Integrate =isqrt= function from GMP?
 */
 

diff --git a/Code/nan_numerics_prime_mem.pl b/Code/nan_numerics_prime_mem.pl
@@ -22,7 +22,7 @@
 */
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-% (SWI-Prolog 7.3.24)
+% (SWI-Prolog 7.3.25)
 
 % TODO: Implement size limits?
 
@@ -39,13 +39,13 @@
 
 /** <module> A simple prime number library :: memoization
 
-The module =prime_mem= provides low-level predicates for the memoization of
+Module =prime_mem= provides low-level predicates for the memoization of
 pairs of consecutive prime numbers.
 
 *NOTE*: Predicates in this module are not meant for public use.
 
 @author		Julio P. Di Egidio
-@version	1.2.1-beta
+@version	1.2.2-beta
 @copyright	2016 Julio P. Di Egidio
 @license	GNU GPLv3
 @tbd		Implement size limits?

diff --git a/Code/nan_numerics_prime_pio.pl b/Code/nan_numerics_prime_pio.pl
@@ -22,7 +22,7 @@
 */
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-% (SWI-Prolog 7.3.24)
+% (SWI-Prolog 7.3.25)
 
 % TODO: Improve leveraging of library(pio)?
 
@@ -35,17 +35,17 @@
 
 /** <module> A simple prime number library :: pure I/O
 
-The module =prime_pio= provides low-level predicates to read/write from/to
-a file or stream all consecutive prime numbers starting from =2= and up to
-a certain limit that is determined by the caller.
+Module =prime_pio= provides low-level predicates to read/write from/to a
+file or stream all consecutive prime numbers starting from =2= and up to a
+certain limit that is determined by the caller.
 
 The accepted file format is a comma-separated list of the consecutive
 prime numbers starting from =2= and terminated by a period.
 
 *NOTE*: Predicates in this module are not meant for public use.
 
 @author		Julio P. Di Egidio
-@version	1.2.1-beta
+@version	1.2.2-beta
 @copyright	2016 Julio P. Di Egidio
 @license	GNU GPLv3
 */

diff --git a/Code/nan_numerics_prime_prb.pl b/Code/nan_numerics_prime_prb.pl
@@ -22,7 +22,7 @@
 */
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-% (SWI-Prolog 7.3.24)
+% (SWI-Prolog 7.3.25)
 
 % TODO: Implement test error estimates?
 % TODO: Implement option for num. of iterations?
@@ -36,7 +36,7 @@
 
 /** <module> A simple prime number library :: probabilistic
 
-The module =prime_prb= provides low-level predicates to test candidate
+Module =prime_prb= provides low-level predicates to test candidate
 primality of numbers based on a probabilistic primality test.
 
 Implements a variant of the *Miller-Rabin* primality test that is
@@ -46,7 +46,7 @@
 *NOTE*: Predicates in this module are not meant for public use.
 
 @author		Julio P. Di Egidio
-@version	1.2.1-beta
+@version	1.2.2-beta
 @copyright	2016 Julio P. Di Egidio
 @license	GNU GPLv3
 @tbd		Implement test error estimates?

diff --git a/Code/nan_numerics_prime_whl.pl b/Code/nan_numerics_prime_whl.pl
@@ -22,7 +22,9 @@
 */
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-% (SWI-Prolog 7.3.24)
+% (SWI-Prolog 7.3.25)
+
+% TODO: Implement dynamic wheel with option for level?
 
 :- module(prime_whl, []).
 
@@ -34,15 +36,17 @@
 
 /** <module> A simple prime number library :: wheel
 
-The module =prime_whl= provides low-level predicates to test candidate
-primality of numbers based on a prime wheel of level =4=.
+Module =prime_whl= provides low-level predicates to test candidate
+primality of numbers based on a prime wheel of level =4=, i.e. generated by
+the first =4= consecutive prime numbers.
 
 *NOTE*: Predicates in this module are not meant for public use.
 
 @author		Julio P. Di Egidio
-@version	1.2.1-beta
+@version	1.2.2-beta
 @copyright	2016 Julio P. Di Egidio
 @license	GNU GPLv3
+@tbd		Implement dynamic wheel with option for level?
 */
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -91,7 +95,8 @@
 
 %!	lev_(-Lev:posint) is det.
 %
-%	Lev is the number of prime numbers generating this wheel.
+%	Lev is the number of consecutive prime numbers starting from =2= that
+%	generate this wheel.
 
 lev_(4/*lev*/).
 

diff --git a/Deploy/pack.bat b/Deploy/pack.bat
@@ -19,7 +19,7 @@
 :  	You should have received a copy of the GNU General Public License
 :  	along with Nan.Numerics.Prime.  If not, see <http://www.gnu.org/licenses/>.
 
-@rem Nan.Numerics.Prime::pack.bat (1.2.1-beta)
+@rem Nan.Numerics.Prime::pack.bat (1.2.2-beta)
 @rem Author: Julio P. Di Egidio ([email protected])
 @rem Requires PowerShell 4.0 and .NET 4.5
 

diff --git a/HISTORY b/HISTORY
@@ -1,17 +1,24 @@
+Nan.Numerics.Prime/Prolog 1.2.2-beta
 Nan.Numerics.Prime
 A simple prime number library
 Copyright 2016 Julio P. Di Egidio
 Licensed under GNU GPLv3.
 http://julio.diegidio.name/Projects/Nan.Numerics.Prime/
 https://github.com/jp-diegidio/Nan.Numerics.Prime-Prolog/
 
+Version 1.2.2-beta:
+-------------------
+- BREAKING: prime_mem_fill/1 becomes det.
+- Improved documentation.
+- Upgraded to SWI-Prolog 7.3.25.
+
 Version 1.2.1-beta:
 -------------------
-- Integration of tests into SWI pack system.
+- Integrated tests into SWI pack system.
 - Bundled Nan.Windows.Scripts (1.2.1).
 - Few non-critical code improvements.
 - Created history file.
 
 Version 1.2-beta:
 -----------------
-- Tagged version 1.2-beta.
+- Baseline version 1.2-beta.