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:
void (*init) (const struct calib_rat_dom * dom, struct calib_rat_obj * x);
Initialize the given rat object x
, where:
R_of_x | is the rat field/domain performing this operation; |
x | is the rational object to initialize. |
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:
x | is the rational object to be cleared. |
void (*set) (struct calib_rat_obj * rop, const struct calib_rat_obj * op);
Set rop
to op
in the “rat” domain, where:
rop | is the rational function receiving the result; and |
op | is the rational function to copy. |
void (*set_si) (struct calib_rat_obj * rop, calib_si_t op);
Set rop
to op
in the “rat” domain, where:
rop | is the rational function receiving the result; and |
op | is the integer value to set. |
void (*set_z) (struct calib_rat_obj * rop, mpz_srcptr op);
Set rop
to op
in the “rat” domain, where:
rop | is the rational function receiving the result; and |
op | is the GMP integer value to set. |
void (*set_q) (struct calib_rat_obj * rop, mpq_srcptr op);
Set rop
to op
in the “rat” domain, where:
rop | is the rational function receiving the result; and |
op | is the GMP rational value to set. |
void (*set_var_power) (struct calib_rat_obj * rop, int var, int power);
Set rop
to var ** power
in the “rat” domain, where:
rop | is the rational function receiving the result; |
var | is the index of the variable; and |
power | is the power to set (may be positive, zero or negative). |
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:
rop | is the rational function receiving the result; |
op1 | is the first operand; and |
op2 | is the second operand. |
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:
rop | is the rational function receiving the result; |
op1 | is the first operand; and |
op2 | is the second operand. |
void (*neg) (struct calib_rat_obj * rop, const struct calib_rat_obj * op);
Set rop
to - op
in the “rat” domain, where:
rop | is the rational function receiving the result; |
op | is the operand to negate. |
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:
rop | is the rational function receiving the result; |
op1 | is the first operand; and |
op2 | is the second operand. |
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:
rop | is the rational function receiving the result; |
op1 | is the first (rational function) operand; and |
op2 | is the second (GMP integer) operand. |
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:
rop | is the rational function receiving the result; |
op1 | is the first (rational function) operand; and |
op2 | is the second (GMP rational) operand. |
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:
rop | is the rational function receiving the result; |
op | is the rational function to exponentiate; and |
power | is the power to take (may be positive, zero or negative). |
void (*inv) (struct calib_rat_obj * rop, const struct calib_rat_obj * op);
Set rop
to 1 / op
in the “rat” domain, where:
rop | is the rational function receiving the result; |
op | is the operand to invert. |
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:
rop | is the rational function receiving the result; |
op1 | is the first operand; and |
op2 | is the second operand. |
void (*canonicalize (struct calib_rat_obj * op);
Modify (if necessary) the given rational object to be in “canonical” form:
where:
op | is the rational object to be canonicalized. |
struct calib_Zxyz_factor * (*factor (const struct calib_rat_obj * op);
Factor op
, returning a list of factors, where:
op | is 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:
op
and rop
.
The parameters are as follows:
rop | receives the substitution result; |
op | is the rational object to which the substitutions are to be applied; |
varmap | defines variable transformations between the subst_rat
expressions and the op and rop rings as described
above; and |
slist | is the list of substitutions to perform. |
void (*free_slist) (struct calib_subst_list * slist);
Free the given list of rational substitutions, where:
slist | defines an array of rational substitutions to free. |
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:
op | is the rational function to test for zero. |
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:
op | is the rational function to test for one. |
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:
rop | receives the resulting rational function; and |
op | is the genrep to convert into rational function form. |
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:
op | is the rational function to convert into genrep form. |
void (*print) (const struct calib_rat_obj * op);
Print the given rational expression (in Maxima input syntax) terminated with a newline, where:
opt | is the rational expression to be printed. |
void (*print_nnl) (const struct calib_rat_obj * op);
Print the given rational expression (in Maxima input syntax) with no terminating newline, where:
opt | is the rational expression to be printed. |