.. _gr-domains: **gr.h (continued)** -- builtin domains and types =============================================================================== Coercions ------------------------------------------------------------------------------- .. function:: int gr_ctx_cmp_coercion(gr_ctx_t ctx1, gr_ctx_t ctx2) Returns 1 if coercing elements into *ctx1* is more meaningful, and returns -1 otherwise. Domain properties ------------------------------------------------------------------------------- .. function:: truth_t gr_ctx_is_finite(gr_ctx_t ctx) truth_t gr_ctx_is_multiplicative_group(gr_ctx_t ctx) truth_t gr_ctx_is_ring(gr_ctx_t ctx) truth_t gr_ctx_is_commutative_ring(gr_ctx_t ctx) truth_t gr_ctx_is_integral_domain(gr_ctx_t ctx) truth_t gr_ctx_is_unique_factorization_domain(gr_ctx_t ctx) truth_t gr_ctx_is_field(gr_ctx_t ctx) truth_t gr_ctx_is_algebraically_closed(gr_ctx_t ctx) truth_t gr_ctx_is_finite_characteristic(gr_ctx_t ctx) truth_t gr_ctx_is_ordered_ring(gr_ctx_t ctx) truth_t gr_ctx_is_zero_ring(gr_ctx_t ctx) Returns whether the structure satisfies the respective mathematical property. The result can be ``T_UNKNOWN``. .. function:: truth_t gr_ctx_is_exact(gr_ctx_t ctx) Returns whether the representation of elements is always exact. .. function:: truth_t gr_ctx_is_canonical(gr_ctx_t ctx) Returns whether the representation of elements is always canonical. .. function:: truth_t gr_ctx_has_real_prec(gr_ctx_t ctx) Returns whether *ctx* or a base field thereof represents real or complex numbers using finite-precision approximations. This returns ``T_TRUE`` both for floating-point approximate fields and for rigorous fields based on ball or interval arithmetic. .. function:: int gr_ctx_set_real_prec(gr_ctx_t ctx, slong prec) int gr_ctx_get_real_prec(slong * prec, gr_ctx_t ctx) Sets or retrieves the floating-point precision in bits. Groups ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_perm(gr_ctx_t ctx, ulong n) Initializes *ctx* to the symmetric group `S_n` representing permutations of `[0, 1, \ldots, n - 1]`. Elements are currently represented as pointers (the representation may change in the future). .. function:: void gr_ctx_init_psl2z(gr_ctx_t ctx) Initializes *ctx* to the modular group `\text{PSL}(2, \mathbb{Z})` with elements of type :type:`psl2z_t`. .. function:: int gr_ctx_init_dirichlet_group(gr_ctx_t ctx, ulong q) Initializes *ctx* to the Dirichlet group `G_q` with elements of type :type:`dirichlet_char_t`. Fails and returns ``GR_DOMAIN`` if *q* is zero. Fails and returns ``GR_UNABLE`` if *q* has a prime factor larger than `10^{16}`, which is currently unsupported by the implementation. Basic rings and fields ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_random(gr_ctx_t ctx, flint_rand_t state) Initializes *ctx* to a random ring. This will currently only generate base rings and composite rings over certain simple base rings. .. function:: void gr_ctx_init_fmpz(gr_ctx_t ctx) Initializes *ctx* to the ring of integers `\mathbb{Z}` with elements of type :type:`fmpz`. .. function:: void gr_ctx_init_fmpq(gr_ctx_t ctx) Initializes *ctx* to the field of rational numbers `\mathbb{Q}` with elements of type :type:`fmpq`. .. function:: void gr_ctx_init_fmpzi(gr_ctx_t ctx) Initializes *ctx* to the ring of Gaussian integers `\mathbb{Z}[i]` with elements of type :type:`fmpzi_t`. Residue rings and finite fields ------------------------------------------------------------------------------- .. function:: int gr_ctx_set_is_field(gr_ctx_t ctx, truth_t is_field) Set whether the given ring is actually a field. For example, in the case of `\mathbb{Z}/n\mathbb{Z}`, this sets whether the modulus is prime. This can speed up some computations and enable some functions to complete that otherwise would return ``GR_UNABLE``. .. function:: void gr_ctx_init_nmod(gr_ctx_t ctx, ulong n) Initializes *ctx* to the ring `\mathbb{Z}/n\mathbb{Z}` of integers modulo *n* where elements have type :type:`ulong`. We require `n \ne 0`. .. function:: void gr_ctx_init_nmod8(gr_ctx_t ctx, unsigned char n) void gr_ctx_init_nmod32(gr_ctx_t ctx, unsigned int n) Initializes *ctx* to the ring `\mathbb{Z}/n\mathbb{Z}` of integers modulo *n* where elements have type :type:`uint8` or :type:`uint32`. The modulus must be nonzero. .. note :: Presently, many operations for these types are not as optimized as those for full-word ``nmods``. It is currently recommended to use :func:`gr_ctx_init_nmod` for best performance unless one specifically wants to minimize memory usage. .. function:: void gr_ctx_init_fmpz_mod(gr_ctx_t ctx, const fmpz_t n) Initializes *ctx* to the ring `\mathbb{Z}/n\mathbb{Z}` of integers modulo *n* where elements have type :type:`fmpz`. The modulus must be positive. * :func:`gr_ctx_init_mpn_mod` Initializes *ctx* to the ring `\mathbb{Z}/n\mathbb{Z}` of integers modulo *n* where elements are flat limb arrays with the same number of limbs as *n*. .. function:: void gr_ctx_init_fq(gr_ctx_t ctx, const fmpz_t p, slong d, const char * var) void gr_ctx_init_fq_nmod(gr_ctx_t ctx, ulong p, slong d, const char * var) void gr_ctx_init_fq_zech(gr_ctx_t ctx, ulong p, slong d, const char * var) Initializes *ctx* to the finite field `\mathbb{F}_q` where `q = p^d`. It is assumed (not checked) that *p* is prime. The variable name *var* can be ``NULL`` to use a default. The corresponding element types are ``fq_t``, ``fq_nmod_t``, ``fq_zech_t``. The ``fq_zech`` context requires `q < 2^{64}` (and in practice a much smaller value than this). Number fields and algebraic numbers ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_nf(gr_ctx_t ctx, const fmpq_poly_t poly) void gr_ctx_init_nf_fmpz_poly(gr_ctx_t ctx, const fmpz_poly_t poly) Initializes *ctx* to the number field with defining polynomial ``poly`` which *must* be irreducible (this is not checked). The elements have type :type:`nf_elem_t`. .. function:: void gr_ctx_init_real_qqbar(gr_ctx_t ctx) void gr_ctx_init_complex_qqbar(gr_ctx_t ctx) Initializes *ctx* to the field of real or complex algebraic numbers with elements of type :type:`qqbar_t`. .. function:: void _gr_ctx_qqbar_set_limits(gr_ctx_t ctx, slong deg_limit, slong bits_limit) Limit degrees of intermediate operands of a *qqbar* context to *deg_limit* and their bit sizes to *bits_limit* (approximately). The limits refer to the sizes of resultants prior to factorization (see :func:`qqbar_binop_within_limits`), so for example adding two degree-100 algebraic numbers requires a degree limit of at least 10000. Warning: currently not all methods respect these limits. Real and complex numbers ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_real_arb(gr_ctx_t ctx, slong prec) void gr_ctx_init_complex_acb(gr_ctx_t ctx, slong prec) Initializes *ctx* to the field of real or complex numbers represented by elements of type :type:`arb_t` and :type:`acb_t`. .. function:: void gr_ctx_arb_set_prec(gr_ctx_t ctx, slong prec) slong gr_ctx_arb_get_prec(gr_ctx_t ctx) Sets or retrieves the bit precision of *ctx* which must be an Arb context (this is currently not checked). .. function:: void gr_ctx_init_real_ca(gr_ctx_t ctx) void gr_ctx_init_complex_ca(gr_ctx_t ctx) void gr_ctx_init_real_algebraic_ca(gr_ctx_t ctx) void gr_ctx_init_complex_algebraic_ca(gr_ctx_t ctx) Initializes *ctx* to the field of real, complex, real algebraic or complex algebraic numbers represented by elements of type :type:`ca_t`. .. function:: void gr_ctx_ca_set_option(gr_ctx_t ctx, slong option, slong value) slong gr_ctx_ca_get_option(gr_ctx_t ctx, slong option) Sets or retrieves options of a Calcium context object. Extended number sets ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_complex_extended_ca(gr_ctx_t ctx) Like :func:`gr_ctx_init_complex_ca` but allows special values (infinities, undefined). Floating-point arithmetic ------------------------------------------------------------------------------- Although domains of floating-point numbers approximate real and complex fields, they are not rings or fields. Floating-point arithmetic can be used in many places where a ring or field is normally assumed, but predicates like "is field" return false. * Equality compares equality of floating-point numbers, with the special rule that NaN is not equal to itself. * In general, the following implementations do not currently guarantee correct rounding except for atomic arithmetic operations (add, sub, mul, div, sqrt) on real floating-point numbers. .. function:: void gr_ctx_init_real_float_arf(gr_ctx_t ctx, slong prec) Initializes *ctx* to the floating-point arithmetic with elements of type :type:`arf_t` and a default precision of *prec* bits. .. function:: void gr_ctx_init_complex_float_acf(gr_ctx_t ctx, slong prec) Initializes *ctx* to the complex floating-point arithmetic with elements of type :type:`acf_t` and a default precision of *prec* bits. Vectors ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_vector_gr_vec(gr_ctx_t ctx, gr_ctx_t base_type) Initializes *ctx* to the domain of all vectors (of any length) over the given *base_type*. Elements have type :type:`gr_vec_struct`. .. function:: void gr_ctx_init_vector_space_gr_vec(gr_ctx_t ctx, gr_ctx_t base_type, slong n) Initializes *ctx* to the space of all vectors of length *n* over the given *base_type*. Elements have type :type:`gr_vec_struct`. Matrices ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_matrix_domain(gr_ctx_t ctx, gr_ctx_t base_ring) Initializes *ctx* to the domain of all matrices (of any shape) over the given *base_ring*. Elements have type :type:`gr_mat_struct`. .. function:: void gr_ctx_init_matrix_space(gr_ctx_t ctx, gr_ctx_t base_ring, slong n, slong m) Initializes *ctx* to the space of matrices over *base_ring* with *n* rows and *m* columns. Elements have type :type:`gr_mat_struct`. .. function:: void gr_ctx_init_matrix_ring(gr_ctx_t ctx, gr_ctx_t base_ring, slong n) Initializes *ctx* to the ring of matrices over *base_ring* with *n* rows columns. Elements have type :type:`gr_mat_struct`. Polynomial rings ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_fmpz_poly(gr_ctx_t ctx) Initializes *ctx* to a ring of integer polynomials of type :type:`fmpz_poly_struct`. .. function:: void gr_ctx_init_fmpq_poly(gr_ctx_t ctx) Initializes *ctx* to a ring of rational polynomials of type :type:`fmpq_poly_struct`. .. function:: void gr_ctx_init_gr_poly(gr_ctx_t ctx, gr_ctx_t base_ring) Initializes *ctx* to a ring of densely represented univariate polynomials over the given *base_ring*. Elements have type :type:`gr_poly_struct`. .. function:: void gr_ctx_init_fmpz_mpoly(gr_ctx_t ctx, slong nvars, const ordering_t ord) Initializes *ctx* to a ring of sparsely represented multivariate polynomials in *nvars* variables over the integers, with monomial ordering *ord*. Elements have type :type:`fmpz_mpoly_struct`. .. function:: void gr_ctx_init_gr_mpoly(gr_ctx_t ctx, gr_ctx_t base_ring, slong nvars, const ordering_t ord) Initializes *ctx* to a ring of sparsely represented multivariate polynomials in *nvars* variables over the given *base_ring*, with monomial ordering *ord*. Elements have type :type:`gr_mpoly_struct`. Power series ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_series_mod_gr_poly(gr_ctx_t ctx, gr_ctx_t base_ring, slong n) Initializes *ctx* to a ring of truncated power series `R[[x]] / \langle x^n \rangle` over the given *base_ring*. Elements have type :type:`gr_poly_struct`. It is assumed that all inputs are already truncated to length *n*, and this invariant is enforced for all outputs. .. function:: void gr_ctx_init_gr_series(gr_ctx_t ctx, gr_ctx_t base_ring, slong prec) Initializes *ctx* to a ring of power series `R[[x]]` over the given *base_ring*. Elements are generally inexact, having an error term `O(x^n)`. The parameter *prec* defines the default precision. Elements have type ``gr_series_struct`` (this type is currently internal). Fraction fields ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_fmpz_mpoly_q(gr_ctx_t ctx, slong nvars, const ordering_t ord) Initializes *ctx* to a ring of sparsely represented multivariate fractions in *nvars* variables over the integers (equivalently, rationals), with monomial ordering *ord*. Elements have type :type:`fmpz_mpoly_q_struct`. Symbolic expressions ------------------------------------------------------------------------------- .. function:: void gr_ctx_init_fexpr(gr_ctx_t ctx) Initializes *ctx* to handle symbolic expressions. Elements have type :type:`fexpr_struct`. .. raw:: latex \newpage