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 inplace.

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 heapallocatedca_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 lengthlen 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()
.