
\chapter{Configuration variables}
\label{configuration}

After downloading and un-taring the tar-file of the package,
the file \texttt{src/caliconfig.h} contains configuration variables
that you should customize according to your needs.
After modification, recompilation is required:
see~\ref{howchanges}
If you modify the value of any of them, reflect this change 
in the help
file of the R function \textbf{califlopp}
(\texttt{man/califlopp.Rd}).

The following tables describe the configuration variables. 


In the first column, in addition to the variable names,
information is given about the  possibility
for the user  to modify the default value: 
an asterisk means that it is the case, through the argument
\textbf{param} of the R function \textbf{califlopp}
(in an \textbf{R} session, see the on-line help of \textbf{califlopp}).
The name of the corresponding component of \textbf{param}
is given in parenthesis in the following table.

\newpage

\section{Input}

\begin{tabular}[t]{|p{5cm}|p{4cm}|p{6cm}|}
\hline
\textbf{Name} & \textbf{Meaning} & \textbf{Comments}  \\ \hline
DEFAULT\_INPUT\_FORMAT \mbox{(input)} \mbox{(*)} & 
Format of the polygons-file &
- should be 1 if each polygon is coded on two lines:
\\ 
 & &
1/ an identification  number, followed by the x-coordinates
\\
& &
2/ the same number, followed by the y-coordinates,
\\  & &
- should be 2 if each polygon is coded on three lines:
\\ & &
1/ an identification number, a name, the number of vertices (followed  possibly by other  data that are ignored)
\\ & &
2/ the x-coordinates
\\ & &
3/ the y-coordinates.
 \\ \hline
DEFAULT\_DELIM  \mbox{(delim)} \mbox{(*)} & 
Separator  character in the polygons-file
 & should be between double-quotes \\ \hline
MAX\_LINE\_POLY &
Maximal number of characters on each line of the polygon
file  & \\ \hline
MAX\_NAME &
Maximal length of the polygon names & \\ \hline
PATH\_MAX &
Maximal number of characters for pathnames & 
usually, PATH\_MAX is defined in stdio.h \\ \hline
\end{tabular}


\section{Output}
\begin{tabular}[h]{|p{5cm}|p{5cm}|p{5cm}|}
\hline
\textbf{Name} & \textbf{Meaning} & \textbf{Comments}  \\ \hline
OUTPUT\_FILE\_FORMAT &
Content of the result-file  &
- should be ALL to output all the results \\ 
& &
- should be FLOW  to output  the polygon identifiers and the flow by
square meter,\\
& &
- should be LIGHT  to output all the results  except for the time.
 \\ \hline
OUTPUT\_WARNING &
Warnings output on the error unit &
- should be ALL to print all warnings,
\\
& &
- should be NOTHING for minimum  warnings.
 \\ \hline
DEFAULT\_OUTPUT  \mbox{(output)} &
Output on the standard output unit &
- should be ALL to print all the results,\\
& &
- should be FLOW to print the integrated flows,
the flows by m$^2$,
\\
& &
- should be LIGHT to print the integrated flows, only, (one line per pair of polygons)\\
& &
- should be NOTHING for no print.
 \\ \hline
DEFAULT\_VERBOSE  \mbox{ (verbose)} \mbox{(*)} &
verbose mode &
 should be 1 to get output about the decomposition into convex polygons
and landscape relocation,   and
 0 otherwise \\ \hline
\end{tabular}

\section{Error treatment}
\begin{tabular}[h]{|p{5cm}|p{5cm}|p{5cm}|}
\hline
\textbf{Name} & \textbf{Meaning} & \textbf{Comments}  \\ \hline
ERR\_POLY &
treatment of erroneous polygons &
- should be 0 if an error on a polygon should be a warning:
   the erroneous polygon is then ignored \\ 
& &
- should be 1 if an error on a  polygon should be fatal \\ \hline
\end{tabular}

\section{Landscape features}
\begin{tabular}[t]{|p{5cm}|p{5cm}|p{5cm}|}
\hline
\textbf{Name} & \textbf{Meaning} & \textbf{Comments}  \\ \hline
MAX\_VERTICES
 & Maximal number of vertices per polygon
 & \\ \hline
MAX\_TRIANGLES
 & Maximal number of convex subpolygons per polygon
 & 
This number depends on the polygons shapes:
more they have obtuse angles, more the number of convex
subpolygons should be  great.
But, be careful:
If values of MAX\_VERTICES and MAX\_TRIANGLES are too big, 
execution errors may occur
("Segmentation fault" or
"Out of memory")
  \\ \hline
TRANSLATE
 & 
Landscape relocation.  
& 
Should be 1 if the landscape should be systematically
relocated, so that
the left-bottom corner of the landscape is (1,1).

(Recommanded value)
  \\ \hline
 SCALE
 & 
The polygon-coordinates are multiplied by SCALE.
 & 
Should be 1 or a multiple of 10.
For example, to take into account centimeters, set SCALE to 100  \\ \hline
SAFE
 & 
Maximal range of the coordinates &
It is the maximal range of the coordinates
after  they have been multiplied by SCALE.

SAFE should be less than INT\_MAX (which is usually= 2147483647)
 \\ \hline
DISTP
&
When the distance between
two successive  vertices
is less than or equal to DISTP, the second vertex is suppressed.
&   Expressed in  meters. \\ \hline
ANGLEPREC
&
Precision of the angle between 3 successive  vertices.
&
When the arccosinus of the angle between three  successive vertices 
is inside [$\pi$-ANGLEPREC, $\pi$+ANGLEPREC], the vertices are considered
as aligned, and the second one is suppressed.
When it is  inside [-ANGLEPREC, +ANGLEPREC], it is supposed that
the sharp spike they form is an artefact,  and the second one is suppressed. \\ \hline

\end{tabular}
\section{Individual dispersal functions}
\label{functions-constants}
\begin{tabular}[h]{|p{7cm}|p{7cm}|}
\hline
\textbf{Name} & \textbf{Meaning}  \\ \hline
DZ1, DZ2, DZ3, DZ4, DZ5
&
Thresholds for dispersal distances:
    When the minimal distance between two polygons
    is greater than
    or equal to
    these  values, the corresponding dispersal function 
(f1 for DZ1, ... f5 for DZ5) is
    supposed to be null; distances are in meter.
    Negative or null values mean that there is no limit
    in the dispersal.
\\ \hline
DP1, DP2, DP3, DP4, DP5
&
Thresholds for dispersal distances:
    When the minimal distance between two polygons is greater than
    or equal to
    these  values, the dispersal is calculated between
    polygons centroids;
    distances are in meter.
\\ \hline
\end{tabular}

\section{Methods features}
\subsection{Cubature method}

\begin{tabular}[h]{|p{5cm}|p{9cm}|}
\hline
\textbf{Name} & \textbf{Meaning}   \\ \hline
DEFAULT\_ABS\_ERR \mbox{ (abser)}\mbox{ (*)}
 & Default absolute precision
 \\ \hline
DEFAULT\_REL\_ERR \mbox{ (reler)}\mbox{ (*)}
 & Default relative precision
 \\ \hline
DEFAULT\_MAX\_PTS 
& Maximal number of evaluation points
per integration region.
 \\ \hline
DEFAULT\_NB\_PTS \mbox{ (maxpts)}\mbox{ (*)}
& Default maximal number of evaluations per triangle (should be in [37,DEFAULT\_MAX\_PTS])  
 \\ \hline
 MAX\_SREGIONS
& Maximal number of subregions per integration region.
 \\ \hline
TZ1, TZ2, TZ3, TZ4, TZ5\mbox{ (tz)}\mbox{ (*)}
&
Method of triangulation for the cubature method.
Should be True, if triangulation from (0,0) has to be done
when  (0,0) is included in the integration area
(recommended value when the dispersal function is very "sharp"
at the origin).
\\ \hline
\end{tabular}
\subsection{Grid method}
\begin{tabular}[h]{|p{5cm}|p{9cm}|}
\hline
\textbf{Name} & \textbf{Meaning}   \\ \hline
 MAX\_EST
 & Maximal number of estimations
 \\ \hline
 DEFAULT\_EST \mbox{ (nr)} \mbox{ (*)}
 & 
Default number of estimations ($\leq$ MAX\_EST)
 \\ \hline
 DEFAULT\_STEPX \mbox{ (step$_0$)} \mbox{ (*)}
 & Default step on the x-axis  grid of points; in meters.
 \\ \hline
 DEFAULT\_STEPY \mbox{ (step$_1$)} \mbox{ (*)}
 & Default  step on the y-axis grid of points; in meters.
 \\ \hline
  DEFAULT\_SEED  \mbox{ (seed)} \mbox{ (*)}
 &  Default value of the seed  for the random number generator.  \\ \hline
\end{tabular}

\section{Numerical  parameters}
\begin{tabular}[h]{|p{4cm}|p{5cm}|p{5cm}|}
\hline
\textbf{Name} & \textbf{Meaning} & \textbf{Comments} \\ \hline
 REAL\_PREC
 & 
Precision for real comparisons in geometrical computations
 & 
Recommended: (REAL\_MIN*1.0e+4)
\\ \hline
\end{tabular}



\chapter{How to make changes}
\label{howchanges}
\begin{enumerate}
\item
Download the tar-archive file of \verb+RCALI+ package and untar it:
a directory named \texttt{RCALI} is created.
\item
Possibly, reflect the changes you make in the source code 
in the help-file \texttt{man/califlopp.Rd} of the function \texttt{califlopp} (default values
of the parameters).
\item 
After alteration of the source code, recompilation is required.
Typically use the standard R command: \texttt{R CMD build RCALI}
on top of your \texttt{RCALI} directory.
\end{enumerate}
