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

321 lines
11 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) 2009, 2010, 2011 Sebastian Pancratz
******************************************************************************/
*******************************************************************************
Memory management
We represent a rational function over $\mathbf{Q}$ as the quotient
of two coprime integer polynomials of type \code{fmpz_poly_t},
enforcing that the leading coefficient of the denominator is
positive. The zero function is represented as $0/1$.
*******************************************************************************
void fmpz_poly_q_init(fmpz_poly_q_t rop)
Initialises \code{rop}.
void fmpz_poly_q_clear(fmpz_poly_q_t rop)
Clears the object \code{rop}.
fmpz_poly_struct * fmpz_poly_q_numref(const fmpz_poly_q_t op)
Returns a reference to the numerator of \code{op}.
fmpz_poly_struct * fmpz_poly_q_denref(const fmpz_poly_q_t op)
Returns a reference to the denominator of \code{op}.
void fmpz_poly_q_canonicalise(fmpz_poly_q_t rop)
Brings \code{rop} into canonical form, only assuming that
the denominator is non-zero.
int fmpz_poly_q_is_canonical(const fmpz_poly_q_t op)
Checks whether the rational function \code{op} is in
canonical form.
*******************************************************************************
Randomisation
*******************************************************************************
void fmpz_poly_q_randtest(fmpz_poly_q_t poly, flint_rand_t state,
slong len1, mp_bitcnt_t bits1,
slong len2, mp_bitcnt_t bits2)
Sets \code{poly} to a random rational function.
void fmpz_poly_q_randtest_not_zero(fmpz_poly_q_t poly, flint_rand_t state,
slong len1, mp_bitcnt_t bits1,
slong len2, mp_bitcnt_t bits2)
Sets \code{poly} to a random non-zero rational function.
*******************************************************************************
Assignment
*******************************************************************************
void fmpz_poly_q_set(fmpz_poly_q_t rop, const fmpz_poly_q_t op)
Sets the element \code{rop} to the same value as the element \code{op}.
void fmpz_poly_q_set_si(fmpz_poly_q_t rop, slong op)
Sets the element \code{rop} to the value given by the \code{slong}
\code{op}.
void fmpz_poly_q_swap(fmpz_poly_q_t op1, fmpz_poly_q_t op2)
Swaps the elements \code{op1} and \code{op2}.
This is done efficiently by swapping pointers.
void fmpz_poly_q_zero(fmpz_poly_q_t rop)
Sets \code{rop} to zero.
void fmpz_poly_q_one(fmpz_poly_q_t rop)
Sets \code{rop} to one.
void fmpz_poly_q_neg(fmpz_poly_q_t rop, const fmpz_poly_q_t op)
Sets the element \code{rop} to the additive inverse of \code{op}.
void fmpz_poly_q_inv(fmpz_poly_q_t rop, const fmpz_poly_q_t op)
Sets the element \code{rop} to the multiplicative inverse of \code{op}.
Assumes that the element \code{op} is non-zero.
*******************************************************************************
Comparison
*******************************************************************************
int fmpz_poly_q_is_zero(const fmpz_poly_q_t op)
Returns whether the element \code{op} is zero.
int fmpz_poly_q_is_one(const fmpz_poly_q_t op)
Returns whether the element \code{rop} is equal to the constant
polynomial $1$.
int fmpz_poly_q_equal(const fmpz_poly_q_t op1, const fmpz_poly_q_t op2)
Returns whether the two elements \code{op1} and \code{op2} are equal.
*******************************************************************************
Addition and subtraction
*******************************************************************************
void fmpz_poly_q_add(fmpz_poly_q_t rop,
const fmpz_poly_q_t op1, const fmpz_poly_q_t op2)
Sets \code{rop} to the sum of \code{op1} and \code{op2}.
void fmpz_poly_q_sub(fmpz_poly_q_t rop,
const fmpz_poly_q_t op1, const fmpz_poly_q_t op2)
Sets \code{rop} to the difference of \code{op1} and \code{op2}.
void fmpz_poly_q_addmul(fmpz_poly_q_t rop,
const fmpz_poly_q_t op1, const fmpz_poly_q_t op2)
Adds the product of \code{op1} and \code{op2} to \code{rop}.
void fmpz_poly_q_submul(fmpz_poly_q_t rop,
const fmpz_poly_q_t op1, const fmpz_poly_q_t op2)
Subtracts the product of \code{op1} and \code{op2} from \code{rop}.
*******************************************************************************
Scalar multiplication and division
*******************************************************************************
void fmpz_poly_q_scalar_mul_si(fmpz_poly_q_t rop,
const fmpz_poly_q_t op, slong x)
Sets \code{rop} to the product of the rational function \code{op}
and the \code{slong} integer $x$.
void fmpz_poly_q_scalar_mul_mpz(fmpz_poly_q_t rop,
const fmpz_poly_q_t op, const mpz_t x)
Sets \code{rop} to the product of the rational function \code{op}
and the \code{mpz_t} integer $x$.
void fmpz_poly_q_scalar_mul_mpq(fmpz_poly_q_t rop,
const fmpz_poly_q_t op, const mpq_t x)
Sets \code{rop} to the product of the rational function \code{op}
and the \code{mpq_t} rational $x$.
void fmpz_poly_q_scalar_div_si(fmpz_poly_q_t rop,
const fmpz_poly_q_t op, slong x)
Sets \code{rop} to the quotient of the rational function \code{op}
and the \code{slong} integer $x$.
void fmpz_poly_q_scalar_div_mpz(fmpz_poly_q_t rop,
const fmpz_poly_q_t op, const mpz_t x)
Sets \code{rop} to the quotient of the rational function \code{op}
and the \code{mpz_t} integer $x$.
void fmpz_poly_q_scalar_div_mpq(fmpz_poly_q_t rop,
const fmpz_poly_q_t op, const mpq_t x)
Sets \code{rop} to the quotient of the rational function \code{op}
and the \code{mpq_t} rational $x$.
*******************************************************************************
Multiplication and division
*******************************************************************************
void fmpz_poly_q_mul(fmpz_poly_q_t rop,
const fmpz_poly_q_t op1, const fmpz_poly_q_t op2)
Sets \code{rop} to the product of \code{op1} and \code{op2}.
void fmpz_poly_q_div(fmpz_poly_q_t rop,
const fmpz_poly_q_t op1, const fmpz_poly_q_t op2)
Sets \code{rop} to the quotient of \code{op1} and \code{op2}.
*******************************************************************************
Powering
*******************************************************************************
void fmpz_poly_q_pow(fmpz_poly_q_t rop, const fmpz_poly_q_t op, ulong exp)
Sets \code{rop} to the \code{exp}-th power of \code{op}.
The corner case of \code{exp == 0} is handled by setting \code{rop} to
the constant function $1$. Note that this includes the case $0^0 = 1$.
*******************************************************************************
Derivative
*******************************************************************************
void fmpz_poly_q_derivative(fmpz_poly_q_t rop, const fmpz_poly_q_t op)
Sets \code{rop} to the derivative of \code{op}.
*******************************************************************************
Evaluation
*******************************************************************************
int fmpz_poly_q_evaluate(mpq_t rop, const fmpz_poly_q_t f, const mpq_t a)
Sets \code{rop} to $f$ evaluated at the rational $a$.
If the denominator evaluates to zero at $a$, returns non-zero and
does not modify any of the variables. Otherwise, returns $0$ and
sets \code{rop} to the rational $f(a)$.
*******************************************************************************
Input and output
The following three methods enable users to construct elements of type\\
\code{fmpz_poly_q_t} from strings or to obtain string representations of
such elements.
The format used is based on the FLINT format for integer polynomials of
type \code{fmpz_poly_t}, which we recall first:
A non-zero polynomial $a_0 + a_1 X + \dotsb + a_n X^n$ of length
$n + 1$ is represented by the string \code{"n+1 a_0 a_1 ... a_n"},
where there are two space characters following the length and single
space characters separating the individual coefficients. There is no
leading or trailing white-space. The zero polynomial is simply
represented by \code{"0"}.
We adapt this notation for rational functions as follows. We denote the
zero function by \code{"0"}. Given a non-zero function with numerator
and denominator string representations \code{num} and \code{den},
respectively, we use the string \code{num/den} to represent the rational
function, unless the denominator is equal to one, in which case we simply
use \code{num}.
There is also a \code{_pretty} variant available, which bases the string
parts for the numerator and denominator on the output of the function
\code{fmpz_poly_get_str_pretty} and introduces parentheses where
necessary.
Note that currently these functions are not optimised for performance and
are intended to be used only for debugging purposes or one-off input and
output, rather than as a low-level parser.
*******************************************************************************
int fmpz_poly_q_set_str(fmpz_poly_q_t rop, const char *s)
Sets \code{rop} to the rational function given
by the string \code{s}.
char * fmpz_poly_q_get_str(const fmpz_poly_q_t op)
Returns the string representation of
the rational function \code{op}.
char * fmpz_poly_q_get_str_pretty(const fmpz_poly_q_t op, const char *x)
Returns the pretty string representation of
the rational function \code{op}.
int fmpz_poly_q_print(const fmpz_poly_q_t op)
Prints the representation of the rational
function \code{op} to \code{stdout}.
int fmpz_poly_q_print_pretty(const fmpz_poly_q_t op, const char *x)
Prints the pretty representation of the rational
function \code{op} to \code{stdout}.