pqc/external/flint-2.4.3/fmpz_factor/doc/fmpz_factor.txt

97 lines
3.9 KiB
Plaintext
Raw Normal View History

2014-05-18 22:03:37 +00:00
/*=============================================================================
This file is part of FLINT.
FLINT is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
FLINT is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with FLINT; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
=============================================================================*/
/******************************************************************************
Copyright (C) 2011 Fredrik Johansson
******************************************************************************/
*******************************************************************************
Factoring integers
An integer may be represented in factored form using the
\code{fmpz_factor_t} data structure. This consists of two \code{fmpz}
vectors representing bases and exponents, respectively. Canonically,
the bases will be prime numbers sorted in ascending order and the
exponents will be positive.
A separate \code{int} field holds the sign, which may be $-1$, $0$ or $1$.
*******************************************************************************
void fmpz_factor_init(fmpz_factor_t factor)
Initialises an \code{fmpz_factor_t} structure.
void fmpz_factor_clear(fmpz_factor_t factor)
Clears an \code{fmpz_factor_t} structure.
void fmpz_factor(fmpz_factor_t factor, const fmpz_t n)
Factors $n$ into prime numbers. If $n$ is zero or negative, the
sign field of the \code{factor} object will be set accordingly.
This currently only uses trial division, falling back to \code{n_factor()}
as soon as the number shrinks to a single limb.
void fmpz_factor_si(fmpz_factor_t factor, slong n)
Like \code{fmpz_factor}, but takes a machine integer $n$ as input.
int fmpz_factor_trial_range(fmpz_factor_t factor, const fmpz_t n,
ulong start, ulong num_primes)
Factors $n$ into prime factors using trial division. If $n$ is
zero or negative, the sign field of the \code{factor} object will be
set accordingly.
The algorithm starts with the given start index in the \code{flint_primes}
table and uses at most \code{num_primes} primes from that point.
The function returns 1 if $n$ is completely factored, otherwise it returns
$0$.
void fmpz_factor_expand_iterative(fmpz_t n, const fmpz_factor_t factor)
Evaluates an integer in factored form back to an \code{fmpz_t}.
This currently exponentiates the bases separately and multiplies
them together one by one, although much more efficient algorithms
exist.
int fmpz_factor_pp1(fmpz_t factor, const fmpz_t n,
ulong B1, ulong B2_sqrt, ulong c)
Use Williams' $p + 1$ method to factor $n$, using a prime bound in
stage 1 of \code{B1} and a prime limit in stage 2 of at least the square
of \code{B2_sqrt}. If a factor is found, the function returns $1$ and
\code{factor} is set to the factor that is found. Otherwise, the function
returns $0$.
The value $c$ should be a random value greater than $2$. Successive
calls to the function with different values of $c$ give additional
chances to factor $n$ with roughly exponentially decaying probability
of finding a factor which has been missed (if $p+1$ or $p-1$ is not
smooth for any prime factors $p$ of $n$ then the function will
not ever succeed).