[help]

YAFU Version 1.35-beta

--------------------------------------------------------------------------------

Introduction:

--------------------------------------------------------------------------------

YAFU is an interactive mathematical environment, similar to

MATLAB, pari/gp, or bc. You write expressions on the command line,

and it will interpret and evaluate them. Results can be assigned

to variables, and variables can be used in expressions. Some basic

programming language syntax like "for" and "if/else" are also available.

Use 'quit' or 'exit' to exit the application.

You can also call yafu from the OS command line, either by providing

an argument to yafu like this:

yafu "2+2"

or

yafu "siqs(rsa(200))"

Or by redirecting input from somewhere else:

echo "2+2" | yafu

yafu < in.txt

Or by providing the name of a script or batchfile that contains valid yafu syntax:

yafu -script do_stuff.txt

yafu -batchfile numbers_to_factor.txt

The use of quotes around the expressions may or may not be necessary

depending on the OS. All expressions supported in the interactive

environment are supported in this way.

In addition, when providing arguments to yafu you can specify

flags to change program behavior. Supported flags are:

-p run yafu at idle priority

-B1pm1 <num> B1 bound in the pm1 method

-B1pp1 <num> B1 bound in the pp1 method

-B1ecm <num> B1 bound in the ECM method

-rhomax <num> max iterations in the rho method

-B2pm1 <num> B2 bound in the pm1 method

-B2pp1 <num> B2 bound in the pp1 method

-B2ecm <num> B2 bound in the ECM method

-qssave <name> Name of the siqs savefile to use in this session

-siqsR <num> Stop after finding num relations in siqs

-siqsT <num> Stop after num seconds in siqs

-logfile <name> Name of the logfile to use in this session

-seed <num,num> 32 bit numbers for use in seeding the RNG <highseed,lowseed>

-batchfile <name> Name of batchfile to use in command line job. Items are

removed from the batchfile as they are completed.

-sigma <num> Input to ECM's sigma parameter. Limited to 32 bits.

-session <name> Use name instead of the default session.log

-threads <num> Use num sieving threads in SIQS and ECM

-v Use to increase verbosity of output, can be used

multiple times

-silent No output except to log file (not available in interactive

environment)

-pfile Adding this flag causes the primes() function to output primes

to primes.txt

-pscreen Adding this flag causes the primes() function to output primes

to the screen

-forceDLP Adding this flag forces SIQS to use double large primes

-fmtmax <num> max iterations for the fermat method

-noopt flag to force siqs to not perform optimization on the small

tf bound

-vproc Increase verbosity of processor detection code on startup

-noecm Set this flag to skip all ECM stages in the factor() function

and instead proceed directly to QS/NFS after small factor

detection.

-one Tells factor() to stop factoring after finding one factor.

-ggnfs_dir <path> path to ggnfs binaries

-op <name> Tells factor() to output primes and prps to file <name>.

-of <name> Tells factor() to output an input number and all found factors

to file <name>.

-ou <name> Tells factor() to output unfactored composites to file <name>.

-no_expr When outputting numbers to file, do not print expression form,

show full decimal expansion.

-plan <name> Tells factor() to follow one of the following pretesting plans:

<name> = none: do only trial division and rho

<name> = noecm: stop before first ecm step and start

nfs/qs

<name> = light: pretest to t-level 2/7 the size of

the input before starting qs/nfs

<name> = normal: pretest to t-level 4/13 the size of

the input before starting qs/nfs

<name> = deep: pretest to t-level 1/3 the size of the

input before starting qs/nfs

<name> = custom: pretest to t-level specified by the

ratio in the –pretest_ratio option

-pretest_ratio <num> A fractional value used in the plan=custom mode of operation to

determine the depth of pretesting. Inputs are pretested

to t-level equal to size of input * pretest_ratio

-work <num> Assert to factor() that the input has already received pretesting

equivalent to the specified t-level. In other words, if you know

that an input has received ~900 ecm curves at B1=1M, then

specify –work 35. This value may be input as floating point.

If the value input is less than 1.0, then the input acts as a

scaling factor to the current input. For example if a 213 digit

number is input along with -work 0.1, work is interpreted as 21.3.

-xover <num> Use this option to specify the decimal digit size beyond which nfs

should be used instead of qs. Specifying this option overrides

any crossover point computed from tuning data. May be entered

as a floating point number.

-pretest [num] Use this switch with factor() for ECM pretesting of the input number.

Optionally provide an integer value specifing the maximum level of

pretesting to do (up to "num" digits, or a t-level of "num")

-ecm_path <path> full path to ecm binary

-nprp <num> Specify the number of witnesses to every Rabin-Miller test in yafu

-ext_ecm <num> specify the B1 value beyond which yafu will attempt to use

external ecm binaries. below the specified threshold it will use

built-in ecm code

-aprcl_p <num> Specify the upper size limit of numbers to be proved prime by APR-CL

(in decimal digits, default = 300, hard upper limit = 6021)

-aprcl_d <num> Specify the upper size limit of numbers that are proved prime by

APR-CL "silently". Above this limit, APR-CL progress will be

printed (in decimal digits, default = 200)

NFS BEHAVIOR OPTIONS - configuring phases to run

general info: if none of these options are specified, yafu will perform all of

them in order (poly search, sieving, filter, LA, sqrt). On restarts, the set

of phases performed is automatically determined by yafu and depends on the state

of one or more saved files associated with the input number. If any of the

following 5 options are specified, only those phases will be performed; checks

against saved files will still be in place (i.e., refusal to overwrite data files)

-np [X,Y] Perform poly search step within nfs(). NOTE: any existing

poly files will be overwritten. Optionally, provide a range of

leading coefficients over which to search in the format: start,stop

-ns [X,Y] Perform sieving step within nfs() if a valid job file exists

for the input number and if the input number is the same as

that specified in an existing data file. Optionally, provide

a range of special Q over which to sieve in the format: start,stop

-nc Perform postprocessing step within nfs(), starting with

filtering

-nc2 Perform postprocessing step within nfs(), starting with

linear algebra

-nc3 Perform postprocessing step within nfs(), starting with sqrt

NFS BEHAVIOR OPTIONS - general

-lathreads <num> Use specified number of threads for linear algebra only. If

not specified, 'threads' threads are used (which defaults to 1).

-a Use special Q on the algebraic side within nfs()

-r Use special Q on the rational side within nfs()

-job <name> Name of input file in nfs - use a file other than ggnfs.job

as the input job file.

-o <name> Name of output file in nfs() - use a file other than

msieve.dat as the output data file

-ggnfsT <num> Timeout to apply to nfs() command, in seconds (default = infinity)

-psearch <name> Specify method of parallel polynomial selection with N threads:

'fast' - divides the search time by N (default)

'wide' - normal time deadline, search N times the

leading coefficient range

'deep' - normal time deadline, search every leading

coefficient with N threads

Note that when N = 1, this option has no effect.

'min' - stop poly search when a score of minimal quality is found

'avg' - stop poly search when a score of average quality is found

'good' - stop poly search when a score of good quality is found

For options 'min', 'avg', and 'good', Batalov's heuristic is used:

https://www.mersenneforum.org/showpost.php?p=305315&postcount=3

with multipliers of 1.0, 1.036 and 1.072.

Default is 'avg'.

-pbatch <num> Size of blocks of leading coefficients to distribute during

NFS polynomial selection. Default is 250.

-R Must specify in order to restart when a previous savefile exists

-siever <num> Specify the ggnfs siever version to use, where <num> is

the integer in the default ggnfs siever name. I.e,

ggnfs-lasieve4I<num>e.exe

-nt <file1>,<file2>... Perform automated trial sieving of the listed job files (then exit)

(yafu will fill any missing ggnfs parameters as necessary)

-testsieve <num> Number of digits beyond which yafu will test sieve the top

3 polynomials discovered by snfs (default: 140)

These flags are ignored when redirecting input to yafu.

These same flags can be specified in a file named yafu.ini in the same

directory as the executable. Put <flag>=<value> pairs on single lines

of the file to override default values. Command line arguments will override

both default values and anything in the .ini file. An example yafu.ini

should have been included along with the binary in the downloadable package.

------------

T-levels

------------

A note on the “t-level” terminology used in factor(). Something that has

received, say, "t30", has had enough ecm curves run on it so that the probability

that a factor of size 30 has been missed is exp(-1) (about 37%). Likewise,

t35 indicates that factors of size 35 are expected to be missed about 37%

of the time (at which point a 30 digit factor would only be expected to be

missed ~5% of the time). t-levels are calculated from tabulated data extracted

by A. Schindel from GMP-ECM in verbose mode. See also the GMP-ECM README file.

I am unaware if t-level is universally accepted terminology or not, but others

frequently use it (mersenneforum.org), and it is a handy way to talk about

how much a particular number has been tested with ecm.

------------

Batchfiles

------------

A command line driver job can take as input a batchfile

using the -batchfile flag. This batchfile can contain any valid YAFU expression

on each line of the file. Optionally, an expression can be supplied on the command

line in the usual manner. In this case the expressions in the batch file are substituted

into the input expression in place of the special character @ in the input expression.

If the @ character is not found, the input expression is ignored and the lines of the batchfile

are treated as the input expressions.

Examples:

To start factoring work on a list of input numbers, one per line, contained in a file called in.bat, do

the following from the command line:

% yafu "factor(@)" -batchfile in.bat

To start work on a list of input expressions, one per line, contained in a file called in.bat, do

the following from the command line:

./yafu "@" -batchfile in.bat

or, equivalently:

./yafu -batchfile in.bat

Lines of the batchfile are removed as they are completed.

------------

Expressions:

------------

An expression is any (nested) series of functions and/or operators.

Any amount of nesting is possible, so long as the expression is

less than 2048 characters. White space can be used anywhere - it is

removed prior to processing. Expressions must be proper infix notation,

for example -1(7*8) will not work but -1*(7*8) will.

------

Bases:

------

YAFU can handle input/output in several different bases, specified

by the IBASE and OBASE reserved words. Recognized bases include

(for the moment) hexadecimal and decimal. Binary and Octal as

well as arbitrary bases are on the agenda. Once IBASE is set to

a base, all other input is interpreted in that base. Likewise once

OBASE is set, all output appears in that representation.

This behavior can be overridden on input by using 0x before a number

to indicate hexadecimal, or 0d for decimal.

All hexadecimal alphabetic characters must be entered in ALL CAPS.

----------

Operators:

----------

Valid operators include the standard +,-,*,/,%,^, as well as ! for

factorial, # for primorial, >> for binary right shift and <<

for binary left shift. Left and right parentheses can also be used

for grouping.

----------

Functions:

----------

Functions all take the form 'funcname(args)', where funcname is the

function's name and args is some number of comma delimited arguments.

Issuing the command 'help funcname' will bring up more detailed help

on a particular function. Some functions support a variable number

of arguments, with a default defined for the optional arguments. See

the individual functions documentation for more info.

The following are all the supported functions:

utility factoring arithmetic

------------------------------------------------------------------------------------------

rsa factor shift

size siqs nroot

primes smallmpqs modexp

nextprime nfs sqrt

rand squfof lg2

randb pm1 log

isprime pp1 ln

ispow rho gcd

issquare trial jacobi

sieverange ecm modinv

testrange fermat fib

bpsw snfs luc

aprcl llt

----------

Variables:

----------

Variable names can be any combination of lower case alphanumeric

characters including _ and `, but the first character must be

in {a-z} or _. Variable names also cannot be the same as certain

reserved words.

---------------

Reserved Words:

---------------

Some words are reserved by the application and most can be altered

by the user to impact the program execution. They can be useful if

you are in interactive mode and want to set a global variable that

wasn't set while invoking yafu (or in the .ini file).

Some examples include:

POLLARD_STG1_MAX - controls the upper bound of p-1 stage 1 factoring

POLLARD_STG2_MAX - controls the upper bound of p-1 stage 2 factoring

WILL_STG1_MAX - controls the upper bound of p+1 stage 1 factoring

WILL_STG2_MAX - controls the upper bound of p+1 stage 2 factoring

ECM_STG1_MAX - controls the upper bound of ECM stage 1 factoring

ECM_STG2_MAX - controls the upper bound of ECM stage 2 factoring

BRENT_MAX_IT - controls the maximum number of iterations in pollard rho

NUM_WITNESSES - the number of witnesses to use in rabin-miller prp tests

IBASE - controls the input numeric base

OBASE - controls the output numeric base

PRIMES_TO_FILE - set to non zero to enable printing primes to a file, when using the

primes() function

PRIMES_TO_SCREEN - set to non zero to enable printing primes to the screen, when using the

primes() function

VFLAG - control verbosity within the interactive environment

[tune]

usage: tune()

description:

performs detailed timing of a sequence of partial SIQS and NFS factorizations. From these,

regression analysis is performed and best-fit functions are created for the purpose of

estimating siqs() and nfs() factorizations. Function coefficients together with machine info

is automatically added to yafu.ini. Estimation parameters are used to determine the optimal

siqs/nfs crossover point.

[nfs]

usage: nfs(expression)

description:

Automated factorization using the number field sieve. Multi-threaded polynomial selection is

handled via msieve library function calls. Sieving then proceeds in a multi-thread aware fashion

using external ggnfs lattice sieve executables. Post processing (filtering, linear algebra, and

sqrt functions) again make use of msieve library calls. The path to the ggnfs lasive binaries must

be specified either on the command line using the -ggnfs_dir switch, or in the yafu.ini file as a

"ggnfs_dir=<path>" line. It is assumed that the ggnfs binaries follow the usual naming convention

(i.e. gnfs-lasieve4IXXe). nfs is automatically resumed if a job is killed prior to completion and

nfs is called again with the same input. Starting a different job will overwrite a previously

incomplete factorization's data files, which is potentially unrecoverable. To skip polynomially

selection and instead use an externally produced polynomial and lattice siever parameterization,

create a file called nfs.job with the following format prior to calling yafu with

nfs("your number"), in the same directory as the yafu binary:

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

the n: "your number here" line must be on the first line of the nfs.job file. All other lines

should be interchangable. Note that, for convenience, nfs will attempt to detect a special form

for all inputs, which should take less than a second; in the overwhelming likelihood that it fails,

nfs will revert to standard gnfs poly select.

With the -nt option, yafu can perform automated trial sieving of an arbitrary list of external

polys, and report which one sieves the fastest.

command line flags affecting nfs:

-ns [X,Y] Only perform sieving step within nfs() if a valid job file exists for the

input number and if the input number is the same as that specified in

an existing data file.

Optionally, provide a range of special Q over which to sieve in the format: start,stop

-np [X,Y] Only perform poly search step within nfs(). NOTE: any existing poly files will

be overwritten. Optionally, provide a range of leading coefficients over which to

search in the format: start,stop

-nc Only perform postprocessing step within nfs(), filter, LA, and sqrt in order

-nc2 Only perform postprocessing step within nfs(), starting with linear algebra

-nc3 Only perform postprocessing step within nfs(), starting with sqrt

-lathreads <num> Use specified number of threads for linear algebra only. If not specified

'threads' threads are used (which defaults to 1).

-a Use special Q on the algebraic side within nfs() (default)

-r Use special Q on the rational side within nfs()

-job <name> Name of input file in nfs - use a file other than ggnfs.job as the input job file.

-o <name> Name of output file in nfs() - use a file other than msieve.dat as the output data file

-ggnfsT <num> Timeout to apply to nfs() command, in seconds (default = infinity)

-ggnfs_dir <path> path to ggnfs binaries

-psearch <name> Specify method of parallel polynomial selection with N threads:

'fast' - divides the search time by N (default)

'wide' - normal time deadline, search N times the leading coefficient range

'deep' - normal time deadline, search every leading coefficient with N threads

Note that when N = 1, this option has no effect.

-pbatch <num> Size of blocks of leading coefficients to distribute during NFS polynomial selection.

Default is 250.

-R Must specify in order to restart when a previous savefile exists

-siever <num> Specify the ggnfs siever version to use, where <num> is the integer in the default

ggnfs siever name. I.e, ggnfs-lasieve4I<num>e.exe

-nt <file1>,<file2>... Perform automated trial sieving of the listed job files (then exit)

(yafu will fill any missing ggnfs parameters as necessary)

-filt_bump <num> Raise the min_rels bound by the specified percentage on unsuccessful filtering

attempts. Floating point number interpreted as a percentage. default = 5%

Note that the new min_rels is not remembered on abort.

Examples:

1) perform poly selection only, in parallel, within a custom starting value (default range),

with verbose output:

"nfs(number)" -v -threads 4 -np 10000,0

2) perform automated nfs on a 400 bit input, but do a 'deep' polynomial search,

and stop the process after 10 hours:

"nfs(rsa(400))" -v -threads 4 -psearch deep -ggnfsT 36000

3) perform automated nfs, using a custom job file, using rational side sieving,

and output to a custom data file

"nfs(number)" -v -threads 4 -job custom.poly -r -o snfs_output.dat

4) perform automated snfs on an input with no known large factors. If applicable, YAFU will

compute and proceed with the primitive factor of the input.

"nfs(2^1039-1)" -v

[snfs]

usage: snfs(expression, cofactor)

description:

Automated factorization using the special number field sieve. yafu generates snfs polynomials

suitable for the input expression, used for factoring the "cofactor" of the expression. Sieving

and post-processing then take place in exactly the same manner as with the nfs function above.

You can resume sieving or postprocessing with either the nfs or snfs functions. As with the nfs

function, you can provide your own polynomial (and ggnfs parameters if desired) in a file named

nfs.job (the "n: <your number>" must be first, as with gnfs); in order to proceed as snfs, you

must have "type: snfs" and "size: <snfs difficulty>" lines in the job file. yafu will adjust the

minimum relations estimate to account for the easier difficulty, and should otherwise proceed

just as in nfs.

Supported special forms are:

Various k*b^n+c including:

Cunningham numbers (b^n +- 1 with with b=2, 3, 5, 6, 7, 10, 11, 12)

Brent forms (b^n +/- 1, where 13<=b<=99)

Odd perfect numbers (b^n - 1, b>99)

Generalized Cullen/Woodall numbers (a*b^a +/- 1)

Others: k*2^n +/- 1, repunits, mersenne plus 2, etc.

(Note that for large b, cases with k>1 or abs(c)>1 may not be detected)

Homogeneous Cunningham numbers (a^n +/- b^n, where a,b <= 12 and gcd(a,b) == 1)

XYYXF numbers (x^y + y^x, where 1<y<x<151)

Inputs constructed from sums of multiples of a common root m=b^p, e.g.:

c5*m^5 + c4*m^4 + c3*m^3 + c2*m^2 + c1*m + c0

where the absolute valud of all cn are < 10000, b ranges from 2 to 19, and p

from 2 to 75*log(10)/log(b).

snfs supports all the command line flags for nfs, as well as one additional flag:

-testsieve <num> Number of digits beyond which yafu will test sieve the top

3 polynomials discovered by snfs (default: 140)

Note: if a certain poly is particularly bad and is taking too long to test sieve,

you can safely terminate the ggnfs process, and yafu should still get an accurate

score and continue trial sieving the other polys.

Examples:

1) perform snfs poly selection but skip test sieving for an odd perfect number,

outputing the poly to a custom job file:

"snfs(158071^37-1, (158071^37-1)/158070)" -v -np -job opn.poly -testsieve 300

2) resume sieving and do post processing:

"snfs(158071^37-1, (158071^37-1)/158070)" -v -R -ns -nc -job opn.poly

[siqs]

usage: siqs(expression)

description:

the siqs factoring method. uses the double large prime variation, small prime variation,

bucket sieving, and too many other optimizations to mention. post-processing is

performed using a port of Jason Papadopoulos's msieve filtering and block Lanczos implementations.

Best if used for inputs < 105 digits. Above that, parameter settings

have not been tested much.

An abort signal (ctrl-c) will stop a factorization in progress. state will be saved

in siqs.dat (default) or a different file specified with the -qssave switch. factorizations

can then be resumed by starting siqs again with the same input. different inputs to

siqs will overwrite the file, so be careful to back up siqs.dat if you stop a factorization

and plan to come back to it after performing other siqs work.

The savefile should appear in the same directory as the executable.

command line flags affecting siqs:

-qssave <name> Name of the siqs savefile to use in this session

-siqsR <num> Stop after finding num relations in siqs

-siqsT <num> Stop after num seconds in siqs

-threads <num> Use num sieving threads in SIQS and ECM

-inmem <num> Inputs with less than <num> digits will not store relations

to a savefile, instead keeping all data in memory. This can be

faster, but inputs will not be able to be resumed if aborted.

-v Use to increase verbosity of output, can be used multiple times

[smallmpqs]

usage: smallmpqs(expression)

description:

the mpqs factoring method optimized for small inputs.

[factor]

usage: factor(expression)

description:

combines a variety of routines to (hopefully) optimally factor an arbitrary input.

command line flags affecting factor:

-one Tells factor() to stop factoring after finding one factor.

-op <name> Tells factor() to output primes and prps to file <name>.

-of <name> Tells factor() to output an input number and all found factors

to file <name>.

-ou <name> Tells factor() to output unfactored composites to file <name>.

-no_expr When outputting numbers to file, do not print expression form,

show full decimal expansion.

-plan <name> Tells factor() to follow one of the following pretesting plans:

<name> = none: do only trial division and rho

<name> = noecm: stop before first ecm step and start

nfs/qs

<name> = light: pretest to t-level 2/7 the size of

the input before starting qs/nfs

<name> = normal: pretest to t-level 4/13 the size of

the input before starting qs/nfs

<name> = deep: pretest to t-level 1/3 the size of the

input before starting qs/nfs

<name> = custom: pretest to t-level specified by the

ratio in the –pretest_ratio option

-pretest_ratio <num> A fractional value used in the plan=custom mode of operation to

determine the depth of pretesting. Inputs are pretested

to t-level equal to size of input * pretest_ratio

-work <num> Assert to factor() that the input has already received pretesting

equivalent to the specified t-level. In other words, if you know

that an input has received ~900 ecm curves at B1=1M, then

specify –work 35. This value may be input as floating point.

-xover <num> Use this option to specify the decimal digit size beyond which gnfs

should be used instead of qs. Specifying this option overrides

any crossover point computed from tuning data. May be entered

as a floating point number.

-snfs_xover <num> Use this option to specify the decimal digit size beyond which snfs

should be used instead of qs. This should be smaller than -xover, since

snfs is usually faster than gfns. Specifying this option overrides

any crossover point computed from tuning data. May be entered

as a floating point number.

-pretest [num] Use this switch with factor() for ECM pretesting of the input number.

Optionally provide an integer value specifing the maximum level of

pretesting to do (up to "num" digits, or a t-level of "num")

The factor() function will also check to see if the input has a SNFS form. If it does,

and if one of the default plans have been selected, and if you haven't also specified

-gnfs as an option, then any subsequent ECM work will be reduced.

[pm1]

usage: pm1(expression)

description:

New in version 1.28: uses GMP-ECM exclusively. Stage 1 bound is configurable using

the POLLARD_STG1_MAX parameter. The default is 100000. Stage 2 bound is also

configurable using the POLLARD_STG2_MAX parameter.

To use the default B2 with gmp-ecm, simply do not specify the B2ecm or B2pp1 or B2pm1

flags in the .ini file or in the command line arguments.

Specifying B2 as well will cause the default value to be overridden.

command line flags affecting pm1:

-B1pm1 <num> B1 bound in the pm1 method

-B2pm1 <num> B2 bound in the pm1 method

[ecm]

usage: ecm(expression1,[expression2])

description:

New in version 1.28: uses GMP-ECM exclusively. Stage 1 bound is configurable using

the ECM_STG1_MAX parameter. The default is 11000. Stage 2 bound is also

configurable using the ECM_STG2_MAX parameter.

To use the default B2 with gmp-ecm, simply do not specify the B2ecm or B2pp1 or B2pm1

flags in the .ini file or in the command line arguments.

Specifying B2 as well will cause the default value to be overridden.

The first argument should be the number to factor and the second

can optionally be a number of curves to run at the current ECM_STG* bounds. If no

expression2 is given, the default behavior is 1 curve at the current ECM_STG* bounds.

To use an external ecm binary instead of the built-in gmp-ecm code, specify a full path

to the binary using the -ecm_path command line option or .ini file entry. Ecm will be

run multi-threaded, if requested, when using an external binary. Note that linux can

also run multi-threaded using the built-in gmp-ecm code. External binaries can still be

used in linux, for example if they are specially optimized for a particular system.

command line flags affecting ecm:

-B1ecm <num> B1 bound in the ECM method

-B2ecm <num> B2 bound in the ECM method

-ecm_path <path> full path to ecm binary

[pp1]

usage: pp1(expression,[expression2])

description:

New in version 1.28: uses GMP-ECM exclusively. Stage 1 bound is configurable using

the WILLIAMS_STG1_MAX parameter. The default is 20000. Stage 2 bound is also

configurable using the WILLIAMS_STG2_MAX parameter.

The first argument should be the number to factor and the second can optionally

be a number of "curves" to run. Typically the number of curves is 3, in order to

make it more likely that an actual pp1 test is performed. For more details, see

C & P.

To use the default B2 with gmp-ecm, simply do not specify the B2ecm or B2pp1 or B2pm1

flags in the .ini file or in the command line arguments.

Specifying B2 as well will cause the default value to be overridden.

command line flags affecting pp1:

-B1pp1 <num> B1 bound in the pp1 method

-B2pp1 <num> B2 bound in the pp1 method

[rho]

usage: rho(expression)

description:

Pollard's rho method, with Brent's improvement. The maximum number of iterations to

perform is configurable using the BRENT_MAX_IT parameter.

command line flags affecting rho:

-rhomax <num> max iterations in the rho method

[trial]

usage: trial(expression1,[expression2])

description:

trial division of the result of expression1 to a bound specified by the result of

the optional expression2. All primes less than the bound are divided into the input.

If no expression2 is provided, the default value is 10000.

[fermat]

usage: fermat(expression1,expression2)

description:

performs the fermat factorization algorithm on expression1, using a maximum of

expression2 iterations.

[squfof]

usage: squfof(expression)

description:

Shanks's square form factorization method, using multipliers. Upper bound of the input

is set to 62 bits.

[gcd]

usage: gcd(expression,expression)

description:

greatest common divisor of two inputs, using the Lehmer/Euclid method.

[jacobi]

usage: jacobi(expression,expression)

description:

jacobi symbol of two inputs p/q

[isprime]

usage: isprime(expression)

description:

uses trial division followed by the rabin-miller probabalistic primalty

test to determine probable-primalty. The number of witnesses in the rabin-miller test

is configurable using the NUM_WITNESSES parameter. The default is 20.

[bpsw]

usage: bpsw(expression)

description:

runs the Baillie-Pomerance-Selfridge-Wagstaff probablistic primality test

to determine probable-primality. There are currently no known composites that

are declared prime by this test.

[aprcl]

usage: aprcl(expression)

description:

runs the Adleman, Pomerance, Rumely, Cohen, and Lenstra primality test on

the given expression to determine if the input is prime or composite. It

can prove numbers up to 6021 digits. Above this size it falls back to a

BPSW probable-primality test.

[issquare]

usage: issquare(expression)

description:

determines if the number the expression evaluates to is a perfect square

[ispow]

usage: ispow(expression)

description:

determines if the number the expression evaluates to is a perfect power

[fib]

usage: fib(expression)

description:

computes the nth fibonacci number

[luc]

usage: luc(expression)

description:

computes the nth lucas number

[modinv]

usage: modinv(expression1,expression2)

description:

computes the modular inverse of one number with respect to another

[lg2]

usage: lg2(expression)

description:

the binary log

[log]

usage: log(expression)

description:

the base 10 log

[ln]

usage: ln(expression)

description:

the natural log

[modexp]

usage: modexp(expression1,expression2,expression3)

description:

modular exponentiation: a^b%n

[sqrt]

usage: sqrt(expression)

description:

sqrt using newton's method

[nroot]

usage: nroot(expression1,expression2)

description:

nth root using newton's method. The result of expression2 is the nth root to take of

the result of expression1.

[shift]

usage: shift(expression1,expression2)

description:

binary left or right shift by result of expression2

[size]

usage: size(expression)

description:

size of a number, digits and bits

[rsa]

usage: rsa(expression)

description:

form a difficult to factor number of a specified bit size. NOT FOR CRYPTOGRAPHIC USE.

[rand]

usage: rand(expression)

description:

form a random number with a specified number of digits

[primes]

usage: primes(expression1,expression2,[expression3])

description:

print or count the primes in a range between the first two parameters.

The third parameter should evaluate to 1 if the range is to only be counted or 0 if printed.

If the PRIMES_TO_FILE environment variable is set to non-zero, the primes will

be output to a file called primes.dat, in the same directory as the executable.

If the PRIMES_TO_SCREEN environement variable is set to non-zero, the primes

will be printed to the screen. By default, PRIMES_TO_FILE and

PRIMES_TO_SCREEN are inactive (equal to zero). The -pfile and -pscreen command line flags

enable the same behavior. It could take a very long time to print if the range is large.

If expression 3 is omitted, the behavior defaults to a count of primes.

expression 1 and expression 2 should both evaluate to numbers less than 4e18.

The condition expression 2 > expression 1 is also enforced.

[sieverange]

usage: sieverange(lower, upper, depth, count)

description:

Sieve an arbitrary range of integers between 'lower' and 'upper' with primes up to a limit of

'depth'. 'Lower' and 'upper' can be arbitrary precision integers, with lower < upper. 'Depth'

is currently limited to values less than 4e9.

The fourth parameter should evaluate to 1 if the range is to only be counted. Otherwise,

primes are actually computed. Note that this value must be 0 if primes are to be output

to the screen or to the file, as discussed below.

If the PRIMES_TO_FILE environment variable is set to non-zero, the values that survive the

sieve will be output to a file called sieved_values.dat, in the same directory as the executable.

If the PRIMES_TO_SCREEN environement variable is set to non-zero, the sieved values

will be printed to the screen. By default, PRIMES_TO_FILE and

PRIMES_TO_SCREEN are inactive (equal to zero). The -pfile and -pscreen command line flags

enable the same behavior. It could take a very long time to print if the range is large.

[testrange]

usage: testrange(lower, upper, depth, num_witnesses)

description:

Sieve an arbitrary range of integers between 'lower' and 'upper' with primes up to a limit of

'depth'. 'Lower' and 'upper' can be arbitrary precision integers, with lower < upper. 'Depth'

is currently limited to values less than 4e9. Subject all surviving values to a PRP check

using 'num_witnesses' witnesses in a Rabin-Miller strong pseudo-prime test.

If the PRIMES_TO_FILE environment variable is set to non-zero, the values that survive the

sieve and prp checks will be output to a file called prp_values.dat, in the same directory

as the executable.

If the PRIMES_TO_SCREEN environement variable is set to non-zero, the sieved values

will be printed to the screen. By default, PRIMES_TO_FILE and

PRIMES_TO_SCREEN are inactive (equal to zero). The -pfile and -pscreen command line flags

enable the same behavior. It could take a very long time to print if the range is large.

If expression 4 is equal to zero, then no prp checks are run and behavior is similar to

sieverange() with count = 0.

[nextprime]

usage: nextprime(expression1,[expression2])

description:

find the next prime after a specified number. If expression2 evaluates to zero,

the next prime is smaller than the given number. Else the next prime is larger than the

specified number. If no expression2 is given, the default is the next bigger prime

(as if a non-zero input were given).

[llt]

usage: llt(expression)

description:

start the lucas lehmer test on the number 2^expression - 1. A small amount of trial

division is first performed, after determining that the expression is prime.

[end]