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 substitute
 * 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:

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:

rat::set():

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

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

rat::set_si():

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

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

rat::set_z():

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

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

rat::set_q():

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

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

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:

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:

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:

rat::neg():

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

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

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:

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:

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:

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:

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:

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:

rat::canonicalize():

	void	(*canonicalize (struct calib_rat_obj *	op);

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

• All common factors between the numerator and denominator are removed,
• The leading coefficient of the denominator is positive,

where:

rat::factor():

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

Factor op, returning a list of factors, where:

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:

• j < 0: variable i must not appear in any of the subst_rat values being substituted;
• j >= 0: variable i in the subst_rat values maps to variable j of op and rop.

The parameters are as follows:

rat::free_slist():

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

Free the given list of rational substitutions, where:

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:

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:

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:

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:

rat::print():

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

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

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: