Provided by: mlucas_17.1-3ubuntu2_amd64 bug

NAME

       mlucas - program to perform Lucas-Lehmer test on a Mersenne number, 2 ^ p - 1

SYNOPSIS

       mlucas
       mlucas -h
       mlucas -s tiny | t | small | s | medium | m | large | l | huge | h | all | a [-iters 100 |
       1000 | 10000 [-nthread threads]]
       mlucas -m exponent | -f exponent [-iters 100 | 1000 | 10000 [-nthread threads]]
       mlucas -fftlen fft_length [-radset radix_set] [-m exponent | -f exponent] -iters 100 |
       1000 | 10000 [-nthread threads]

DESCRIPTION

       This manual page documents briefly the mlucas command.

       mlucas is an open-source (and free/libre) program for performing Lucas-Lehmer test on
       prime-exponent Mersenne numbers, that is, integers of the form 2 ^ p - 1, with prime
       exponent p.  In short, everything you need to search for world-record Mersenne primes!  It
       has been used in the verification of various Mersenne primes, including the 45th, 46th and
       48th found Mersenne prime.

       You may use it to test any suitable number as you wish, but it is preferable that you do
       so in a coordinated fashion, as part of the Great Internet Mersenne Prime Search (GIMPS).
       For more information on GIMPS, see the Great Internet Mersenne Prime Search subsection
       within the NOTES section and SEE ALSO section.  Note that mlucas is not (yet) as efficient
       as the main GIMPS client, George Woltman's Prime95 program (a.k.a. mprime for the
       (gnu/)linux version), but that program is not truly open-source (and free/libre), since it
       requires the user to abide by the prize-sharing rules set by its author (incompatible with
       freedom to run the program as you wish, for any purpose), should a user be lucky enough to
       find a new prime eligible for one of the monetary prizes offered by the Electronic Freedom
       Foundation (see EFF Cooperative Computing Awards <https://www.eff.org/awards/coop> for
       details).

       mlucas reads the exponents from the $MLUCAS_PATH/worktodo.ini file.  Results are written
       to the $MLUCAS_PATH/results.txt file and the exponent-specific $MLUCAS_PATH/*.stat file
       (see section FILES for details).  Error messages are written to stderr and the
       $MLUCAS_PATH/*.stat file.  Exponents can also be passed as command-line arguments but this
       is mainly used for debugging (see section OPTIONS for details).  In addition, mlucas can
       perform the Pe'pin primality test on Fermat numbers 2 ^ (2 ^ n) + 1, using an exponent-
       optimized fast-transform length much like that used for testing Mersenne numbers.

       New users are urged to jump straight to the EXAMPLE section and follow the examples and
       pointers to other sections.  Users with little time for in-depth reading should at least
       read the NOTES, BUGS and EXAMPLE sections for a brief introduction to the Great Internet
       Mersenne Prime Search, undesirable restrictions and common usages.  FILES section is also
       highly recommended since it describes the mlucas configuration files used for host-
       specific optimization and other mlucas-generated files.  Advanced users should also peruse
       the OPTIONS section since it introduces less-commonly-used advanced options.  Experienced
       users who find this manual inadequate should consult the SEE ALSO section for further
       information.  Lastly, the Mlucas README, available both online and offline, is highly
       recommended since it is written and maintained by the author of mlucas and should be
       considered the final authority.

OPTIONS

       mlucas follows the traditional POSIX (see standards(7) for details) command line syntax,
       with short options starting with one dashes (`-').  A summary of options is included
       below.  A complete description is in the SEE ALSO section.

       -h     Show version of program and summary of options.

       -s t, -s tiny
              Run 100-iteration self-test on a set of 32 Mersenne exponents, ranging from 173431
              to 2455003.  This will take around 1 minute on a fast (pre-2010) CPU.

       -s s, -s small
              Run 100-iteration self-test on a set of 24 Mersenne exponents, ranging from 173431
              to 1245877.  This will take around 10 minutes on a fast (pre-2010) CPU.

       -s m, -s medium
              Run 100-iteration self-test on a set of 24 Mersenne exponents, ranging from 1327099
              to 9530803.  This will take around an hour on a fast (pre-2010) CPU.

       -s l, -s large
              Run 100-iteration self-test on a set of 24 Mersenne exponents, ranging from
              10151971 to 72851621.  This will take around an hour on a fast (pre-2010) CPU.

       -s h, -s huge
              Run 100-iteration self-test on a set of 16 Mersenne exponents, ranging from
              77597293 to 282508657.  This will take a couple of hours on a fast (pre-2010) CPU.

       -s a, -s all
              Run 100-iteration self-test on all Mersenne exponents and all FFT radix sets.  This
              will take several hours on a fast (pre-2010) CPU.

       -fftlen fft_length
              This allows the user to specify the length of the fast-transform (FFT) used to
              effect the large-integer modular multiply which is at the heart of all such
              nonfactorial primality tests.  The length unit here is in terms of the number of
              double-precision machine words used in the multiword-integer encoding of the
              primality test residue which is both input and result of each of said multiplies.
              Because mlucas is intended for testing numbers with many millions of bits, we
              generally speak of these FFT lengths in terms of kilodoubles (= 2 ^ 10 or 1024
              doubles).  If fft_length is one of the available FFT lengths (in kilodoubles), run
              all available FFT radices available at that length, unless the -radset flag is also
              invoked (see below for details).  If -fftlen is invoked with either the -m or -f
              flag, the self-tests will perform the first 100 iterations of a Lucas-Lehmer test
              (-m) or Pe'pin test (-f) on the user-specified Mersenne or Fermat number.  If no
              user-set exponent is invoked, do 100 Lucas-Lehmer test iterations using the default
              self-test Mersenne or Fermat exponent for that FFT length.  The program uses this
              to find the optimal radix set for a given FFT length on your hardware.

       -iters 100 | 1000 | 10000
              Do 100, 1000 or 10000 self-test iterations of the type determined by the modulus-
              related options (-s / -m = Lucas-Lehmer test iterations with initial seed 4, -f =
              Pe'pin test squarings with initial seed 3).  Default is 100 iterations.

       -radset radix_set
              Specify index of a set of complex FFT radices to use, based on the big selection
              table in the function get_fft_radices().  This requires a supported value of
              -fftlen to be specified, meaning (for an FFT length supported by the program) an
              index 0, 1, 2, ... and so on.  0 is always a valid radix set index; how high one
              can go in the enumeration depends on the FFT length.  As soon as the user tries an
              index out of range of the current FFT length, the program will error-exit with an
              informational message to that effect, which also notes the maximum allowable radix
              set index for that FFT length.

       -nthread threads
              For multithread-enabled (default) build, perform the test in parallel mode with
              this many threads.

       -m exponent
              Perform a Lucas-Lehmer primality test of the Mersenne number M(exponent) = 2 ^
              exponent - 1, where exponent must be an odd prime.  If -iters is also invoked, this
              indicates a timing test.  This requires suitable added arguments (-fftlen and,
              optionally, -radset) to be supplied.  If the -fftlen option (and optionally
              -radset) is also invoked but -iters is not, the program first checks the first line
              of the $MLUCAS_PATH/worktodo.ini file to see if the assignment specified there is a
              Lucas-Lehmer test with the same exponent as specified via the -m argument.  If so,
              the -fftlen argument is treated as a user override of the default FFT length for
              the exponent.  If -radset is also invoked, this is similarly treated as a user-
              specified radix set for the user-set FFT length; otherwise the program will use the
              $MLUCAS_PATH/mlucas.cfg file to select the radix set to be used for the user-forced
              FFT length.  If the $MLUCAS_PATH/worktodo.ini file entry does not match the -m
              value, a set of timing self-tests is run on the user-specified Mersenne number
              using all sets of FFT radices available at the specified FFT length.  If the
              -fftlen option is not invoked, the tests use all sets of FFT radices available at
              that exponent's default FFT length.  Use this to find the optimal radix set for a
              single given Mersenne exponent on your hardware, similarly to the -fftlen option.
              Perform 100 iterations, or as many as specified via the -iters flag.

       -f exponent
              Perform a base-3 Pe'pin test on the Fermat number F(exponent) = 2 ^ (2 ^ exponent)
              + 1.  If desired this can be invoked together with the -fftlen option as for the
              Mersenne-number self-tests (see above notes on the -m flag; note that not all FFT
              lengths supported for -m are available for -f: -m permits FFT lengths of form odd *
              2 ^ n with odd = any of 1, 3, 5, 7, 9, 11, 13, 15; -f allows odd = 1, 7, 15 and 63)
              Optimal radix sets and timings are written to the $MLUCAS_PATH/fermat.cfg file.
              Perform 100 iterations, or as many as specified via the -iters flag.

EXIT STATUS

       The list of exit status values is limited. It is not possible to determine the cause of
       failure from the exit status value alone. However, mlucas make use of stderr to print
       error messages as well as saving them to the $MLUCAS_PATH/*.stat file, where * is in the
       form

           pexponent

       for Mersenne number 2 ^ exponent - 1 or

           fexponent

       for Fermat number 2 ^ (2 ^ exponent) + 1.  (see FILES section for details).

       0      Exit successfully.

       1      Assertion failure.
              Cannot determine the number of CPUs.
              Unknown fetal error.
              Radix set index not available for given FFT length.

       255    thread_policy_set() failure.
              malloc(3), calloc(3) or realloc(3) failure.
              pthread_create(3) or pthread_join(3) failure.

ENVIRONMENT

       mlucas honors the following environment variables, if they exist:

       MLUCAS_PATH
              The path to read mlucas configuration files and to write mlucas generated files
              (see FILES section for details).  MLUCAS_PATH must end with a slash (e.g.,
              /home/foolish/bar/.  If MLUCAS_PATH is not set, then MLUCAS_PATH defaults to
              $HOME/.mlucas.d/, where the environmental variable $HOME will be expanded in the
              environment where mlucas is invoked.  mlucas will attept to make the directory with
              parents pointed by MLUCAS_PATH using the mkdir(1) command.  The effect is similar
              to executing mkdir -p $MLUCAS_PATH in the shell provided that the -p flag is
              honored.

FILES

       This section details mlucas configuration files and mlucas generated files.  As noted in
       the ENVIRONMENT section, $MLUCAS_PATH defaults to $HOME/mlucas.d/ but this can be
       overridden at run-time by setting the MLUCAS_PATH environment variable.

       $MLUCAS_PATH/*.stat
              The filename-prefix wildcard * is as described in the EXIT STATUS section; for the
              primality test of the Mersenne number 2 ^ exponent - 1 it is of the form

                  pexponent

              All important events, per-10000-iteration residues (or per-100000-iteration if more
              than 4 threads are used for the test) and the final residue during Lucas-Lehmer
              test of exponent are recorded in this file. It can be seen as an exponent-specific
              detailed $MLUCAS_PATH/results.txt (see $MLUCAS_PATH/results.txt below for details).
              This file is useful for debugging purposes. Its format looks like:

                  INFO: event
                  ...
                  Mexponent: using FFT length fft_lengthK = fft_length * 1024 8-byte floats.
                  Bz<this gives an average> bits bits per digit
                  Using complex FFT radices radix_set (product of all elements of radix_set =
                  fft_length / 2)
                  ...
                  [date_and_time] Mexponent Iter# = iterations clocks =
                  time_taken_per_10000_iterations [   time_taken_per_iteration sec/iter] Res64:
                  residue.  AvgMaxErr = roe_avg.  MaxErr = roe_max
                  ...
                  [Restarting Mexponent at iteration = iteration.  Res64: residue
                  Mexponent: using FFT length fft_lengthK = fft_length * 1024 8-byte floats.
                  this gives an average bits bits per digit
                  Using complex FFT radices radix_set] (product of all elements of radix_set =
                  fft_length / 2)
                  ...
                  Mexponent is not prime.  Res64: residue.  Program: E17.1
                  Mexponent mod 2^36     =          remainder_1
                  Mexponent mod 2^35 - 1 =          remainder_2
                  Mexponent mod 2^36 - 1 =          remainder_3

       $MLUCAS_PATH/fermat.cfg
              The format of this file is exactly the same as the format of
              $MLUCAS_PATH/mlucas.cfg (see $MLUCAS_PATH/mlucas.cfg below for details).

       $MLUCAS_PATH/mlucas.cfg
              This file stores the radix set with best timing for each FFT length. Its format
              looks like:

                  17.1
                  fft_length msec/iter = timing ROE[avg,max] = [roe_avg, roe_max] radices =
                  radix_set
                  ...

              Normally, the timing entry for each line should be monotonic from above to below
              since larger FFT length should take longer to test.  But it is OK for a given
              fft_length to have a higher timing than the one after it since mlucas checks the
              timings listed in this file for all FFT lengths >= the default FFT length for the
              number being tested, and uses the FFT length having the smallest listed timing.
              However, if you notice that this file has any entries such that a given fft_length
              has a timing 5% or more greater than the next-larger FFT length, or higher timing
              than two or more larger FFT lengths, please contact the author (see BUGS section
              for details).

       $MLUCAS_PATH/nthreads.ini
              This file sets the number of threads used.  It should only contain a positive
              integer since the content of this file is read by sscanf(in_line, "%d", &NTHREADS);
              where the variable in_line contains the content of the $MLUCAS_PATH/nthreads.ini
              file.  If this file is not present, mlucas will use as many threads as the number
              of CPUs detected.  The number of threads used set by this file can be overridden by
              setting -nthread flag at run-time.  This file is for those who want to set the
              number of threads to be greater or less than the number of CPUs detected.  This can
              be useful since some users reported up to 10% performance gain when using more
              threads than the number of CPUs detected.

       $MLUCAS_PATH/results.txt
              Important events which occurred during Lucas-Lehmer test and the final residue
              obtained are recorded in this file. This file summarizes important information in
              all $MLUCAS_PATH/*.stat files (see $MLUCAS_PATH/*.stat above for details) into a
              single file. This file (more specifically, any results which were added to it since
              your last checkin from) should be submitted to the PrimeNet server (see subsection
              Great Internet Mersenne Prime Search in section NOTES for details) since the Lucas-
              Lehmer test exponents are obtained from the PrimeNet server (see
              $MLUCAS_PATH/worktodo.ini below for details). Its format looks like:

                  INFO: event
                  ...
                  [Mexponent Roundoff warning on iteration iteration, maxerr = roundoff_error
                   Retrying iteration interval to see if roundoff error is reproducible.
                  [Retry of iteration interval with fatal roundoff error was successful.]]
                  ...
                  Mexponent is not prime.  Res64: residue.  Program: E17.1
                  Mexponent mod 2^36     =          remainder_1
                  Mexponent mod 2^35 - 1 =          remainder_2
                  Mexponent mod 2^36 - 1 =          remainder_3
                  ...

       $MLUCAS_PATH/worktodo.ini
              This file contains Lucas-Lehmer test assignments to be tested. Its format looks
              like:

                  assignment=ID,exponent,trial factored up to,has P-1 factoring
                  ...

              The assignment field contains Test if the assignment is a first-time Lucas-Lehmer
              test, or DoubleCheck if the assignment is a double-check Lucas-Lehmer test.  (The
              program handles both cases the same way.)
              ID is a unique 32-digit hex number.
              exponent specifies the Mersenne number (of the form 2 ^ exponent - 1) to be tested.
              trial factored up to is the number of bit this Mersenne number has been trial
              factored up to without finding a factor.
              has P-1 factoring = 0 if no prior P-1 factoring has been done, = 1 if P-1 factoring
              (without finding a factor) has been done.  Since mlucas currently has no P-1
              factoring capability it simply discards these data, but users should prefer = 1
              here since such an assignment is slightly more likely (5-10%) to yield a prime.

              To do Lucas-Lehmer test, you should reserve exponents from the PrimeNet server and
              copy lines in the above format into the $MLUCAS_PATH/worktodo.ini file (see
              subsection Great Internet Mersenne Prime Search in section NOTES for details).  You
              may need to create the $MLUCAS_PATH/worktodo.ini file if it does not exist.

       Save files in $MLUCAS_PATH
              All files matching the following extended regular expression (see regex(7) for
              details) in $MLUCAS_PATH directory are save files:

                  ^[fpq][0123456789]+([.][0123456789]+0M)?$

              For both of the supported test types, duplicate pairs of savefiles are written at
              each checkpoint, to guard against corruption of the on-disk savefiles.  Lucas-
              Lehmer test savefile-pair names start with <p> and <q>, respectively, while Pe'pin
              test savefile-pair names start with <f> and <q>, respectively.  They should not be
              modified but backups may be made by the user.  By default, the program will save a
              persistent backup of the primary (p or f) save file every 10 millionth iteration,
              for examples upon completion of the Lucas-Lehmer test of M57885161 the user will
              find the following exponent-associated files in the $MLUCAS_PATH directory:

                  p57885161.stat
                  p57885161.10M
                  p57885161.20M
                  p57885161.30M
                  p57885161.40M
                  p57885161.50M

NOTES

   Great Internet Mersenne Prime Search
       This subsection needs to be compeleted...

BUGS

       The argument parser is buggy.  The relative position of arguments is relevant to mlucas,
       the order of arguments in SYNOPSIS should be followed to avoid confusing the parser.  Only
       100, 1000 and 10000 are supported for -iters flag.  However, the parser will not reject
       unsupported arguments.  Using unsupported arguments for -iters flag may trigger strange
       behaviour.

       Sometimes there is more than one applicable exit status values (see EXIT STATUS section
       for details).  In such case, there is no guarantee which will be returned.  For example,
       if malloc(3) failure triggers an assertion failure.  It is possible that mlucas returns 1
       instead of 255 as exit status value.

       For problems regarding the program mlucas, please contact the author Ernst W. Mayer
       <ewmayer@aol.com>.  For installation and documentation related problems regarding the
       Debian package and this manual, please use reportbug(1) to contact Alex Vong
       <alexvong1995@gmail.com>.

EXAMPLE

       There are 3 common cases where you will want to run this program.  Normally, you should do
       a spot-check first to quick-test your build, followed by the self-test range for `medium'
       exponents.  Finally, full-blown Lucas-Lehmer testing which is the main purpose of this
       program.

       mlucas -fftlen 192 -iters 100 -radset 0 -nthread 2
              Perform spot-check to see if mlucas works and fill-in a bug report if it does not.
              The spot check should produce residues matching the internal tabulated ones.  If
              the residues does not match, mlucas should emit a verbose error message.

       mlucas -s m
              Perform timing self-test for `medium' exponents to tune code parameters for your
              platform.  Ordinary users are recommended to do this self-test only.  For best
              results, run any self-tests under zero- or constant-load conditions.  The self-
              tests append (or create if $MLUCAS_PATH/mlucas.cfg does not exist) new timing data
              to the $MLUCAS_PATH/mlucas.cfg (see FILES section for details).  Before doing any
              self-tests, you should first check if there is an existing $MLUCAS_PATH/mlucas.cfg
              file and either delete it or do a backup-via-rename to to prevent mixing old and
              new timing data.  $MLUCAS_PATH/mlucas.cfg normally locates at $HOME/.mlucas.d/
              directory although this can be overridden at run-time by settingthe MLUCAS_PATH
              environment variable (see ENVIRONMENT section for details).

       mlucas &
              Perform Lucas-Lehmer test on Mersenne numbers by running mlucas as a background job
              (see JOB CONTROL section in bash(1) and Builtins subsection in dash(1) for
              details).  To perform Lucas-Lehmer test on a given Mersenne number, you must first
              perform a self-test for `medium' exponents mentioned above, or if you only desire
              to test a single selected Mersenne number, a self-test for the default FFT length
              for that number:

                  mlucas -m exponent -iters 100

              In the case of multi-exponent "production testing", you should reserve exponent
              from the PrimeNet server and add them into $MLUCAS_PATH/worktodo.ini (see the
              subsection Great Internet Mersenne Prime Search within the section NOTES and FILES
              section for details).

   Advanced Usage Tips
       To start mlucas in terminal 1, add the following lines to your login shell initialization
       file, such as $HOME/.profile (see INVOCATION section in bash(1) and Invocation subsection
       dash(1) for details).

           # Test if we are in tty1
           if test `tty` = '/dev/tty1'
           then
               # turn on job control
               set -m
               # start mlucas
               nice mlucas > /dev/null 2>&1 &
           fi

SEE ALSO

       bash(1), dash(1), reportbug(1)

       <https://www.mersenneforum.org/mayer/README.html>, /usr/share/doc/mlucas/html/README.html

       mlucas is documented fully by Mlucas README, available both online and offline as shown
       above.

       Great Internet Mersenne Prime Search <https://www.mersenne.org/>

       Mersenne Forum <https://www.mersenneforum.org/>

       Chris Caldwell's web page on Mersenne numbers <https://primes.utm.edu/mersenne/index.html>

       Richard Crandall and Barry Fagin, Discrete Weighted Transforms and Large-Integer
       Arithmetic.
       <https://pdfs.semanticscholar.org/07c0/fae878fe9d6a117de08282802fb7b892bf2d.pdf>

       Richard E. Crandall, Ernst W. Mayer, and Jason S. Papadopoulos, The Twenty-Fourth Fermat
       Number is Composite. <https://www.mersenneforum.org/mayer/F24.pdf>