mlucas - Online in the Cloud

PROGRAM:

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.

Use mlucas online using onworks.net services