Choosing types

FLINT usually has more than one type for a given mathematical object. The integers modulo n alone can be ulong residues with an nmod_t, fmpz residues with an fmpz_mod_ctx_t, fixed-length limb arrays in an mpn_mod context, or elements of any of these through the generic interface gr. The types differ in the range of parameters they accept, in speed (often by large factors for small inputs), in the functionality that exists for them, and in how they are called. The sections below give the general principles and tables of the types by domain, with their limits.

General principles#

Use the narrowest representation that fits. A type whose elements have a bounded size, such as a word-size residue, needs no memory allocation, no branches on the size of the operands and no pointer chasing, and can be packed into vectors and matrices on which vectorised kernels operate. If the modulus is below 2^{64}, nmod types are several times faster than fmpz_mod types for the same computation; for small non-prime finite fields, Zech logarithms are much faster than polynomial representations. The price is a limit on the parameters, which the tables below give for each type.

Use the type of the module that does what you need. The classic modules (fmpz_poly, nmod_mat, fmpz_mpoly, ...) contain algorithms that exist for one ring only: factorisation of integer polynomials, LLL reduction, Hermite normal forms, multivariate GCDs. Before choosing a representation for speed, check that the module of that type has the operations your program needs.

Decide between exact and approximate arithmetic. Exact types (fmpz, fmpq, residues, finite fields, number fields, qqbar, ca) give exact results whose size may grow. Ball types (arb, acb and the dfloat and decimal balls) give rigorous error bounds at a fixed working precision. Floating-point types (arf, nfloat, the dfloat numbers, double) give approximations without automatic error tracking. See Ball arithmetic and Exact real and complex numbers.

Use the generic interface for rings that have no module of their own and for code that must work over several rings. Polynomials over \mathbb{Z}[i], matrices over a number field, power series over \mathbb{Z}/n\mathbb{Z} for a large n or polynomials whose coefficients are power series have no dedicated type, but are available as gr_poly, gr_mat and so on over the right context. Where a classic module exists, its functions are at least as fast as the generic ones (the generic contexts call them for the critical operations) and usually more complete. The trade-offs are described in Generic programming.

Mind the context. Types whose parameters are not stored in the object (fmpz_mod, fq, padic, the multivariate types, gr) take a context argument, which must outlive the objects. For historical reasons, the nmod_poly and nmod_mat types store their modulus in each object, which is simpler to call but makes objects larger.

Integers#

Integers modulo n#

Operations that divide (polynomial division and GCD, matrix inversion and solving) generally require a prime modulus, or at least invertible pivots and leading coefficients. With the classic types the requirement is a documented precondition, and violating it raises an exception or gives undefined results; the generic gr interface instead returns GR_DOMAIN or GR_UNABLE.

Finite fields#

fq_default_ctx_init chooses fq_zech if d > 1 and d times the bit length of p is at most 16 (so q < 2^{16}), fq_nmod if d > 1 and p < 2^{\mathtt{FLINT\_BITS}}, nmod or fmpz_mod if d = 1, and fq otherwise (fq_default_ctx_init_type forces a choice); see Getting started with finite fields. Each representation has modules for vectors, matrices, polynomials, polynomial factorisation and embeddings (fq_nmod_poly, fq_zech_mat, fq_default_poly_factor, ...), and fq_nmod and fq_zech also multivariate polynomials (fq_nmod_mpoly, fq_zech_mpoly).

Univariate polynomials and power series#

Lengths and degrees are slong; the practical limit is memory. Most classic polynomial modules have _series functions (inverse, square root, exponential, logarithm, composition and reversion of power series truncated to a length).

Multivariate polynomials#

All these types store terms sparsely, sorted in a monomial ordering of the context, with exponent vectors packed into fields of bits bits (mpoly.h). Exponents are not bounded: up to FLINT_BITS bits, several fields share a word (at least MPOLY_MIN_BITS = 8 bits per field), and larger exponents take several words per field; the packing is enlarged automatically when a result needs it. fmpq_mpoly stores a rational content times a primitive fmpz_mpoly. For univariate problems, it is generally better to use the univariate types which store polynomials densely.

Matrices#

For approximate (non-rigorous) linear algebra at or above double precision, gr_mat over an nfloat or dfloat context is the fastest choice; for certified results, use arb_mat or acb_mat.

p-adic numbers and number fields#

Real and complex numbers#

The ball types are the only real and complex types whose results are guaranteed in all cases (the dfloat and decimal balls are rigorous as well, but cover less functionality). The floating-point types are for approximate computations, typically followed by a rigorous verification, and are not rings in the sense of gr (Inexact elements and truth values).

Exact real and complex numbers#

Ball arithmetic can prove that two numbers differ, by computing them accurately enough that their balls are disjoint, but never that they are equal: a ball that contains zero is compatible with a tiny nonzero number. Computations that need equality (is a pivot zero, does an expression reproduce a known constant) can use FLINT's exact real and complex numbers, which represent numbers symbolically, so that arithmetic is exact and numerical values are available to any precision. This part of FLINT was developed as the library Calcium [Joh2021calcium].

The predicates of ca return T_TRUE, T_FALSE or T_UNKNOWN (Triple-valued logic): equality of algebraic numbers is decided within configurable limits, and equality involving transcendental numbers in many but not all cases, since it is not known to be decidable in general. A program must handle T_UNKNOWN (Dealing with T_UNKNOWN, What is decided in practice). qqbar decides every predicate, but its minimal polynomials can grow quickly; computations whose degrees explode, such as sums of many square roots, can be cheaper with ca, which keeps them in a field with several generators. For numbers in \mathbb{Q} or in one fixed number field, fmpq and nf_elem are much faster.

Exact numbers are far too slow to replace floating-point or ball arithmetic in numerical computations. A mostly numerical computation should use balls, and fall back on exact numbers only where an exact comparison is needed; exact numbers are also useful for testing numerical code. The contexts gr_ctx_init_real_qqbar, gr_ctx_init_complex_qqbar, gr_ctx_init_real_ca, gr_ctx_init_complex_ca and related ones make these numbers available to the generic polynomial and matrix algorithms (Number fields and algebraic numbers, Real and complex numbers). Choosing a representation for exact numbers compares the representations in detail, and Exact computation has worked examples.

Generic rings#

The generic interface gr makes all the ring types above, and rings built from them, available through one set of functions over a context gr_ctx_t (gr_domains). Use it for rings without a module of their own, for the types that exist only as generic rings (mpn_mod, nfloat, dfloat, decimal, padic_radix), and for code that must work over several rings. Getting started with generic rings is the tutorial, and Generic programming discusses what generic code costs.

@misc{flint-doc-guide-types-choosing,
  author       = {{The FLINT team}},
  title        = {{Choosing types}},
  howpublished = {FLINT: Fast Library for Number Theory, documentation, version 3.7.0-dev},
  year         = {2026},
  url          = {https://flintlib.org/doc/guide/types/choosing.html},
  note         = {Generated 2026-10-20}
}