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, ulong 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, ulong 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, slong 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, const 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().