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

/*=============================================================================

    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
    Copyright (C) 2011 Sebastian Pancratz

******************************************************************************/


*******************************************************************************

    Memory management

*******************************************************************************

void fmpq_init(fmpq_t x)

    Initialises the \code{fmpq_t} variable \code{x} for use. Its value
    is set to 0.

void fmpq_clear(fmpq_t x)

    Clears the \code{fmpq_t} variable \code{x}. To use the variable again,
    it must be re-initialised with \code{fmpq_init}.

fmpq * _fmpq_vec_init(slong n)

    Initialises a vector of \code{fmpq} values of length $n$ and sets
    all values to 0. This is equivalent to generating a \code{fmpz} vector
    of length $2n$ with \code{_fmpz_vec_init} and setting all denominators
    to 1.

void _fmpq_vec_clear(fmpq * vec, slong n)

    Frees an \code{fmpq} vector.

*******************************************************************************

    Canonicalisation

*******************************************************************************

void fmpq_canonicalise(fmpq_t res)

    Puts \code{res} in canonical form: the numerator and denominator are
    reduced to lowest terms, and the denominator is made positive.
    If the numerator is zero, the denominator is set to one.

    If the denominator is zero, the outcome of calling this function is
    undefined, regardless of the value of the numerator.

void _fmpq_canonicalise(fmpz_t num, fmpz_t den)

    Does the same thing as \code{fmpq_canonicalise}, but for numerator
    and denominator given explicitly as \code{fmpz_t} variables. Aliasing
    of \code{num} and \code{den} is not allowed.

int fmpq_is_canonical(const fmpq_t x)

    Returns nonzero if \code{fmpq_t} x is in canonical form
    (as produced by \code{fmpq_canonicalise}), and zero otherwise.

int _fmpq_is_canonical(const fmpz_t num, const fmpz_t den)

    Does the same thing as \code{fmpq_is_canonical}, but for numerator
    and denominator given explicitly as \code{fmpz_t} variables.

*******************************************************************************

    Basic assignment

*******************************************************************************

void fmpq_set(fmpq_t dest, const fmpq_t src)

    Sets \code{dest} to a copy of \code{src}. No canonicalisation
    is performed.

void fmpq_swap(fmpq_t op1, fmpq_t op2)

    Swaps the two rational numbers \code{op1} and \code{op2}.

void fmpq_neg(fmpq_t dest, const fmpq_t src)

    Sets \code{dest} to the additive inverse of \code{src}.

void fmpq_abs(fmpq_t dest, const fmpq_t src)

    Sets \code{dest} to the absolute value of \code{src}.

void fmpq_zero(fmpq_t res)

    Sets the value of \code{res} to 0.

void fmpq_one(fmpq_t res)

    Sets the value of \code{res} to $1$.

*******************************************************************************

    Comparison

*******************************************************************************

int fmpq_is_zero(const fmpq_t res)

    Returns nonzero if \code{res} has value 0, and returns zero otherwise.

int fmpq_is_one(const fmpq_t res)

    Returns nonzero if \code{res} has value $1$, and returns zero otherwise.

int fmpq_equal(const fmpq_t x, const fmpq_t y)

    Returns nonzero if \code{x} and \code{y} are equal, and zero otherwise.
    Assumes that \code{x} and \code{y} are both in canonical form.

int fmpq_sgn(const fmpq_t x)

    Returns the sign of the rational number $x$.

int fmpq_cmp(const fmpq_t x, const fmpq_t y)

    Returns negative if $x < y$, zero if $x = y$, and positive if $x > y$.

void fmpq_height(fmpz_t height, const fmpq_t x)

    Sets \code{height} to the height of $x$, defined as the larger of
    the absolute values of the numerator and denominator of $x$.

mp_bitcnt_t fmpq_height_bits(const fmpq_t x)

    Returns the number of bits in the height of $x$.

*******************************************************************************

    Conversion

*******************************************************************************

void fmpq_set_fmpz_frac(fmpq_t res, const fmpz_t p, const fmpz_t q)

    Sets \code{res} to the canonical form of the fraction \code{p / q}.
    This is equivalent to assigning the numerator and denominator
    separately and calling \code{fmpq_canonicalise}.

void fmpq_set_si(fmpq_t res, slong p, ulong q)

    Sets \code{res} to the canonical form of the fraction \code{p / q}.

void _fmpq_set_si(fmpz_t rnum, fmpz_t rden, slong p, ulong q)

    Sets \code{(rnum, rden)} to the canonical form of the fraction
    \code{p / q}. \code{rnum} and \code{rden} may not be aliased.

void fmpq_set_mpq(fmpq_t dest, const mpq_t src)

    Sets the value of \code{dest} to that of the \code{mpq_t} variable
    \code{src}.

void fmpq_get_mpq(mpq_t dest, const fmpq_t src)

    Sets the value of \code{dest}

int fmpq_get_mpfr(mpfr_t dest, const fmpq_t src, mpfr_rnd_t rnd)

    Sets the MPFR variable \code{dest} to the value of \code{src},
    rounded to the nearest representable binary floating-point value
    in direction \code{rnd}. Returns the sign of the rounding,
    according to MPFR conventions.

char * _fmpq_get_str(char * str, int b, const fmpz_t num, const fmpz_t den)

char * fmpq_get_str(char * str, int b, const fmpq_t x)

    Prints the string representation of $x$ in base $b \in [2, 36]$ 
    to a suitable buffer.

    If \code{str} is not \code{NULL}, this is used as the buffer and 
    also the return value.  If \code{str} is \code{NULL}, allocates 
    sufficient space and returns a pointer to the string.

void flint_mpq_init_set_readonly(mpq_t z, const fmpq_t f)

    Sets the unitialised \code{mpq_t} $z$ to the value of the 
    readonly \code{fmpq_t} $f$.

    Note that it is assumed that $f$ does not change during 
    the lifetime of $z$.

    The rational $z$ has to be cleared by a call to 
    \code{flint_mpq_clear_readonly()}.

    The suggested use of the two functions is as follows:
    \begin{lstlisting}[language=C]
    fmpq_t f;
    ...
    {
        mpq_t z;

        flint_mpq_init_set_readonly(z, f);
        foo(..., z);
        flint_mpq_clear_readonly(z);
    }
    \end{lstlisting}

    This provides a convenient function for user code, only 
    requiring to work with the types \code{fmpq_t} and \code{mpq_t}.

void flint_mpq_clear_readonly(mpq_t z)

    Clears the readonly \code{mpq_t} $z$.

void fmpq_init_set_readonly(fmpq_t f, const mpq_t z)

    Sets the uninitialised \code{fmpq_t} $f$ to a readonly 
    version of the rational $z$.

    Note that the value of $z$ is assumed to remain constant 
    throughout the lifetime of $f$.

    The \code{fmpq_t} $f$ has to be cleared by calling the 
    function \code{fmpq_clear_readonly()}.

    The suggested use of the two functions is as follows:
    \begin{lstlisting}[language=C]
    mpq_t z;
    ...
    {
        fmpq_t f;

        fmpq_init_set_readonly(f, z);
        foo(..., f);
        fmpq_clear_readonly(f);
    }
    \end{lstlisting}

void fmpq_clear_readonly(fmpq_t f)

    Clears the readonly \code{fmpq_t} $f$.

*******************************************************************************

    Input and output

*******************************************************************************

void fmpq_fprint(FILE * file, const fmpq_t x)

    Prints \code{x} as a fraction to the stream \code{file}.   
    The numerator and denominator are printed verbatim as integers, 
    with a forward slash (/) printed in between.

void _fmpq_fprint(FILE * file, const fmpz_t num, const fmpz_t den)

    Does the same thing as \code{fmpq_fprint}, but for numerator
    and denominator given explicitly as \code{fmpz_t} variables. 

void fmpq_print(const fmpq_t x)

    Prints \code{x} as a fraction. The numerator and denominator are
    printed verbatim as integers, with a forward slash (/) printed in
    between.

void _fmpq_print(const fmpz_t num, const fmpz_t den)

    Does the same thing as \code{fmpq_print}, but for numerator
    and denominator given explicitly as \code{fmpz_t} variables. 

*******************************************************************************

    Random number generation

*******************************************************************************

void fmpq_randtest(fmpq_t res, flint_rand_t state, mp_bitcnt_t bits)

    Sets \code{res} to a random value, with numerator and denominator
    having up to \code{bits} bits. The fraction will be in canonical
    form. This function has an increased probability of generating
    special values which are likely to trigger corner cases.

void _fmpq_randtest(fmpz_t num, fmpz_t den, flint_rand_t state,
    mp_bitcnt_t bits)

    Does the same thing as \code{fmpq_randtest}, but for numerator
    and denominator given explicitly as \code{fmpz_t} variables. Aliasing
    of \code{num} and \code{den} is not allowed.

void fmpq_randtest_not_zero(fmpq_t res, flint_rand_t state, mp_bitcnt_t bits)

    As per \code{fmpq_randtest}, but the result will not be $0$. 
    If \code{bits} is set to $0$, an exception will result.

void fmpq_randbits(fmpq_t res, flint_rand_t state, mp_bitcnt_t bits)

    Sets \code{res} to a random value, with numerator and denominator
    both having exactly \code{bits} bits before canonicalisation,
    and then puts \code{res} in canonical form. Note that as a result
    of the canonicalisation, the resulting numerator and denominator can
    be slightly smaller than \code{bits} bits.

void _fmpq_randbits(fmpz_t num, fmpz_t den, flint_rand_t state,
        mp_bitcnt_t bits)

    Does the same thing as \code{fmpq_randbits}, but for numerator
    and denominator given explicitly as \code{fmpz_t} variables. Aliasing
    of \code{num} and \code{den} is not allowed.


*******************************************************************************

    Arithmetic

*******************************************************************************


void fmpq_add(fmpq_t res, const fmpq_t op1, const fmpq_t op2)

void fmpq_sub(fmpq_t res, const fmpq_t op1, const fmpq_t op2)

void fmpq_mul(fmpq_t res, const fmpq_t op1, const fmpq_t op2)

void fmpq_div(fmpq_t res, const fmpq_t op1, const fmpq_t op2)

    Sets \code{res} respectively to \code{op1 + op2}, \code{op1 - op2},
    \code{op1 * op2}, or \code{op1 / op2}. Assumes that the inputs
    are in canonical form, and produces output in canonical form.
    Division by zero results in an error.
    Aliasing between any combination of the variables is allowed.

void _fmpq_add(fmpz_t rnum, fmpz_t rden, const fmpz_t op1num,
    const fmpz_t op1den, const fmpz_t op2num, const fmpz_t op2den)

void _fmpq_sub(fmpz_t rnum, fmpz_t rden, const fmpz_t op1num,
    const fmpz_t op1den, const fmpz_t op2num, const fmpz_t op2den)

void _fmpq_mul(fmpz_t rnum, fmpz_t rden, const fmpz_t op1num,
    const fmpz_t op1den, const fmpz_t op2num, const fmpz_t op2den)

void _fmpq_div(fmpz_t rnum, fmpz_t rden, const fmpz_t op1num,
    const fmpz_t op1den, const fmpz_t op2num, const fmpz_t op2den)

    Sets \code{(rnum, rden)} to the canonical form of the sum,
    difference, product or quotient respectively of the fractions
    represented by \code{(op1num, op1den)} and \code{(op2num, op2den)}.
    Aliasing between any combination of the variables is allowed,
    whilst no numerator is aliased with a denominator.

void fmpq_addmul(fmpq_t res, const fmpq_t op1, const fmpq_t op2)

void fmpq_submul(fmpq_t res, const fmpq_t op1, const fmpq_t op2)

    Sets \code{res} to \code{res + op1 * op2} or \code{res - op1 * op2}
    respectively, placing the result in canonical form. Aliasing
    between any combination of the variables is allowed.

void _fmpq_addmul(fmpz_t rnum, fmpz_t rden, const fmpz_t op1num,
    const fmpz_t op1den, const fmpz_t op2num, const fmpz_t op2den)

void _fmpq_submul(fmpz_t rnum, fmpz_t rden, const fmpz_t op1num,
    const fmpz_t op1den, const fmpz_t op2num, const fmpz_t op2den)

    Sets \code{(rnum, rden)} to the canonical form of the fraction
    \code{(rnum, rden)} + \code{(op1num, op1den)} * \code{(op2num, op2den)} or
    \code{(rnum, rden)} - \code{(op1num, op1den)} * \code{(op2num, op2den)}
    respectively. Aliasing between any combination of the variables is allowed,
    whilst no numerator is aliased with a denominator.

void fmpq_inv(fmpq_t dest, const fmpq_t src)

    Sets \code{dest} to \code{1 / src}. The result is placed in canonical
    form, assuming that \code{src} is already in canonical form.

void _fmpq_pow_si(fmpz_t rnum, fmpz_t rden, 
                  const fmpz_t opnum, const fmpz_t opden, slong e);

void fmpq_pow_si(fmpq_t res, const fmpq_t op, slong e);

    Sets \code{res} to \code{op} raised to the power~$e$, where~$e$ 
    is a \code{slong}.  If $e$ is $0$ and \code{op} is $0$, then 
    \code{res} will be set to $1$.

void fmpq_mul_fmpz(fmpq_t res, const fmpq_t op, const fmpz_t x)

    Sets \code{res} to the product of the rational number \code{op} 
    and the integer \code{x}.

void fmpq_div_fmpz(fmpq_t res, const fmpq_t op, const fmpz_t x)

    Sets \code{res} to the quotient of the rational number \code{op} 
    and the integer \code{x}.

void fmpq_mul_2exp(fmpq_t res, const fmpq_t x, mp_bitcnt_t exp)

    Sets \code{res} to \code{x} multiplied by \code{2^exp}.

void fmpq_div_2exp(fmpq_t res, const fmpq_t x, mp_bitcnt_t exp)

    Sets \code{res} to \code{x} divided by \code{2^exp}.

*******************************************************************************

    Modular reduction and rational reconstruction

*******************************************************************************

int _fmpq_mod_fmpz(fmpz_t res,
        const fmpz_t num, const fmpz_t den, const fmpz_t mod)

int fmpq_mod_fmpz(fmpz_t res, const fmpq_t x, const fmpz_t mod)

    Sets the integer \code{res} to the residue $a$ of
    $x = n/d$ = \code{(num, den)} modulo the positive integer $m$ = \code{mod},
    defined as the $0 \le a < m$ satisfying $n \equiv a d \pmod m$.
    If such an $a$ exists, 1 will be returned, otherwise 0 will
    be returned.

int _fmpq_reconstruct_fmpz_2(fmpz_t n, fmpz_t d, const fmpz_t a,
        const fmpz_t m, const fmpz_t N, const fmpz_t D)

int fmpq_reconstruct_fmpz_2(fmpq_t res, const fmpz_t a, const fmpz_t m,
        const fmpz_t N, const fmpz_t D)

    Reconstructs a rational number from its residue $a$ modulo $m$.

    Given a modulus $m > 1$, a residue $0 \le a < m$, and positive $N, D$
    satisfying $2ND < m$, this function attempts to find a fraction $n/d$ with
    $0 \le |n| \le N$ and $0 < d \le D$ such that $\gcd(n,d) = 1$ and
    $n \equiv ad \pmod m$. If a solution exists, then it is also unique.
    The function returns 1 if successful, and 0 to indicate that no solution
    exists.

int _fmpq_reconstruct_fmpz(fmpz_t n, fmpz_t d, const fmpz_t a,
    const fmpz_t m)

int fmpq_reconstruct_fmpz(fmpq_t res, const fmpz_t a, const fmpz_t m)

    Reconstructs a rational number from its residue $a$ modulo $m$,
    returning 1 if successful and 0 if no solution exists.
    Uses the balanced bounds $N = D = \lfloor\sqrt{m/2}\rfloor$.


*******************************************************************************

    Rational enumeration

*******************************************************************************

void _fmpq_next_minimal(fmpz_t rnum, fmpz_t rden,
    const fmpz_t num, const fmpz_t den)

void fmpq_next_minimal(fmpq_t res, const fmpq_t x)

    Given $x$ which is assumed to be nonnegative and in canonical form, sets
    \code{res} to the next rational number in the sequence obtained by
    enumerating all positive denominators $q$, for each $q$ enumerating
    the numerators $1 \le p < q$ in order and generating both $p/q$ and $q/p$,
    but skipping all $\gcd(p,q) \ne 1$. Starting with zero, this generates
    every nonnegative rational number once and only once, with the first
    few entries being:

    $$0, 1, 1/2, 2, 1/3, 3, 2/3, 3/2, 1/4, 4, 3/4, 4/3, 1/5, 5, 2/5, \ldots.$$

    This enumeration produces the rational numbers in order of
    minimal height. It has the disadvantage of being somewhat slower to
    compute than the Calkin-Wilf enumeration.

void _fmpq_next_signed_minimal(fmpz_t rnum, fmpz_t rden,
    const fmpz_t num, const fmpz_t den)

void fmpq_next_signed_minimal(fmpq_t res, const fmpq_t x)

    Given a signed rational number $x$ assumed to be in canonical form, sets
    \code{res} to the next element in the minimal-height sequence
    generated by \code{fmpq_next_minimal} but with negative numbers
    interleaved:

    $$0, 1, -1, 1/2, -1/2, 2, -2, 1/3, -1/3, \ldots.$$

    Starting with zero, this generates every rational number once
    and only once, in order of minimal height.

void _fmpq_next_calkin_wilf(fmpz_t rnum, fmpz_t rden,
    const fmpz_t num, const fmpz_t den)

void fmpq_next_calkin_wilf(fmpq_t res, const fmpq_t x)

    Given $x$ which is assumed to be nonnegative and in canonical form, sets
    \code{res} to the next number in the breadth-first traversal of the
    Calkin-Wilf tree. Starting with zero, this generates every nonnegative
    rational number once and only once, with the first few entries being:

    $$0, 1, 1/2, 2, 1/3, 3/2, 2/3, 3, 1/4, 4/3, 3/5, 5/2, 2/5, \ldots.$$

    Despite the appearance of the initial entries, the Calkin-Wilf
    enumeration does not produce the rational numbers in order of height:
    some small fractions will appear late in the sequence. This order
    has the advantage of being faster to produce than the minimal-height
    order.

void _fmpq_next_signed_calkin_wilf(fmpz_t rnum, fmpz_t rden,
    const fmpz_t num, const fmpz_t den)

void fmpq_next_signed_calkin_wilf(fmpq_t res, const fmpq_t x)

    Given a signed rational number $x$ assumed to be in canonical form, sets
    \code{res} to the next element in the Calkin-Wilf sequence with
    negative numbers interleaved:

    $$0, 1, -1, 1/2, -1/2, 2, -2, 1/3, -1/3, \ldots.$$

    Starting with zero, this generates every rational number once
    and only once, but not in order of minimal height.

*******************************************************************************

    Continued fractions

*******************************************************************************

slong fmpq_get_cfrac(fmpz * c, fmpq_t rem, const fmpq_t x, slong n)

    Generates up to $n$ terms of the (simple) continued fraction expansion
    of $x$, writing the coefficients to the vector $c$ and the remainder $r$
    to the \code{rem} variable. The return value is the number $k$ of
    generated terms. The output satisfies:

    $$
    x = c_0 + \cfrac{1}{c_1 + \cfrac{1}{c_2 +
        \cfrac{1}{ \ddots + \cfrac{1}{c_{k-1} + r }}}}
    $$

    If $r$ is zero, the continued fraction expansion is complete.
    If $r$ is nonzero, $1/r$ can be passed back as input to generate
    $c_k, c_{k+1}, \ldots$. Calls to \code{fmpq_get_cfrac} can therefore
    be chained to generate the continued fraction incrementally,
    extracting any desired number of coefficients at a time.

    In general, a rational number has exactly two continued fraction
    expansions. By convention, we generate the shorter one. The longer
    expansion can be obtained by replacing the last coefficient
    $a_{k-1}$ by the pair of coefficients $a_{k-1} - 1, 1$.

    As a special case, the continued fraction expansion of zero consists
    of a single zero (and not the empty sequence).

    This function implements a simple algorithm, performing repeated
    divisions. The running time is quadratic.

void fmpq_set_cfrac(fmpq_t x, const fmpz * c, slong n)

    Sets $x$ to the value of the continued fraction

    $$
    x = c_0 + \cfrac{1}{c_1 + \cfrac{1}{c_2 +
        \cfrac{1}{ \ddots + \cfrac{1}{c_{n-1}}}}}
    $$

    where all $c_i$ except $c_0$ should be nonnegative.
    It is assumed that $n > 0$.

    For large $n$, this function implements a subquadratic algorithm.
    The convergents are given by a chain product of 2 by 2 matrices.
    This product is split in half recursively to balance the size
    of the coefficients.

slong fmpq_cfrac_bound(const fmpq_t x)

    Returns an upper bound for the number of terms in the continued
    fraction expansion of $x$. The computed bound is not necessarily sharp.

    We use the fact that the smallest denominator
    that can give a continued fraction of length $n$ is the Fibonacci
    number $F_{n+1}$.