[libmath-prime-util-perl] 06/07: Documentation

[Partha P. Mukherjee]

This is an automated email from the git hooks/post-receive script.

ppm-guest pushed a commit to annotated tag v0.09
in repository libmath-prime-util-perl.

commit f1ac8f0def0d4df9e266e4b3209322a9b7070129
Author: Dana Jacobsen <dana at acm.org>
Date:   Mon Jun 25 04:40:38 2012 -0600

    Documentation
---
 lib/Math/Prime/Util.pm    | 14 ++++++++++----
 lib/Math/Prime/Util/PP.pm | 43 ++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 50 insertions(+), 7 deletions(-)

diff --git a/lib/Math/Prime/Util.pm b/lib/Math/Prime/Util.pm
index f680a79..6a8f3b7 100644
--- a/lib/Math/Prime/Util.pm
+++ b/lib/Math/Prime/Util.pm
@@ -359,7 +359,9 @@ and L<Math::Factor::XS>.  It seems to be faster than L<Math::Pari> for
 everything except factoring certain 16-20 digit numbers.
 
 The module is thread-safe and allows concurrency between Perl threads while
-still sharing a prime cache.  It is not itself multithreaded.
+still sharing a prime cache.  It is not itself multithreaded.  The one caveat
+is on Win32 where you must use C<precalc> if the function will use primes
+(C<primes>, C<prime_count> greater than 900M, C<nth_prime> greater than 45M).
 
 
 =head1 FUNCTIONS
@@ -789,7 +791,10 @@ If you use later versions of Perl, or Perl 5.6.2 32-bit, or Perl 5.6.2 64-bit
 and keep numbers below C<~ 2^52>, then everything works.  The best solution is
 to update to a more recent Perl.
 
-The module is thread-safe and should allow good concurrency.
+The module is thread-safe and should allow good concurrency on all platforms
+that support Perl threads except Win32 (Cygwin works).  With Win32, either
+don't use threads or make sure C<prime_precalc> is called before using
+C<primes>, C<prime_count>, or C<nth_prime> with large inputs.
 
 
 =head1 PERFORMANCE
@@ -826,8 +831,9 @@ Perl modules, counting the primes to C<800_000_000> (800 million), in seconds:
       11.7   Math::Prime::XS             0.29     "" but needs a count API
       15.0   Bit::Vector                 7.2
       59.1   Math::Prime::Util::PP       0.09     Perl
-     548.1   RosettaCode sieve           2012-06  simplistic Perl
-   [hours]   Math::Primality             0.04     Perl + GMP
+     170.0   Faster Perl sieve (net)     2012-01  array of odds
+     548.1   RosettaCode sieve (net)     2012-06  simplistic Perl
+   >5000     Math::Primality             0.04     Perl + GMP
 
 
 
diff --git a/lib/Math/Prime/Util/PP.pm b/lib/Math/Prime/Util/PP.pm
index e9c40d8..51e0b35 100644
--- a/lib/Math/Prime/Util/PP.pm
+++ b/lib/Math/Prime/Util/PP.pm
@@ -1065,19 +1065,56 @@ Version 0.09
 
 =head1 SYNOPSIS
 
-  # TODO
+   .... See L<Math::Prime::Util> ...
+
 
 =head1 DESCRIPTION
 
-  # TODO
+   .... See L<Math::Prime::Util> ...
+
 
 =head1 LIMITATIONS
 
+The SQUFOF and Fermat factoring algorithms are not implemented yet.
+
+Some of the prime methods use more memory than they should, as the segmented
+sieve is not properly used in C<primes> and C<prime_count>.
+
 
 =head1 PERFORMANCE
 
+Performance compared to the XS/C code is quite poor for many operations.  Some
+operations that are relatively close for small and medium-size values:
+
+  next_prime / prev_prime
+  is_prime / is_prob_prime
+  miller_rabin
+  ExponentialIntegral / LogarithmicIntegral / RiemannR
+  primearray
+
+Operations that are slower include:
+
+  primes
+  random_prime / random_ndigit_prime
+  factor / all_factors
+  nth_prime
+  primecount
+
+Performance improvement in this code is still possible.  The prime sieve is
+over 2x faster than anything I was able to find online, but it is still has
+room for improvement.
+
+Fundamentally some of these operations will be much faster in C than Perl.  I
+expect any of the CPAN XS modules supporting related features to be faster,
+however if those modules are available, then the XS code in
+L<Math::Prime::Util> should be.
+
+Memory use will generally be higher for the PP code, and in some cases B<much>
+higher.  Some of this may be addressed in a later release.
+
+For small values (e.g. primes and prime counts under 10M) most of this will
+not matter.  
 
-  # TODO
 
 =head1 SEE ALSO
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libmath-prime-util-perl.git