Documentation for programmers

Revision as of 16:49, 15 May 2012

Currently the only reasonably well documented file in the package is the global header file Global.h which lists global type definitions and routines, including all the routines called by the original version of poly.x. The ideal of documenting everything (including the code) seems utterly unattainable and even the more modest goal of supplying good descriptions of all the structures and routines occurring in all header files is probably beyond what can be achieved. Perhaps it will be possible to provide clear documentation at least for the routines called by the new ('-x') options of poly.x and for the essential routines of the 'nef'-part of the package as listed in Nef.h. As the most important header files correspond to applications (Subpoly.h to class.x, Nef.h to nef.x and Global.h to poly.x) we will include their discussion in the respective documentation pages. Two minor files LG.h and Rat.h are described briefly at the end of the last section of the paper.

Bugs/Problems

One of the core routines in Polynf.c is 'Aux_Make_Poly_NF', which (apparently) converts a matrix into upper triangular form; 'Aux_Make_Poly_NF' is the routine called by 'Make_Poly_UTriang' which is listed in Global.h. It seems that Max wrote two distinct routines

int  GLZ_Make_Trian_NF(Long X[][VERT_Nmax], int *n, int *nv,
		       GL_Long G[POLY_Dmax][POLY_Dmax]);    /* current=best */

int  SL2Z_Make_Poly_NF(Long X[][VERT_Nmax], int *n, int *nv,
		       SL_Long S[POLY_Dmax][POLY_Dmax]);    /* previous=bad */

with that functionality; 'Aux_Make_Poly_NF' in the present version just calls 'GLZ_Make_Trian_NF' and compares it to the older 'SL2Z_Make_Poly_NF' if a corresponding precompiler option 'TEST_GLZ_VS_SL' is set (which it is not, by default). While trying to separate computation and output for the '-T' option of poly.x, I (HS) encountered serious problems that I could eventually trace to 'Aux_Make_Poly_NF' by turning on the comparison. In this case it appears that the older 'SL2Z_Make_Poly_NF' gives the correct result and the newer 'GLZ_Make_Trian_NF' is wrong. The problems occurred for cases where the matrix was square rather than rectangular with more columns than lines; it is to be hoped that otherwise computations are correct. In the present case I solved the problem by introducing a function 'SL2Z_Aux_Make_Poly_NF' (which, of course, calls 'SL2Z_Make_Poly_NF') and using it in the place of 'Aux_Make_Poly_NF'. If similar troubles occur again, a good strategy would be to first turn on 'TEST_GLZ_VS_SL'.