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


13 Za — The Ring Z(a)

CALIB provides the Za domain, representing the ring Z(a), the extension of the integers with given algebraic integer a (specified via a monic irreducible polynomial in Z[x] of degree at least two). The “values” of this domain are represented by the following object:

struct calib_Za_obj {
	const struct calib_Za_dom *
		dom;		/* Z(a) domain containing this value	*/
	mpz_ptr	coeff;		/* Coefficients.  This is an array of	*/
				/* k integers.				*/
};

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 Za domain is constructed by specifying a monic, irreducible “generator” polynomial of degree k in Z[x]. One may access CALIB’s Za domain as follows:

	#include "calib/Za.h"
	...
	struct calib_Zx_obj *	apoly;
	struct calib_Za_dom *	Za;

	apoly = /* monic, irreducible polynomial defining 'a'. */

	Za = calib_make_Za_dom (apoly);
	...
	calib_free_Za_dom (Za);

Let k be the degree of the monic polynomial defining the algebraic integer a. The “values” of this Za domain are polynomials in Z[a] having degree at most k-1.

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

Za::init():

	void	(*init) (const struct calib_Za_dom *	rp,
			 struct calib_Z_obj *		x);

Initialize Za value object x to be a member of the Za domain rp, where:

rpis the Za ring/domain performing this operation; and
xis the Za value object to be initialized.

Za::clear():

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

Clear out the given Za value object x (freeing all memory it might hold), where:

xis the Za value object to be cleared.

Za::set():

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

Set rop to op in Za, where:

ropis the destination Z(a) value; and
opis the source Z(a) value.

Za::set_si():

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

Set rop to op in Za, where:

ropis the destination Z(a) value; and
opis the source integer value.

Za::set_z():

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

Set rop to op in Za, where:

ropis the destination Z(a) value; and
opis the source GMP integer value.

Za::set_q():

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

Set rop to op in Za, where:

rpis the Za ring/domain performing this operation;
ropis the destination Z(a) value; and
opis the source GMP integer value.

The denominator of op must be 1.

Za::set_var_power():

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

Set rop to a ** power in Za, where:

ropis the destination Z(a) value; and
poweris the power to set (must be non-negative).

Za::add():

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

Set rop to op1 + op2 in Za, where:

ropis the destination Z(a) value;
ais the first operand; and
bis the second operand.

Za::sub():

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

Set rop to op1 - op2 in Za, where:

ropis the destination Z(a) value;
op1is the first operand; and
op2is the second operand.

Za::neg():

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

Set rop to - op in Za, where:

ropis the destination Z(a) value; and
opis the operand to be negated.

Za::mul():

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

Set rop to op1 * op2 in Za, where:

ropis the destination Z(a) value;
op1is the first operand; and
op2is the second operand.

Za::mul_z():

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

Set rop to op1 * op2 in Za, where:

ropis the destination Z(a) value;
op1is the first operand; and
op2is the second operand.

Za::mul_a():

	void	(*mul_a) (struct calib_Za_obj *		rop,
			  const struct calib_Za_obj *	op);

Set rop to op * a (multiply by algebraic integer a), where:

ropis the destination Z(a) value; and
opis the source operand being multiplied.

Za::ipow():

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

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

ropis the destination Z(a) value;
opis the operand to exponentiate; and
poweris the power to take (must be >= 0).

Za::pinv():

	void	(*pinv) (struct calib_Za_obj *		rop,
			 mpz_ptr			d,
			 const struct calib_Za_obj *	op);

Pseudo-inverse in Z(a). Compute rop in Z(a) and d in Z such that rop * op = d, where:

ropis the destination Z(a) value;
dis a single GMP integer receiving the value d; and
opis the source operand to pseudo-invert.

Za::div_z_exact():

	void	(*div_z_exact)
			(struct calib_Za_obj *		rop,
			 const struct calib_Za_obj *	op1,
			 mpz_srcptr			op2);

Set rop to op1 / op2 in Za, where:

ropis the destination Z(a) value;
op1is the first operand; and
op2is the second operand.

The division must be exact.

Za::prim_part():

	void	(*prim_part) (mpz_ptr				content,
			      struct calib_Za_obj *		ppart,
			      const struct calib_Za_obj *	op);

Compute content and primitive part of op in Z(a), storing them in content and ppart, respectively, where:

contentreceives the content of op;
ppartis the Z(a) value object receiving the primitive part of op; and
opis the operand for which to compute the content and primitive part.

Za::cvZa():

	void	(*cvZa) (struct calib_Za_obj *		rop,
			 const struct calib_Za_obj *	op);

Set rop to op. Note that rop and op are permitted to belong to different Za domains, and this routine performs the necessary conversion, where:

ropis the destination Z(a) value; and
opis the source Z(a) value to convert.

Za::degree():

	int	(*degree) (const struct calib_Za_obj *	op);

Return the degree (in a) of the given Z(a) value op, where:

opis the operand for which to get the degree.

Note that the degree of a zero value is -1.

Za::zerop():

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

Return 1 if-and-only-if op is identically zero and 0 otherwise, where:

opis the operand to test for zero.

Za::onep():

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

Return 1 if-and-only-if op is identically one and 0 otherwise, where:

opis the operand to test for one.

Za::set_genrep():

	void	(*set_genrep) (struct calib_Za_obj *		rop,
			       const struct calib_genrep *	op,
			       const char *			var);

Given a genrep op and the name var of the algebraic integer a, convert this genrep into a value in this Z(a) domain, storing the result in rop, where:

ropis the Z(a) value object receiving value;
opis the genrep being converted; and
varis the name of the algebraic integer a appearing within genrep op.

Za::to_genrep():

	struct calib_genrep *
		(*to_genrep) (const struct calib_Za_obj *	op,
			      const char *			var);

Return a dynamically-allocated genrep representing the given value op of the given Z(a) domain, using the given variable name var to represent the algebraic integer a, where:

opis value from Z(a) being converted to genrep form; and
varis the name of the algebraic integer a as it should appear within the genrep returned.

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