Documentation for programmers

Revision as of 20:37, 16 May 2012

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. 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'.

Advanced option tuning for mori.x

The pre-compiler command 'TRACE_TRIANGULATION' in the C file 'MoriCone.c' enables diagnostic information about the triangulation. This data might be of use for the motivated programmer who wants to extend the subdivision algorithm.

The C file 'SingularInput.c' is the interface to SINGULAR. The input for SINGULAR can be displayed in the standard output of 'mori.x' by turning on the pre-compiler definition 'TEST_PRINT_SINGULAR\_IO' in 'SingularInput.c'. Furthermore, the output format of options '-i' and '-t' can be partially modified according to the user's needs. The letters denoting the toric divisor classes (set to `d' by default in option '-t') as well as that denoting the basis of divisor classes (set to `J' by default in option '-i') can be substituted by changing the pre-compiler commands 'T_DIV' and 'DIVclassBase'. The pre-compiler command 'DijkEQ' controls the symbol `->' in option '-t'.