mlucas/doc/mlucas.1

.\"                                      Hey, EMACS: -*- nroff -*-
.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" mlucas.1 - man page of mlucas written for Debian GNU/Linux
.\" Copyright (C) 2015, 2017 Alex Vong <alexvong1995@gmail.com>,
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write to the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.\" for reference for writing man pages, see man-page(7).
.\" for Perl Pod format, see perlpod(1).
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MLUCAS 1"
.TH MLUCAS 1 "2017-01-27" "Mlucas 14.2" "User Commands"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
mlucas \- program to perform Lucas\-Lehmer test on a Mersenne number,
2 ^ p \- 1
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.PD 0
.de Sp
.br
..
\&\fBmlucas\fR
.PP
\&\fBmlucas \-h\fR
.PP
\&\fBmlucas\fR \fB\-s\fR \fBtiny\fR | \fBt\fR | \fBsmall\fR | \fBs\fR | \fBmedium\fR | \fBm\fR |
\&\fBlarge\fR | \fBl\fR | \fBhuge\fR | \fBh\fR | \fBall\fR | \fBa\fR
[\fB\-iters\fR \fB100\fR | \fB1000\fR | \fB10000\fR [\fB\-nthread\fR \fIthreads\fR]]
.PP
\&\fBmlucas\fR \fB\-m\fR \fIexponent\fR | \fB\-f\fR \fIexponent\fR
[\fB\-iters\fR \fB100\fR | \fB1000\fR | \fB10000\fR [\fB\-nthread\fR \fIthreads\fR]]
.PP
\&\fBmlucas\fR \fB\-fftlen\fR \fIfft_length\fR
[\fB\-radset\fR \fIradix_set\fR]
[\fB\-m\fR \fIexponent\fR | \fB\-f\fR \fIexponent\fR]
\&\fB\-iters\fR \fB100\fR | \fB1000\fR | \fB10000\fR
[\fB\-nthread\fR \fIthreads\fR]
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This manual page documents briefly the \fBmlucas\fR command.
.PP
\&\fBmlucas\fR 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.
.PP
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 \fBGreat Internet Mersenne Prime Search\fR (\fB\s-1GIMPS\s0\fR).
For more information on \fB\s-1GIMPS\s0\fR,
see the \fBGreat Internet Mersenne Prime Search\fR subsection
within the \fB\s-1NOTES\s0\fR section and \fB\s-1SEE ALSO\s0\fR section.
Note that \fBmlucas\fR is not (yet) as efficient as the main \fB\s-1GIMPS\s0\fR client,
George Woltman's \fBPrime95\fR program
(a.k.a. \fBmprime\fR 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 \fIfreedom to run the program as you wish,
for any purpose\fR),
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 \s-1EFF\s0 Cooperative Computing Awards <https://www.eff.org/awards/coop>
for details).
.PP
\&\fBmlucas\fR reads the exponents from the \fI\f(CI$MLUCAS_PATH\fI/worktodo.ini\fR file.
Results are written to the \fI\f(CI$MLUCAS_PATH\fI/results.txt\fR file
and the exponent-specific \fI\f(CI$MLUCAS_PATH\fI/*.stat\fR file
(see section \fB\s-1FILES\s0\fR for details).
Error messages are written to \fIstderr\fR
and the \fI\f(CI$MLUCAS_PATH\fI/*.stat\fR file.
Exponents can also be passed as command-line arguments
but this is mainly used for debugging (see section \fB\s-1OPTIONS\s0\fR for details).
In addition, \fBmlucas\fR 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.
.PP
New users are urged to jump straight to the \fB\s-1EXAMPLE\s0\fR section
and follow the examples and pointers to other sections.
Users with little time for in-depth reading
should at least read the \fB\s-1NOTES\s0\fR, \fB\s-1BUGS\s0\fR and \fB\s-1EXAMPLE\s0\fR sections
for a brief introduction to the \fBGreat Internet Mersenne Prime Search\fR,
undesirable restrictions and common usages.
\&\fB\s-1FILES\s0\fR section is also highly recommended
since it describes the \fBmlucas\fR configuration files
used for host-specific optimization and other \fBmlucas\fR\-generated files.
Advanced users should also peruse the \fB\s-1OPTIONS\s0\fR section
since it introduces less-commonly-used advanced options.
Experienced users who find this manual inadequate
should consult the \fB\s-1SEE ALSO\s0\fR section for further information.
Lastly, the \fIMlucas \s-1README\s0\fR, available both online and offline,
is highly recommended
since it is written and maintained by the author of \fBmlucas\fR
and should be considered the final authority.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fBmlucas\fR follows the traditional \s-1POSIX \s0(see 
.BR standards (7)
for details)
command line syntax,
with short options starting with one dashes (`\fI\-\fR').
A summary of options is included below.
A complete description is in the \fB\s-1SEE ALSO\s0\fR section.
.TP 7
\fB\-h\fR
.IX Item "-h"
Show version of program and summary of options.
.TP 7
\fB\-s t, \-s tiny\fR
.IX Item "-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) \s-1CPU.\s0
.TP 7
\fB\-s s, \-s small\fR
.IX Item "-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) \s-1CPU.\s0
.TP 7
\fB\-s m, \-s medium\fR
.IX Item "-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) \s-1CPU.\s0
.TP 7
\fB\-s l, \-s large\fR
.IX Item "-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) \s-1CPU.\s0
.TP 7
\fB\-s h, \-s huge\fR
.IX Item "-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) \s-1CPU.\s0
.TP 7
\fB\-s a, \-s all\fR
.IX Item "-s a, -s all"
Run 100\-iteration self-test on all Mersenne exponents
and all \s-1FFT\s0 radix sets.
This will take several hours on a fast (pre\-2010) \s-1CPU.\s0
.TP 7
\fB\-fftlen\fR \fIfft_length\fR
.IX Item "-fftlen fft_length"
This allows the user to specify the length of the fast-transform (\s-1FFT\s0)
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 \s-1FFT\s0 lengths in terms of kilodoubles
(= 2 ^ 10 or 1024 doubles).
If \fIfft_length\fR is one of the available \s-1FFT\s0 lengths (in kilodoubles),
run all available \s-1FFT\s0 radices available at that length,
unless the \fI\-radset\fR flag is also invoked (see below for details).
If \fI\-fftlen\fR is invoked with either the \fI\-m\fR or \fI\-f\fR flag,
the self-tests will perform the first 100 iterations
of a Lucas-Lehmer test (\fI\-m\fR) or Pe'pin test (\fI\-f\fR)
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 \s-1FFT\s0 length.
The program uses this to find the optimal radix set for a given \s-1FFT\s0 length
on your hardware.
.TP 7
\fB\-iters\fR \fB100\fR | \fB1000\fR | \fB10000\fR
.IX Item "-iters 100 | 1000 | 10000"
Do \fI100\fR, \fI1000\fR or \fI10000\fR self-test iterations of the type determined
by the modulus-related options
(\fI\-s\fR / \fI\-m\fR = Lucas-Lehmer test iterations with initial seed 4,
\&\fI\-f\fR = Pe'pin test squarings with initial seed 3).
Default is \fI100\fR iterations.
.TP 7
\fB\-radset\fR \fIradix_set\fR
.IX Item "-radset radix_set"
Specify index of a set of complex \s-1FFT\s0 radices to use,
based on the big selection table in the function 
.BR get_fft_radices ().
This requires a supported value of \fI\-fftlen\fR to be specified,
meaning (for an \s-1FFT\s0 length supported by the program)
an index \fB0\fR, \fB1\fR, \fB2\fR, ... and so on.
\&\fB0\fR is always a valid radix set index;
how high one can go in the enumeration depends on the \s-1FFT\s0 length.
As soon as the user tries an index out of range of the current \s-1FFT\s0 length,
the program will error-exit with an informational message to that effect,
which also notes the maximum allowable radix set index for that \s-1FFT\s0 length.
.TP 7
\fB\-nthread\fR \fIthreads\fR
.IX Item "-nthread threads"
For multithread-enabled (default) build,
perform the test in parallel mode with this many threads.
.TP 7
\fB\-m\fR \fIexponent\fR
.IX Item "-m exponent"
Perform a Lucas-Lehmer primality test of the Mersenne number
M(\fIexponent\fR) = 2 ^ \fIexponent\fR \- 1,
where \fIexponent\fR must be an odd prime.
If \fI\-iters\fR is also invoked, this indicates a timing test.
This requires suitable added arguments
(\fI\-fftlen\fR and, optionally, \fI\-radset\fR) to be supplied.
If the \fI\-fftlen\fR option (and optionally \fI\-radset\fR) is also invoked
but \fI\-iters\fR is not,
the program first checks
the first line of the \fI\f(CI$MLUCAS_PATH\fI/worktodo.ini\fR file to see
if the assignment specified there is a Lucas-Lehmer test
with the same exponent as specified via the \fI\-m\fR argument.
If so, the \fI\-fftlen\fR argument is treated as a user override
of the default \s-1FFT\s0 length for the exponent.
If \fI\-radset\fR is also invoked, this is similarly treated as
a user-specified radix set for the user-set \s-1FFT\s0 length;
otherwise the program will use the \fI\f(CI$MLUCAS_PATH\fI/mlucas.cfg\fR file
to select the radix set to be used for the user-forced \s-1FFT\s0 length.
If the \fI\f(CI$MLUCAS_PATH\fI/worktodo.ini\fR file entry
does not match the \fI\-m\fR value,
a set of timing self-tests is run on the user-specified Mersenne number
using all sets of \s-1FFT\s0 radices available at the specified \s-1FFT\s0 length.
If the \fI\-fftlen\fR option is not invoked,
the tests use all sets of \s-1FFT\s0 radices
available at that exponent's default \s-1FFT\s0 length.
Use this to find the optimal radix set
for a single given Mersenne exponent on your hardware,
similarly to the \fI\-fftlen\fR option.
Perform 100 iterations, or as many as specified via the \fI\-iters\fR flag.
.TP 7
\fB\-f\fR \fIexponent\fR
.IX Item "-f exponent"
Perform a base\-3 Pe'pin test on the Fermat number
F(\fIexponent\fR) = 2 ^ (2 ^ \fIexponent\fR) + 1.
If desired this can be invoked together with the \fI\-fftlen\fR option
as for the Mersenne-number self-tests (see above notes on the \fI\-m\fR flag;
note that not all \s-1FFT\s0 lengths supported for \fI\-m\fR are available for \fI\-f\fR:
\&\fI\-m\fR permits \s-1FFT\s0 lengths of form \fIodd\fR * 2 ^ n
with \fIodd\fR = any of \fB1\fR, \fB3\fR, \fB5\fR, \fB7\fR, \fB9\fR, \fB11\fR, \fB13\fR, \fB15\fR;
\&\fI\-f\fR allows odd = \fB1\fR, \fB7\fR, \fB15\fR and \fB63\fR)
Optimal radix sets and timings
are written to the \fI\f(CI$MLUCAS_PATH\fI/fermat.cfg\fR file.
Perform 100 iterations, or as many as specified via the \fI\-iters\fR flag.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
.TP 4
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, \fBmlucas\fR make use of \fIstderr\fR to print error messages as well as saving them to the \fI\f(CI$MLUCAS_PATH\fI/*.stat\fR file, where \fI*\fR is in the form
.IX Item "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"
.Sp
.PD 0
.de Sp
.br
..
p\fIexponent\fR
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.TP 4
for Mersenne number 2 ^ \fIexponent\fR \- 1 or
.IX Item "for Mersenne number 2 ^ exponent - 1 or"
.Sp
.PD 0
.de Sp
.br
..
f\fIexponent\fR
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.PP
for Fermat number 2 ^ (2 ^ \fIexponent\fR) + 1.
(see \fB\s-1FILES\s0\fR section for details).
.TP 7
\fB0\fR
.IX Item "0"
Exit successfully.
.TP 7
\fB1\fR
.IX Item "1"
.PD 0
.de Sp
.br
..
Assertion failure.
.Sp
Cannot determine the number of CPUs.
.Sp
Unknown fetal error.
.Sp
Radix set index not available for given \s-1FFT\s0 length.
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.TP 7
\fB255\fR
.IX Item "255"
.PD 0
.de Sp
.br
..
.BR thread_policy_set ()
failure.
.Sp
.BR malloc (3),
.BR calloc (3)
or 
.BR realloc (3)
failure.
.Sp
.BR pthread_create (3)
or 
.BR pthread_join (3)
failure.
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
\&\fBmlucas\fR honors the following environment variables, if they exist:
.TP 7
\fB\s-1MLUCAS_PATH\s0\fR
.IX Item "MLUCAS_PATH"
The path to read \fBmlucas\fR configuration files
and to write \fBmlucas\fR generated files (see \fB\s-1FILES\s0\fR section for details).
\&\fB\s-1MLUCAS_PATH\s0\fR must end with a slash (e.g., \fI/home/foolish/bar/\fR.
If \fB\s-1MLUCAS_PATH\s0\fR is not set,
then \fB\s-1MLUCAS_PATH\s0\fR defaults to \fI\f(CI$HOME\fI/.mlucas.d/\fR,
where the environmental variable \fI\f(CI$HOME\fI\fR will be expanded
in the environment where \fBmlucas\fR is invoked.
\&\fBmlucas\fR will attept to make the directory with parents
pointed by \fB\s-1MLUCAS_PATH\s0\fR using the 
.BR mkdir (1)
command.
The effect is similar to executing \fImkdir \-p \f(CI$MLUCAS_PATH\fI\fR in the shell
provided that the \fI\-p\fR flag is honored.
.SH "FILES"
.IX Header "FILES"
This section details \fBmlucas\fR configuration files
and \fBmlucas\fR generated files.
As noted in the \fB\s-1ENVIRONMENT\s0\fR section,
\&\fB\f(CB$MLUCAS_PATH\fB\fR defaults to \fI\f(CI$HOME\fI/mlucas.d/\fR but this can be
overridden at run-time by setting the \fB\s-1MLUCAS_PATH\s0\fR environment variable.
.TP 7
\fB\f(CB$MLUCAS_PATH\fB/*.stat\fR
.IX Item "$MLUCAS_PATH/*.stat"
.RS 7
.PD 0
.TP 4
The filename-prefix wildcard \fI*\fR is as described in the \s-1EXIT STATUS\s0 section; for the primality test of the Mersenne number 2 ^ \fIexponent\fR \- 1 it is of the form
.IX Item "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"
.Sp
.PD 0
.de Sp
.br
..
.PD
p\fIexponent\fR
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.RE
.RS 7
.TP 4
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 \fIexponent\fR are recorded in this file. It can be seen as an \fIexponent\fR\-specific detailed \fI\f(CI$MLUCAS_PATH\fI/results.txt\fR (see \fI\f(CI$MLUCAS_PATH\fI/results.txt\fR below for details). This file is useful for debugging purposes. Its format looks like:
.IX Item "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:"
.Sp
.PD 0
.de Sp
.br
..
\&\fB\s-1INFO\s0\fR: \fIevent\fR
.Sp
\&...
.Sp
\&\fBM\fR\fIexponent\fR: \fBusing \s-1FFT\s0 length\fR \fIfft_length\fR\fBK\fR
\&\fB=\fR \fIfft_length * 1024\fR \fB8\-byte floats.\fR
Bz<this gives an average> \fIbits\fR \fBbits per digit\fR
.Sp
\&\fBUsing complex \s-1FFT\s0 radices\fR \fIradix_set\fR
(product of all elements of radix_set = fft_length / 2)
.Sp
\&...
.Sp
\&\fB[\fR\fIdate_and_time\fR\fB]\fR
\&\fBM\fR\fIexponent\fR
\&\fBIter#\fR \fB=\fR \fIiterations\fR
\&\fBclocks\fR \fB=\fR \fItime_taken_per_10000_iterations\fR
\&\fB[\fR\fI   time_taken_per_iteration\fR \fBsec/iter\fR\fB]\fR
\&\fBRes64:\fR \fIresidue\fR\fB.\fR
\&\fBAvgMaxErr\fR \fB=\fR \fIroe_avg\fR\fB.\fR
\&\fBMaxErr\fR \fB=\fR \fIroe_max\fR
.Sp
\&...
.Sp
[\fBRestarting\fR \fBM\fR\fIexponent\fR \fBat iteration\fR \fB=\fR \fIiteration\fR\fB.\fR
\&\fBRes64:\fR \fIresidue\fR
.Sp
\&\fBM\fR\fIexponent\fR: \fBusing \s-1FFT\s0 length\fR \fIfft_length\fR\fBK\fR
\&\fB=\fR \fIfft_length * 1024\fR \fB8\-byte floats.\fR
.Sp
\&\fBthis gives an average\fR \fIbits\fR \fBbits per digit\fR
.Sp
\&\fBUsing complex \s-1FFT\s0 radices\fR \fIradix_set\fR]
(product of all elements of radix_set = fft_length / 2)
.Sp
\&...
.Sp
\&\fBM\fR\fIexponent\fR \fBis not prime.\fR
\&\fBRes64:\fR \fIresidue\fR\fB.\fR
\&\fBProgram: E14.2\fR
.Sp
\&\fBM\fR\fIexponent\fR \fBmod 2^36\fR     \fB=\fR          \fIremainder_1\fR
.Sp
\&\fBM\fR\fIexponent\fR \fBmod 2^35 \- 1\fR \fB=\fR          \fIremainder_2\fR
.Sp
\&\fBM\fR\fIexponent\fR \fBmod 2^36 \- 1\fR \fB=\fR          \fIremainder_3\fR
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.RE
.RS 7
.RE
.TP 7
\fB\f(CB$MLUCAS_PATH\fB/fermat.cfg\fR
.IX Item "$MLUCAS_PATH/fermat.cfg"
The format of this file is exactly the same as
the format of \fI\f(CI$MLUCAS_PATH\fI/mlucas.cfg\fR
(see \fI\f(CI$MLUCAS_PATH\fI/mlucas.cfg\fR below for details).
.TP 7
\fB\f(CB$MLUCAS_PATH\fB/mlucas.cfg\fR
.IX Item "$MLUCAS_PATH/mlucas.cfg"
.RS 7
.PD 0
.TP 4
This file stores the radix set with best timing for each \s-1FFT\s0 length. Its format looks like:
.IX Item "This file stores the radix set with best timing for each FFT length. Its format looks like:"
.Sp
.PD 0
.de Sp
.br
..
.PD
\&\fB14.2\fR
.Sp
\&\fIfft_length\fR \fBmsec/iter\fR \fB=\fR \fItiming\fR
\&\fBROE[avg,max]\fR \fB=\fR \fB[\fR\fIroe_avg\fR\fB,\fR \fIroe_max\fR\fB]\fR
\&\fBradices\fR \fB=\fR \fIradix_set\fR
.Sp
\&...
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.RE
.RS 7
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.Sp
Normally, the \fItiming\fR entry for each line should be monotonic
from above to below since larger \s-1FFT\s0 length should take longer to test.
But it is \s-1OK\s0 for a given \fIfft_length\fR to have a higher \fItiming\fR than
the one after it since \fBmlucas\fR checks the timings listed in this file
for all \s-1FFT\s0 lengths >= the default \s-1FFT\s0 length for the number being tested,
and uses the \s-1FFT\s0 length having the smallest listed timing.
However, if you notice that this file has any entries such that
a given \fIfft_length\fR has a timing 5% or more greater than the next-larger
\&\s-1FFT\s0 length, or higher timing than two or more larger \s-1FFT\s0 lengths,
please contact the author (see \fB\s-1BUGS\s0\fR section for details).
.RE
.TP 7
\fB\f(CB$MLUCAS_PATH\fB/nthreads.ini\fR
.IX Item "$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
\&\fBsscanf(\fR\fIin_line\fR, \fI\*(L"%d\*(R"\fR\fB,\fR \fI&NTHREADS\fR\fB);\fR
where the variable \fIin_line\fR
contains the content of the \fI\f(CI$MLUCAS_PATH\fI/nthreads.ini\fR file.
If this file is not present,
\&\fBmlucas\fR 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 \fI\-nthread\fR 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.
.TP 7
\fB\f(CB$MLUCAS_PATH\fB/results.txt\fR
.IX Item "$MLUCAS_PATH/results.txt"
.RS 7
.PD 0
.TP 4
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 \fI\f(CI$MLUCAS_PATH\fI/*.stat\fR files (see \fI\f(CI$MLUCAS_PATH\fI/*.stat\fR 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 \fBGreat Internet Mersenne Prime Search\fR in section \fB\s-1NOTES\s0\fR for details) since the Lucas-Lehmer test exponents are obtained from the PrimeNet server (see \fI\f(CI$MLUCAS_PATH\fI/worktodo.ini\fR below for details). Its format looks like:
.IX Item "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:"
.Sp
.PD 0
.de Sp
.br
..
.PD
\&\fB\s-1INFO:\s0\fR \fIevent\fR
.Sp
\&...
.Sp
[\fBM\fR\fIexponent\fR \fBRoundoff warning on iteration\fR \fIiteration\fR\fB,\fR
\&\fBmaxerr\fR \fB=\fR \fIroundoff_error\fR
.Sp
\&\fB Retrying iteration interval to see if roundoff error is reproducible.\fR
.Sp
[\fBRetry of iteration interval with fatal roundoff error was successful.\fR]]
.Sp
\&...
.Sp
\&\fBM\fR\fIexponent\fR\fB is not prime.\fR
\&\fBRes64:\fR \fIresidue\fR\fB.\fR
\&\fBProgram: E14.2\fR
.Sp
\&\fBM\fR\fIexponent\fR \fBmod 2^36\fR     \fB=\fR          \fIremainder_1\fR
.Sp
\&\fBM\fR\fIexponent\fR \fBmod 2^35 \- 1\fR \fB=\fR          \fIremainder_2\fR
.Sp
\&\fBM\fR\fIexponent\fR \fBmod 2^36 \- 1\fR \fB=\fR          \fIremainder_3\fR
.Sp
\&...
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.RE
.RS 7
.RE
.TP 7
\fB\f(CB$MLUCAS_PATH\fB/worktodo.ini\fR
.IX Item "$MLUCAS_PATH/worktodo.ini"
.RS 7
.PD 0
.TP 4
This file contains Lucas-Lehmer test assignments to be tested. Its format looks like:
.IX Item "This file contains Lucas-Lehmer test assignments to be tested. Its format looks like:"
.Sp
.PD 0
.de Sp
.br
..
.PD
\&\fIassignment\fR\fB=\fR\fI\s-1ID\s0\fR\fB,\fR\fIexponent\fR\fB,\fR\fItrial
factored up to\fR\fB,\fR\fIhas P\-1 factoring\fR
.Sp
\&...
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.RE
.RS 7
.Sp
The \fIassignment\fR field contains \fBTest\fR
if the assignment is a first-time Lucas-Lehmer test,
or \fBDoubleCheck\fR if the assignment is a double-check Lucas-Lehmer test.
(The program handles both cases the same way.)
.PD 0
.de Sp
.br
..
.Sp
\&\fI\s-1ID\s0\fR is a unique 32\-digit hex number.
.Sp
\&\fIexponent\fR specifies the Mersenne number
(of the form 2 ^ \fIexponent\fR \- 1) to be tested.
.Sp
\&\fItrial factored up to\fR is the number of bit this Mersenne number
has been trial factored up to without finding a factor.
.Sp
\&\fIhas P\-1 factoring\fR \fB=\fR \fB0\fR if no prior P\-1 factoring has been done,
\&\fB=\fR \fB1\fR 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 \fB=\fR \fB1\fR here
since such an assignment is slightly more likely (5\-10%) to yield a prime.
.PD
.de Sp
.if t .sp .5v
.if n .sp
..
.Sp
To do Lucas-Lehmer test,
you should reserve exponents from the PrimeNet server
and copy lines in the above format into the
\&\fI\f(CI$MLUCAS_PATH\fI/worktodo.ini\fR file (see subsection
\&\fBGreat Internet Mersenne Prime Search\fR in section \fB\s-1NOTES\s0\fR for details).
You may need to create the \fI\f(CI$MLUCAS_PATH\fI/worktodo.ini\fR file
if it does not exist.
.RE
.TP 7
\fBSave files in \f(CB$MLUCAS_PATH\fB\fR
.IX Item "Save files in $MLUCAS_PATH"
All files matching the following extended regular expression
(see 
.BR regex (7)
for details)
in \fI\f(CI$MLUCAS_PATH\fI\fR directory are save files:
.Sp
.Vb 1
\&    ^[fpq][0123456789]+([.][0123456789]+0M)?$
.Ve
.Sp
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
(\fBp\fR or \fBf\fR) 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 \fI\f(CI$MLUCAS_PATH\fI\fR directory:
.Sp
.Vb 6
\&    p57885161.stat
\&    p57885161.10M
\&    p57885161.20M
\&    p57885161.30M
\&    p57885161.40M
\&    p57885161.50M
.Ve
.SH "NOTES"
.IX Header "NOTES"
.SS "Great Internet Mersenne Prime Search"
.IX Subsection "Great Internet Mersenne Prime Search"
This subsection needs to be compeleted...
.SH "BUGS"
.IX Header "BUGS"
The argument parser is buggy.
The relative position of arguments is relevant to \fBmlucas\fR,
the order of arguments in \fB\s-1SYNOPSIS\s0\fR
should be followed to avoid confusing the parser.
Only \fI100\fR, \fI1000\fR and \fI10000\fR are supported for \fI\-iters\fR flag.
However, the parser will not reject unsupported arguments.
Using unsupported arguments for \fI\-iters\fR flag
may trigger strange behaviour.
.PP
Sometimes there is more than one applicable exit status values
(see \fB\s-1EXIT STATUS\s0\fR section for details).
In such case, there is no guarantee which will be returned.
For example,
if 
.BR malloc (3)
failure triggers an assertion failure.
It is possible that \fBmlucas\fR returns \fI1\fR
instead of \fI255\fR as exit status value.
.PP
For problems regarding the program \fBmlucas\fR,
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 
.BR reportbug (1)
to contact Alex Vong <alexvong1995@gmail.com>.
.SH "EXAMPLE"
.IX Header "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.
.TP 7
\fBmlucas \-fftlen 192 \-iters 100 \-radset 0 \-nthread 2\fR
.IX Item "mlucas -fftlen 192 -iters 100 -radset 0 -nthread 2"
Perform spot-check to see if \fBmlucas\fR 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,
\&\fBmlucas\fR should emit a verbose error message.
.TP 7
\fBmlucas \-s m\fR
.IX Item "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 \fI\f(CI$MLUCAS_PATH\fI/mlucas.cfg\fR does not exist)
new timing data to the \fI\f(CI$MLUCAS_PATH\fI/mlucas.cfg\fR
(see \fB\s-1FILES\s0\fR section for details).
Before doing any self-tests,
you should first check if there is an existing
\&\fI\f(CI$MLUCAS_PATH\fI/mlucas.cfg\fR file
and either delete it or do a backup-via-rename to
to prevent mixing old and new timing data.
\&\fI\f(CI$MLUCAS_PATH\fI/mlucas.cfg\fR normally locates at
\&\fI\f(CI$HOME\fI/.mlucas.d/\fR directory
although this can be overridden at run-time
by settingthe \fB\s-1MLUCAS_PATH\s0\fR environment variable
(see \fB\s-1ENVIRONMENT\s0\fR section for details).
.TP 7
\fBmlucas &\fR
.IX Item "mlucas &"
.RE
.RS 7
Perform Lucas-Lehmer test on Mersenne numbers
by running \fBmlucas\fR as a background job
(see \fB\s-1JOB CONTROL\s0\fR section in 
.BR bash (1)
and \fBBuiltins\fR subsection in 
.BR 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 \s-1FFT\s0 length for that number:
.RS 4
.Sp
mlucas \-m \fIexponent\fR \-iters 100
.RE
.Sp
In the case of multi-exponent \*(L"production testing\*(R",
you should reserve exponent from the PrimeNet server
and add them into \fI\f(CI$MLUCAS_PATH\fI/worktodo.ini\fR
(see the subsection \fBGreat Internet Mersenne Prime Search\fR
within the section \fB\s-1NOTES\s0\fR and \fB\s-1FILES\s0\fR section for details).
.SS "Advanced Usage Tips"
.IX Subsection "Advanced Usage Tips"
To start \fBmlucas\fR in terminal 1,
add the following lines to your login shell initialization file,
such as \fI\f(CI$HOME\fI/.profile\fR
(see \fB\s-1INVOCATION\s0\fR section in 
.BR bash (1)
and \fBInvocation\fR subsection 
.BR dash (1)
for details).
.PP
.Vb 8
\&    # Test if we are in tty1
\&    if test \`tty\` = \*(Aq/dev/tty1\*(Aq
\&    then
\&        # turn on job control
\&        set \-m
\&        # start mlucas
\&        nice mlucas > /dev/null 2>&1 &
\&    fi
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.BR bash (1),
.BR dash (1),
.BR reportbug (1)
.PP
<http://hogranch.com/mayer/README.html>,
\&\fI/usr/share/doc/mlucas/html/README.html\fR
.PP
\&\fBmlucas\fR is documented fully by \fIMlucas \s-1README\s0\fR,
available both online and offline as shown above.
.PP
\&\fIGreat Internet Mersenne Prime Search\fR <http://www.mersenne.org>
.PP
\&\fIMersenne Forum\fR <http://www.mersenneforum.org>
.PP
\&\fIChris Caldwell's web page on Mersenne numbers\fR <http://www.utm.edu/research/primes/mersenne.shtml>
.PP
\&\fIRichard Crandall and Barry Fagin, Discrete Weighted Transforms and Large-Integer Arithmetic.\fR <http://www.faginfamily.net/barry/Papers/Discrete%20Weighted%20Transforms.pdf>
.PP
\&\fIRichard E. Crandall, Ernst W. Mayer, and Jason S. Papadopoulos, The Twenty-Fourth Fermat Number is Composite.\fR <http://hogranch.com/mayer/F24.pdf>