CALIB provides the GFpk
domain, representing the Galois
Field GF(p^k) — the finite field having exactly p^k
members, where p is a prime, and k>1 is an integer.
The “values” of this domain are represented by the following object:
struct calib_GFpk_obj { const struct calib_GFpk_dom * dom; /* GF(p^k) domain containing this value */ mpz_ptr coeff; /* Coefficients. This is an array of */ /* k integers in Z_p. */ };
These value objects are subject to init()
and clear()
operations.
All such objects must be initialized prior to use by any other CALIB
operation.
Memory leaks result if they are not cleared when done.
The CALIB GFpk
domain is constructed by specifying an
irreducible “generator” polynomial of degree k in
Z_p[x].
One may access CALIB’s GFpk
domain as follows:
#include "calib/GFpk.h" ... struct calib_Zpx_obj * gpoly; struct calib_GFpk_dom * dom; gpoly = /* generator polynomial in Zp[x] of degree k. */ dom = calib_make_GFpk_dom (gpoly); ... calib_free_GFpk_dom (dom);
There is also a lower-level function to construct a
struct calib_GFpk_dom
object from an array of generator
polynomial coefficients:
extern struct calib_GFpk_dom * calib_make_GFpk_dom_z ( const struct calib_Zp_dom * cf, int k, mpz_srcptr gcoeff);
The struct calib_GFpk_dom
object contains the following members
(pointers to functions) that provide operations of the domain:
void (*init) (const struct calib_GFpk_dom * f, struct calib_GFpk_obj * x);
Initialize GFpk value object x
to be a member of the GFpk
domain f
, where:
f | is the GFpk domain performing this operation; and |
x | is the GFpk value object to be initialized. |
void (*clear) (struct calib_GFpk_obj * x);
Clear out the given GFpk value object x
(freeing all memory it
might hold), where:
x | is the GFpk value object to be cleared. |
void (*set) (struct calib_GFpk_obj * rop, const struct calib_GFpk_obj * op);
Set rop
to op
in GF(p^k), where:
rop | is the GFpk value object receiving the result; and |
op | is the source GFpk value object. |
void (*set_si) (struct calib_GFpk_obj * rop, calib_si_t op);
Set rop
to op
in GF(p^k), where:
rop | is the GFpk value object receiving the result; and |
op | is the signed integer to convert into GF(p^k) form. |
void (*set_z) (struct calib_GFpk_obj * rop, mpz_srcptr op);
Set rop
to op
in GF(p^k), where:
rop | is the GFpk value object receiving the result; and |
op | is the GMP integer to convert into GF(p^k) form. |
void (*set_q) (struct calib_GFpk_obj * rop, mpq_srcptr op);
Set rop
to op
in GF(p^k), where:
rop | is the GFpk value object receiving the result; and |
op | is the GMP rational to convert into GF(p^k) form. |
void (*set_var_power) (struct calib_GFpk_obj * rop, int power);
Set rop
to a**power
in GF(p^k) (a is the
GF(p^k) polynomial variable), where:
rop | is the GFpk value object receiving the result; and |
power | is the power to set (must be non-negative). |
void (*add) (struct calib_GFpk_obj * rop, const struct calib_GFpk_obj * op1, const struct calib_GFpk_obj * op2);
Set rop
to op1 + op2
in GF(p^k), where:
rop | is the GFpk value object receiving the result; |
op1 | is the first operand; and |
op2 | is the second operand. |
void (*sub) (struct calib_GFpk_obj * rop, const struct calib_GFpk_obj * op1, const struct calib_GFpk_obj * op2);
Set rop
to op1 - op2
in GF(p^k), where:
rop | is the GFpk value object receiving the result; |
op1 | is the first operand; and |
op2 | is the second operand. |
void (*neg) (struct calib_GFpk_obj * rop, mpz_srcptr op);
Set rop
to - op
in GF(p^k)
, where:
rop | is the GFpk value object receiving the result; and |
op | is the operand being negated. |
void (*mul) (struct calib_GFpk_obj * rop, const struct calib_GFpk_obj * op1, const struct calib_GFpk_obj * op2);
Set rop
to op1 * op2
in GF(p^k), where:
rop | is the GFpk value object receiving the result; |
op1 | is the first operand; and |
op2 | is the second operand. |
void (*mul_z) (struct calib_GFpk_obj * rop, const struct calib_GFpk_obj * op1, mpz_srcptr op2);
Set rop
to op1 * op2
in GF(p^k), where:
rop | is the GFpk value object receiving the result; |
op1 | is the first operand; and |
op2 | is the second operand (a single GMP integer). |
void (*mul_a) (struct calib_GFpk_obj * rop, const struct calib_GFpk_obj * op);
Set rop
to op * a
(mulitply by the generator polynomial
variable ’a’) in GF(p^k), where:
rop | is the GFpk value object receiving the result; |
op | is the operand being multiplied. |
void (*ipow) (struct calib_GFpk_obj * rop, const struct calib_GFpk_obj * op, int power);
Set rop
to op ** power
in GF(p^k), where:
rop | is the GFpk value object receiving the result; |
op | is the operand to exponentiate; and |
power | is the power to take (may be positive, negative or zero). |
void (*inv) (struct calib_GFpk_obj * rop, const struct calib_GFpk_obj * op);
Set rop
to the multiplicative inverse of op
in
GF(p^k), where:
rop | is the GFpk value object receiving the result; and |
op | is the operand to invert (must not be zero). |
void (*pth_root) (struct calib_GFpk_obj * rop, const struct calib_GFpk_obj * op);
Set rop
to the p-th root of op
in GF(p^k),
where:
rop | is the GFpk value object receiving the result; |
op | is the operand whose p-th root is computed. |
The p-th root of op is the element y in GF(p^k) such that y^p = op. This can be calculated as y = op^M, where M = p^(k-1).
void (*cvZa) (struct calib_GFpk_obj * rop, const struct calib_Za_obj * op);
Convert the given Za value op
into the corresponding element of
target GF(p^k) domain, storing the result in rop
, where:
rop | is the GFpk value object receiving the result; and |
op | is the element of Z(a) (array of GMP integers) to convert. |
It is intended that the generator polynomial defining Z(a) may be different from the generator polynomial defining GF(p^k).
int (*degree) (const struct calib_GFpk_obj * op);
Return the degree (in variable a of the GF(p^k)
generator polyomial) of the given element op
of
GF(p^k), where:
op | is the GFpk value object whose degree is to be returned. |
Note that the degree of a zero value is -1.
calib_bool (*zerop) (const struct calib_GFpk_obj * op);
Return 1 if-and-only-if the given GFpk value object is identically zero and 0 otherwise, where:
op | is the GFpk value object to test for zero. |
calib_bool (*onep) (const struct calib_GFpk_obj * op);
Return 1 if-and-only-if the given GFpk value object is identically 1 and 0 otherwise, where:
op | is the GFpk value object to test for one. |
void (*set_random) (struct calib_GFpk_obj * rop, struct calib_Random * randp);
Set rop
to be a random element of GF(p^k) using the
given random number generator, where:
rop | is the GFpk value to set to a randomized value; and |
randp | is the random number generator to use. |
void (*set_genrep) (struct calib_GFpk_obj * rop, struct calib_genrep * op, const char * var);
Given a genrep op
and the name var
of the GF(p^k)
generator polynomial variable (as it appears in op
), convert
this genrep into a value in this GF(p^k) domain, storing the
result in rop
, where:
rop | is the GFpk value receiving the result; |
op | is the genrep being converted; and |
var | is the name of the GF(p^k) generator polyomial variable
appearing within genrep op . |
struct calib_genrep * (*to_genrep) (const struct calib_GFpk_obj * op, const char * var);
Return a dynamically-allocated genrep representing the given GFpk
value op
, using the given variable name var
to represent
the variable of the GF(p^k) generator polynomial, where:
op | is the GFpk value object to convert; and |
var | is the name to use when representing the variable of the GF(p^k) generator polyomial within the genrep returned. |