MLUCAS(1)

📦
version 20.1.1 · 4 versions
, in ubuntu questing, ubuntu resolute, ubuntu stonking

💖 MLUCAS 💖

okay bestie, welcome to the manual page for mlucas (that's section 1 of the manual, User Commands, in case you were wondering where this lives) 💅

✨ NAME ✨

mlucas — the program that runs the Lucas-Lehmer test on a Mersenne number, 2 ^ p - 1. that's it, that's the whole name line 🫶

🦋 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 🌸

[FIXME: This man page is potentially outdated, please see the online documentation <https://www.mersenneforum.org/mayer/README.html> or the help text located in /usr/share/doc/mlucas/help.txt.gz for up-to-date information.]

so, real talk: this manual page documents briefly the mlucas command. just the highlights, the vibe, the essentials 💫

mlucas is an open-source (and free/libre, no cap) program for performing the Lucas-Lehmer test on prime-exponent Mersenne numbers — that means integers of the form 2 ^ p - 1, where the exponent p is prime. short version? this is everything you need to go hunting for world-record Mersenne primes 👑✨ it's literally been used in the verification of various Mersenne primes, including the 45th, 46th and 48th found Mersenne prime. iconic behaviour, honestly.

you may use it to test any suitable number as you wish, bestie, but it is preferable that you do so in a coordinated fashion, as part of the Great Internet Mersenne Prime Search (GIMPS). for more info on GIMPS, go peek at the Great Internet Mersenne Prime Search subsection inside the NOTES section and the SEE ALSO section 🫶

okay now the tea ☕ — 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), because it requires the user to abide by the prize-sharing rules set by its author — which is incompatible with freedom to run the program as you wish, for any purpose 🙈. and yeah, that applies 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 the EFF Cooperative Computing Awards at <https://www.eff.org/awards/coop> for the deets 💸

so how does it actually work? mlucas reads the exponents from the $MLUCAS_PATH/worktodo.ini file 📖. results get written to the $MLUCAS_PATH/results.txt file and the exponent-specific $MLUCAS_PATH/*.stat file (check the FILES section for details). error messages go to stderr and to the $MLUCAS_PATH/*.stat file. exponents can also be passed as command-line arguments, but that's mainly used for debugging (see the OPTIONS section for details) 🔍. bonus: mlucas can also perform the Pe'pin primality test on Fermat numbers 2 ^ (2 ^ n) + 1, using an exponent-optimized fast-transform length much like the one used for testing Mersenne numbers. versatile queen 💅

new users are urged to jump straight to the EXAMPLE section and follow the examples and pointers to the other sections, fr fr. got no time for in-depth reading? then at minimum read the NOTES, BUGS and EXAMPLE sections for a brief intro to GIMPS, the undesirable restrictions, and common usages 🌸. the 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. and lastly — the Mlucas README, available both online and offline, is highly recommended, because it's 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 dash (-). a summary of options is included below 👇 a complete description is in the SEE ALSO section.

  • -h — show the version of the program and a summary of options. the little "hi bestie, here's what I can do" moment 💖
  • -s t, -s tiny — run a 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 a 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 a 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 a 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 a 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 a 100-iteration self-test on all Mersenne exponents and all FFT radix sets. this will take several hours on a fast (pre-2010) CPU 💀 go make a snack, bestie
  • -fftlen fft_length — this lets you 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 the 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 you can go in the enumeration depends on the FFT length. the moment you try an index out of range of the current FFT length, the program will error-exit with an informational message to that effect — and that message also notes the maximum allowable radix set index for that FFT length, so it's a helpful little rejection, not a mean one 🙈
  • -nthread threads — for a multithread-enabled (default) build, perform the test in parallel mode with this many threads. go parallel, go fast, slay ⚡
  • -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 the notes above 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 🌈

ngl, 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 makes 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 the Mersenne number 2 ^ exponent - 1, or

fexponent

for the Fermat number 2 ^ (2 ^ exponent) + 1. (see the 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 🌿

bestie, mlucas is a lil diva and it will read these environment variables if they exist. so like, set them or don't, but know what's up 💅

  • MLUCAS_PATH — the path where mlucas reads its config files and writes its generated files (peep the FILES section for the tea 🫖). IMPORTANT: MLUCAS_PATH must end with a slash (like /home/foolish/bar/. — yes really). if MLUCAS_PATH isn't set, it defaults to $HOME/.mlucas.d/, and that $HOME gets expanded in the environment where mlucas is invoked. mlucas will attempt to make the directory (with parents!) pointed to by MLUCAS_PATH using the mkdir(1) command. the effect is basically like running mkdir -p $MLUCAS_PATH in the shell — provided that the -p flag is honored. no cap.

📁 FILES 📁

okay so this section is the whole tour of mlucas's config files and its generated files. as we said up in ENVIRONMENT, $MLUCAS_PATH defaults to $HOME/mlucas.d/, but you can override that at run-time by setting the MLUCAS_PATH environment variable. slay, customization ✨

🌸 $MLUCAS_PATH/*.stat

the filename-prefix wildcard * works as described in the EXIT STATUS section, iykyk. for the primality test of the Mersenne number 2 ^ exponent - 1, it takes the form:

pexponent

every important event, the per-10000-iteration residues (or per-100000-iteration if more than 4 threads are used for the test 😳), and the final residue during the Lucas-Lehmer test of exponent all get recorded in this file. think of it as an exponent-specific, detailed version of $MLUCAS_PATH/results.txt (scroll down for the details on that one 💖). this file is super 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 right below for the details, bestie 🫶).

🌸 $MLUCAS_PATH/mlucas.cfg

this file stores the radix set with the 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 top to bottom, since a larger FFT length should take longer to test. BUT it's totally OK for a given fft_length to have a higher timing than the one right after it, because mlucas checks the timings listed in this file for all FFT lengths >= the default FFT length for the number being tested, and then uses the FFT length that has the smallest listed timing. smart, right? 😌

⚠️ heads up though: if you notice this file has any entries where a given fft_length has a timing 5% or more greater than the next-larger FFT length, or a higher timing than two or more larger FFT lengths, please contact the author (see the BUGS section for the deets 📩).

🌸 $MLUCAS_PATH/nthreads.ini

this file sets the number of threads used. it should only contain a positive integer, because the content of this file gets 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 isn't present, mlucas will use as many threads as the number of CPUs detected. 👑

the number of threads set by this file can be overridden by setting the -nthread flag at run-time. this file is for the girlies who wanna set the number of threads to be greater or less than the number of CPUs detected. why would you do that? well, some users reported up to 10% performance gain when using more threads than the number of CPUs detected. iconic behaviour fr fr 🔥

🌸 $MLUCAS_PATH/results.txt

important events that happened during the Lucas-Lehmer test, plus the final residue obtained, all get recorded in this file. it summarizes the important info from all the $MLUCAS_PATH/*.stat files (see above bb 💜) into a single file.

this file — more specifically, any results which were added to it since your last checkin — should be submitted to the PrimeNet server (see the Great Internet Mersenne Prime Search subsection in the NOTES section for details), since the Lucas-Lehmer test exponents are obtained from the PrimeNet server (see $MLUCAS_PATH/worktodo.ini below for that 💖).

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 the Lucas-Lehmer test assignments to be tested. its format looks like:

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

okay let's break down the fields, one by one, because this one has lore:

  • 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 exact same way, no drama 💅)
  • 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 bits 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, because such an assignment is slightly more likely (5-10%) to yield a prime. so like, free odds boost, take it bestie ✨

to do a 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 the Great Internet Mersenne Prime Search subsection in the NOTES section for details). you may need to create the $MLUCAS_PATH/worktodo.ini file if it doesn't exist yet — go forth and touch it 🌸

🌸 Save files in $MLUCAS_PATH

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

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

for both of the supported test types, duplicate pairs of savefiles get written at each checkpoint, to guard against corruption of the on-disk savefiles. protection is self-care 🛡️

  • Lucas-Lehmer test savefile-pair names start with <p> and <q>, respectively.
  • Pe'pin test savefile-pair names start with <f> and <q>, respectively.
do NOT modify them — but backups may be made by the user, that's allowed 💖

by default, the program will save a persistent backup of the primary (p or f) save file every 10 millionth iteration. for example, 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 📝

this subsection needs to be compeleted...

(yes bestie, that's the whole subsection. it's giving "we'll finish it later" energy 😭 the author said what he said.)

💀 BUGS 💀

okay, the tea on the bugs, and we're being honest here:

the argument parser is buggy. 🫠 the relative position of arguments matters to mlucas, so you should follow the order of arguments in the SYNOPSIS to avoid confusing the parser. also, only 100, 1000 and 10000 are supported for the -iters flag. and here's the cursed part: the parser will not reject unsupported arguments. so if you pass unsupported values to the -iters flag, it may trigger strange behaviour. no error message, just chaos. you've been warned bestie 💀

sometimes there's more than one applicable exit status value (see the EXIT STATUS section for details). in that case, there is no guarantee which one will be returned. for example, if a malloc(3) failure triggers an assertion failure, it's possible that mlucas returns 1 instead of 255 as the exit status value. unpredictable queen 😭

for problems regarding the program mlucas, please contact the author Ernst W. Mayer <ewmayer AT aol DOT com> 📩

for installation and documentation related problems regarding the Debian package and this manual, please use reportbug(1) to contact Alex Vong <alexvong1995 AT protonmail DOT com> 🫶

🌟 EXAMPLE (the "what do I actually type" section) 🌟

Okay bestie, there are 3 common cases where you're gonna wanna run this program. The vibe is: spot-check first to quick-test your build, then the self-test range for medium exponents, and finally the full-blown Lucas-Lehmer testing which is, like, the entire main character purpose of this program. ✨

  • mlucas -fftlen 192 -iters 100 -radset 0 -nthread 2 — do the spot-check to see if mlucas even works, and if it doesn't, fill in a bug report. 🙈 The spot check should produce residues matching the internal tabulated ones. If the residues don't match, mlucas should emit a verbose error message. (She's dramatic about it, as she should be. 💅)
  • mlucas -s m — do the 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 (peep the FILES section for details, iykyk). 🫶
Before doing any self-tests, you should first check if there's an existing $MLUCAS_PATH/mlucas.cfg file and either delete it or do a backup-via-rename to prevent mixing old and new timing data. No cap, mixing them is a mess. 😭

$MLUCAS_PATH/mlucas.cfg normally locates at $HOME/.mlucas.d/ directory although this can be overridden at run-time by setting the 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 a 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 the 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 in dash(1) for details). It's giving set it and forget it. 🧚

# 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 🔗

mlucas is documented fully by Mlucas README, available both online and offline as shown above. Both! Because she contains multitudes. 🦋

And that's the whole page, bestie!! 🎀 This is Mlucas 20.1.1, dated 2019-01-26, and it's page MLUCAS(1) in the manual. Go forth and hunt primes — you're literally the main character of the Mersenne search now. 💜✨🫶

📦 where this page comes from