Next: , Previous: , Up: Top   [Contents][Index]


12 GFpkx — The Polynomial Ring GF(p^k)[x]

CALIB provides the GFpkx domain, representing the ring GF(p^k)[x], the univariate polynomials having coefficients that are in the Galois Field GF(p^k). The “values” of this domain are represented by the following object:

struct calib_GFpkx_obj {
	int	degree;		/* Degree of polynomial			*/
	int	size;		/* Size of coeff buffer (degree < size) */
	const struct calib_GFpkx_dom *
		dom;		/* Domain of polynomial			*/
	struct calib_GFpk_obj *
		coeff;		/* Coefficients of polynomial.          */
};

The following additional object is used to represent linked-lists of factors produced by various GFpkx factorization algorithms:

struct calib_GFpkx_factor {
	int				multiplicity;
	struct calib_GFpkx_obj *	factor;
	struct calib_GFpkx_factor *	next;
};

CALIB GFpkx domains are constructed by specifying a GFpk domain used to represent the coefficients of the corresponding GFpkx polynomials.

One may access CALIB’s GFpkx domain as follows:

	#include "calib/GFpkx.h"
	...
	struct calib_Zpx_obj *		gpoly;
	struct calib_GFpk_dom *		GFpk;
        struct calib_GFpkx_dom *	GFpkx;
	struct calib_GFpkx_obj		poly1, poly2;
	...
	gpoly = /* Make generator polynomial in Zp[x]. */
	GFpk  = calib_make_GFpk_dom (gpoly);
	GFpkx = calib_make_GFpkx_dom (GFpk);
	...
	GFpkx -> init (&poly1);
	GFpkx -> init (&poly2);
	...
	GFpkx -> mul (GFpkx, &poly1, &poly1, &poly2);
	...
	GFpkx -> clear (&poly2);
	GFpkx -> clear (&poly1);
	calib_free_GFpkx_dom (GFpkx);
	calib_free_GFPk_dom (GFpk);
	...

The struct calib_GFpkx_dom object contains the following members (pointers to functions) that provide operations of the domain:

GFpkx::init():

	void	(*init) (const struct calib_GFpkx_dom *	K_of_x,
			 struct calib_GFpkx_obj *	x);

Initialize the given GFpkx polynomial x, where:

K_of_xis the GFpkx ring/domain the polynomial belongs to; and
xis the polynomial to initialize.

GFpkx::init_degree():

	void	(*init_degree)
			 (const struct calib_GFpkx_dom *	K_of_x,
			  struct calib_GFpkx_obj *		x,
			  int					degree);

Initialize the given GFpkx polynomial x (while assuring that internal buffers are sufficiently large to hold a polynomial of up to the given degree without further allocation), where:

K_of_xis the GFpkx ring/domain the polynomial belongs to;
xis the polynomial to initialize; and
degreeis the guaranteed minimimum degree polynomial that x will be able to hold (without further buffer allocation) upon successful completion of this operation.

GFpkx::alloc():

	void	(*alloc) (struct calib_GFpkx_obj *		rop,
			  int					degree);

Force the given (already initialized) polynomial rop to have buffer space sufficient to hold a polynomial of at least the given degree, where:

ropis the polynomial whose allocation is to be adjusted; and
degreeis the guaranteed minimum degree polynomial that rop will be able to hold (without further buffer allocation) upon successful completion of this operation.

GFpkx::clear():

	void	(*clear) (struct calib_GFpkx_obj *	x);

Clear out the given polynomial x (freeing all memory it might hold and returning it to the constant value of zero), where:

xis the polynomial to be cleared.

GFpkx::set():

	void	(*set) (struct calib_GFpkx_obj *	rop,
			const struct calib_GFpkx_obj *	op);

Set rop to op in GFpkx, where:

ropis the polynomial receiving the result;
ropis the polynomial to copy.

GFpkx::set_si():

	void	(*set_si) (struct calib_GFpkx_obj *		rop,
			   calib_si_t				op);

Set rop to op in GFpkx, where:

ropis the polynomial receiving the result;
opis the integer value to set.

GFpkx::set_z():

	void	(*set_z) (struct calib_GFpkx_obj *		rop,
			  mpz_srcptr				op);

Set rop to op in GFpkx, where:

ropis the polynomial receiving the result;
opis the GMP integer value to set.

GFpkx::set_q():

	void	(*set_q) (struct calib_GFpkx_obj *		rop,
			  mpq_srcptr				op);

Set rop to op in GFpkx, where:

ropis the polynomial receiving the result;
opis the GMP rational value to set.

GFpkx::set_var_power():

	void	(*set_var_power)
			 (struct calib_GFpkx_obj *		rop,
			  int					power);

Set rop to x ** power in GFpkx, where:

ropis the Zpx polynomial receiving the result;
poweris the power to set (must be non-negative).

GFpkx::add():

	void	(*add) (struct calib_GFpkx_obj *	rop,
			const struct calib_GFpkx_obj *	op1,
			const struct calib_GFpkx_obj *	op2);

Set rop to op1 + op2 in GFpkx, where:

ropis the polynomial receiving the result;
op1is the first operand; and
op2is the second operand.

GFpkx::sub():

	void	(*sub) (struct calib_GFpkx_obj *	rop,
			const struct calib_GFpkx_obj *	op1,
			const struct calib_GFpkx_obj *	op2);

Set rop to op1 - op2 in GFpkx, where:

ropis the polynomial receiving the result;
op1is the first operand; and
op2is the second operand.

GFpkx::neg():

	void	(*neg) (struct calib_GFpkx_obj *	rop,
			const struct calib_GFpkx_obj *	op);

Set rop to - op in GFpkx, where:

ropis the GFpkx polynomial receiving the result; and
opis the GFpkx polynomial being negated.

GFpkx::mul():

	void	(*mul) (struct calib_GFpkx_obj *	rop,
			const struct calib_GFpkx_obj *	op1,
			const struct calib_GFpkx_obj *	op2);

Set rop to op1 * op2 in GFpkx, where:

ropis the polynomial receiving the result;
op1is the first operand; and
op2is the second operand.

GFpkx::mul_z():

	void	(*mul_z) (struct calib_GFpkx_obj *		rop,
			  const struct calib_GFpkx_obj *	op1,
			  mpz_srcptr				op2);

Set rop to op1 * op2 in GFpkx, where:

ropis the polynomial receiving the result;
op1is the first (polynomial) operand; and
op2is the second (GMP integer) operand.

GFpkx::ipow():

	void	(*ipow) (struct calib_GFpkx_obj *	rop,
			 const struct calib_GFpkx_obj *	op,
			 int				power);

Set rop to op ** power in GFpkx, where:

ropis the polynomial receiving the result;
opis the polynomial to exponentiate; and
poweris the power to take (must be >= 0).

GFpkx::dup():

	struct calib_GFpkx_obj *
		(*dup) (const struct calib_GFpkx_obj *	op);

Return a dynamically-allocated GFpkx polynomial that is a copy of op, where:

opis the polynomial to be duplicated.

GFpkx::free():

	void	(*free) (struct calib_GFpkx_obj *	poly);

Free the given dynamically-allocated polynomial poly, where:

polyis the polynomial to be freed.

This is equivalent to performing GFpkx -> clear (poly);, followed by free (poly);.

GFpkx::eval():

	void	(*eval) (struct calib_GFpk_obj *	rop,
			 const struct calib_GFpkx_obj *	poly,
			 const struct calib_GFpk_obj *	value);

Evaluate polynomial poly at the given value, storing the result in rop, where:

ropis the GFpk value object receiving the result;
opis the polynomial to be evaluated; and
valueis the GFpk value at which to evaluate the polynomial.

GFpkx::div():

	void	(*div) (struct calib_GFpkx_obj *	quotient,
			struct calib_GFpkx_obj *	remainder,
			const struct calib_GFpkx_obj *	a,
			const struct calib_GFpkx_obj *	b);

Polynomial division in GF(p^k)[x], where:

quotientreceives the quotient polynomial (may be NULL);
remainderreceives the remainder polynomial (may be NULL);
ais the dividend polynomial; and
bis the divisor polynomial (may not be zero).

Division in GF(p^k)[x] has the following properties:

GFpkx::gcd():

	void	(*gcd) (struct calib_GFpkx_obj *	gcd,
			const struct calib_GFpkx_obj *	a,
			const struct calib_GFpkx_obj *	b);

Compute the greatest common divisor (GCD) of a and b, storing the result in gcd, where:

gcdreceives the resulting GCD polynomial (always monic);
ais the first operand polynomial; and
bis the second operand polynomial.

The GCD is always monic unless a = b = 0.

GFpkx::extgcd():

	void	(*extgcd) (struct calib_GFpkx_obj *		gcd,
			   struct calib_GFpkx_obj *		xa,
			   struct calib_GFpkx_obj *		xb,
			   const struct calib_GFpkx_obj *	a,
			   const struct calib_GFpkx_obj *	b);

The extended Euclidean algorithm. Compute polynomials gcd, xa and xb such that gcd = a * xa + b * xb, where:

K_of_xis the GFpkx ring/domain performing this operation;
gcdreceives the resulting GCD polynomial (always monic);
xareceives the multiplier polynomial for a;
xbreceives the multiplier polynomial for b;
ais the first operand polynomial; and
bis the second operand polynomial.

The result satisfies the following properties:

  1. degree(xa) < degree(b)
  2. degree(xb) < degree(a)

GFpkx::cvZax():

	struct calib_GFpkx_obj *
		(*cvZax) (const struct calib_GFpkx_dom *	K_of_x,
			  const struct calib_Zax_obj *		op);

Return a dynamically-allocated GFpkx polynomial that is copied from the given Zax polynomial op, where:

K_of_xis the destination GFpkx ring/domain;
polyis the Zax polynomial to be copied into GFpkx form.

Note: this function requires that K_of_x and the Zax domain of op have the same generator polynomial — it is a fatal error if they do not.

GFpkx::factor():

	struct calib_GFpkx_factor *
		(*factor) (const struct calib_GFpkx_obj *	poly);

Factor the given polynomial poly into its irreducible factors, returning a linked list of these factors, where:

polyis the GFpkx polynomial to be factored.

Except for an optional leading constant factor, all other factors are monic and irreducible.

GFpkx::free_factors():

	void	(*free_factors)
			(struct calib_GFpkx_factor *	factors);

Free up the given list of GFpkx factors, where:

factorsis a linked-list factors to be freed.

GFpkx::set_random():

	void	(*set_random) (struct calib_GFpkx_obj *		rop,
			       int				d,
			       struct calib_Random *		randp);

Set rop to be a randomly chosen GFpkx polynomial of degree d, using random numbers from randp, where:

ropreceives the GFpkx polynomial result;
dis the degree of polynomial to generate; and
randpis the random number generator to use.

GFpkx::zerop():

	calib_bool
		(*zerop) (const struct calib_GFpkx_obj *	op);

Return 1 if-and-only-if the given GFpkx polynomial is identically zero and 0 otherwise, where:

opis the GFpkx polynomial to test for zero.

GFpkx::onep():

	calib_bool
		(*onep) (const struct calib_GFpkx_obj *		op);

Return 1 if-and-only-if the given GFpkx polynomial is identically one and 0 otherwise, where:

opis the GFpkx polynomial to test for one.

GFpkx::set_genrep():

	void	(*set_genrep) (struct calib_GFpkx_obj *		rop,
			       const struct calib_genrep *	op,
			       const char *			xvar,
			       const char *			avar);

Compute a GFpkx polynomial obtained from the given genrep op, interpreting xvar to be the name of the variable used by the GFpkx polynomial and avar to be the name of the variable used by the GFpk coefficients, storing the result in rop, where:

ropreceives the GFpkx polynomial result;
opis the genrep to convert into GFpkx polynomial form;
xvaris the variable name (appearing within genrep op) that is to be interpreted as the polynomial variable in GFpkx; and
avaris the variable name (appearing within genrep op) that is to be interpreted as the variable used by the GFpk coefficients.

GFpkx::to_genrep():

	struct calib_genrep *
		(*to_genrep) (const struct calib_GFpkx_obj *	op,
			      const char *			xvar,
			      const char *			avar);

Return a dynamically-allocated genrep corresponding to the given GFpkx polynomial op, using xvar as the name of the GFpkx polynomial variable and avar as the name of the GFpk coefficient variable within the returned genrep, where:

opis the GFpkx polynomial to convert into genrep form;
xvaris the variable name to use in the genrep for the polynomial variable of GFpkx; and
avaris the variable name to use in the genrep for the GFpk coefficients.

GFpkx::factors_to_genrep():

	struct calib_genrep *
		(*factors_to_genrep)
			(const struct calib_GFpkx_factor *	factors,
			 const char *				xvar,
			 const char *				avar);

Return a dynamically-allocated genrep corresponding to the given list of GFpkx factors, using xvar as the name of the GFpkx polynomial variable and avar as the name of the GFpk coefficient variable within the returned genrep, where:

factorsis the list of GFpkx polynomial factors to convert into genrep form; and
xvaris the variable name to use in the genrep for the polynomial variable of GFpkx;
avaris the variable name to use in the genrep for the GFpk coefficients.

Next: , Previous: , Up: Top   [Contents][Index]