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


17 rat — The Rational Functions Z[x,y,z] / Z[x,y,z]

CALIB provides to rat domain, representing the quotient field R / R — the rational functions — where R is the ring of multi-variate polynomials with integer coefficients.

The “values” of this domain are represented by the following object:

struct calib_rat_obj {
	const struct calib_rat_dom *
				dom;	/* Rational function domain */
	struct calib_Zxyz_obj	numer;	/* Numerator polynomial */
	struct calib_Zxyz_obj	denom;	/* Denominator polynomial */
};

The CALIB rat domain is constructed by specifying a Zxyz domain to represent the numerator and denominator of the corresponding rational functions.

The calib/rat.h header defines the following additional objects:

/*
 * An object to represent a set of variable substitutions,
 * each variable being replaced with a given rational expression.
 */

struct calib_subst_list {
	int			num_subst;	/* Number of substitutions */
	struct calib_rsubst *	subst;		/* Array of substitutions */
};

/*
 * An object to represent a rational expression to substitutions.
 * for a given variable.
 * In order to accomodate variables that are not part of the polynomial
 * domain of `val', the `varname' field can be the name of an arbitrary
 * variable.  Convention:
 *
 *	((var >=  0) AND (varname EQ NULL)) OR
 *	((var EQ -1) AND (varname NE NULL))
 */

struct calib_rsubst {
	int			var;	/* Variable number to be substituted */
					/* (or -1) */
	const char *		varname;
					/* Variable name (or NULL) */
	struct calib_rat_obj	val;	/* Rational value to replace */
					/* var with */
};

One may access CALIB’s rat domain as follows:

	#include "calib/rat.h"
	#include "calib/Zxyz.h"
	...
        const struct calib_Zxyz_dom *	Zxyz;
	const struct calib_rat_dom *	rat;
	struct calib_rat_obj		ratvar;
	const char *			varnames [3] = {"x", "y", "z"};
	...
	Zxyz	= calib_make_Zxyz_dom (3, varnames);
	rat	= calib_make_rat_dom (Zxyz);
	...
	rat -> init (rat, &ratvar);
	...
	rat -> canonicalize (&ratvar);
	...
	rat -> print (&ratvar);
	...
	rat -> clear (&ratvar);
	...
	calib_free_rat_dom (rat);
	calib_free_Zxyz_dom (Zxyz);

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

rat::init():

	void	(*init) (const struct calib_rat_dom *	dom,
			 struct calib_rat_obj *		x);

Initialize the given rat object x, where:

R_of_xis the rat field/domain performing this operation;
xis the rational object to initialize.

rat::clear():

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

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

xis the rational object to be cleared.

rat::set():

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

Set rop to op in the “rat” domain, where:

ropis the rational function receiving the result; and
opis the rational function to copy.

rat::set_si():

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

Set rop to op in the “rat” domain, where:

ropis the rational function receiving the result; and
opis the integer value to set.

rat::set_z():

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

Set rop to op in the “rat” domain, where:

ropis the rational function receiving the result; and
opis the GMP integer value to set.

rat::set_q():

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

Set rop to op in the “rat” domain, where:

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

rat::set_var_power():

	void	(*set_var_power)
			 (struct calib_rat_obj *	rop,
			  int				var,
			  int				power);

Set rop to var ** power in the “rat” domain, where:

ropis the rational function receiving the result;
varis the index of the variable; and
poweris the power to set (may be positive, zero or negative).

rat::add():

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

Set rop to op1 + op2 in the “rat” domain, where:

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

rat::sub():

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

Set rop to op1 - op2 in the “rat” domain, where:

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

rat::neg():

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

Set rop to - op in the “rat” domain, where:

ropis the rational function receiving the result;
opis the operand to negate.

rat::mul():

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

Set rop to op1 * op2 in the “rat” domain, where:

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

rat::mul_z():

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

Set rop to op1 * op2 in the “rat” domain, where:

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

rat::mul_q():

	void	(*mul_q) (struct calib_rat_obj *	rop,
			  const struct calib_rat_obj *	op1,
			  mpq_srcptr			op2);

Set rop to op1 * op2 in the “rat” domain, where:

ropis the rational function receiving the result;
op1is the first (rational function) operand; and
op2is the second (GMP rational) operand.

rat::ipow():

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

Set rop to op ** power in the “rat” domain, where:

ropis the rational function receiving the result;
opis the rational function to exponentiate; and
poweris the power to take (may be positive, zero or negative).

rat::inv():

	void	(*inv) (struct calib_rat_obj *		rop,
			const struct calib_rat_obj *	op);

Set rop to 1 / op in the “rat” domain, where:

ropis the rational function receiving the result;
opis the operand to invert.

rat::div():

	void	(*div) (struct calib_rat_obj *		rop,
			const struct calib_rat_obj *	op1,
			const struct calib_rat_obj *	op2);

Set rop to op1 / op2 in the “rat” domain, where:

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

rat::canonicalize():

	void	(*canonicalize (struct calib_rat_obj *	op);

Modify (if necessary) the given rational object to be in “canonical” form:

where:

opis the rational object to be canonicalized.

rat::factor():

	struct calib_Zxyz_factor *
		(*factor (const struct calib_rat_obj *	op);

Factor op, returning a list of factors, where:

opis the rational object to be factored.

Note: This returns a list of struct calib_Zxyz_factor objects for which the denominator’s factors have negative multiplicies. The Zxyz::factors_to_genrep routine properly handles such negative multiplicities.

rat::substitute_with_varmap():

	void	(*substitute_with_varmap)
			(struct calib_rat_obj *		rop,
			 const struct calib_rat_obj *	op,
			 const int *			varmap,
			 struct calib_subst_list *	slist);

Efficiently perform a set slist of variable substitutions (struct calib_rsubst objects) each having the form:

			var = subst_rat

to the given rational expression op, storing the result into rop. The subst_rat values are first transformed from one Zxyz ring to another according to the given varmap — an array indexed by variables appearing in the subst_rat values being substituted. Let j = varmap[i]. There are two cases:

The parameters are as follows:

ropreceives the substitution result;
opis the rational object to which the substitutions are to be applied;
varmapdefines variable transformations between the subst_rat expressions and the op and rop rings as described above; and
slistis the list of substitutions to perform.

rat::free_slist():

	void	(*free_slist) (struct calib_subst_list *	slist);

Free the given list of rational substitutions, where:

slistdefines an array of rational substitutions to free.

rat::zerop():

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

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

opis the rational function to test for zero.

rat::onep():

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

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

opis the rational function to test for one.

rat::set_genrep():

	void	(*set_genrep) (struct calib_rat_obj *		rop,
			       const struct calib_genrep *	op);

Compute a rational function obtained from the given genrep op, storing the result in rop. Use the domain of rop to map variable names in op to variable numbers in the resulting rational function, where:

ropreceives the resulting rational function; and
opis the genrep to convert into rational function form.

rat::to_genrep():

	struct calib_genrep *
		(*to_genrep) (const struct calib_rat_obj *	op);

Return a dynamically-allocated genrep corresponding to the given rational function op (whose rat domain provides variable names to use for each variable number), where:

opis the rational function to convert into genrep form.

rat::print():

	void	(*print) (const struct calib_rat_obj *	op);

Print the given rational expression (in Maxima input syntax) terminated with a newline, where:

optis the rational expression to be printed.

rat::print_nnl():

	void	(*print_nnl) (const struct calib_rat_obj *	op);

Print the given rational expression (in Maxima input syntax) with no terminating newline, where:

optis the rational expression to be printed.

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