# 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

- **Factoring drivers:** [factor](#factor) · [siqs](#siqs) · [smallmpqs](#smallmpqs) · [nfs](#nfs) · [snfs](#snfs) · [squfof](#squfof) · [pm1](#pm1) · [pp1](#pp1) · [rho](#rho) · [trial](#trial) · [ecm](#ecm) · [fermat](#fermat)
- **Primality / testing:** [isprime](#isprime) · [bpsw](#bpsw) · [aprcl](#aprcl) · [issquare](#issquare) · [ispow](#ispow) · [llt](#llt)
- **Number theory:** [gcd](#gcd) · [jacobi](#jacobi) · [modinv](#modinv) · [modexp](#modexp) · [fib](#fib) · [luc](#luc)
- **Arithmetic / math:** [shift](#shift) · [nroot](#nroot) · [sqrt](#sqrt) · [lg2](#lg2) · [log](#log) · [ln](#ln)
- **Utilities:** [rsa](#rsa) · [rand](#rand) · [randb](#randb) · [size](#size) · [primes](#primes) · [bigprimes](#bigprimes) · [nextprime](#nextprime) · [tune](#tune)

---

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

```bash
# 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

```bash
# 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.