
\section{Input Files}

\label{sec:input}


The instructions provided go through how to create input files, run these files through Bertini and Bertini\_real, and view a graphical representation of the results using MATLAB. Most of this information about Bertini, its input files, and syntax will be taken or paraphrased from the slightly-out-of-date Bertini User's Manual, which can be read \href{https://bertini.nd.edu/BertiniUsersManual.pdf}{here}. 


The \texttt{input} file has two parts, grouped as follows (where the \% symbol is the comment character in the \texttt{input} file, as usual):

\begin{center}\begin{minipage}{0.9\linewidth}

\begin{lstlisting}[language=c++, caption=Adapted from \cite{BM13}, captionpos=b]
CONFIG
% Lists of configuration settings (optional)
tracktype:1; % needed in order to run Bertini_real
END;
INPUT
% Symbol declarations
% Optional assignments (parameters, constants, etc.)
% Function definitions
END;
\end{lstlisting}
\end{minipage}\end{center}

The upper portion of the file consists of a list of configuration settings. Any configuration that is not listed in the \texttt{input} file will be set to its default value. A table of all configuration settings that may be changed, along with their default settings and acceptable ranges, may be found in the Appendix.\par
The syntax for the configuration lines is straightforward. It consists of the name of the setting (in all caps), followed by a colon, a space, the setting, and a semicolon. For example, to change the tracking type to 1 (the default is 0), simply include the following line in the \texttt{CONFIG} portion of the \texttt{input} file:

\begin{center}\begin{minipage}{0.9\linewidth}

\begin{lstlisting}[language=c++, caption=Adapted from \cite{BM13}, captionpos=b]
TRACKTYPE: 1;
\end{lstlisting}
\end{minipage}\end{center}

The lower portion of the \texttt{input} file begins with a list of symbol declarations (for the variables, functions, constants, and so on). All such declarations have the same format:
\begin{center}\begin{minipage}{0.9\linewidth}

\begin{lstlisting}[language=c++, caption=Adapted from \cite{BM13}, captionpos=b]
KEYWORD a1, a2, a3;
\end{lstlisting}
\end{minipage}\end{center}

where \texttt{KEYWORD} depends upon the type of declaration. All symbols used in the \texttt{input} file must be declared, with the exception of subfunctions. Here are details regarding each type of symbol that may be used in the input file:
\begin{itemize}

\item{FUNCTIONS:}
Regardless of the type of run, all functions must be named, and the names must be declared using the keyword \texttt{function}. Also, the functions must be defined in the same order that they were declared.

\item{VARIABLES}
In all cases except user-defined homotopies, the variables are listed by group with one group per line, with each line beginning with either the keyword \texttt{variable\_group} (for complex variable groups against which the polynomials have not been homogenized) or the keyword \texttt{hom\_variable\_group} (for variable groups against which the polynomials have been homogenized).
 Note that the user must choose one type of variable group for the entire input file, i.e., mixing of variable groups is not allowed in this release of Bertini. Also, only one variable group may be used for a positive-dimensional run. For example, if there are two
 nonhomogenized variable groups, the appropriate syntax would be
\begin{center}\begin{minipage}{0.9\linewidth}

\begin{lstlisting}[language=c++, caption=Adapted from \cite{BM13}, captionpos=b]
variable_group z1, z2;
variable_group z3;
\end{lstlisting}
\end{minipage}\end{center}

In the case of user-defined homotopies, the keyword is \texttt{variable}, and all variables should be defined in the same line.





\item{CONSTANTS:}
Bertini will accept numbers in either standard notation (e.g., 3.14159 or 0.0023) or scientific notation (e.g., 3.14159e1 or 2.3e-3). No decimal point is needed in the case of an integer. To define complex numbers, simply use the reserved symbol I for $\sqrt{-1}$, e.g., \texttt{1.35 + 0.98*I}. Please note that the multiplication symbol * is always necessary, i.e. concatenation does not
 mean anything to Bertini. Since it is sometimes useful to have constants gathered in one location (rather than scattered
 throughout the functions), Bertini has a \texttt{constant} type. If a constant type is to be used, it must be both declared and assigned to. Here is an example:
\begin{center}\begin{minipage}{0.9\linewidth}

\begin{lstlisting}[language=c++, caption=Adapted from \cite{BM13}, captionpos=b]
...
g1 = 1.25;
g2 = 0.75 - 1.13*I;
...
\end{lstlisting}
\end{minipage}\end{center}

Bertini will read in all provided digits and will make use of as many as possible in computations, depending on the working precision level. If the working precision level exceeds the number of digits provided for a particular number, all further digits are assumed to be
 0 (i.e., the input is always assumed to be exact). This seems to be the natural, accepted implementation choice, but it could cause difficulty if the user truncates coefficients without realizing the impact of this action on the corresponding algebraic set.

\item{SUBFUNCTIONS:}
Redundant subexpressions are common in polynomial systems coming from applications. For example, the subexpression \texttt{x\string^ 2 + 1.0} may appear in each of ten polynomials. One of Bertini’s advantages is that it allows for the use of subfunctions. To use a subfunction, simply choose a symbol, assign the expression to the symbol, and then use it in the functions. There is no need to declare subfunctions (and no way to do so anyway).

\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption=Adapted from \cite{BM13}, captionpos=b]
...
V = x/2 + 1.0;
...
f1 = 2*V^2 + 4.0;
...
\end{lstlisting}
\end{minipage}\end{center}

\item{SIN, COS, PI, AND EXP:}
Starting with Bertini v1.2, the sine function sin, cosine function cos and exponential function exp are built into Bertini. Additionally, Bertini uses \texttt{Pi} for the constant $\pi$. To avoid confusion with scientific notation, the constant \textit{e} is not specifically built in Bertini, but the user can define their own constant and set it equal to \texttt{exp(1)}, as shown below.
\begin{center}\begin{minipage}{0.9\linewidth}

\begin{lstlisting}[language=c++, caption=Adapted from \cite{BM13}, captionpos=b]
...
constant EN; % Euler's number e
EN = exp(1);
...
\end{lstlisting}
\end{minipage}\end{center}

It is important to note that Bertini will return an error if the argument of \texttt{sin}, \texttt{cos}, or \texttt{exp} depends upon a variable when trying to solve a polynomial system. There is no such restriction for user-provided homotopies.
\end{itemize}


\subsection{On Bertini input syntax}
Common complaints about Bertini are that (a) the parser that reads in the input is very picky and (b) the error messages are often to general. The development team agrees and will continue to work on this (especially during an upcoming complete rewrite). In the meantime, here is a list of syntax rules that are commonly broken, resulting in syntax errors:

\begin{itemize}
\item All lines (except \texttt{CONFIG} and \texttt{INPUT}, if used) must end with a semicolon.
\item Bertini is case-sensitive.
\item The symbol for $\sqrt{-1}$ is \texttt{I}, not \texttt{i}. If you prefer to use \texttt{i}, you may define \texttt{i} as a subfunction by
including the statement \texttt{i = I;}.
\item In scientific notation, the base is represented by \texttt{e} or {\tt E}, e.g., 2.2e-4. 
\item For multiplication, * is necessary (concatenation is not enough).
\item Exponentiation is designated by \string^.
\item All symbols except subfunctions must be declared prior to use.  You cannot combine declaration and definition, sadly.
\item No symbol can be declared twice. This error often occurs when copying and pasting in the
creation of the input file.
\item A pathvariable and at least one parameter are needed for user-defined homotopies. Please
refer to the previous section for details.
\item White space (tabs, spaces, and new lines) is ignored.
\end{itemize}
