Documentation for programmers

From Palp
Jump to: navigation, search

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.




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

mori.x -fM

The combination of the options '-f' and '-M' of mori.x does not work. Apparently the function 'ReadInt' creates the problem (it tries to read from 'inFILE' which is NULL if '-f' is set).

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

Tracking polytope analysis

PALP performs surprisingly well even in the analysis of polytopes of rather many dimensions. As the standard problem of finding the equations of a polytope given in terms of its vertices may take a long time (something like several days for a 20-dimensional polytope), it may be desirable to generate output that tracks the program's progress. This can be effected by turning on the precompiler-parameter SHOW_NEW_CEq at the beginning of the file Vertex.c.

Personal tools