<!-- #################################################################### -->
<!-- ##                                                                ## -->
<!-- ##  general.xml        FactInt documentation         Stefan Kohl  ## -->
<!-- ##                                                                ## -->
<!-- #################################################################### -->

<Chapter Label="ch:General">
<Heading>The General Factorization Routine</Heading>

<!-- #################################################################### -->

<Section Label="sec:Factors">
<Heading>The method for <C>Factors</C></Heading>

The &FactInt; package provides a better method for the operation
<C>Factors</C> for integer arguments, which supersedes the one included in
the &GAP; Library:

<ManSection>
  <Meth Name="Factors" Arg="n" Label="FactInt's method, for integers"/>
  <Returns>
    a sorted list of the prime factors of <A>n</A>.
  </Returns>
  <Description>
    <Index Key="primality of the factors">primality of the factors</Index>
    The returned factors pass the built-in probabilistic primality test of
    &GAP; (<C>IsProbablyPrimeInt</C>, Baillie-PSW Primality Test; see the
    &GAP; Reference Manual).
    If the method fails to compute the prime factorization of <A>n</A>,
    an error is signalled.
    The same holds for all other factorization routines provided by this
    package.
    The following is a rough description of how the factorization method
    works: <P/>

    First of all, the method checks whether <M>n = b^k \pm 1</M> for some
    <M>b</M>, <M>k</M> and looks for factors corresponding to polynomial
    factors of <M>x^k \pm 1</M>.
    Provided that <M>b</M> and <M>k</M> are not too large, the factors that
    do not correspond to polynomial factors are taken from Richard P. Brent's
    Factor Tables&nbsp;<Cite Key="Brent04"/>.
    The code for accessing these tables has been contributed by Frank Lübeck.
    <P/>

    <Index Key="Brent factor tables">Brent factor tables</Index>
    These tables are nowadays maintained by Jonathan Crombie, and have grown
    far too large to be distributed in full.
    The subset shipped with &FactInt; is determined as follows: for a
    base&nbsp;<M>b</M> and an exponent&nbsp;<M>k</M>, all currently known
    factors of <M>b^k \pm 1</M> are included if <M>b \leq 100</M>, or if
    <M>b</M> is a prime less than&nbsp;1000, or if the pair
    <M>(b,k)</M> was already covered by the tables distributed with
    &FactInt;&nbsp;1.6.3.
    In particular, everything that was available in earlier versions of
    &FactInt; is still available, in many cases with additional factors.
    <P/>

    Users who need factors beyond this range can replace the distributed
    tables by the full collection using the undocumented function
    <C>FetchBrentFactors</C>; see the comments in <F>lib/general.gi</F>.
    This requires write access to the &FactInt; installation directory as
    well as the external programs <C>curl</C> and <C>gzip</C>.
    <P/>

    Then the method uses trial division and a number of cheap methods for
    various common special cases.
    After the small and other <Q>easy</Q> factors have been found this way,
    &FactInt;'s method searches for <Q>medium-sized</Q> factors using
    Pollard's Rho (by the library function <C>FactorsRho</C>, see the &GAP;
    Reference Manual), Pollard's&nbsp;<M>p-1</M>
    (see&nbsp;<Ref Func="FactorsPminus1" Label="Pollard's p-1"/>),
    Williams'&nbsp;<M>p+1</M>
    (see&nbsp;<Ref Func="FactorsPplus1" Label="Williams' p+1"/>)
    and the Elliptic Curves Method (ECM, 
    see&nbsp;<Ref Func="FactorsECM" Label="Elliptic Curves Method, ECM"/>)
    in this order. <P/>

    If there is still an unfactored part remaining after that,
    it is factored using the Multiple Polynomial Quadratic Sieve (MPQS,
    see&nbsp;<Ref Func="FactorsMPQS"
                  Label="Multiple Polynomial Quadratic Sieve, MPQS"/>).
    <P/>

    The following options are interpreted:

    <List>
      <Mark><A>TDHints</A></Mark>
      <Item>
        A list of additional trial divisors.
        This is useful only if certain primes&nbsp;<M>p</M> are expected to
        divide <M>n</M> with probability significantly larger than
        <M>\frac{1}{p}</M>.
      </Item>
      <Mark><A>RhoSteps</A></Mark>
      <Item>
        The number of steps for Pollard's Rho.
      </Item>
      <Mark><A>RhoCluster</A></Mark>
      <Item>
        The number of steps between two gcd computations in Pollard's Rho.
      </Item>
      <Mark><A>Pminus1Limit1</A> / <A>Pminus1Limit2</A></Mark>
      <Item>
        The first- / second stage limit for Pollard's&nbsp;<M>p-1</M>
        (see&nbsp;<Ref Func="FactorsPminus1" Label="Pollard's p-1"/>).
      </Item>
      <Mark><A>Pplus1Residues</A></Mark>
      <Item>
        The number of residues to be tried by Williams'&nbsp;<M>p+1</M>
        (see&nbsp;<Ref Func="FactorsPplus1" Label="Williams' p+1"/>).
      </Item>
      <Mark><A>Pplus1Limit1</A> / <A>Pplus1Limit2</A></Mark>
      <Item>
        The first- / second stage limit for Williams'&nbsp;<M>p+1</M>
        (see&nbsp;<Ref Func="FactorsPplus1" Label="Williams' p+1"/>).
      </Item>
      <Mark><A>ECMCurves</A></Mark>
      <Item>
        The number of elliptic curves to be tried by the
        Elliptic Curves Method (ECM)
        (see&nbsp;<Ref Func="FactorsECM"
                       Label="Elliptic Curves Method, ECM"/>).
        Also admissible: a function that takes the number <M>n</M> to be
        factored as an argument and returns the desired number
        of curves to be tried.
      </Item>
      <Mark><A>ECMLimit1</A> / <A>ECMLimit2</A></Mark>
      <Item>
        The initial first- / second stage limit for ECM
        (see&nbsp;<Ref Func="FactorsECM"
                       Label="Elliptic Curves Method, ECM"/>).
      </Item>
      <Mark><A>ECMDelta</A></Mark>
      <Item>
        The increment per curve for the first
        stage limit in ECM. The second stage limit is adjusted appropriately
        (see&nbsp;<Ref Func="FactorsECM"
                       Label="Elliptic Curves Method, ECM"/>).
      </Item>
      <Mark><A>ECMDeterministic</A></Mark>
      <Item>
        If true, ECM chooses its curves deterministically, i.e. repeatable
        (see&nbsp;<Ref Func="FactorsECM"
                       Label="Elliptic Curves Method, ECM"/>).
      </Item>
      <Mark><A>FBMethod</A></Mark>
      <Item>
        Specifies which of the factor base methods should be
        used to do the <Q>hard work</Q>. Currently implemented:
        <C>"CFRAC"</C> and <C>"MPQS"</C>
        (see&nbsp;<Ref Func="FactorsCFRAC"
                      Label="Continued Fraction Algorithm, CFRAC"/>
        and&nbsp;<Ref Func="FactorsMPQS"
                      Label="Multiple Polynomial Quadratic Sieve, MPQS"/>,
        respectively).
        Default: <C>"MPQS"</C>.
      </Item>
    </List>

    For the use of the &GAP; Options Stack, see Chapter <E>Options Stack</E>
    in the &GAP; Reference Manual. <P/>

    Setting <A>RhoSteps</A>, <A>Pminus1Limit1</A>, <A>Pplus1Residues</A>,
    <A>Pplus1Limit1</A>, <A>ECMCurves</A> or <A>ECMLimit1</A> equal to zero
    switches the respective method off. The method chooses defaults for all
    option values that are not explicitly set by the user. The option values
    are also interpreted by the routines for the particular factorization
    methods described in the next chapter.
<Example><![CDATA[
gap> Factors( Factorial(44) + 1 );
[ 694763, 9245226412016162109253, 413852053257739876455072359 ]
gap> Factors( 2^997 - 1 );
[ 167560816514084819488737767976263150405095191554732902607, 
  79934306053602222928609369601238840619880168466272137576868879760059\
3002563860297371289151859287894468775962208410650878341385577817736702\
2158878920741413700868182301410439178049533828082651513160945607018874\
830040978453228378816647358334681553 ]
]]></Example>
  </Description>
</ManSection>

The above method for <C>Factors</C> calls the following function,
which is the actual <Q>workhorse</Q> of this package:

<ManSection>
  <Func Name="FactInt" Arg="n" Label="factorization of an integer"/>
  <Returns>
    a list of two lists, where the first list contains the determined
    prime factors of&nbsp;<A>n</A> and the second list contains the
    remaining unfactored parts of&nbsp;<A>n</A>, if there are any.
  </Returns>
  <Description>
    This function interprets all options which are interpreted by the
    method for <C>Factors</C> described above. In addition, it interprets
    the options <A>cheap</A> and <A>FactIntPartial</A>.
    If the option <A>cheap</A> is set, only usually
    cheap factorization attempts are made.
    If the option <A>FactIntPartial</A> is set, the factorization process
    is stopped before invoking the (usually time-consuming) MPQS or CFRAC,
    if the number of digits of the remaining unfactored part exceeds the
    bound passed as option value <A>MPQSLimit</A> or <A>CFRACLimit</A>,
    respectively. <P/>

    <C>Factors(<A>n</A>)</C> is equivalent to
    <C>FactInt(<A>n</A>:<A>cheap</A>:=false,
                        <A>FactIntPartial</A>:=false)[1]</C>.
<Example><![CDATA[
gap> FactInt( Factorial(300) + 1 : cheap );
[ [ 461, 259856122109, 995121825812791, 3909669044842609, 
      4220826953750952739, 14841043839896940772689086214475144339 ], 
  [ 104831288231765723173983836560438594053336296629073932563520618687\
9287645058010688827246061541065631119345674081834085960064144597037243\
9235869682208979384309498719255615067943353399357029226058930732298505\
5816977495398426741656633461747046623641451042655247093315505417820370\
9451745871701742000546384614472756584182478531880962594857275869690727\
9733563594352516014206081210368516157890709802912711149521530885498556\
1244667790208245620301404499928532222524585946881528337257061789593197\
99211283640357942345263781351 ] ]
]]></Example>
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

<Section Label="sec:Info">
<Heading>Getting information about the factoring process</Heading>

<Index Key="information about factoring process">
  information about factoring process
</Index>

Optionally, the &FactInt; package prints information on the progress of
the factorization process:

<ManSection>
  <InfoClass Name="InfoFactInt"
             Label="FactInt's Info class"/>
  <Func      Name="FactIntInfo" Arg="level"
             Label="setting the InfoLevel of InfoFactInt"/>
  <Description>
    This Info class makes it possible to monitor what happens during the
    factoring process. <P/>

    If <C>InfoLevel(InfoFactInt) = 1</C>, then basic information
    about the factoring techniques used is displayed. If this InfoLevel has
    value&nbsp;2, then additionally all <Q>relevant</Q> steps in the
    factoring algorithms are mentioned. If it is set equal to&nbsp;3, then
    large amounts of details of the progress of the factoring process are
    shown. <P/>

    Enter <C>FactIntInfo(<A>level</A>)</C> to set the
    <C>InfoLevel</C> of <C>InfoFactInt</C> to the positive
    integer <A>level</A>. The call <C>FactIntInfo(<A>level</A>);</C>
    is equivalent to <C>SetInfoLevel(InfoFactInt,<A>level</A>);</C>. <P/>

    The informational output is usually not literally the same in
    each factorization attempt for a given integer with given parameters.
    For a description of the Info mechanism, see Section
    <E>Info Functions</E> in the &GAP; Reference Manual. 
  </Description>
</ManSection>

</Section>

<!-- #################################################################### -->

</Chapter>

<!-- #################################################################### -->
