ca.h

Initialises ctx and sets all options to their default values. The fields \mathbb{Q} and \mathbb{Q}(i) are created immediately.

Clears ctx, freeing all cached extension numbers and fields. All ca_t numbers (and vectors, polynomials and matrices of numbers) belonging to ctx must be cleared before.

Prints a description of ctx to standard output: the number of cached extension numbers and fields, and a list of the fields with their ideals of relations.

Returns, or sets to value, the option with index i, which must be one of the constants CA_OPT_VERBOSE, ..., CA_OPT_TRIG_FORM below.

Initialises x for use with the context ctx and sets it to the rational number 0.

Clears x, freeing any memory it uses.

Swaps x and y in constant time.

Sets res to a copy of x.

Sets res to the integer or rational number v, as an element of \mathbb{Q}.

Sets res to the exact value of the double x, or to x + yi. A finite double becomes a dyadic rational number, \pminf becomes \pm \infty, and NaN becomes Unknown.

Sets res, which belongs to res_ctx, to the value of src, which belongs to src_ctx. The value is preserved, but the representation may differ since it depends on the options and cached fields of the target context.

Sets res to 0, 1 or -1, as an element of \mathbb{Q}.

Sets res to the imaginary unit i or to -i, as an element of the number field \mathbb{Q}(i), which is always present in the context.

Sets res to \pi, the generator of the field \mathbb{Q}(\pi), or to \pi i, an element of \mathbb{Q}(\pi, i) (it is not an extension number of its own).

Sets res to Euler's constant \gamma \approx 0.5772, the generator of the field \mathbb{Q}(\gamma). It is not known whether \gamma is irrational, and the implementation assumes no relations involving it.

Sets res to Unknown, Undefined or unsigned infinity \tilde \infty.

Sets res to the signed infinity +\infty, -\infty, +i \infty or -i \infty. Other signed infinities are obtained by multiplying one of these by a number.

Sets res to the algebraic number x.

Attempts to evaluate x to an explicit integer, rational number or algebraic number. On success, sets res to this number and returns 1; otherwise returns 0 and leaves res unspecified.

Returns whether ca_get_qqbar has a chance to succeed, that is, whether x is a number all of whose extension numbers are, recursively, algebraic numbers, square roots, rational powers, absolute values, signs, real and imaginary parts, conjugates, floors or ceilings of evaluable numbers. Nothing is evaluated.

Sets res to a symbolic expression for x. Rational numbers and special values give simple expressions. Other numbers give an expression Where(f(a_1, ..., a_n), Def(a_1, e_1), ..., Def(a_n, e_n)) that defines symbols a_1, a_2, ... for the extension numbers involved (recursively) and expresses x as a rational function of them.

Sets res to the value of the symbolic expression expr and returns 1, or returns 0 if expr cannot be evaluated.

Prints x to standard output or to the file fp, in the style given by CA_OPT_PRINT_FLAGS, without a trailing newline.

Returns a string with the output that ca_print would produce. The caller must free it with flint_free.

Prints a decimal approximation of x with n significant digits, as ca_get_decimal_str computes it, to standard output.

Sets res to a random rational number with numerator and denominator of up to bits bits.

Sets res to a random number obtained by evaluating a random expression. At depth 0 it is a random rational number, an element of a quadratic field with coefficients of up to bits bits, or a constant such as \pi; for positive depth it may instead be an arithmetic operation or a function applied to operands generated recursively with depth depth - 1. The result is always a number, not a special value.

Sets res to a random special value or, with some probability, to a number generated by ca_randtest.

Sets res to a random element of the field of x, with numerator coefficients of up to bits bits and a denominator of up to den_bits bits. The number x must be an element of a field \mathbb{Q}(a) with one algebraic generator.

Returns whether x and y have the same representation: they belong to the same field (with structurally identical generators) and are the same rational function in it, or they are the same special value.

Compares the representations of x and y in a total order, returning -1, 0 or 1. The order is structural (it compares fields, then coefficients) and has no meaning as an order of the numbers.

Returns a hash of the representation of x; values with equal representations (ca_equal_repr) have equal hashes. All special values have the same hash.

Returns whether x is Unknown, or any special value (not a number).

Returns whether x is represented as an element of \mathbb{Q}, as the element 0 or 1 of \mathbb{Q}, or as an integer in \mathbb{Q}. Since operations normally demote rational results to \mathbb{Q} (see ca_condense_field), a rational value usually has this representation, but this is not guaranteed.

Returns whether x is represented as an element of a field \mathbb{Q}(a) with a single algebraic generator, stored as an nf_elem.h.

Returns whether x is represented as an element of a field \mathbb{Q}(a) whose generator a is a root of unity. In that case, if p and q are not NULL, sets them to the integers with 0 \le p < q and \gcd(p, q) = 1 such that a = e^{2 \pi i p / q}.

Returns whether x is represented as an element of a generic field, that is, it is a number that is neither represented in \mathbb{Q} nor in a field with a single algebraic generator.

Returns T_TRUE if x is a number (a field element), T_FALSE if it is an infinity or Undefined, and T_UNKNOWN if it is Unknown.

Checks whether x is equal to the number 0, 1, -1, i or -i. Special values are not equal to any number; Unknown gives T_UNKNOWN.

The cheap first stage of ca_check_is_zero: decides the question from the representation alone for elements of \mathbb{Q} and of fields with one algebraic generator, returns T_FALSE for special values other than Unknown, and T_UNKNOWN otherwise. Nothing is evaluated.

Checks whether x is an algebraic number, a rational number or an integer. Special values give T_FALSE (or T_UNKNOWN for Unknown).

Checks whether x is a real number, a negative real number, or a purely imaginary number (\operatorname{Re}(x) = 0; zero counts as imaginary). These functions return T_FALSE for all special values, including infinities with a real or imaginary sign, and T_UNKNOWN for Unknown.

Checks whether x is Undefined, any infinity, unsigned infinity, or any signed infinity. These depend only on the kind of value, so the answer is T_UNKNOWN only for Unknown.

Checks whether x is the signed infinity +\infty, -\infty, +i \infty or -i \infty. For a signed infinity this tests the sign with ca_check_equal, which may give T_UNKNOWN.

Checks whether x = y. Two numbers are compared by testing x - y for zero, after a quick check of the representations; special values are equal if they are the same kind of value (with equal signs for signed infinities). The result is T_UNKNOWN if either operand is Unknown, and may be T_UNKNOWN if x and y cannot be distinguished numerically and their equality cannot be proved.

Checks whether x < y, x \le y, x > y or x \ge y. Only real numbers and \pm \infty are comparable. If either operand is proved not comparable (a non-real number, unsigned infinity, a signed infinity other than \pm \infty, or Undefined) the result is T_FALSE, not T_UNKNOWN.

Sets res to -x. The negation of c \infty is (-c) \infty; the other special values are unchanged.

Sets res to x + y.

Sets res to x - y, with the same rules for special values as x + (-y).

Sets res to x y.

Sets res to 1/x. In a field with one algebraic generator the result has a rational denominator; in a generic field the denominator is not rationalised.

Sets res to x / y, which is x \cdot (1/y) for numbers.

Sets res to s + (-1)^{\mathit{subtract}} \sum_{i=0}^{\mathit{len}-1} x_{i \cdot \mathit{xstep}} \, y_{i \cdot \mathit{ystep}}.

Sets res to the polynomial poly evaluated at x.

Sets res to the multivariate polynomial f (in the context mctx) evaluated at the vector x, which must have one entry per variable. The horner version uses a multivariate Horner scheme, and the default version currently calls the horner version.

Sets res to the multivariate rational function f evaluated at x, dividing the values of the numerator and the denominator.

Like ca_fmpz_mpoly_q_evaluate and ca_inv, but assume without checking that the value of the denominator, respectively x, is nonzero, which avoids a zero test. If the assumption is false, the result is meaningless; ca_inv_no_division_by_zero throws an exception if x is manifestly zero.

Sets res to x^2.

Sets res to x^y, with the principal branch x^y = \exp(y \log x) for non-integer y.

Sets res to x^n, always by field arithmetic (binary exponentiation), whereas ca_pow_si may create x^n as a new extension number for large n. Special values of x give Unknown.

Sets res to the principal square root of x, with \operatorname{Re}(\sqrt{x}) \ge 0 and \sqrt{x} = i \sqrt{|x|} for negative real x.

Sets res to \sqrt{n}.

Sets res to |x|. For special values, |c \infty| = |\tilde \infty| = +\infty, and Undefined and Unknown map to themselves.

Sets res to the complex sign of x, which is x/|x| for x \ne 0 and 0 for x = 0. For special values, \operatorname{sgn}(c \infty) = c, \operatorname{sgn}(\tilde \infty) is Undefined, and Undefined and Unknown map to themselves.

Sets res to the extension of the real sign function that is 1 in the open right half-plane, -1 in the open left half-plane, and the sign of the imaginary part on the imaginary axis; equivalently \operatorname{csgn}(z) = z / \sqrt{z^2} for z \ne 0, and \operatorname{csgn}(0) = 0. For a signed infinity \operatorname{csgn}(c \infty) = \operatorname{csgn}(c); unsigned infinity gives Undefined. The result is Unknown when the required sign tests fail.

Sets res to the argument (phase) of x in (-\pi, \pi], with \arg(0) = 0. If \operatorname{sgn}(x) is a root of unity e^{\pi i p/q}, the result is the rational multiple p \pi / q. For special values, \arg(c \infty) = \arg(c), \arg(\tilde \infty) is Undefined, and Undefined and Unknown map to themselves.

Sets res to the real or imaginary part of x. Every infinity gives Undefined, including real and imaginary infinities.

Sets res to the complex conjugate \overline{x}.

Sets res to \lfloor x \rfloor or \lceil x \rceil; for a nonreal number, of its real part. The integer is determined numerically when the real part is not too close to an integer; otherwise the result is the generator of the field \mathbb{Q}(\lfloor x \rfloor). All infinities give Undefined.

Sets res to e^x. In the generic case the result is the generator of \mathbb{Q}(e^x).

Sets res to the principal branch of the natural logarithm, with -\pi < \operatorname{Im}(\log x) \le \pi. In the generic case the result is the generator of \mathbb{Q}(\log x).

Sets res1 to \sin x and res2 to \cos x. Either output may be NULL if only the other function is wanted.

Sets res to \sin x or \cos x, computed with ca_sin_cos.

Sets res to \tan x, as a quotient of a sine and a cosine, in terms of complex exponentials, or directly as the generator of \mathbb{Q}(\tan x) (possibly after a transformation of the argument). ca_tan uses the form selected by CA_OPT_TRIG_FORM. Simple algebraic values simplify to elements of number fields.

Sets res to \cot x = 1/\tan x.

Sets res to the principal branch of \operatorname{atan} x.

Sets res to the principal branch of \operatorname{asin} x or \operatorname{acos} x.

Sets res to \Gamma(x). Integers give factorials (or \tilde \infty at the poles 0, -1, -2, \ldots), half-integers give rational multiples of \sqrt{\pi}, and otherwise the result is an element of a field containing \Gamma(x); the relation \Gamma(x + n) = x (x+1) \cdots (x+n-1) \Gamma(x) between generators that differ by integers is added to the ideal of relations.

Sets res to the error function \operatorname{erf}(x), the complementary error function \operatorname{erfc}(x) = 1 - \operatorname{erf}(x) or the imaginary error function \operatorname{erfi}(x) = -i \operatorname{erf}(ix). Odd symmetry is used to normalise the argument, and the relations between the three functions at related arguments are added to the ideal of relations. For special values, \operatorname{erf}(\pm \infty) = \pm 1, \operatorname{erfc}(+\infty) = 0, \operatorname{erfc}(-\infty) = 2, \operatorname{erf}(\pm i \infty) = \pm i \infty, and unsigned infinity gives Undefined.

Sets res to an enclosure of the value of x, computed by evaluating the representation in ball arithmetic with working precision prec, without any adaptive refinement. Enclosures of the extension numbers are cached in the context. A special value gives an indeterminate ball (see acb_indeterminate).

Sets res to an enclosure of the value of x, increasing the working precision until the result has a relative accuracy of prec bits, or for the accurate_parts version until the real and the imaginary part separately have prec accurate bits.

Returns a decimal approximation of x with up to digits significant digits, as computed by ca_get_acb (or ca_get_acb_accurate_parts if flags is 1), correct to within one unit in the last digit. Fewer digits are returned if the evaluation does not reach the requested accuracy, and the string "?" if x is not a number or no finite enclosure is obtained. The caller must free the string with flint_free.

Initialises fac to the empty product, which represents 1, or clears it.

Sets fac to the empty product.

Prints the factors of fac to standard output, one line (b) ^ (e) per factor.

Multiplies fac by b^e, where b is base and e is exp. If a base with the same representation (see ca_equal_repr) is already present, its exponent is increased by e; otherwise the factor is appended.

Sets res to the product b_1^{e_1} \cdots b_n^{e_n}, computed with ca_pow and ca_mul.

Sets res to a factorisation x = b_1^{e_1} \cdots b_n^{e_n} of the number x, which must not be a special value. flags combines one of the polynomial options and one of the integer options below.

Sets resx and resy to copies of x and y represented as elements of a common field, whose generators are the union of the generators of both fields, sorted in the structural order used for elimination. Both inputs must be numbers, not special values, and the outputs must be distinct from the inputs (unless the fields are already equal or one of them is \mathbb{Q}).

Moves res to a smaller field when this is possible by inspecting its representation: a rational value is demoted to \mathbb{Q}, and an element of a generic field that only depends on one algebraic generator becomes an element of the number field generated by it. This is done automatically by most operations.

If x is a generator a_k of its field \mathbb{Q}(a_1, \ldots, a_n), returns a pointer to the extension number a_k; otherwise returns NULL.

Changes the internal representation of x to that of an element of field (allocating or freeing data as needed). The value of x is destroyed.

Changes the internal representation of x to that of an element of \mathbb{Q}. The value of x is destroyed unless it already is one.

Returns the field \mathbb{Q}(a) generated by the extension number a = func, func(x) or func(x, y), creating and caching the extension number and the field if necessary.

Sets res to the generator of the field \mathbb{Q}(f(x)) or \mathbb{Q}(f(x, y)) with f = func, without any simplification or checks. The arguments must be numbers.

Reduces the numerator and the denominator of res, an element of the generic field field, modulo the ideal of relations of the field (by pseudo-division with remainder), and cancels common factors.

Tries to simplify the fraction res using the ideal of relations of field, currently by moving monomial factors of the denominator to the numerator: if a relation has a leading monomial u sharing a factor g with the denominator, numerator and denominator are multiplied by u/g and reduced, which is kept if the denominator decreases.