# ca_field.h – extension fields

A `ca_field_t` represents the parent field \(K = \mathbb{Q}(a_1,\ldots,a_n)\) of a `ca_t` element. A `ca_field_t` contains a list of pointers to `ca_ext_t` objects as well as a reduction ideal.

The user does not normally need to create `ca_field_t` objects manually: a `ca_ctx_t` context object manages a cache of fields automatically.

Internally, three types of field representation are used:

- The trivial field \(\mathbb{Q}\).

- An Antic number field \(\mathbb{Q}(a)\) where a is defined by a `qqbar_t`

- A generic field \(\mathbb{Q}(a_1,\ldots,a_n)\) where \(n \ge 1\), and \(a_1\) is not defined by a `qqbar_t` if \(n = 1\).

The field type mainly affects the internal storage of the field elements; the distinction is mostly transparent to the external interface.

## Type and macros

For all types, a type_t is defined as an array of length one of type type_struct, permitting a type_t to be passed by reference.

type ca_field_struct

type ca_field_t

  Represents a formal field.

type ca_field_ptr

  Alias for `ca_field_struct *`.

type ca_field_srcptr

  Alias for `const ca_field_struct *`.

CA_FIELD_LENGTH(K)

  Accesses the number n of extension numbers of K. This is 0 if \(K = \mathbb{Q}\).

CA_FIELD_EXT(K)

  Accesses the array of extension numbers as a `ca_ext_ptr`.

CA_FIELD_EXT_ELEM(K, i)

  Accesses the extension number at position i (indexed from zero) as a `ca_ext_t`.

CA_FIELD_HASH(K)

  Accesses the hash value of K.

CA_FIELD_IS_QQ(K)

  Returns whether K is the trivial field \(\mathbb{Q}\).

CA_FIELD_IS_NF(K)

  Returns whether K represents an Antic number field \(K = \mathbb{Q}(a)\) where a is represented by a `qqbar_t`.

CA_FIELD_IS_GENERIC(K)

  Returns whether K represents a generic field.

CA_FIELD_NF(K)

  Assuming that K represents an Antic number field \(K = \mathbb{Q}(a)\), accesses the `nf_t` object representing this field.

CA_FIELD_NF_QQBAR(K)

  Assuming that K represents an Antic number field \(K = \mathbb{Q}(a)\), accesses the `qqbar_t` object representing a.

CA_FIELD_IDEAL(K)

  Assuming that K represents a multivariate field, accesses the reduction ideal as a `fmpz_mpoly_t` array.

CA_FIELD_IDEAL_ELEM(K, i)

  Assuming that K represents a multivariate field, accesses element i (indexed from zero) of the reduction ideal as a `fmpz_mpoly_t`.

CA_FIELD_IDEAL_LENGTH(K)

  Assuming that K represents a multivariate field, accesses the number of polynomials in the reduction ideal.

CA_FIELD_MCTX(K, ctx)

  Assuming that K represents a multivariate field, accesses the `fmpz_mpoly_ctx_t` context object for multivariate polynomial arithmetic on the internal representation of elements in this field.

## Memory management

void ca_field_init_qq(ca_field_t K, ca_ctx_t ctx)

  Initializes K to represent the trivial field \(\mathbb{Q}\).

void ca_field_init_nf(ca_field_t K, const qqbar_t x, ca_ctx_t ctx)

  Initializes K to represent the algebraic number field \(\mathbb{Q}(x)\).

void ca_field_init_const(ca_field_t K, calcium_func_code func, ca_ctx_t ctx)

  Initializes K to represent the field \(\mathbb{Q}(x)\) where x is a builtin constant defined by func (example: func = CA_Pi for \(x = \pi\)).

void ca_field_init_fx(ca_field_t K, calcium_func_code func, const ca_t x, ca_ctx_t ctx)

  Initializes K to represent the field \(\mathbb{Q}(a)\) where \(a = f(x)\), given a number x and a builtin univariate function func (example: func = CA_Exp for \(e^x\)).

void ca_field_init_fxy(ca_field_t K, calcium_func_code func, const ca_t x, const ca_t y, ca_ctx_t ctx)

  Initializes K to represent the field \(\mathbb{Q}(a,b)\) where \(a = f(x, y)\).

void ca_field_init_multi(ca_field_t K, slong len, ca_ctx_t ctx)

  Initializes K to represent a multivariate field \(\mathbb{Q}(a_1, \ldots, a_n)\) in n extension numbers. The extension numbers must subsequently be assigned one by one using `ca_field_set_ext()`.

void ca_field_set_ext(ca_field_t K, slong i, ca_ext_srcptr x_index, ca_ctx_t ctx)

  Sets the extension number at position i (here indexed from 0) of K to the generator of the field with index x_index in ctx. (It is assumed that the generating field is a univariate field.)

  This only inserts a shallow reference: the field at index x_index must be kept alive until K has been cleared.

void ca_field_clear(ca_field_t K, ca_ctx_t ctx)

  Clears the field K. This does not clear the individual extension numbers, which are only held as references.

## Input and output

void ca_field_print(const ca_field_t K, ca_ctx_t ctx)

  Prints a description of the field K to standard output.

## Ideal

void ca_field_build_ideal(ca_field_t K, ca_ctx_t ctx)

  Given K with assigned extension numbers, builds the reduction ideal in-place.

void ca_field_build_ideal_erf(ca_field_t K, ca_ctx_t ctx)

  Builds relations for error functions present among the extension numbers in K. This heuristic adds relations that are consequences of the functional equations \(\operatorname{erf}(x) = -\operatorname{erf}(-x)\), \(\operatorname{erfc}(x) = 1-\operatorname{erf}(x)\), \(\operatorname{erfi}(x) = -i\operatorname{erf}(ix)\).

## Structure operations

int ca_field_cmp(const ca_field_t K1, const ca_field_t K2, ca_ctx_t ctx)

  Compares the field objects K1 and K2 in a canonical sort order, returning -1, 0 or 1. This only performs a lexicographic comparison of the representations of K1 and K2; the return value does not say anything meaningful about the relative structures of K1 and K2 as mathematical fields.

## Cache

type ca_field_cache_struct

type ca_field_cache_t

  Represents a set of distinct `ca_field_t` instances. This object contains an array of pointers to individual heap-allocated `ca_field_struct` objects as well as a hash table for quick lookup.

void ca_field_cache_init(ca_field_cache_t cache, ca_ctx_t ctx)

  Initializes cache for use.

void ca_field_cache_clear(ca_field_cache_t cache, ca_ctx_t ctx)

  Clears cache, freeing the memory allocated internally. This does not clear the individual extension numbers, which are only held as references.

ca_field_ptr ca_field_cache_insert_ext(ca_field_cache_t cache, ca_ext_struct **x, slong len, ca_ctx_t ctx)

  Adds the field defined by the length-len list of extension numbers x to cache without duplication. If such a field already exists in cache, a pointer to that instance is returned. Otherwise, a field with extension numbers x is inserted into cache and a pointer to that new instance is returned. Upon insertion of a new field, the reduction ideal is constructed via `ca_field_build_ideal()`.