docfile.txt

[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]