Provided by: mlucas_17.1-3_amd64

**NAME**

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

**SYNOPSIS**

mlucasmlucas-hmlucas-stiny|t|small|s|medium|m|large|l|huge|h|all|a[-iters100|1000|10000[-nthreadthreads]]mlucas-mexponent|-fexponent[-iters100|1000|10000[-nthreadthreads]]mlucas-fftlenfft_length[-radsetradix_set] [-mexponent|-fexponent]-iters100|1000|10000[-nthreadthreads]

**DESCRIPTION**

This manual page documents briefly themlucascommand.mlucasis 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 theGreatInternetMersennePrimeSearch(GIMPS). For more information onGIMPS, see theGreatInternetMersennePrimeSearchsubsection within theNOTESsection andSEEALSOsection. Note thatmlucasis not (yet) as efficient as the mainGIMPSclient, George Woltman'sPrime95program (a.k.a.mprimefor 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 withfreedomtoruntheprogramasyouwish,foranypurpose), 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).mlucasreads the exponents from the$MLUCAS_PATH/worktodo.inifile. Results are written to the$MLUCAS_PATH/results.txtfile and the exponent-specific$MLUCAS_PATH/*.statfile (see sectionFILESfor details). Error messages are written tostderrand the$MLUCAS_PATH/*.statfile. Exponents can also be passed as command-line arguments but this is mainly used for debugging (see sectionOPTIONSfor details). In addition,mlucascan 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 theEXAMPLEsection and follow the examples and pointers to other sections. Users with little time for in-depth reading should at least read theNOTES,BUGSandEXAMPLEsections for a brief introduction to theGreatInternetMersennePrimeSearch, undesirable restrictions and common usages.FILESsection is also highly recommended since it describes themlucasconfiguration files used for host- specific optimization and othermlucas-generated files. Advanced users should also peruse theOPTIONSsection since it introduces less-commonly-used advanced options. Experienced users who find this manual inadequate should consult theSEEALSOsection for further information. Lastly, theMlucasREADME, available both online and offline, is highly recommended since it is written and maintained by the author ofmlucasand should be considered the final authority.

**OPTIONS**

mlucasfollows the traditional POSIX (seestandards(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 theSEEALSOsection.-hShow version of program and summary of options.-st,-stinyRun 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.-ss,-ssmallRun 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.-sm,-smediumRun 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.-sl,-slargeRun 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.-sh,-shugeRun 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.-sa,-sallRun 100-iteration self-test on all Mersenne exponents and all FFT radix sets. This will take several hours on a fast (pre-2010) CPU.-fftlenfft_lengthThis 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). Iffft_lengthis one of the available FFT lengths (in kilodoubles), run all available FFT radices available at that length, unless the-radsetflag is also invoked (see below for details). If-fftlenis invoked with either the-mor-fflag, 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.-iters100|1000|10000Do100,1000or10000self-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 is100iterations.-radsetradix_setSpecify index of a set of complex FFT radices to use, based on the big selection table in the functionget_fft_radices(). This requires a supported value of-fftlento be specified, meaning (for an FFT length supported by the program) an index0,1,2, ... and so on.0is 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.-nthreadthreadsFor multithread-enabled (default) build, perform the test in parallel mode with this many threads.-mexponentPerform a Lucas-Lehmer primality test of the Mersenne number M(exponent) = 2 ^exponent- 1, whereexponentmust be an odd prime. If-itersis also invoked, this indicates a timing test. This requires suitable added arguments (-fftlenand, optionally,-radset) to be supplied. If the-fftlenoption (and optionally-radset) is also invoked but-itersis not, the program first checks the first line of the$MLUCAS_PATH/worktodo.inifile to see if the assignment specified there is a Lucas-Lehmer test with the same exponent as specified via the-margument. If so, the-fftlenargument is treated as a user override of the default FFT length for the exponent. If-radsetis 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.cfgfile to select the radix set to be used for the user-forced FFT length. If the$MLUCAS_PATH/worktodo.inifile entry does not match the-mvalue, 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-fftlenoption 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-fftlenoption. Perform 100 iterations, or as many as specified via the-itersflag.-fexponentPerform 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-fftlenoption as for the Mersenne-number self-tests (see above notes on the-mflag; note that not all FFT lengths supported for-mare available for-f:-mpermits FFT lengths of formodd* 2 ^ n withodd= any of1,3,5,7,9,11,13,15;-fallows odd =1,7,15and63) Optimal radix sets and timings are written to the$MLUCAS_PATH/fermat.cfgfile. Perform 100 iterations, or as many as specified via the-itersflag.

**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,mlucasmake use ofstderrto print error messages as well as saving them to the$MLUCAS_PATH/*.statfile, where*is in the form pexponentfor Mersenne number 2 ^exponent- 1 or fexponentfor Fermat number 2 ^ (2 ^exponent) + 1. (seeFILESsection for details).0Exit successfully.1Assertion failure. Cannot determine the number of CPUs. Unknown fetal error. Radix set index not available for given FFT length.255thread_policy_set() failure.malloc(3),calloc(3) orrealloc(3) failure.pthread_create(3) orpthread_join(3) failure.

**ENVIRONMENT**

mlucashonors the following environment variables, if they exist:MLUCAS_PATHThe path to readmlucasconfiguration files and to writemlucasgenerated files (seeFILESsection for details).MLUCAS_PATHmust end with a slash (e.g.,/home/foolish/bar/. IfMLUCAS_PATHis not set, thenMLUCAS_PATHdefaults to$HOME/.mlucas.d/, where the environmental variable$HOMEwill be expanded in the environment wheremlucasis invoked.mlucaswill attept to make the directory with parents pointed byMLUCAS_PATHusing themkdir(1) command. The effect is similar to executingmkdir-p$MLUCAS_PATHin the shell provided that the-pflag is honored.

**FILES**

This section detailsmlucasconfiguration files andmlucasgenerated files. As noted in theENVIRONMENTsection,$MLUCAS_PATHdefaults to$HOME/mlucas.d/but this can be overridden at run-time by setting theMLUCAS_PATHenvironment variable.$MLUCAS_PATH/*.statThe 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 pexponentAll 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 ofexponentare recorded in this file. It can be seen as anexponent-specific detailed$MLUCAS_PATH/results.txt(see$MLUCAS_PATH/results.txtbelow for details). This file is useful for debugging purposes. Its format looks like:INFO:event...Mexponent:usingFFTlengthfft_lengthK=fft_length*10248-bytefloats.Bz<this gives an average>bitsbitsperdigitUsingcomplexFFTradicesradix_set(product of all elements of radix_set = fft_length / 2) ...[date_and_time]MexponentIter#=iterationsclocks=time_taken_per_10000_iterations[time_taken_per_iterationsec/iter]Res64:residue.AvgMaxErr=roe_avg.MaxErr=roe_max... [RestartingMexponentatiteration=iteration.Res64:residueMexponent:usingFFTlengthfft_lengthK=fft_length*10248-bytefloats.thisgivesanaveragebitsbitsperdigitUsingcomplexFFTradicesradix_set] (product of all elements of radix_set = fft_length / 2) ...Mexponentisnotprime.Res64:residue.Program:E17.1Mexponentmod2^36=remainder_1Mexponentmod2^35-1=remainder_2Mexponentmod2^36-1=remainder_3$MLUCAS_PATH/fermat.cfgThe format of this file is exactly the same as the format of$MLUCAS_PATH/mlucas.cfg(see$MLUCAS_PATH/mlucas.cfgbelow for details).$MLUCAS_PATH/mlucas.cfgThis file stores the radix set with best timing for each FFT length. Its format looks like:17.1fft_lengthmsec/iter=timingROE[avg,max]=[roe_avg,roe_max]radices=radix_set... Normally, thetimingentry 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 givenfft_lengthto have a highertimingthan the one after it sincemlucaschecks 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 givenfft_lengthhas 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 (seeBUGSsection for details).$MLUCAS_PATH/nthreads.iniThis file sets the number of threads used. It should only contain a positive integer since the content of this file is read bysscanf(in_line,"%d",&NTHREADS);where the variablein_linecontains the content of the$MLUCAS_PATH/nthreads.inifile. If this file is not present,mlucaswill use as many threads as the number of CPUs detected. The number of threads used set by this file can be overridden by setting-nthreadflag 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.txtImportant 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/*.statfiles (see$MLUCAS_PATH/*.statabove 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 subsectionGreatInternetMersennePrimeSearchin sectionNOTESfor details) since the Lucas- Lehmer test exponents are obtained from the PrimeNet server (see$MLUCAS_PATH/worktodo.inibelow for details). Its format looks like:INFO:event... [MexponentRoundoffwarningoniterationiteration,maxerr=roundoff_errorRetryingiterationintervaltoseeifroundofferrorisreproducible.[Retryofiterationintervalwithfatalroundofferrorwassuccessful.]] ...Mexponentisnotprime.Res64:residue.Program:E17.1Mexponentmod2^36=remainder_1Mexponentmod2^35-1=remainder_2Mexponentmod2^36-1=remainder_3...$MLUCAS_PATH/worktodo.iniThis file contains Lucas-Lehmer test assignments to be tested. Its format looks like:assignment=ID,exponent,trialfactoredupto,hasP-1factoring... Theassignmentfield containsTestif the assignment is a first-time Lucas-Lehmer test, orDoubleCheckif the assignment is a double-check Lucas-Lehmer test. (The program handles both cases the same way.)IDis a unique 32-digit hex number.exponentspecifies the Mersenne number (of the form 2 ^exponent- 1) to be tested.trialfactoreduptois the number of bit this Mersenne number has been trial factored up to without finding a factor.hasP-1factoring=0if no prior P-1 factoring has been done,=1if 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=1here 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.inifile (see subsectionGreatInternetMersennePrimeSearchin sectionNOTESfor details). You may need to create the$MLUCAS_PATH/worktodo.inifile if it does not exist.Savefilesin$MLUCAS_PATHAll files matching the following extended regular expression (seeregex(7) for details) in$MLUCAS_PATHdirectory 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 (porf) 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_PATHdirectory: p57885161.stat p57885161.10M p57885161.20M p57885161.30M p57885161.40M p57885161.50M

**NOTES**

GreatInternetMersennePrimeSearchThis subsection needs to be compeleted...

**BUGS**

The argument parser is buggy. The relative position of arguments is relevant tomlucas, the order of arguments inSYNOPSISshould be followed to avoid confusing the parser. Only100,1000and10000are supported for-itersflag. However, the parser will not reject unsupported arguments. Using unsupported arguments for-itersflag may trigger strange behaviour. Sometimes there is more than one applicable exit status values (seeEXITSTATUSsection for details). In such case, there is no guarantee which will be returned. For example, ifmalloc(3) failure triggers an assertion failure. It is possible thatmlucasreturns1instead of255as exit status value. For problems regarding the programmlucas, please contact the author Ernst W. Mayer <ewmayer@aol.com>. For installation and documentation related problems regarding the Debian package and this manual, please usereportbug(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-fftlen192-iters100-radset0-nthread2Perform spot-check to see ifmlucasworks 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,mlucasshould emit a verbose error message.mlucas-smPerform 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.cfgdoes not exist) new timing data to the$MLUCAS_PATH/mlucas.cfg(seeFILESsection for details). Before doing any self-tests, you should first check if there is an existing$MLUCAS_PATH/mlucas.cfgfile and either delete it or do a backup-via-rename to to prevent mixing old and new timing data.$MLUCAS_PATH/mlucas.cfgnormally locates at$HOME/.mlucas.d/directory although this can be overridden at run-time by settingtheMLUCAS_PATHenvironment variable (seeENVIRONMENTsection for details).mlucas&Perform Lucas-Lehmer test on Mersenne numbers by runningmlucasas a background job (seeJOBCONTROLsection inbash(1) andBuiltinssubsection indash(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 -mexponent-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 subsectionGreatInternetMersennePrimeSearchwithin the sectionNOTESandFILESsection for details).AdvancedUsageTipsTo startmlucasin terminal 1, add the following lines to your login shell initialization file, such as$HOME/.profile(seeINVOCATIONsection inbash(1) andInvocationsubsectiondash(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.htmlmlucasis documented fully byMlucasREADME, available both online and offline as shown above.GreatInternetMersennePrimeSearch<https://www.mersenne.org/>MersenneForum<https://www.mersenneforum.org/>ChrisCaldwell'swebpageonMersennenumbers<https://primes.utm.edu/mersenne/index.html>RichardCrandallandBarryFagin,DiscreteWeightedTransformsandLarge-IntegerArithmetic.<https://pdfs.semanticscholar.org/07c0/fae878fe9d6a117de08282802fb7b892bf2d.pdf>RichardE.Crandall,ErnstW.Mayer,andJasonS.Papadopoulos,TheTwenty-FourthFermatNumberisComposite.<https://www.mersenneforum.org/mayer/F24.pdf>