Skip to content

Functions Reference

Jump to bottom
bbuhrow edited this page Jun 9, 2026 · 1 revision

Functions Reference

Functions all take the form funcname(args), where args is some number of comma-delimited arguments. Each argument is an Expressions, Variables, and Reserved Words that YAFU evaluates before passing it in. Some functions accept optional arguments with defaults; see the individual entries below.

Inside an interactive YAFU session, typing help funcname brings up the documentation for that function (read from docfile.txt).

Table of contents

tune

tune()

Performs detailed timing of a sequence of partial SIQS and NFS factorizations. Regression analysis on the timings produces best-fit functions used for estimating future siqs() and nfs() runs. The function coefficients and machine info are automatically appended to yafu.ini as tune_info=... lines. Estimation parameters are then used to choose the optimal SIQS/NFS crossover.

factor

factor(expression)

Combines a variety of routines to (hopefully) optimally factor an arbitrary input. This is YAFU's main driver, and what most users actually run.

Options that affect factor():

  • one — stop after finding one factor.
  • op <name> — output primes/PRPs to file.
  • of <name> — output input + all found factors to file.
  • ou <name> — output unfactored composites to file.
  • no_expr — write full decimal expansion rather than expression form.
  • plan <name> — pretesting plan: none, noecm, light, normal, deep, custom. See Pretesting Plans and T-Levels.
  • pretest_ratio <num> — used by plan=custom.
  • work <num> — assert input has already received pretesting equivalent to t-level num. May be floating-point; if < 1.0, treated as a fraction of input size.
  • xover <num> — GNFS/SIQS crossover in decimal digits. Overrides tune() result.
  • snfs_xover <num> — SNFS/SIQS crossover. Should be smaller than xover (SNFS is usually faster than GNFS).
  • pretest [num] — ECM-pretest only; optional cap as digits or t-level.

If the input has an SNFS form and you've selected a default plan (and haven't passed gnfs), subsequent ECM work is automatically reduced.

siqs

siqs(expression)

The Self-Initializing Quadratic Sieve. Uses the double large prime variation, small prime variation, bucket sieving, and many other optimizations. Post-processing uses a port of Jason Papadopoulos's msieve filtering and block Lanczos. Best for inputs < 105 digits; above that, parameter tuning is less reliable.

Ctrl-C aborts a run; state is saved to siqs.dat (or whatever was set with qssave). Resume by calling siqs again with the same input. Different inputs overwrite the savefile, so back it up before switching jobs. The savefile must be in the same directory as the executable.

Options that affect siqs():

  • qssave <name> — savefile name.
  • siqsR <num> — stop after num relations.
  • siqsT <num> — stop after num seconds.
  • threads <num> — sieving threads.
  • inmem <num> — inputs below this digit count keep relations in memory (faster, but not resumable).
  • v — verbosity.

A full list of SIQS-tuning options (siqsB, siqsTF, siqsLPB, siqsM, siqsNB, siqsTFSm, forceDLP, forceTLP, siqsMFBD, siqsMFBT, siqsBDiv, siqsBT, noopt) is in Configuration and Command-Line Options#qs-siqs-options.

smallmpqs

smallmpqs(expression)

MPQS optimized for small inputs.

nfs

nfs(expression)

Automated factorization using the general number field sieve. Polyselect is multi-threaded via msieve library calls. Sieving uses external GGNFS lattice sieve binaries (ggnfs-lasieve4IXXe). Post-processing (filter, linear algebra, sqrt) goes back through msieve.

The path to the GGNFS binaries must be set, either via -ggnfs_dir <path> or ggnfs_dir=<path> in yafu.ini. The binaries must follow the standard naming convention.

NFS auto-resumes if a job is killed and nfs is called again with the same input. Starting a different job overwrites the savefiles — potentially unrecoverable, so be careful.

Skipping poly select with an external poly

Put a file called nfs.job next to the YAFU binary, with the line n: <your number> on the first line. Then call nfs("your number"). Example contents:

n: <your number here>
skew: 18508.57
Y0: -164285488596487844605
Y1: 96982771931
c0: 3745552009373958707561976
c1: -171516434496742996334
c2: -98669563931139619
c3: 246374333386
c4: 139871450
c5: 3900
rlim: 2500000
alim: 2500000
lpbr: 26
lpba: 26
mfbr: 52
mfba: 52
rlambda: 2.500000
alambda: 2.500000

All lines after the n: line are order-independent.

nfs() will try to detect a special form for any input (sub-second); if detection fails (the usual case) it falls back to standard GNFS polyselect.

With -nt, YAFU can trial-sieve an arbitrary list of external polys and report which sieves fastest.

Options that affect nfs():

Option Effect
ns [X,Y] only sieve, optionally over a range of special-Q start,stop
np [X,Y] only polyselect, optionally over a range of leading coefficients (existing poly file is overwritten)
nc only post-process (filter → LA → sqrt)
nc2 post-process starting at LA (starts LA from scratch!)
nc3 post-process starting at sqrt
ncr resume an in-progress LA
lathreads <num> LA-only thread count
a / r algebraic / rational side sieving (a is default)
job <name> input job file (default ggnfs.job)
o <name> output data file (default msieve.dat)
ggnfsT <num> timeout in seconds (default ∞)
ggnfs_dir <path> GGNFS binary directory
psearch <name> fast (split range/N), wide (search N× range), deep (all threads on same coeff), min / avg / good (Batalov heuristic; default avg)
pbatch <num> block size of leading coeffs to distribute (default 250)
R required to restart over an existing savefile
siever <num> GGNFS siever version (the <num> in ggnfs-lasieve4I<num>e)
nt <file1>,<file2>,... trial-sieve listed job files then exit
filt_bump <num> percentage to raise min_rels on failed filter attempts (default 5%; not remembered across aborts)

Examples

# 1) poly select only, parallel, with a custom starting value
yafu "nfs(number)" -v -threads 4 -np 10000,0

# 2) automated NFS on 400 bits with a deep poly search and a 10-hour cap
yafu "nfs(rsa(400))" -v -threads 4 -psearch deep -ggnfsT 36000

# 3) automated NFS with a custom job file, rational side, custom data file
yafu "nfs(number)" -v -threads 4 -job custom.poly -r -o snfs_output.dat

# 4) automated SNFS on an input with no known large factors; YAFU
#    computes and proceeds with the primitive factor if applicable
yafu "nfs(2^1039-1)" -v

snfs

snfs(expression, cofactor)

Automated factorization using the special number field sieve. YAFU generates SNFS polynomials suitable for the input expression, used to factor the cofactor of the expression. Sieving and post-processing then behave exactly like nfs(). You can resume either with nfs() or snfs().

To supply your own polynomial: put it in a file named nfs.job (with n: <your number> first, as for GNFS). To make YAFU proceed as SNFS, the file must also contain type: snfs and size: <snfs difficulty> lines. YAFU adjusts the minimum-relations estimate to account for the easier difficulty.

Supported special forms

  • Various k*b^n+c, including:
    • Cunningham numbers (b^n ± 1, b ∈ {2, 3, 5, 6, 7, 10, 11, 12})
    • Brent forms (b^n ± 1, 13 ≤ b ≤ 99)
    • Odd perfect numbers (b^n − 1, b > 99)
    • Generalized Cullen/Woodall (a*b^a ± 1)
    • Others: k*2^n ± 1, repunits, Mersenne plus 2, etc.
    • Note: for large b, cases with k > 1 or |c| > 1 may not be detected.
  • Homogeneous Cunninghams (a^n ± b^n, a,b ≤ 12, gcd(a,b) = 1)
  • XYYXF numbers (x^y + y^x, 1 < y < x < 151)
  • Inputs of the form c5*m^5 + c4*m^4 + c3*m^3 + c2*m^2 + c1*m + c0 where m = b^p, |cn| < 10000, 2 ≤ b ≤ 19, and 2 ≤ p ≤ 75·log(10)/log(b).

snfs supports every nfs() flag plus:

Option Effect
testsieve <num> digit-size beyond which YAFU will test-sieve the top 3 SNFS polys (default 140). If a poly is unusably slow you can safely kill the GGNFS process and YAFU will continue scoring the others.

Examples

# 1) SNFS poly select on an odd perfect number, skipping test sieve,
#    writing to a custom job file
yafu "snfs(158071^37-1, (158071^37-1)/158070)" -v -np -job opn.poly -testsieve 300

# 2) resume sieving + post-processing
yafu "snfs(158071^37-1, (158071^37-1)/158070)" -v -R -ns -nc -job opn.poly

pm1

pm1(expression)

Pollard P−1. As of YAFU 1.28, uses GMP-ECM exclusively. Stage 1 bound is POLLARD_STG1_MAX (default 100000); stage 2 is POLLARD_STG2_MAX.

To use the GMP-ECM default B2, just leave B2ecm / B2pp1 / B2pm1 unset. Specifying B2 overrides the default.

Options: B1pm1, B2pm1.

ecm

ecm(expression1, [expression2])

Elliptic Curve Method. As of 1.28, uses GMP-ECM exclusively. Stage 1 bound is ECM_STG1_MAX (default 11000); stage 2 is ECM_STG2_MAX. Leave B2ecm unset for the GMP-ECM default.

  • expression1 — number to factor.
  • expression2 (optional) — number of curves to run at the current ECM_STG* bounds. Default: 1 curve.

To use an external ECM binary, set ecm_path (CLI flag or yafu.ini). External binaries run multi-threaded when threads are requested. The built-in GMP-ECM can also run multi-threaded on Linux.

Options: B1ecm, B2ecm, ecm_path.

pp1

pp1(expression, [expression2])

Williams P+1. As of 1.28, uses GMP-ECM exclusively. Stage 1 bound is WILLIAMS_STG1_MAX (default 20000); stage 2 is WILLIAMS_STG2_MAX.

  • expression1 — number to factor.
  • expression2 (optional) — number of "curves" to run. Typical value is 3, to make it more likely an actual P+1 test gets performed. (See Crandall & Pomerance for details.)

Options: B1pp1, B2pp1.

rho

rho(expression)

Pollard's rho with Brent's improvement. Max iterations is BRENT_MAX_IT.

Options: rhomax.

trial

trial(expression1, [expression2])

Trial division of expression1 by all primes up to expression2. Default bound is 10000.

fermat

fermat(expression1, expression2)

Fermat's factorization algorithm on expression1, capped at expression2 iterations.

squfof

squfof(expression)

Shanks's SQUFOF (square-form factorization) with multipliers. Upper bound on input is 62 bits.

gcd

gcd(expression, expression)

Greatest common divisor via Lehmer/Euclid.

jacobi

jacobi(expression, expression)

Jacobi symbol p/q.

isprime

isprime(expression)

Trial division followed by Rabin-Miller probabilistic primality. Number of witnesses is NUM_WITNESSES (default 20).

bpsw

bpsw(expression)

Baillie–Pomerance–Selfridge–Wagstaff probabilistic primality test. No known composites pass it.

aprcl

aprcl(expression)

Adleman–Pomerance–Rumely–Cohen–Lenstra primality proof. Proves up to 6021 digits; above that, falls back to BPSW.

issquare

issquare(expression)

Tests whether the input is a perfect square.

ispow

ispow(expression)

Tests whether the input is a perfect power.

fib

fib(expression)

The n-th Fibonacci number.

luc

luc(expression)

The n-th Lucas number.

modinv

modinv(expression1, expression2)

Modular inverse of one number with respect to another.

lg2

lg2(expression)

Binary log (log base 2).

log

log(expression)

Base-10 log.

ln

ln(expression)

Natural log.

modexp

modexp(expression1, expression2, expression3)

Modular exponentiation: a^b mod n.

sqrt

sqrt(expression)

Integer square root via Newton's method.

nroot

nroot(expression1, expression2)

The expression2-th root of expression1, via Newton's method.

shift

shift(expression1, expression2)

Binary left/right shift of expression1 by expression2 bits.

size

size(expression)

Print the size of the number (digits and bits).

rsa

rsa(expression)

Generate a difficult-to-factor number of a specified bit size. Not for cryptographic use.

rand

rand(expression)

Random number with a specified number of digits.

randb

randb(expression)

Random number with a specified number of bits. (Mentioned in the utility-function list in docfile.txt.)

primes

primes(expression1, expression2, [expression3])

Print or count primes in [expression1, expression2]. If expression3 is 1, count; if 0, print. Default is count.

  • PRIMES_TO_FILE non-zero → output to primes.dat.
  • PRIMES_TO_SCREEN non-zero → print to screen.
  • -pfile and -pscreen set the same behavior.

Both endpoints must be < 4e18, and expression2 > expression1.

bigprimes

bigprimes(lower, upper, depth)

Sieve an arbitrary range [lower, upper] of (possibly arbitrary-precision) integers using primes up to depth. depth is currently capped at < 2e9. Survivors are PRP-tested, so the output is probable primes only.

  • PRIMES_TO_FILE non-zero → output to prp_values.dat.
  • PRIMES_TO_SCREEN non-zero → print to screen.

nextprime

nextprime(expression1, [expression2])

Find the next prime after expression1.

  • expression2 == 0: find the next prime smaller than the input.
  • Otherwise: find the next prime larger (default if omitted).

llt

llt(expression)

Lucas–Lehmer test on 2^expression - 1. A small amount of trial division is performed first, after confirming that the exponent is prime.

Clone this wiki locally