Data.Number.Flint.Calcium.Ca.Field

A CaFieldt represents the parent field \(K = \mathbb{Q}(a_1,\ldots,a_n)\) of a Ca element. A CaField contains a list of pointers to CaExt objects as well as a reduction ideal.

The user does not normally need to create CaField objects manually: a CaCtx 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.
• A generic field \(\mathbb{Q}(a_1,\ldots,a_n)\) where \(n \ge 1\), and \(a_1\) is not defined by a QQbar if \(n = 1\).

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

Extension fields

data CaField

Constructors

CaField !(ForeignPtr CCaField)

type CCaField = CFlint CaField

Memory management

ca_field_init_qq :: Ptr CCaField -> Ptr CCaCtx -> IO ()

ca_field_init_qq K ctx

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

ca_field_init_nf :: Ptr CCaField -> Ptr CQQbar -> Ptr CCaCtx -> IO ()

ca_field_init_nf K x ctx

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

ca_field_init_const :: Ptr CCaField -> CCalciumFunctionCode -> Ptr CCaCtx -> IO ()

ca_field_init_const K func 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\)).

ca_field_init_fx :: Ptr CCaField -> CCalciumFunctionCode -> Ptr CCa -> Ptr CCaCtx -> IO ()

ca_field_init_fx K func x 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\)).

ca_field_init_fxy :: Ptr CCaField -> CCalciumFunctionCode -> Ptr CCa -> Ptr CCa -> Ptr CCaCtx -> IO ()

ca_field_init_fxy K func x y ctx

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

ca_field_init_multi :: Ptr CCaField -> CLong -> Ptr CCaCtx -> IO ()

ca_field_init_multi K len 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.

ca_field_set_ext :: Ptr CCaField -> CLong -> Ptr CCaExt -> Ptr CCaCtx -> IO ()

ca_field_set_ext K i x_index 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.

ca_field_clear :: Ptr CCaField -> Ptr CCaCtx -> IO ()

ca_field_clear K ctx

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

Input and output

ca_field_print :: Ptr CCaField -> Ptr CCaCtx -> IO ()

ca_field_print K ctx

Prints a description of the field K to standard output.

Ideal

ca_field_build_ideal :: Ptr CCaField -> Ptr CCaCtx -> IO ()

ca_field_build_ideal K ctx

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

ca_field_build_ideal_erf :: Ptr CCaField -> Ptr CCaCtx -> IO ()

ca_field_build_ideal_erf K 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

ca_field_cmp :: Ptr CCaField -> Ptr CCaField -> Ptr CCaCtx -> IO CInt

ca_field_cmp K1 K2 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

ca_field_cache_init :: Ptr CCaFieldCache -> Ptr CCaCtx -> IO ()

ca_field_cache_init cache ctx

Initializes cache for use.

ca_field_cache_clear :: Ptr CCaFieldCache -> Ptr CCaCtx -> IO ()

ca_field_cache_clear cache ctx

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

ca_field_cache_insert_ext :: Ptr CCaFieldCache -> Ptr (Ptr CCaExt) -> CLong -> Ptr CCaCtx -> IO (Ptr CCaField)

ca_field_cache_insert_ext cache x len 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.