This is the README file for the ecm library.
To use the library, you need to add the following line in your source file:
#include "ecm.h"
and link with -lecm.
The public interface is defined in the "ecm.h" file. It contains the following
functions:
int ecm_factor (mpz_t f, mpz_t n, double B1, ecm_params p)
where n is the number to factor, f is the factor found (if any),
B1 is the stage 1 bound, and p contains auxiliary parameters (see below).
When p is NULL, default values for those parameters are chosen.
The ecm_factor() function returns:
* a positive value if a factor was found (1 for step 1, 2 for step 2),
* zero when no factor was found,
* a negative value when an error occurred.
void ecm_init (ecm_params p)
Initialize the parameters to default values.
void ecm_clear (ecm_params p)
Clear the parameters.
Detailed description of parameters (ecm_params):
* p->method is the factorization method (ECM_ECM for ECM, ECM_PM1 for P-1,
ECM_PP1 for P+1). Default is ECM_ECM.
* p->x (if non zero) is the starting point (ECM, P-1, P+1). For ECM, we take
as starting point (x0 : y0) where x0=x, y0=1; for P-1, we take x0;
for P+1, we take x0 as starting point of the Lucas sequence.
When ecm_factor() returns, p->x is the point obtained after stage 1.
* p->param (ECM only) is the parametrization that are going to be used to
compute the curve b*y^2 = x^3 + a*x^2 + x.
ECM_PARAM_DEFAULT let the choice of the parametrization to the program
ECM_PARAM_SUYAMA use Suyama parametrization a = (v-u)^3*(3*u+v)/(4*u^3*v)-2,
u = s^2-5, v = 4*s.
The initial point (if p->x is zero) is taken as x0=u^3/v^3, y0=1
(thus b is taken as x0^3 + a*x0^2 + x0).
ECM_PARAM_BATCH_SQUARE (only for 64-bit machine) a=4*i^2-2, x0=2, i is a
random 32-bit integer.
ECM_PARAM_BATCH_2 a = 4*d(k)-2, x0=2. Use an elliptic parametrization to
compute d(k) such that the curve has a 6-torsion point.
ECM_PARAM_BATCH_32BITS_D is mostly use for the gpu computation, a = 4*d-2,
x0=2, d is a random 32-bit integer.
ECM-PARAM_BATCH_SQUARE, ECM-PARAM_BATCH_2, ECM-PARAM_BATCH_32BITS_D are said
to used batch mode for the scalar multiplication. They should always have
x0 =2
* p->sigma (ECM only) is the value of the parameter used with the
parametrization (choosen with p->param).
ECM_PARAM_SUYAMA p->sigma is s.
ECM_PARAM_BATCH_SQUARE p->sigma is i (32-bit integer)
ECM_PARAM_BATCH_2 p->sigma is k, the parameter in the elliptic
parametrization (can be 64-bit integer on 64-bit machine)
ECM_PARAM_BATCH_32BITS_D p->sigma is d (32-bit integer)
* p->sigma_is_A (ECM only) indicates that p->sigma is the 'a' parameter
from the elliptic curve.
* p->go is the initial group order to preload (default is 1).
* p->B1done tells that step 1 was already done up to B1done. This means that
all prime powers <= B1done were dealt with. If for example B1done=100
and B1=200, prime 2 was dealt with up to power 6, thus it remains to
"multiply" once by 2 to go up to power 7. Of course, all primes p such
that B1done < p <= B1 will be considered with power 1.
* p->B2min is the lower bound for stage 2, which will treat all primes p such
that B2min <= p <= B2. If negative, B2min will be set to B1.
* p->B2 is the upper bound for stage 2 (default is automatically computed from
B1, to optimize the efficiency of the method).
* p->k is the number of blocks used in stage 2 (default is ECM_DEFAULT_K).
* p->S defines the polynomial used for Brent-Suyama's extension in stage 2.
If positive, the polynomial used is x^S; if negative, it is Dickson's
polynomial of degree S with parameter a=-1, where D_{1,a}(x) = x,
D_{2,a}(x) = x^2-2*a, and D_{k+2,a}(x) = x*D_{k+1,a}(x) - a*D_{k,a}(x),
or equivalently D_{k,a}(2*sqrt(a)*cos(t)) = 2*a^(k/2)*cos(k*t).
If zero, choice is automatic (and should be close to optimal).
Default is ECM_DEFAULT_S.
* p->repr defines the representation used for modular arithmetic: 1 means
the 'mpz' class from GMP, 2 means 'modmuln' (Montgomery's multiplication,
quadratic implementation), 3 means 'redc' (Montgomery's multiplication,
subquadratic implementation), -1 indicates not to use a special base-2
representation (when the input number is a factor of 2^n +/- 1).
Other values (including 0) mean the representation will be chosen
automatically (hopefully in some optimal way).
* p->nobase2step2 disable special base-2 code in ecm stage 2 only
* p->verbose is the verbosity level: 0 for no output, 1 for normal output
(like default for GMP-ECM), 2 for diagnostic output without inter-
mediate residues (like -v in GMP-ECM), 3 for diagnostic output with
residues (like -v -v), 4 for high diagnostic output (-v -v -v),
and 5 for trace output (-v -v -v -v).
* p->os is the output stream used for verbose output. Default is stdout.
* p->es is the output stream used for errors. Default is stderr.
* p->TreeFilename if non NULL, is the file name to store the product tree
of F (option -treefile f).
* p->maxmem is the maximum amount of memory in bytes that should be used in
stage 2. Setting this value too low (< 10MB, say) will cause stage 2
to perform very poorly, or return with an error code.
* p->stage1time is the time already spent in stage 1 (useful to get a correct
estimation of the expected time to find factors).
* p->rng is a random number generator state.
* p->use_ntt if equal to 1, use NTT in stage 2.
* p->(*stop_asap) pointer to function: if the function returns zero, continue
normally, otherwise exit as soon as possible. May be NULL.
* batch_s, batch_last_B1_used,
* p->gpu, p-> gpu_device, p->gpu_device_init, p->gpu_number_of_curves
See README.gpu
Generated by dwww version 1.15 on Sat Jun 22 12:53:40 CEST 2024.