
\section{Running Bertini\_real}
\label{sec:running_br}

Bertini\_real is called from the command line.   This is done simply by calling \texttt{bertini\_real} (or \texttt{bertini\_real.exe} for Cygwin users) from the command line. If the input file is called anything other than \texttt{input}, than the \texttt{-input} or \texttt{-i} option followed by the filename must be used. 

It is important to note that for Bertini\_real to run, the MATLAB executable must be on the path.


Bertini\_real uses the tracker options for Bertini, which are set at the top of the input file, in the {\tt CONFIG} section.

We suggest the following configuration options in the input file for Bertini\_real: 
\begin{itemize}
\item {\tt sharpendigits} $\approx$ 30

helps keep regeneration start points on target, and helps identify points which are supposed to be the same point.
\end{itemize}


Other options can improve performance and tighten up the produced decomposition. 


\subsection{Files Needed for Input}
In order to sucessfully run Bertini\_real, the program needs to be able to access the original \texttt{input} file that was used in Bertini, as well as the \texttt{witness\_data} file generated by Bertini.


\subsection{Command prompt, options}
There are a number of inline commands that can be used while running Bertini\_real. Below is a table that describes these options:\footnote{This table prepared by Beth Sudkamp.  Thanks Beth!}

\begin{longtabu} to \textwidth {
    X[1,c]	% option
    X[1,c]	% Modification options
    X[2,c]	% Command line appearance
    X[2,c]}	% Description/definition		
 \\ 
\caption{Bertini\_real command line options}\\
\toprule
\rowfont\bfseries
\textbf{Option} & \textbf{Alter} & \textbf{Command Line} & \textbf{Description}  \\
 \\ \hline  \\
\endfirsthead
\caption[]{\textit{Continued from previous page}}\\
 \\ \hline
\textbf{Option} & \textbf{Alter} & \textbf{Command Line} & \textbf{Description}  \\
 \\ \hline \\
\endhead
\bottomrule \multicolumn{4}{r}{\textit{Continued on next page}} \\
\endfoot
\bottomrule \multicolumn{4}{r}{} \\
\endlastfoot

\texttt{-component} & integer index of the component & \texttt{bertini\_real -component 1} & Decomposes only one component of the entire figure \\  \\ \hline \\
\texttt{-debug} &  n/a  & \texttt{bertini\_real -debug} &  If used, program will pause for 30 seconds before running for debugging purposes \\  \\ \hline \\
\texttt{-dim} or \texttt{-d} & target dimension of solution & \texttt{bertini\_real -d 2} &  Sets a target dimension to be used for the solution \\  \\ \hline \\
\texttt{-gammatrick} or \texttt{-g} & \texttt{1} (if you'd like Bertini\_real to use the gamma trick) or \texttt{0} (if not) & \texttt{bertini\_real -g 1} &  Indicator for whether Bertini\_real should use the gamma trick in a particular solver \\  \\ \hline \\
\texttt{-help} or \texttt{-h} & n/a & \texttt{bertini\_real -h} & Displays a help message containing the version of Bertini\_real, where Bertini\_real can be found online, support information, and finally the command line options. \\  \\ \hline \\
\texttt{-input} or \texttt{-i} & filename & \texttt{bertini\_real -i myfile} & Used if input file is named something other than `input'  \\  \\ \hline \\
\texttt{-mode} or \texttt{-m} & \texttt{bertini\_real} (default) or \texttt{crit}  & \texttt{bertini\_real -m crit} &  Sets the mode of Bertini\_real to be used \\  \\ \hline \\
\texttt{-nostifle} or \texttt{-ns} & n/a & \texttt{bertini\_real -ns} & If used, screen output will not be stifled \\  \\ \hline \\
\texttt{-nomerge} or \texttt{-nm} & n/a & \texttt{bertini\_real -nm} & Indicates that Bertini\_real should not merge ends \\  \\ \hline \\
\texttt{-output} or \texttt{-out} or \texttt{-o} & name of the output directory & \texttt{bertini\_real -out bertinir\_results} & Places the output files in a different directory \\  \\ \hline \\
\texttt{-projection} or \texttt{-pi} or \texttt{-p} &  desired filename & \texttt{bertini\_real -p myprojection} & Indicator for whether to read the projection from a file, rather than randomly choose it \\  \\ \hline \\
\texttt{-quick} or \texttt{-q} & n/a & \texttt{bertini\_real -q} & Solves problem quickly, but not as robust \\  \\ \hline \\
\texttt{-veryquick} or \texttt{-vq} & n/a & \texttt{bertini\_real -vq} & Solves problem very quickly, but not as robust  \\  \\ \hline \\
\texttt{-sphere} or \texttt{-s} & the name of the file for Bertini\_real to read & \texttt{bertini\_real -sphere mysphere} & Sets indicator that Bertini\_real should use sphere created by user rather than just compute sphere \\  \\ \hline \\
\texttt{-verb} & the level of the verbosity & \texttt{bertini\_real -verb 2} & Shows or hides output text \\  \\ \hline \\ 
\texttt{-version} or \texttt{-v} & n/a & \texttt{bertini\_real -version} & Displays the version of Bertini\_real running on your computer \\  \\ \hline
\end{longtabu}




	\subsection{Parallelism}

Bertini\_real is parallel-enabled, using MPI (but not OpenMP or threads). To use multiple processors, call it as you would any other MPI program: \texttt{mpiexec [options] bertini\_real}.






\subsection{Projections and spheres of interest}


 Here we describe the {\tt pi} file in Section~\ref{sec:pi}, and a {\tt sphere} of interest in Section~\ref{sec:sphere}.

\subsubsection{The user-defined projection, \texttt{pi}}
\label{sec:pi}

The {\tt pi} file, defining a specific projection to use for decomposing your curve or surface, has a simple format.  You indicate the number of variables, and then give the projection.  No punctuation or delimiters necessary.  

Using a particular projection, contained in a file of arbitrary name, is indicated to Bertini\_real by passing the {\tt -pi} flag.  For example, {\tt bertini\_real -pi my\_projection}.

By default, Bertini\_real uses a randomly generated projection to decompose the object.  This is so that the object is in {\em general position}, which is required for set-of-measure-zero guarantees that all elements of the critical space lie in the distinct fibers of the projection.


For decomposing surfaces, if you feel the need to supply your own projection, please consider using two projections $\pi_1$ and $\pi_2$ such that $\pi_1 \cdot \pi_2 = 0$.  That is, orthogonal projections tend to produce cleaner decompositions.

\File{A file describing a user-defined projection used to decompose a real object in 4 dimensions.  The first number indicates the number of coordinates, which must match the number in the object's ambient space.  Then, the values for the projection.  Try to use orthogonal projections for surfaces.}{pi}{example_projection}

\subsubsection{The sphere of interest, \texttt{sphere}}
\label{sec:sphere}

While Bertini\_real will happily compute a bounding sphere for you, containing all the interesting parts of your object, it may be very large, or kind of wonky in the case of some projections.  Hence, we allow the user to specify their sphere of interest by way of plain text file.

The {\tt sphere} file allows the user to bound the space in which to decompose their object.  
If there is a region of space you are interested in, you can compute your object inside a sphere of interest.

To inform Bertini\_real that you are using your own sphere rather than the computed one, use the {\tt -sphere} flag.  For example, {\tt bertini\_real -sphere my\_sphere\_file}.  This generally will not speed up computation at all, since there's no way to know prior to point computation whether the endpoint will be in or out of the sphere.  All it will change is the bounded region.


\File{A file describing a sphere of interest to Bertini\_real.  The radius appears first, followed by the coordinates of the center of the sphere.  Real coordinates only, omit the imaginary part.}{sphere}{example_sphere}
