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.

Contents

Changes from palp-2.11 to palp-2.20

Note that there exists an inofficial version 2.12 which is mainly like 2.20 but has a different GNUmakefile that allows to choose names for the executables that are different from the usual ones that end with ".x". (In that version it is possible to have that suffix, or a prefix of "palp_" or both or none of them.) Since most packagers seem to have their own methods of creating alternative names if desired, this feature was discarded again for palp-2.20, but any self-references referring to the ".x"-names (e.g. in help-screens etc.) were eliminated or replaced by references to the name by which a user called the program.

Furthermore, palp-2.20 was called palp-2.2 until I (HS) was informed that according to standard practice 2.2 would be considered previous to 2.11.

class.c: Error message upon using HFlag with wrong POLY_Dmax: moved to the first occurrence of Hflag. This fixes a bug (introduced in palp-2.0) that led to unwanted calls of "Do_the_Classification" (usually resulting in error messages).

cws.c: new routines implementing the option -m which leads to a fast identification of transverse weight systems in a given degree range.

LG.c: Two modifications (additions) in Write_WH (inspired by 1711.09698):

      if(_P->n > 5){
	for (j=2; 2*j <= _P->n-1; j++){
	  fprintf(outFILE,";%d",_VH->h[j][j]);
	  for(i=j+1;i<_P->n-j;i++) fprintf(outFILE,",%d",_VH->h[j][i]);}}

(output of LG-"Hodge"-numbers beyond V[1][i]), and

     if(_P->n==6) chi=24*(ho[1]-ho[2]+ho[3]-ho[4]);

(computing the Euler characteristic for CY 5-folds).

LG.c: Beginning of "void LGO_VaHo(Weight *W,VaHo *V)" modified (see code for explanations), so that the following example from sec. 4.1 of the first PALP-paper works again:

echo "6521466 1805 1806 151662 931638 2173822 3260733" | poly.x -lf

This points to a bug introduced in palp-1.1 which is still there, e.g. upon

echo "6521466 1805 1806 151662 931638 2173822 3260733" | poly.x -Lf

LG.h:

typedef struct {int D,E,sts; int h[POLY_Dmax][POLY_Dmax];} 	VaHo;

(larger range to avoid going out, previous error pointed out by Friedrich Schoeller).

MoriCone.c: End of HyperSurfDivisorsQ modified: some senseless stuff eliminated ("if (0) { ... }"); "Subdivide" is called only if necessary, which allows functionalities that don't require triangulation to work in those cases in which triangulation is not possible.

MoriCone.c: In order to allow the use of "FilterFlag" (option "-f") together with the option "-M", "TriList_to_MoriList" is modified in the following manner: added "if (_Flag->FilterFlag) inFILE = stdin;" at the beginning and "if (_Flag->FilterFlag) inFILE = NULL;" at the end; prompts for input are made subject to "if (!_Flag->FilterFlag)".

Subadd.c: various changes to avoid going out of ranges of arrays (pointed out, again, by Friedrich Schoeller).

Subdb.c: Fix for h11=491-Problem (a bug pointed out by Mike Stillman):

  else if (H1||H2) {HM_from=0; HM_to=max(H1,H2);}

modified to

  else if (H1||H2) {HM_to=max(H1,H2); HM_from=max(0,HM_to-Hod_Dif_max);}

Vertex.c: Modified structure of Complete_Poly (inverse matrix computation pulled out), the Hodge number computations are slightly modified (routines RaiseDip and RaiseNip pulled out), and the new quick routines (cf. option -q in poly.x) from Qadd_for_completion to QuickAnalysis are added.

Most .c-files: Line breaks to get rid of compiler remarks about misleading indentations.

Changes from palp-2.1 to palp-2.11

Following suggestions by J. Puydt:

Removed the meaningless line

int nr_SR_elements;

from Mori.h.

Replaced "printf(ctime(&_NFL->TIME));" by "fputs(ctime(&_NFL->TIME),stdout);" at several points in Subadd.c and Subdb.c.

Global.h: declaration of POLY_Dmax subject to #ifndef POLY_Dmax.

Following suggestions by M. Orlitzky:

New GNUmakefile: Instead of

CC=gcc

CFLAGS=-O3 -g -W -Wall -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE

we now have

CC ?= gcc

CPPFLAGS += -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE
CFLAGS ?= -O3 -g -W -Wall

so that the user's own settings are (also) respected. CPPFLAGS and LDFLAGS are included in the compilation, e.g.

	$(CC) $(CFLAGS) -o poly.x poly.o $(OBJECTS) LG.o

is replaced by

	$(CC) $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) -o poly.x poly.o $(OBJECTS) LG.o

Bugs/Problems

Aux_Make_Poly_NF

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
Namespaces

Variants
Actions
Navigation
Tools